diff options
| -rw-r--r-- | docs/designdefense.rst | 48 | ||||
| -rw-r--r-- | docs/tutorials/bfgwiki/basiclayout.rst | 2 |
2 files changed, 26 insertions, 24 deletions
diff --git a/docs/designdefense.rst b/docs/designdefense.rst index bc028fb4d..ea6104618 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -419,20 +419,21 @@ BFG "Encourages Use of ZCML" the :term:`Zope Component Architecture` registry that :mod:`repoze.bfg` uses as its application configuration. -Quick answer: well, it doesn't *really* encourage the use of ZCML. -Application developers can use the ``bfg_view`` decorator for the most -common form of configuration. But, yes, a :mod:`repoze.bfg` -application currently does need to possess a ZCML file for it to begin -executing successfully even if its only contents are a ``<scan>`` -directive that kicks off the location of decorated views. - -However, in the interest of completeness and in the spirit of -providing a lowest common denominator, :mod:`repoze.bfg` 1.2 will -include a completely imperative mode for all configuration. You will -be able to make "single file" apps in this mode, which should help -people who need to see everything done completely imperatively. For -example, the very most basic :mod:`repoze.bfg` "helloworld" program -will become something like: +Quick answer: well, it doesn't *really* encourage the use of ZCML. In +:mod:`repoze.bfg` 1.0 and 1.1, application developers could use +decorators for the most common form of configuration. But, yes, a +:mod:`repoze.bfg` 1.0/1.1 application needed to possess a ZCML file +for it to begin executing successfully even if its only contents were +a ``<scan>`` directive that kicked off a scan to find decorated view +callables. + +In the interest of completeness and in the spirit of providing a +lowest common denominator, :mod:`repoze.bfg` 1.2 includes a completely +imperative mode for all configuration. You will be able to make +"single file" apps in this mode, which should help people who need to +see everything done completely imperatively. For example, the very +most basic :mod:`repoze.bfg` "helloworld" program will become +something like: .. code-block:: python :linenos: @@ -450,9 +451,9 @@ will become something like: app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() -In this mode, no ZCML will be required for end users. Hopefully this -mode will allow people who are used to doing everything imperatively -feel more comfortable. +In this mode, no ZCML is required for end users. Hopefully this mode +will allow people who are used to doing everything imperatively feel +more comfortable. BFG Uses ZCML; ZCML is XML and I Don't Like XML ----------------------------------------------- @@ -482,10 +483,11 @@ All :mod:`repoze.bfg` declarations are singleton tags, unlike many other XML configuration systems. No XML *values* in ZCML are meaningful; it's always just XML tags and attributes. So in the very common case it's not really very much different than an otherwise -"flat" configuration format like ``.ini``, except a deeloper *can* -supply a directive that requires nesting, and multiple "sections" can -exist with the same "name" (e.g. two ``<route>`` declarations) must be -able to exist simultaneously. +"flat" configuration format like ``.ini``, except a developer can +*create* a directive that requires nesting (none of these exist in +:mod:`repoze.bfg` itself), and multiple "sections" can exist with the +same "name" (e.g. two ``<route>`` declarations) must be able to exist +simultaneously. You might think some other configuration file format would be better. But all configuration formats suck in one way or another. I @@ -803,8 +805,8 @@ BFG Has Too Many Dependencies This is true. At the time of this writing, the total number of Python package distributions that :mod:`repoze.bfg` depends upon transitively is 14 if you use Python 2.6, or 16, if you use Python 2.4 or 2.5. -This is a lot more than zero dependencies: a metric which various -Python microframeworks and Django boast. +This is a lot more than zero package distribution dependencies: a +metric which various Python microframeworks and Django boast. The :mod:`zope.component` and :mod:`zope.configuration` packages on which :mod:`repoze.bfg` depends have transitive dependencies on diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst index e2f8ac00e..f8943eeab 100644 --- a/docs/tutorials/bfgwiki/basiclayout.rst +++ b/docs/tutorials/bfgwiki/basiclayout.rst @@ -110,7 +110,7 @@ be in ``run.py`` and its ``app`` function: #. *Lines 17 - 18*. We create a :term:`root factory` using the finder. #. Line *19*. We construct a :term:`Configurator` with a - :term:`root_factory` and the settings keywords parsed by + :term:`root factory` and the settings keywords parsed by PasteDeploy. The root factory is named ``get_root``. We then use the ``make_wsgi_app`` method of the :term:`Configurator` to return a :term:`WSGI` application. |