- General documentation freshening which takes imperative

  configuration into account in more places and uses glossary
  references more liberally.

2 files changed, 28 insertions, 30 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 705e5aef5..7720bf5fc 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -21,18 +21,17 @@ used to create all kinds of web applications.
    libraries to create an application is often initially easier than
    using a framework to create an application, because the developer
    can choose to cede control to library code he has not authored
-   selectively, making the resulting application easier to understand.
-   When using a framework, the developer is typically required to cede
-   a greater portion of control to code he has not authored: code that
-   resides in the framework itself.  You needn't use a framework at
-   all to create a web application using Python.  A rich set of
-   libraries exists for the platform which you can snap together to
-   effectively create your own framework.  In practice, however, using
-   an existing framework to create an application is often more
-   practical than rolling your own via a set of libraries if the
-   framework provides a set of facilities and assumptions that fit
-   your application requirements.  :mod:`repoze.bfg` is a framework
-   that fits a large set of assumptions in the domain of web
+   selectively. When using a framework, the developer is typically
+   required to cede a greater portion of control to code he has not
+   authored: code that resides in the framework itself.  You needn't
+   use a framework at all to create a web application using Python.  A
+   rich set of libraries exists for the platform which you can snap
+   together to effectively create your own framework.  In practice,
+   however, using an existing framework to create an application is
+   often more practical than rolling your own via a set of libraries
+   if the framework provides a set of facilities and assumptions that
+   fit your application requirements.  :mod:`repoze.bfg` is a
+   framework that fits a large set of assumptions in the domain of web
    application construction.
 
 As a framework, the primary job of :mod:`repoze.bfg` is to make it
@@ -51,11 +50,10 @@ instance, it's easy to think of the values implied by a ``.ini`` file
 which is parsed at application startup time as "configuration".
 :mod:`repoze.bfg` extends this pattern all the way out to application
 development, using the term "configuration" to express standardized
-methods the framework makes available to developers which can be used
-to plug code into a deployment of the framework itself.  When you plug
-code into the :mod:`repoze.bfg` framework, you are indeed
-"configuring" :mod:`repoze.bfg` for the purpose of creating a
-particular application deployment.
+methods which can be used to plug code into a deployment of the
+framework itself.  When you plug code into the :mod:`repoze.bfg`
+framework, you are indeed "configuring" :mod:`repoze.bfg` for the
+purpose of creating a particular application deployment.
 
 There are a number of different mechanisms you may use to configure
 :mod:`repoze.bfg` to create an application: *imperative* configuration
@@ -75,9 +73,10 @@ Hello World, Configured Imperatively
 ------------------------------------
 
 Experienced Python programmers may find the "imperative" configuration
-mechanism fits the way they already do things. This is the configuration
-mode in which developers cede the least amount of control to the framework.
-Because of this, it is also the easiest configuration mode to understand.
+mechanism fits the way they already do things. This is the
+configuration mode in which developers cede the least amount of
+control to the framework.  It is often the easiest configuration mode
+to understand.
 
 Here's one of the simplest :mod:`repoze.bfg` applications, configured
 imperatively:
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index a94c493a6..4417ffcd5 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -16,10 +16,9 @@ Like :term:`Zope`, :mod:`repoze.bfg` uses Zope Page Templates
 (:term:`ZPT`) as its default and best-supported templating
 language. However, :mod:`repoze.bfg` uses a different implementation
 of the :term:`ZPT` specification than Zope does: the :term:`Chameleon`
-:term:`chameleon.zpt` templating engine. This templating engine
-complies largely with the `Zope Page Template
-<http://wiki.zope.org/ZPT/FrontPage>`_ template specification, however
-it is significantly faster.
+templating engine. This templating engine complies largely with the
+`Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_ template
+specification, however it is significantly faster.
 
 .. note:: The language definition documentation for Chameleon
    ZPT-style templates is available from `the Chameleon website
@@ -27,7 +26,7 @@ it is significantly faster.
    <http://chameleon.repoze.org/docs/latest/>`_ for the Chameleon ZPT
    language specification.
 
-Given that there is a :term:`chameleon.zpt` template named ``foo.pt``
+Given that there is a :term:`Chameleon` ZPT template named ``foo.pt``
 in a directory in your application named ``templates``, you can render
 the template from a view like so:
 
@@ -90,7 +89,7 @@ changing the content-type and status:
 A Sample Template
 ~~~~~~~~~~~~~~~~~
 
-Here's what a simple :term:`chameleon.zpt` template used under
+Here's what a simple :term:`Chameleon` ZPT template used under
 :mod:`repoze.bfg` might look like:
 
 .. code-block:: xml
@@ -113,7 +112,7 @@ Here's what a simple :term:`chameleon.zpt` template used under
     </html>
 
 Note the use of :term:`Genshi` -style ``${replacements}`` above.  This
-is one of the ways that :term:`chameleon.zpt` differs from standard
+is one of the ways that :term:`Chameleon` ZPT differs from standard
 ZPT.  The above template expects to find a ``project`` key in the set
 of keywords passed in to it via ``render_template`` or
 ``render_template_to_response``. Typical ZPT attribute-based syntax
@@ -124,9 +123,9 @@ Using ZPT Macros in :mod:`repoze.bfg`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Unlike Zope "browser views", :mod:`repoze.bfg` doesn't make any names
-(such as ``context`` or ``view``) available to :term:`chameleon.zpt`
-templates by default.  Instead, it expects you to pass all the names
-you need into the template.
+(such as ``context`` or ``view``) available to :term:`Chameleon` ZPT
+templates by default unless a :term:`renderer` is used.  Instead, it
+expects you to pass all the names you need into the template.
 
 One of the common needs in ZPT-based template is to one template's
 "macros" from within a different template.  In Zope, this is typically