- Created new top-level documentation section: "ZCML Directives".

  This section contains detailed ZCML directive information, some of
  which was removed from various narrative chapters.

7 files changed, 59 insertions, 713 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 3183d278a..049be2ca3 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -521,6 +521,8 @@ a good deal of what's going on "under the hood" when we configure a
 :mod:`repoze.bfg` application imperatively.  However, another mode of
 configuration exists named *declarative* configuration.
 
+.. _helloworld_declarative:
+
 Hello World, Configured Declaratively
 -------------------------------------
 
@@ -663,19 +665,16 @@ The ``configure.zcml`` ZCML file contains this bit of XML:
    :linenos:
 
     <configure xmlns="http://namespaces.repoze.org/bfg">
-       ... body ...
+       <!-- other directives -->
     </configure>
 
 Because :term:`ZCML` is XML, and because XML requires a single root
 tag for each document, every ZCML file used by :mod:`repoze.bfg` must
-contain a ``<configure>`` container tag, which acts as the root XML
-tag.  Usually, the start tag of the ``<configure>`` container tag has
-a default namespace associated with it. In the file above, the
-``xmlns="http://namepaces.repoze.org/bfg"`` attribute of the
-``configure`` start tag names the default XML namespace, which is
-``http://namespaces.repoze.org/bfg``.  See
-:ref:`word_on_xml_namespaces` for more information about XML
-namespaces.
+contain a ``configure`` container directive, which acts as the root
+XML tag.  It is a "container" directive because its only job is to
+contain other directives.
+
+See also :ref:`configure_directive` and :ref:`word_on_xml_namespaces`.
 
 The ``<include>`` Tag
 ~~~~~~~~~~~~~~~~~~~~~
@@ -719,6 +718,8 @@ However, the ``<include package="repoze.bfg.includes"/>`` tag needs to
 exist only in a "top-level" ZCML file, it needn't also exist in ZCML
 files *included by* a top-level ZCML file.
 
+See also :ref:`include_directive`.
+
 The ``<view>`` Tag
 ~~~~~~~~~~~~~~~~~~
 
@@ -839,54 +840,6 @@ application, a :data:`repoze.bfg.exceptions.ConfigurationError` will
 be raised when you attempt to start the application with information
 about which tags might have conflicted.
 
