Docs updates.

2 files changed, 62 insertions, 104 deletions

diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index bfe971b55..b82b4d826 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -13,9 +13,21 @@ source code that makes up the application.  The behavior of a
 Rules for Building An Extensible Application
 --------------------------------------------
 
-We'll describe the rules that must be obeyed by the developer of a
-:mod:`repoze.bfg` application if he or she wants his application to be
-maximally extensible.
+There's only one rule you need to obey if you want to build a
+maximally extensible :mod:`repoze.bfg` application: you should not use
+any :term:`configuration decoration` or :term:`imperative
+configuration`. This means the application developer should avoid
+relying on :term:`configuration decoration` meant to be detected via
+the a :term:`scan`, and you mustn't configure your :mod:`repoze.bfg`
+application *imperatively* by using any code which configures the
+application through methods of the :term:`Configurator` (except for
+its ``load_zcml`` method).  Instead, should must use :term:`ZCML` for
+the equivalent purposes. :term:`ZCML` declarations that belong to an
+application can be "overridden" by integrators as necessary, but
+decorators and imperative code which perform the same tasks cannot.
+
+In general: use only :term:`ZCML` to configure your application if
+you'd like it to be extensible.
 
 Fundamental Plugpoints
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -28,23 +40,6 @@ declarations made using the ZCML ``<view>`` directive (or the
 repoze bfg using the :term:`pkg_resources` API such as static files
 and templates.
 
-There's only one rule you need to obey if you want to build a
-maximally extensible :mod:`repoze.bfg` application: you should not use
-any :term:`configuration decoration` or :term:`imperative
-configuration`. This means the application developer should avoid
-relying on :term:`configuration decoration` meant to be detected via
-the ZCML ``<scan>`` directive, and you mustn't configure your
-:mod:`repoze.bfg` application *imperatively* by using any code which
-configures the application through methods of the :term:`Configurator`
-except for its ``load_zcml`` method.  Instead, you must use
-:term:`ZCML` for the equivalent purposes. :term:`ZCML` declarations
-that belong to an application can be "overridden" by integrators as
-necessary, but decorators and imperative code which perform the same
-tasks cannot.
-
-In general: use only :term:`ZCML` to configure your application if
-you'd like it to be extensible.
-
 ZCML Granularity
 ~~~~~~~~~~~~~~~~
 
@@ -89,10 +84,9 @@ If you've inherited a :mod:`repoze.bfg` application which uses
 one of two things may be true:
 
 - If you just want to *extend* the application, you can write
-  additional ZCML that registers more views or routes, loading the
-  existing views by using the ``scan`` ZCML directive and continuing
-  to use any existing imperative configuration done by the original
-  application.
+  additional ZCML that registers more views or routes, loading any
+  existing ZCML and continuing to use any existing imperative
+  configuration done by the original application.
 
 - If you want to *override* configuration in the application, you
   *may* need to change the source code of the original application.
@@ -107,11 +101,10 @@ one of two things may be true:
 
   If the source of trouble is configuration done imperatively (perhaps
   in the function called during application startup), you'll need to
-  or copying configuration information out of decorator arguments and
-  code which does imperative configuration into equivalent
+  change the code: convert imperative configuration into equivalent
   :term:`ZCML` declarations.
 
-Once this is done, you should be able to extend or modify the
+Once this is done, you should be able to extend or override the
 application like any other (see :ref:`extending_the_application`).
 
 .. _extending_the_application:
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 7ed0172fc..8f6e0f62f 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -13,7 +13,27 @@ Changing the Not Found View
 
 When :mod:`repoze.bfg` can't map a URL to view code, it invokes a
 notfound :term:`view`. The view it invokes can be customized through
-application configuration.
+application configuration.  This view can be configured in via
+:term:`imperative configuration` or :term:`ZCML`.
+
+.. topic:: Using Imperative Configuration
+
+   If your application uses :term:`imperative configuration`, you can
+   replace the Not Found view by using the ``set_notfound_view``
+   method of the ``Configurator`` named ``config``:
+
+   .. code-block:: python
+      :linenos:
+
+      import helloworld.views
+      config.set_notfound_view(helloworld.views.notfound_view)
+
+   Replace ``helloworld.views.notfound_view`` with a reference to the
+   Python :term:`view callable` you want to use to represent the Not
+   Found view.
+
+   See :ref:`configuration_module` for more information about other
+   arguments to the ``set_notfound_view`` method.
 
 .. topic:: Using ZCML
 
@@ -68,25 +88,6 @@ application configuration.
 
      .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
-.. topic:: Using Imperative Configuration
-
-   If your application uses :term:`imperative configuration`, you can
-   replace the Not Found view by using the ``set_notfound_view``
-   method of the ``Configurator`` named ``config``:
-
-   .. code-block:: python
-      :linenos:
-
-      import helloworld.views
-      config.set_notfound_view(helloworld.views.notfound_view)
-
-   Replace ``helloworld.views.notfound_view`` with a reference to the
-   Python :term:`view callable` you want to use to represent the Not
-   Found view.
-
-   See :ref:`configuration_module` for more information about other
-   arguments to the ``set_notfound_view`` method.
-
 Here's some sample code that implements a minimal NotFound view:
 
 .. code-block:: python
@@ -112,8 +113,27 @@ Changing the Forbidden View
 When :mod:`repoze.bfg` can't authorize execution of a view based on
 the authorization policy in use, it invokes a "forbidden view".  The
 default forbidden response has a 401 status code and is very plain,
-but it can be overridden as necessary using one of the following
-mechanisms:
+but it can be overridden as necessary using either :term:`imperative
+configuration` or :term:`ZCML`:
+
+.. topic:: Using Imperative Configuration
+
+   If your application uses :term:`imperative configuration`, you can
+   replace the Forbidden view by using the ``set_forbidden_view``
+   method of the ``Configurator`` named ``config``:
+
+   .. code-block:: python
+      :linenos:
+
+      import helloworld.views
+      config.set_forbiddden_view(helloworld.views.forbidden_view)
+
+   Replace ``helloworld.views.forbidden_view`` with a reference to the
+   Python :term:`view callable` you want to use to represent the
+   Forbidden view.
+
+   See :ref:`configuration_module` for more information about other
+   arguments to the ``set_forbidden_view`` method.
 
 .. topic:: Using ZCML
 
@@ -169,25 +189,6 @@ mechanisms:
 
      .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
-.. topic:: Using Imperative Configuration
-
-   If your application uses :term:`imperative configuration`, you can
-   replace the Forbidden view by using the ``set_forbidden_view``
-   method of the ``Configurator`` named ``config``:
-
-   .. code-block:: python
-      :linenos:
-
-      import helloworld.views
-      config.set_forbiddden_view(helloworld.views.forbidden_view)
-
-   Replace ``helloworld.views.forbidden_view`` with a reference to the
-   Python :term:`view callable` you want to use to represent the
-   Forbidden view.
-
-   See :ref:`configuration_module` for more information about other
-   arguments to the ``set_forbidden_view`` method.
-
 Like any other view, the forbidden view must accept at least a
 ``request`` parameter, or both ``context`` and ``request``.  The
 ``context`` (available as ``request.context`` if you're using the
@@ -219,42 +220,6 @@ Here's some sample code that implements a minimal forbidden view:
    an alternate forbidden view.  For example, it would make sense to
    return a response with a ``403 Forbidden`` status code.
 
-Changing the response factory
------------------------------
-
-You may change the class used as the "response factory" from within
-the :mod:`repoze.bfg` ``chameleon_zpt``, ``chameleon_genshi``,
-``chameleon_text`` (the ``render_template_to_response`` function used
-within each) and other various places where a Response object is
-constructed by :mod:`repoze.bfg`.  The default "response factory" is
-the class ``webob.Response``.  You may change it by placing the
-following ZCML in your ``configure.zcml`` file.
-
-.. code-block:: xml
-   :linenos:
-
-   <utility provides="repoze.bfg.interfaces.IResponseFactory"
-            component="helloworld.factories.response_factory"/>
-
-Replace ``helloworld.factories.response_factory`` with the Python
-dotted name to the response factory you want to use.  Here's some
-sample code that implements a minimal response factory:
-
-.. code-block:: python
-
-   from webob import Response
-
-   class MyResponse(Response):
-      pass
-
-   def response_factory():
-       return MyResponse
-
-Unlike a request factory, a response factory does not need to return
-an object that implements any particular interface; it simply needs
-have a ``status`` attribute, a ``headerlist`` attribute, and and
-``app_iter`` attribute.
-
 .. _changing_the_traverser:
 
 Changing the Traverser