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

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

10 files changed, 1575 insertions, 713 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index fab733878..b2a211113 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -490,6 +490,9 @@ Glossary
     The configuration mode in which you use Python to call methods on
     a :term:`Configurator` in order to add each :term:`configuration
     declaration` required by your application.
+  Declarative Configuration
+    The configuration mode in which you use :term:`ZCML` to make
+    a set of :term:`configuration declaration` statements.
   Not Found View
      The :term:`view callable` invoked by :mod:`repoze.bfg` when the
      developer explicitly raises a
diff --git a/docs/index.rst b/docs/index.rst
index 9538dbaf6..aef653803 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -88,6 +88,16 @@ Per-module :mod:`repoze.bfg` API documentation.
    api/view
    api/wsgi
 
+ZCML Directives
+===============
+
+Documentation for each :mod:`repoze.bfg` :term:`ZCML directive`.
+
+.. toctree::
+   :maxdepth: 2
+
+   zcml
+
 Tutorials
 =========
 
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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/zcml.rst b/docs/zcml.rst
new file mode 100644
index 000000000..efca070bc
--- /dev/null
+++ b/docs/zcml.rst
@@ -0,0 +1,1503 @@
+.. _zcml_directives:
+
+ZCML Directives
+===============
+
+:term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg`
+application to perform :term:`declarative configuration`.  Each
+:term:`ZCML directive` supplied by :mod:`repoze.bfg` is documented
+below.
+
+.. _configure_directive:
+
+``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 directive, which acts as the root
+XML tag.  It is a "container" directive because its only job is to
+contain other directives.
+
+Attributes
+~~~~~~~~~~
+
+``xmlns``
+
+   The default XML namespace used for subdirectives.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <configure xmlns="http://namespaces.repoze.org/bfg">
+
+      <!-- other directives -->
+
+   </configure>
+
+.. _word_on_xml_namespaces:
+
+A Word On XML Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually, the start tag of the ``<configure>`` container tag has a
+default *XML namespace* associated with it. This is usually
+``http://namepaces.repoze.org/bfg``, named by the ``xmlns`` attribute
+of the ``configure`` start tag.
+
+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>`_.
+
+The conventions in this document assume that the default XML namespace
+is ``http://namespaces.repoze.org/bfg``.
+
+Alternatives
+~~~~~~~~~~~~
+
+None.
+
+See Also
+~~~~~~~~
+
+See also :ref:`helloworld_declarative`.
+
+.. _include_directive:
+
+``include``
+-----------
+
+The ``include`` directive includes configuration from an external ZCML
+file.  Use of the ``include`` tag allows a user to split configuration
+across multiple ZCML files, and allows package distributors to provide
+default ZCML configuration for specific purposes which can be
+included by the integrator of the package as necessary.
+
+Attributes
+~~~~~~~~~~
+
+``package``
+
+   A :term:`dotted Python name` which references a Python :term:`package`.
+
+``filename``
+
+   An absolute or relative filename which references a ZCML file.
+
+The ``package`` and ``filename`` attributes can be used together or
+separately as necessary.
+
+Examples
+~~~~~~~~
+
+.. topic:: Loading the File Named ``configure.zcml`` from a Package Implicitly
+
+   .. code-block:: xml
+      :linenos:
+
+      <include package="some.package" />
+
+.. topic:: Loading the File Named ``other.zcml`` From the Current Package
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="other.zcml" />
+
+.. topic:: Loading a File From a Subdirectory of the Current Package
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="subdir/other.zcml" />
+
+.. topic:: Loading the File Named ``/absolute/path/other.zcml``
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="/absolute/path/other.zcml" />
+
+.. topic:: Loading the File Named ``other.zcml`` From a Package Explicitly
+
+   .. code-block:: xml
+      :linenos:
+
+      <include package="some.package" filename="other.zcml" />
+
+Alternatives
+~~~~~~~~~~~~
+
+None.
+
+See Also
+~~~~~~~~
+
+See also :ref:`helloworld_declarative`.
+
+.. _view_directive:
+
+``view``
+--------
+
+A ``view`` declaration directs :mod:`repoze.bfg` to create a single
+:term:`view configuration` registration in the current
+:term:`application registry`.
+
+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.
+
+Attributes
+~~~~~~~~~~
+
+Non-Predicate Attributes
+########################
+
+``view``
+
+  The :term:`dotted Python name` to a :term:`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 :term:`dotted Python 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 :term:`dotted Python name` 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 :term:`dotted Python name` 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; a :term:`dotted Python name` to each callable separated by a
+  space).  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.
+
+Examples
+~~~~~~~~
+
+.. topic:: Registering A Default View for a Class
+
+  .. code-block:: xml
+     :linenos:
+
+        <view
+           for=".models.MyModel"
+           view=".views.hello_world"
+         />
+
+.. topic:: Registering A View With a Predicate
+
+  .. code-block:: xml
+     :linenos:
+
+        <view
+           for=".models.MyModel"
+           view=".views.hello_world_post"
+           request_method="POST"
+         />
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also add a :term:`view configuration` via:
+
+- Using the :class:`repoze.bfg.view.bfg_view` class as a decorator.
+
+- Using the :meth:`repoze.bfg.configuration.Configurator.add_view` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`views_chapter`.
+
+.. _route_directive:
+
+``route``
+---------
+
+The ``route`` directive adds a single :term:`route configuration` to
+the :term:`application registry`.
+
+Attributes
+~~~~~~~~~~
+
+``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 :term:`dotted Python 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 :term:`dotted Python 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.
+
+``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 :term:`dotted Python 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 :term:`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 :term:`dotted Python name` 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``
+
+  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.
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also add a :term:`route configuration` via:
+
+- Using the :meth:`repoze.bfg.configuration.Configurator.add_route` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`urldispatch_chapter`.
+
+.. _subscriber_directive:
+
+``subscriber``
+--------------
+
+The ``subscriber`` ZCML directive configures an :term:`subscriber`
+callable to listen for events broadcast by the :mod:`repoze.bfg` web
+framework.
+
+Attributes
+~~~~~~~~~~
+
+``for``
+
+   The class or :term:`interface` that you are subscribing the
+   listener for, e.g. :class:`repoze.bfg.interfaces.INewRequest`.
+   Registering a subscriber for a specific class or interface limits
+   the event types that the subscriber will receive to those specified
+   by the interface or class.  Default: ``zope.interface.Interface``
+   (implying *any* event type).
+
+``handler``
+
+   A :term:`dotted Python name` which references an event handler
+   callable.  The callable should accept a single argument: ``event``.
+   The return value of the callable is ignored.
+
+Examples
+~~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <subscriber
+      for="repoze.bfg.interfaces.INewRequest"
+      handler=".subscribers.handle_new_request"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also register an event listener by using the
+:meth:`repoze.bfg.configuration.Configurator.add_subscriber` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`events_chapter`.
+
+.. _notfound_directive:
+
+``notfound``
+------------
+
+When :mod:`repoze.bfg` can't map a URL to view code, it invokes a
+:term:`not found view`.  The default not found view is very plain, but
+the view callable used can be configured via the ``notfound`` ZCML
+tag.
+
+Attributes
+~~~~~~~~~~
+
+``view``
+
+  The :term:`dotted Python name` to a :term:`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`).
+
+``attr``
+
+  The attribute of the view callable to use if ``__call__`` is not
+  correct (has the same meaning as in the context of
+  :ref:`view_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:`view_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:`view_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.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <notfound 
+       view="helloworld.views.notfound_view"/>
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.set_notfound_view`
+method performs the same job as the ``notfound`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`changing_the_notfound_view`.
+
+.. _forbidden_directive:
+
+``forbidden``
+-------------
+
+When :mod:`repoze.bfg` can't authorize execution of a view based on
+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 the
+``forbidden`` ZCML directive.
+
+Attributes
+~~~~~~~~~~
+
+``view``
+
+  The :term:`dotted Python name` to a :term:`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`).
+
+``attr``
+
+  The attribute of the view callable to use if ``__call__`` is not
+  correct (has the same meaning as in the context of
+  :ref:`view_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:`view_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:`view_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.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <forbidden
+       view="helloworld.views.forbidden_view"/>
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.set_forbidden_view`
+method performs the same job as the ``forbidden`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`changing_the_forbidden_view`.
+
+.. _scan_directive:
+
+``scan``
+--------
+
+To make use of :term:`configuration decoration` decorators, you must
+perform a :term:`scan`.  A scan finds these decorators in code.  The
+``scan`` ZCML directive tells :mod:`repoze.bfg` to begin such a scan.
+
+Attributes
+~~~~~~~~~~
+
+``package``
+
+    The package to scan or the single dot (``.``), meaning the
+    "current" package (the package in which the ZCML file lives).
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+    
+   <scan package="."/>
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.scan` method performs
+the same job as the ``scan`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`mapping_views_to_urls_using_a_decorator_section`.
+
+.. _resource_directive:
+
+``resource``
+------------
+
+The ``resource`` directive adds a resource override for a single
+resource.
+
+Attributes
+~~~~~~~~~~
+
+``to_override``
+
+   A :term:`resource specification` specifying the resource to be
+   overridden.
+
+``override_with``
+
+   A :term:`resource specification` specifying the resource which
+   is used as the override.
+
+Examples
+~~~~~~~~
+
+.. topic:: Overriding a Single Resource File
+
+  .. code-block:: xml
+     :linenos:
+
+     <resource
+       to_override="some.package:templates/mytemplate.pt"
+       override_with="another.package:othertemplates/anothertemplate.pt"
+     />
+
+.. topic:: Overriding all Resources in a Package
+
+  .. code-block:: xml
+     :linenos:
+
+     <resource
+       to_override="some.package"
+       override_with="another.package"
+      />
+
+.. topic:: Overriding all Resources in a Subdirectory of a Package
+
+  .. code-block:: xml
+     :linenos:
+
+     <resource
+       to_override="some.package:templates/"
+       override_with="another.package:othertemplates/"
+      />
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.override_resource`
+method can be used instead of the ``resource`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`resource_zcml_directive`.
+
+.. _static_directive:
+
+``static``
+----------
+
+Use of the ``static`` ZCML directive or allows you to serve static
+resources (such as JavaScript and CSS files) within a
+:mod:`repoze.bfg` application. Theis mechanism makes static files
+available at a name relative to the application root URL.
+
+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).  Optional.
+
+Examples
+~~~~~~~~
+
+.. topic:: Serving Static Files from an Absolute Path
+
+   .. code-block:: xml
+      :linenos:
+
+      <static
+         name="static"
+         path="/var/www/static"
+         />
+
+.. topic:: Serving Static Files from a Package-Relative Path
+
+   .. code-block:: xml
+      :linenos:
+
+      <static
+         name="static"
+         path="some_package:a/b/c/static"
+         />
+
+.. topic:: Serving Static Files from a Current-Package-Relative Path
+
+   .. code-block:: xml
+      :linenos:
+
+      <static
+         name="static"
+         path="static_files"
+         />
+
+Alternatives
+~~~~~~~~~~~~
+
+:meth:`repoze.bfg.configuration.configurator.add_static_view` can also
+be used to add a static view.
+
+See Also
+~~~~~~~~
+
+See also :ref:`static_resources_section` and
+:ref:`generating_static_resource_urls`.
+
+.. _renderer_directive:
+
+``renderer``
+------------
+
+The ``renderer`` ZCML directive can be used to override an existing
+existing :term:`renderer` or to add a new renderer.
+
+Attributes
+~~~~~~~~~~
+
+``factory``
+
+    A :term:`dotted Python name` referencing a callable object that
+    accepts a renderer name and returns a :term:`renderer` object.
+
+``name``
+
+   The renderer name, which is a string.
+
+Examples
+~~~~~~~~
+
+.. topic:: Registering a Non-Template Renderer
+
+   .. code-block:: xml
+      :linenos:
+
+      <renderer
+         factory="some.renderer"
+         name="mynewrenderer"
+         />
+
+.. topic:: Registering a Template Renderer
+
+   .. code-block:: xml
+      :linenos:
+
+      <renderer
+         factory="some.jinja2.renderer"
+         name=".jinja2"
+         />
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.add_renderer` method
+is equivalent to the ``renderer`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`adding_and_overriding_renderers`.
+
+.. _authtktauthenticationpolicy_directive:
+
+``authtktauthenticationpolicy``
+-------------------------------
+
+When this directive is used, authentication information is obtained
+from an :mod:`paste.auth.auth_tkt` cookie value, assumed to be set by
+a custom login form.
+
+Attributes
+~~~~~~~~~~
+
+``secret``
+
+    The ``secret`` is a string that will be used to encrypt the data
+    stored by the cookie.  It is required and has no default.
+
+``callback``
+
+    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``.
+
+``cookie_name``
+
+    The ``cookie_name`` is the name used for the cookie that contains
+    the user information.  It defaults to ``repoze.bfg.auth_tkt``.
+
+``secure``
+
+    ``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``
+
+    ``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``
+
+    ``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``
+
+    ``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``
+
+    ``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.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <authtktauthenticationpolicy
+    secret="goshiamsosecret"
+    callback=".somemodule.somefunc"
+    cookie_name="mycookiename"
+    secure="false"
+    include_ip="false"
+    timeout="86400"
+    reissue_time="600"
+    max_age="31536000"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy` and
+pass it to the :class:`repoze.bfg.configuration.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy`.
+
+.. _remoteuserauthenticationpolicy_directive:
+
+``remoteuserauthenticationpolicy``
+----------------------------------
+
+When this directive is used, authentication information is obtained
+from a ``REMOTE_USER`` key in the WSGI environment, assumed to
+be set by a WSGI server or an upstream middleware component.
+
+Attributes
+~~~~~~~~~~
+
+``environ_key``
+
+    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``.
+
+``callback``
+
+    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``.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <remoteuserauthenticationpolicy
+    environ_key="REMOTE_USER"
+    callback=".somemodule.somefunc"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy` and
+pass it to the :class:`repoze.bfg.configuration.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy`.
+
+.. _repozewho1authenticationpolicy_directive:
+
+``repozewho1authenticationpolicy``
+----------------------------------
+
+When this directive is used, authentication information is obtained
+from a ``repoze.who.identity`` key in the WSGI environment, assumed to
+be set by :term:`repoze.who` middleware.
+
+Attributes
+~~~~~~~~~~
+
+``identifier_name``
+
+    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``.
+
+``callback``
+
+    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``.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <repozewho1authenticationpolicy
+    identifier_name="auth_tkt"
+    callback=".somemodule.somefunc"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`repoze.bfg.authentication.RepozeWho1AuthenticationPolicy` and
+pass it to the :class:`repoze.bfg.configuration.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`repoze.bfg.authentication.RepozeWho1AuthenticationPolicy`.
+
+.. _aclauthorizationpolicy_directive:
+
+``aclauthorizationpolicy``
+--------------------------
+
+When this directive is used, authorization information is obtained
+from :term:`ACL` objects attached to model instances.
+
+Attributes
+~~~~~~~~~~
+
+None.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <aclauthorizationpolicy/>
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`repoze.bfg.authorization.ACLAuthorizationPolicy` and pass it
+to the :class:`repoze.bfg.configuration.Configurator` constructor as
+the ``authorization_policy`` argument during initial application
+configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authorization_policies_directives_section` and
+:ref:`security_chapter`.
+
+.. _adapter_directive:
+
+``adapter``
+-----------
+
+Register a :term:`Zope Component Architecture` "adapter".
+
+Attributes
+~~~~~~~~~~
+
+``factory``
+
+  The adapter factory (often a class).
+
+``provides``
+
+  The :term:`interface` that an adapter instance resulting from a
+  lookup will provide.
+
+``for``
+
+  Interfaces or classes to be adapted, separated by spaces,
+  e.g. ``interfaces.IFoo interfaces.IBar``.
+
+``name``
+
+  The adapter name.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <adapter
+     for=".foo.IFoo .bar.IBar"
+     provides=".interfaces.IMyAdapter"
+     factory=".adapters.MyAdapter"
+     />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the ``registerAdapter`` method of the ``registry`` attribute of a
+:term:`Configurator` instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+None.
+
+.. _utility_directive:
+
+``utility``
+-----------
+
+Register a :term:`Zope Component Architecture` "utility".
+
+Attributes
+~~~~~~~~~~
+
+``component``
+
+  The utility component (cannot be specified if ``factory`` is
+  specified).
+
+``factory``
+
+  A factory that creates a component (cannot be specified if
+  ``component`` is specified).
+
+``provides``
+
+  The :term:`interface` that an utility instance resulting from a
+  lookup will provide.
+
+``name``
+
+  The utility name.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <utility
+     provides=".interfaces.IMyUtility"
+     component=".utilities.MyUtility"
+     />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the ``registerUtility`` method of the ``registry`` attribute of a
+:term:`Configurator` instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+None.
+
+