-.. _word_on_xml_namespaces:
-
-A Word On XML Namespaces
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using the ``http://namespaces.repoze.org/bfg`` namespace as the
-default XML namespace isn't strictly necessary; you can use a
-different default namespace as the default.  However, if you do, the
-declaration tags which are defined by :mod:`repoze.bfg` such as the
-``<view>`` declaration tag will need to be defined in such a way that
-the XML parser that :mod:`repoze.bfg` uses knows which namespace the
-:mod:`repoze.bfg` tags are associated with.  For example, the
-following files are all completely equivalent:
-
-.. topic:: Use of A Non-Default XML Namespace
-
-  .. code-block:: xml
-     :linenos:
-
-      <configure xmlns="http://namespaces.zope.org/zope"
-                 xmlns:bfg="http://namespaces.repoze.org/bfg">
-
-        <include package="repoze.bfg.includes" />
-
-        <bfg:view
-           view="helloworld.hello_world"
-           />
-
-      </configure>
-
-.. topic:: Use of A Per-Tag XML Namespace Without A Default XML Namespace
-
-  .. code-block:: xml
-     :linenos:
-
-      <configure>
-
-        <include package="repoze.bfg.includes" />
-
-        <view xmlns="http://namespaces.repoze.org/bfg"
-           view="helloworld.hello_world"
-           />
-
-      </configure>
-
-For more information about XML namespaces, see `this older, but simple
-XML.com article <http://www.xml.com/pub/a/1999/01/namespaces.html>`_.
-
 Conclusions
 -----------
 
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index c257ddb86..b2d2f20b5 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -65,14 +65,6 @@ registry` by either of the following methods:
          handler=".subscribers.mysubscriber"
        />
 
-   The *subscriber* :term:`ZCML directive` takes two attributes:
-   ``for``, and ``handler``.  The value of ``for`` is the interface
-   the subscriber is registered for.  Registering a subscriber for a
-   specific interface limits the event types that the subscriber will
-   receive to those specified by the interface. The value of
-   ``handler`` is a Python dotted-name path to the subscriber
-   function.
-
 Each of the above examples implies that every time the
 :mod:`repoze.bfg` framework emits an event object that supplies an
 :class:`repoze.bfg.interfaces.INewRequest` interface, the
@@ -112,7 +104,9 @@ file:
       handler=".subscribers.handle_new_response"
     />
 
-Or imperatively via the
+See also :ref:`subscriber_directive`.
+
+Subscribers may also be configured imperatively via the
 :meth:`repoze.bfg.configuration.Configurator.add_subscriber` method:
 
 .. ignore-next-block
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index f8ad29832..6bfd99e52 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -12,9 +12,10 @@ 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.  This view can be configured in via
-:term:`imperative configuration` or :term:`ZCML`.
+:term:`not found view`, which is a :term:`view callable`. The view it
+invokes can be customized through application configuration.  This
+view can be configured in via :term:`imperative configuration` or
+:term:`ZCML`.
 
 .. topic:: Using Imperative Configuration
 
@@ -48,43 +49,8 @@ application configuration.  This view can be configured in via
    Replace ``helloworld.views.notfound_view`` with the Python dotted name
    to the notfound view you want to use.
 
-   Other available attributes of the ``notfound`` ZCML directive are as
-   follows:
-
-   attr
-
-     The attribute of the view callable to use if ``__call__`` is not
-     correct (has the same meaning as in the context of
-     :ref:`the_view_zcml_directive`; see the description of ``attr``
-     there).
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-   renderer
-
-     This is either a single string term (e.g. ``json``) or a string
-     implying a path or :term:`resource specification`
-     (e.g. ``templates/views.pt``) used when the view returns a
-     non-:term:`response` object.  This attribute has the same meaning as
-     it would in the context of :ref:`the_view_zcml_directive`; see the
-     description of ``renderer`` there).
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-   wrapper
-
-     The :term:`view name` (*not* an object dotted name) of another view
-     declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
-     which will receive the response body of this view as the
-     ``request.wrapped_body`` attribute of its own request, and the
-     response returned by this view as the ``request.wrapped_response``
-     attribute of its own request.  This attribute has the same meaning
-     as it would in the context of :ref:`the_view_zcml_directive`; see
-     the description of ``wrapper`` there).  Note that the wrapper view
-     *should not* be protected by any permission; behavior is undefined
-     if it does.
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+   Other attributes of the ``notfound`` directive are documented at
+   :ref:`notfound_directive`.
 
 Here's some sample code that implements a minimal NotFound view:
 
@@ -110,10 +76,10 @@ 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 either :term:`imperative
-configuration` or :term:`ZCML`:
+the :term:`authorization policy` in use, it invokes a :term:`forbidden
+view`.  The default forbidden response has a 401 status code and is
+very plain, but it can be overridden as necessary using either
+:term:`imperative configuration` or :term:`ZCML`:
 
 .. topic:: Using Imperative Configuration
 
@@ -148,43 +114,8 @@ configuration` or :term:`ZCML`:
    Replace ``helloworld.views.forbidden_view`` with the Python
    dotted name to the forbidden view you want to use.
 
-   Other available attributes of the ``forbidden`` ZCML directive are as
-   follows:
-
-   attr
-
-     The attribute of the view callable to use if ``__call__`` is not
-     correct (has the same meaning as in the context of
-     :ref:`the_view_zcml_directive`; see the description of ``attr``
-     there).
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-   renderer
-
-     This is either a single string term (e.g. ``json``) or a string
-     implying a path or :term:`resource specification`
-     (e.g. ``templates/views.pt``) used when the view returns a
-     non-:term:`response` object.  This attribute has the same meaning as
-     it would in the context of :ref:`the_view_zcml_directive`; see the
-     description of ``renderer`` there).
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-   wrapper
-
-     The :term:`view name` (*not* an object dotted name) of another view
-     declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
-     which will receive the response body of this view as the
-     ``request.wrapped_body`` attribute of its own request, and the
-     response returned by this view as the ``request.wrapped_response``
-     attribute of its own request.  This attribute has the same meaning
-     as it would in the context of :ref:`the_view_zcml_directive`; see
-     the description of ``wrapper`` there).  Note that the wrapper view
-     *should not* be protected by any permission; behavior is undefined
-     if it does.
-
-     .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+   Other attributes of the ``forbidden`` directive are documented at
+   :ref:`forbidden_directive`.
 
 Like any other view, the forbidden view must accept at least a
 ``request`` parameter, or both ``context`` and ``request``.  The
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 91e4aee92..53d01c920 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -227,7 +227,7 @@ templates and static files.  Any software which uses the
 :func:`pkg_resources.get_resource_string` APIs will obtain an
 overridden file when an override is used.
 
-.. _resource_directive:
+.. _resource_zcml_directive:
 
 The ``resource`` ZCML Directive
 -------------------------------
@@ -293,3 +293,4 @@ For example:
       override_with="another.package:templates/"
      />
 
+See also :ref:`resource_directive`.
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 5cebd9792..0d1e3295d 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -473,55 +473,8 @@ An example of its usage, with all attributes fully expanded:
     max_age="31536000"
     />
 
-The ``secret`` is a string that will be used to encrypt the data
-stored by the cookie.  It is required and has no default.
-
-The ``callback`` is a Python dotted name to a function passed the
-string representing the userid stored in the cookie and the request as
-positional arguments.  The callback is expected to return None if the
-user represented by the string doesn't exist or a sequence of group
-identifiers (possibly empty) if the user does exist.  If ``callback``
-is None, the userid will be assumed to exist with no groups.  It
-defaults to ``None``.
-
-The ``cookie_name`` is the name used for the cookie that contains the
-user information.  It defaults to ``repoze.bfg.auth_tkt``.
-
-``secure`` is a boolean value.  If it's set to "true", the cookie will
-only be sent back by the browser over a secure (HTTPS) connection.
-It defaults to "false".
-
-``include_ip`` is a boolean value.  If it's set to true, the
-requesting IP address is made part of the authentication data in the
-cookie; if the IP encoded in the cookie differs from the IP of the
-requesting user agent, the cookie is considered invalid.  It defaults
-to "false".
-
-``timeout`` is an integer value.  It represents the maximum age in
-seconds which the auth_tkt ticket will be considered valid.  If
-``timeout`` is specified, and ``reissue_time`` is also specified,
-``reissue_time`` must be a smaller value than ``timeout``.  It
-defaults to ``None``, meaning that the ticket will be considered valid
-forever.
-
-``reissue_time`` is an integer value.  If ``reissue_time`` is
-specified, when we encounter a cookie that is older than the reissue
-time (in seconds), but younger that the ``timeout``, a new cookie will
-be issued.  It defaults to ``None``, meaning that authentication
-cookies are never reissued.  A value of ``0`` means reissue a cookie
-in the response to every request that requires authentication.
-
-``max_age`` is the maximum age of the auth_tkt *cookie*, in seconds.
-This differs from ``timeout`` inasmuch as ``timeout`` represents the
-lifetime of the ticket contained in the cookie, while this value
-represents the lifetime of the cookie itself.  When this value is set,
-the cookie's ``Max-Age`` and ``Expires`` settings will be set,
-allowing the auth_tkt cookie to last between browser sessions.  It is
-typically nonsensical to set this to a value that is lower than
-``timeout`` or ``reissue_time``, although it is not explicitly
-prevented.  It defaults to ``None``, meaning (on all major browser
-platforms) that auth_tkt cookies will last for the lifetime of the
-user's browser session.
+See :ref:`authtktauthenticationpolicy_directive` for details about
+this directive.
 
 ``remoteuserauthenticationpolicy``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -540,16 +493,8 @@ An example of its usage, with all attributes fully expanded:
     callback=".somemodule.somefunc"
     />
 
-The ``environ_key`` is the name that will be used to obtain the remote
-user value from the WSGI environment.  It defaults to ``REMOTE_USER``.
-
-The ``callback`` is a Python dotted name to a function passed the
-string representing the remote user and the request as positional
-arguments.  The callback is expected to return None if the user
-represented by the string doesn't exist or a sequence of group
-identifiers (possibly empty) if the user does exist.  If ``callback``
-is None, the userid will be assumed to exist with no groups.  It
-defaults to ``None``.
+See :ref:`remoteuserauthenticationpolicy_directive` for detailed
+information.
 
 ``repozewho1authenticationpolicy``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -568,18 +513,8 @@ An example of its usage, with all attributes fully expanded:
     callback=".somemodule.somefunc"
     />
 
-The ``identifier_name`` controls the name used to look up the
-:term:`repoze.who` "identifier" plugin within
-``request.environ['repoze.who.plugins']`` which is used by this policy to
-"remember" and "forget" credentials.  It defaults to ``auth_tkt``.
-
-The ``callback`` is a Python dotted name to a function passed the
-repoze.who identity and the request as positional arguments.  The
-callback is expected to return None if the user represented by the
-identity doesn't exist or a sequence of group identifiers (possibly
-empty) if the user does exist.  If ``callback`` is None, the userid
-will be assumed to exist with no groups.   It defaults to ``None``.
-
+See :ref:`repozewho1authenticationpolicy_directive` for detailed
+information.
 
 .. _authorization_policies_directives_section:
 
@@ -601,6 +536,8 @@ An example of its usage, with all attributes fully expanded:
 In other words, it has no configuration attributes; its existence in a
 ``configure.zcml`` file enables it.
 
+See :ref:`aclauthorizationpolicy_directive` for detailed information.
+
 .. _creating_an_authentication_policy:
 
 Creating Your Own Authentication Policy
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index ac604e347..443ffbfaa 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -53,8 +53,6 @@ error to the user's browser when no routes match.
 .. note:: See :ref:`modelspy_project_section` for an example of a
           simple root factory callable that will use traversal.
 
-.. _route_zcml_directive:
-
 The ``add_route`` Configurator Method
 -------------------------------------
 
@@ -72,228 +70,25 @@ See the :meth:`repoze.bfg.configuration.Configurator.add_route` API
 documentation for more information and options for adding a route
 imperatively.
 
-.. note:: The documentation that follows in this chapter assumes that
-   :term:`ZCML` will be used to perform route configuration; all
-   attributes of the ``<route>`` ZCML directive have analogues which
-   can be supplied as arguments to the
-   :meth:`repoze.bfg.configuration.Configurator.add_route` API.
-
-The ``route`` ZCML Directive
+Configuring a Route via ZCML
 ----------------------------
 
 Instead of using the imperative method of adding a route, you can use
-:term:`ZCML` for the same purpose.
-
-The ``route`` ZCML directive has these possible attributes.  All
-attributes are optional unless the description names them as required.
-
-path
-
-  The path of the route e.g. ``ideas/:idea``.  This attribute is
-  required.  See :ref:`route_path_pattern_syntax` for information
-  about the syntax of route paths.
-
-name
-
-  The name of the route, e.g. ``myroute``.  This attribute is
-  required.  It must be unique among all defined routes in a given
-  configuration.
-
-factory
-
-  The Python dotted-path name to a function that will generate a
-  :mod:`repoze.bfg` context object when this route matches.
-  e.g. ``mypackage.models.MyFactoryClass``.  If this argument is not
-  specified, a default root factory will be used.
-
-view
-
-  The Python dotted-path name to a function that will be used as a
-  view callable when this route matches.
-  e.g. ``mypackage.views.my_view``.
-
-xhr
-
-  This value should be either ``True`` or ``False``.  If this value is
-  specified and is ``True``, the :term:`request` must possess an
-  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
-  route to match.  This is useful for detecting AJAX requests issued
-  from jQuery, Prototype and other Javascript libraries.  If this
-  predicate returns false, route matching continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-request_method
-
-  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
-  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified,
-  this route will match if the request has *any* request method.  If
-  this predicate returns false, route matching continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-path_info
-
-  The value of this attribute represents a regular expression pattern
-  that will be tested against the ``PATH_INFO`` WSGI environment
-  variable.  If the regex matches, this predicate will be true.  If
-  this predicate returns false, route matching continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-request_param
-
-  This value can be any string.  A view declaration with this
-  attribute ensures that the associated route will only match when the
-  request has a key in the ``request.params`` dictionary (an HTTP
-  ``GET`` or ``POST`` variable) that has a name which matches the
-  supplied value.  If the value supplied to the attribute has a ``=``
-  sign in it, e.g. ``request_params="foo=123"``, then the key
-  (``foo``) must both exist in the ``request.params`` dictionary, and
-  the value must match the right hand side of the expression (``123``)
-  for the route to "match" the current request.  If this predicate
-  returns false, route matching continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-header
-
-  The value of this attribute represents an HTTP header name or a
-  header name/value pair.  If the value contains a ``:`` (colon), it
-  will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
-  or ``Host:localhost``).  The *value* of an attribute that represent
-  a name/value pair should be a regular expression.  If the value does
-  not contain a colon, the entire value will be considered to be the
-  header name (e.g. ``If-Modified-Since``).  If the value evaluates to
-  a header name only without a value, the header specified by the name
-  must be present in the request for this predicate to be true.  If
-  the value evaluates to a header name/value pair, the header
-  specified by the name must be present in the request *and* the
-  regular expression specified as the value must match the header
-  value.  Whether or not the value represents a header name or a
-  header name/value pair, the case of the header name is not
-  significant.  If this predicate returns false, route matching
-  continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+:term:`ZCML` for the same purpose.  For example:
 
-accept
-
-  The value of this attribute represents a match query for one or more
-  mimetypes in the ``Accept`` HTTP request header.  If this value is
-  specified, it must be in one of the following forms: a mimetype
-  match token in the form ``text/plain``, a wildcard mimetype match
-  token in the form ``text/*`` or a match-all wildcard mimetype match
-  token in the form ``*/*``.  If any of the forms matches the
-  ``Accept`` header of the request, this predicate will be true.  If
-  this predicate returns false, route matching continues.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-custom_predicates
-
-  This value should be a sequence of references to custom predicate
-  callables.  Use custom predicates when no set of predefined
-  predicates does what you need.  Custom predicates can be combined
-  with predefined predicates as necessary.  Each custom predicate
-  callable should accept two arguments: ``context`` and ``request``
-  and should return either ``True`` or ``False`` after doing arbitrary
-  evaluation of the context and/or the request.  If all callables
-  return ``True``, the associated route will be considered viable for
-  a given request.  If any custom predicate returns ``False``, route
-  matching continues.  Note that the value ``context`` will always be
-  ``None`` when passed to a custom route predicate.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
-
-view_for
-
-  The Python dotted-path name to a class or an interface that the
-  :term:`context` of the view should match for the view named by the
-  route to be used.  This attribute is only useful if the ``view``
-  attribute is used.  If this attribute is not specified, the default
-  (``None``) will be used.
-
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
-
-  This attribute can also be spelled as ``for``.
-
-view_permission
-
-  The permission name required to invoke the view associated with this
-  route.  e.g. ``edit``. (see :ref:`using_security_with_urldispatch`
-  for more information about permissions).
-
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
-
-  This attribute can also be spelled as ``permission``.
-
-view_renderer
-
-  This is either a single string term (e.g. ``json``) or a string
-  implying a path or :term:`resource specification`
-  (e.g. ``templates/views.pt``).  If the renderer value is a single
-  term (does not contain a dot ``.``), the specified term will be used
-  to look up a renderer implementation, and that renderer
-  implementation will be used to construct a response from the view
-  return value.  If the renderer term contains a dot (``.``), the
-  specified term will be treated as a path, and the filename extension
-  of the last element in the path will be used to look up the renderer
-  implementation, which will be passed the full path.  The renderer
-  implementation will be used to construct a response from the view
-  return value.  See :ref:`views_which_use_a_renderer` for more
-  information.
-
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
-
-  This attribute can also be spelled as ``renderer``.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-view_request_type
-
-  A dotted Python name to an interface representing a :term:`request
-  type`.  If this argument is not specified, any request type will be
-  considered a match for the view associated with this route.
-
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
-
-  This attribute can also be spelled as ``request_type``.
-
-view_containment
-
-  This value should be a Python dotted-path string representing the
-  class that a graph traversal parent object of the :term:`context`
-  must be an instance of (or :term:`interface` that a parent object
-  must provide) in order for this view to be found and called.  Your
-  models must be "location-aware" to use this feature.  See
-  :ref:`location_aware` for more information about location-awareness.
-
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-view_attr
+.. code-block:: xml
+   :linenos:
 
-  The view machinery defaults to using the ``__call__`` method of the
-  view callable (or the function itself, if the view callable is a
-  function) to obtain a response dictionary.  The ``attr`` value allows
-  you to vary the method attribute used to obtain the response.  For
-  example, if your view was a class, and the class has a method named
-  ``index`` and you wanted to use this method instead of the class'
-  ``__call__`` method to return the response, you'd say
-  ``attr="index"`` in the view configuration for the view.  This is
-  most useful when the view definition is a class.
+   <route
+       name="myroute"
+       path="/prefix/:one/:two"
+    />
 
-  If the ``view`` attribute is not provided, this attribute has no
-  effect.
+See :ref:`route_directive` for full ``route`` ZCML directive
+documentation.
 
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+.. note:: The documentation that follows in this chapter assumes that
+   :term:`ZCML` will be used to perform route configuration.
 
 The Matchdict
 -------------
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index a073bb6d8..5f9eb9140 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -331,254 +331,7 @@ A ZCML ``view`` declaration's ``view`` attribute can also name a
 class.  In this case, the rules described in :ref:`class_as_view`
 apply for the class which is named.
 
-.. _the_view_zcml_directive:
-
-The ``view`` ZCML Directive
-+++++++++++++++++++++++++++
-
-The ``view`` ZCML directive has many possible attributes.  Some of the
-attributes are descriptive or influence rendering.  Other attributes
-are :term:`predicate` attributes, meaning that they imply an
-evaluation to true or false when view lookup is performed.
-
-*All* predicates named in a view configuration must evaluate to true
-in order for the view callable it names to be considered "invokable"
-for a given request.  See :ref:`view_lookup_ordering` for a
-description of how a view configuration matches (or doesn't match)
-during a request.
-
-The possible attributes of the ``view`` ZCML directive are described
-below.  They are divided into predicate and non-predicate categories.
-
-Non-Predicate Attributes
-########################
-
-view
-
-  The Python dotted-path name to the view callable.  This attribute is
-  required unless a ``renderer`` attribute also exists.  If a
-  ``renderer`` attribute exists on the directive, this attribute
-  defaults to a view that returns an empty dictionary (see
-  :ref:`views_which_use_a_renderer`).
-
-permission
-
-  The name of a *permission* that the user must possess in order to
-  call the view.  See :ref:`view_security_section` for more
-  information about view security and permissions.
-
-attr
-
-  The view machinery defaults to using the ``__call__`` method of the
-  view callable (or the function itself, if the view callable is a
-  function) to obtain a response dictionary.  The ``attr`` value
-  allows you to vary the method attribute used to obtain the response.
-  For example, if your view was a class, and the class has a method
-  named ``index`` and you wanted to use this method instead of the
-  class' ``__call__`` method to return the response, you'd say
-  ``attr="index"`` in the view configuration for the view.  This is
-  most useful when the view definition is a class.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-renderer
-
-  This is either a single string term (e.g. ``json``) or a string
-  implying a path or :term:`resource specification`
-  (e.g. ``templates/views.pt``).  If the renderer value is a single
-  term (does not contain a dot ``.``), the specified term will be used
-  to look up a renderer implementation, and that renderer
-  implementation will be used to construct a response from the view
-  return value.  If the renderer term contains a dot (``.``), the
-  specified term will be treated as a path, and the filename extension
-  of the last element in the path will be used to look up the renderer
-  implementation, which will be passed the full path.  The renderer
-  implementation will be used to construct a response from the view
-  return value.
-
-  Note that if the view itself returns a response (see
-  :ref:`the_response`), the specified renderer implementation is never
-  called.
-
-  When the renderer is a path, although a path is usually just a
-  simple relative pathname (e.g. ``templates/foo.pt``, implying that a
-  template named "foo.pt" is in the "templates" directory relative to
-  the directory in which the ZCML file is defined), a path can be
-  absolute, starting with a slash on UNIX or a drive letter prefix on
-  Windows.  The path can alternately be a :term:`resource
-  specification` in the form
-  ``some.dotted.package_name:relative/path``, making it possible to
-  address template resources which live in a separate package.
-
-  The ``renderer`` attribute is optional.  If it is not defined, the
-  "null" renderer is assumed (no rendering is performed and the value
-  is passed back to the upstream BFG machinery unmolested).
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-wrapper
-
-  The :term:`view name` (*not* an object dotted name) of another view
-  declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
-  which will receive the response body of this view as the
-  ``request.wrapped_body`` attribute of its own request, and the
-  response returned by this view as the ``request.wrapped_response``
-  attribute of its own request.  Using a wrapper makes it possible to
-  "chain" views together to form a composite response.  The response
-  of the outermost wrapper view will be returned to the user.  The
-  wrapper view will be found as any view is found: see
-  :ref:`view_lookup_ordering`.  The "best" wrapper view will be found
-  based on the lookup ordering: "under the hood" this wrapper view is
-  looked up via ``repoze.bfg.view.render_view_to_response(context,
-  request, 'wrapper_viewname')``. The context and request of a wrapper
-  view is the same context and request of the inner view.  If this
-  attribute is unspecified, no view wrapping is done.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-Predicate Attributes
-####################
-
-name
-
-  The *view name*.  Read the :ref:`traversal_chapter` to understand
-  the concept of a view name.
-
-for
-
-  A Python dotted-path name representing the Python class that the
-  :term:`context` must be an instance of, *or* the :term:`interface`
-  that the :term:`context` must provide in order for this view to be
-  found and called.  This predicate is true when the :term:`context`
-  is an instance of the represented class or if the :term:`context`
-  provides the represented interface; it is otherwise false.
-
-route_name
-
-  *This attribute services an advanced feature that isn't often used
-  unless you want to perform traversal *after* a route has matched.*
-  This value must match the ``name`` of a ``<route>`` declaration (see
-  :ref:`urldispatch_chapter`) that must match before this view will be
-  called.  Note that the ``route`` configuration referred to by
-  ``route_name`` usually has a ``*traverse`` token in the value of its
-  ``path``, representing a part of the path that will be used by
-  traversal against the result of the route's :term:`root factory`.
-  See :ref:`hybrid_chapter` for more information on using this
-  advanced feature.
-
-request_type
-
-  This value should be a Python dotted-path string representing the
-  :term:`interface` that the :term:`request` must have in order for
-  this view to be found and called.  The presence of this attribute is
-  largely for backwards compatibility with applications written for
-  :mod:`repoze.bfg` version 1.0.  This value may be an HTTP
-  ``REQUEST_METHOD`` string, e.g.  ('GET', 'HEAD', 'PUT', 'POST', or
-  'DELETE').  Passing request method strings as a ``request_type`` is
-  deprecated.  Use the ``request_method`` attribute instead for
-  maximum forward compatibility.
-
-request_method
-
-  This value can either be one of the strings 'GET', 'POST', 'PUT',
-  'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``.  A view
-  declaration with this attribute ensures that the view will only be
-  called when the request's ``method`` (aka ``REQUEST_METHOD``) string
-  matches the supplied value.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-request_param
-
-  This value can be any string.  A view declaration with this
-  attribute ensures that the view will only be called when the request
-  has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
-  ``POST`` variable) that has a name which matches the supplied value.
-  If the value supplied to the attribute has a ``=`` sign in it,
-  e.g. ``request_params="foo=123"``, then the key (``foo``) must both
-  exist in the ``request.params`` dictionary, and the value must match
-  the right hand side of the expression (``123``) for the view to
-  "match" the current request.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-containment
-
-  This value should be a Python dotted-path string representing the
-  class that a graph traversal parent object of the :term:`context`
-  must be an instance of (or :term:`interface` that a parent object
-  must provide) in order for this view to be found and called.  Your
-  models must be "location-aware" to use this feature.  See
-  :ref:`location_aware` for more information about location-awareness.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-xhr
-
-  This value should be either ``True`` or ``False``.  If this value is
-  specified and is ``True``, the :term:`request` must possess an
-  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has
-  the value ``XMLHttpRequest`` for this view to be found and called.
-  This is useful for detecting AJAX requests issued from jQuery,
-  Prototype and other Javascript libraries.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-accept
-
-  The value of this attribute represents a match query for one or more
-  mimetypes in the ``Accept`` HTTP request header.  If this value is
-  specified, it must be in one of the following forms: a mimetype
-  match token in the form ``text/plain``, a wildcard mimetype match
-  token in the form ``text/*`` or a match-all wildcard mimetype match
-  token in the form ``*/*``.  If any of the forms matches the
-  ``Accept`` header of the request, this predicate will be true.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-header
-
-  The value of this attribute represents an HTTP header name or a
-  header name/value pair.  If the value contains a ``:`` (colon), it
-  will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
-  or ``Host:localhost``).  The *value* of an attribute that represent
-  a name/value pair should be a regular expression.  If the value does
-  not contain a colon, the entire value will be considered to be the
-  header name (e.g. ``If-Modified-Since``).  If the value evaluates to
-  a header name only without a value, the header specified by the name
-  must be present in the request for this predicate to be true.  If
-  the value evaluates to a header name/value pair, the header
-  specified by the name must be present in the request *and* the
-  regular expression specified as the value must match the header
-  value.  Whether or not the value represents a header name or a
-  header name/value pair, the case of the header name is not
-  significant.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-path_info
-
-  The value of this attribute represents a regular expression pattern
-  that will be tested against the ``PATH_INFO`` WSGI environment
-  variable.  If the regex matches, this predicate will be true.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-custom_predicates
-
-  This value should be a sequence of references to custom predicate
-  callables (e.g. ``dotted.name.one dotted.name.two``, if used in
-  ZCML; Python dotted names to callables separated by spaces).  Use
-  custom predicates when no set of predefined predicates do what you
-  need.  Custom predicates can be combined with predefined predicates
-  as necessary.  Each custom predicate callable should accept two
-  arguments: ``context`` and ``request`` and should return either
-  ``True`` or ``False`` after doing arbitrary evaluation of the
-  context and/or the request.  If all callables return ``True``, the
-  associated view callable will be considered viable for a given
-  request.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
+See :ref:`view_directive` for complete ZCML directive documentation.
 
 .. _mapping_views_to_urls_using_a_decorator_section:
 
@@ -691,7 +444,7 @@ Or replaces the need to add this imperative configuration stanza:
 All arguments to :class:`repoze.bfg.view.bfg_view` are optional.
 Every argument to :class:`repoze.bfg.view.bfg_view` matches the
 meaning of the same-named attribute in ZCML view configuration
-described in :ref:`the_view_zcml_directive`.
+described in :ref:`view_directive`.
 
 If ``name`` is not supplied, the empty string is used (implying
 the default view).
@@ -738,9 +491,8 @@ If ``xhr`` is specified, it must be a boolean value.  If the value is
 If ``accept`` is specified, it must be a mimetype value.  If
 ``accept`` is specified, the view will only be invoked if the
 ``Accept`` HTTP header matches the value requested.  See the
-description of ``accept`` in :ref:`the_view_zcml_directive` for
-information about the allowable composition and matching behavior of
-this value.
+description of ``accept`` in :ref:`view_directive` for information
+about the allowable composition and matching behavior of this value.
 
 If ``header`` is specified, it must be a header name or a
 ``headername:headervalue`` pair.  If ``header`` is specified, and
@@ -748,8 +500,8 @@ possesses a value the view will only be invoked if an HTTP header
 matches the value requested.  If ``header`` is specified without a
 value (a bare header name only), the view will only be invoked if the
 HTTP header exists with any value in the request.  See the description
-of ``header`` in :ref:`the_view_zcml_directive` for information about
-the allowable composition and matching behavior of this value.
+of ``header`` in :ref:`view_directive` for information about the
+allowable composition and matching behavior of this value.
 
 View lookup ordering for views registered with the
 :class:`repoze.bfg.view.bfg_view` decorator is the same as for those
@@ -1387,6 +1139,8 @@ tag):
    <renderer
       factory="repoze.bfg.renderers.json_renderer_factory"/>
 
+See also :ref:`renderer_directive`.
+
 .. _view_security_section:
 
 View Security
@@ -1463,29 +1217,6 @@ Use of the imperative configuration method
 :meth:`repoze.bfg.configuration.configurator.add_static_view` is
 completely equivalent to using ZCML for the same purpose.
 
-The ZCML directive can accept three attributes:
-
-name
-
-  The (application-root-relative) URL prefix of the static directory.
-  For example, to serve static files from ``/static`` in most
-  applications, you would provide a ``name`` of ``static``.
-
-path
-
-  A path to a directory on disk where the static files live.  This
-  path may either be 1) absolute (e.g. ``/foo/bar/baz``) 2)
-  Python-package-relative (e.g. (``packagename:foo/bar/baz``) or 3)
-  relative to the package directory in which the ZCML file which
-  contains the directive (e.g. ``foo/bar/baz``).
-
-cache_max_age
-
-  The number of seconds that the static resource can be cached, as
-  represented in the returned response's ``Expires`` and/or
-  ``Cache-Control`` headers, when any static file is served from this
-  directive.  This defaults to 3600 (5 minutes).
-
 Here's an example of a ``static`` ZCML directive that will serve files
 up ``/static`` URL from the ``/var/www/static`` directory of the
 computer which runs the :mod:`repoze.bfg` application.
@@ -1533,9 +1264,13 @@ directive's ``path`` is ``/path/to/static``,
 subdirectories recursively, and any subdirectories may hold files;
 these will be resolved by the static view as you would expect.
 
+See :ref:`static_directive` for detailed information.
+
 .. note:: The ``<static>`` ZCML directive is new in :mod:`repoze.bfg`
    1.1.
 
+.. _generating_static_resource_urls:
+
 Generating Static Resource URLs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~