Using a single chapter for the API docs and a single chapter for the ZCML directives made it hard to read.

21 files changed, 1538 insertions, 1541 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 2bd5fca01..70ec4c4f5 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -5,27 +5,3 @@ Comprehensive reference material for every public API exposed by
 :mod:`repoze.bfg` is available within this chapter.  The API
 documentation is organized alphabetically by module name.
 
-.. toctree::
-   :maxdepth: 1
-
-   api/authorization
-   api/authentication
-   api/chameleon_text
-   api/chameleon_zpt
-   api/configuration
-   api/events
-   api/exceptions
-   api/interfaces
-   api/location
-   api/paster
-   api/router
-   api/scripting
-   api/security
-   api/settings
-   api/testing
-   api/threadlocal
-   api/traversal
-   api/url
-   api/view
-   api/wsgi
-
diff --git a/docs/authorintro.rst b/docs/authorintro.rst
index 4355fc125..c4b19338f 100644
--- a/docs/authorintro.rst
+++ b/docs/authorintro.rst
@@ -52,7 +52,7 @@ Book Content
 ============
 
 This book is divided into three major parts: a narrative documentation
-part, a tutorial part, and an API documentation part.
+part, a tutorial part, and a reference part.
 
 Narrative Documentation
 
@@ -66,14 +66,16 @@ Narrative Documentation
 
 Tutorials
 
-  Each tutorial builds a sample application or implements a concept
-  and describes the concept in terms of the example.  You should read
-  the tutorials if you want a guided tour of :mod:`repoze.bfg`.
+  Each tutorial builds a sample application or implements a set of
+  concepts with a sample; it then describes the application or
+  concepts in terms of the sample.  You should read the tutorials if
+  you want a guided tour of :mod:`repoze.bfg`.
 
 Reference
 
-  The API documentation is reference material related to the
-  :mod:`repoze.bfg` API.  Use it while you're developing a
+  Two parts form the reference section: the API documentation and
+  :term:`ZCML` directive documentation.  These parts provide
+  convenient reference material related to developing a
   :mod:`repoze.bfg` application.
 
 .. index::
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 4000ea077..d1105faa8 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -23,7 +23,7 @@ Narrative Documentation
 @@@@@@@@@@@@@@@@@@@@@@@
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    narr/introduction
    narr/install
@@ -52,7 +52,7 @@ Tutorials
 @@@@@@@@@
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    tutorials/bfgwiki/index.rst
    tutorials/bfgwiki2/index.rst
@@ -62,14 +62,57 @@ Tutorials
    tutorials/zodbsessions/index.rst
    tutorials/catalog/index.rst
 
-Reference material
-@@@@@@@@@@@@@@@@@@
+API Documentation
+@@@@@@@@@@@@@@@@@
+
+.. toctree::
+   :maxdepth: 1
+
+   api/authorization
+   api/authentication
+   api/chameleon_text
+   api/chameleon_zpt
+   api/configuration
+   api/events
+   api/exceptions
+   api/interfaces
+   api/location
+   api/paster
+   api/router
+   api/scripting
+   api/security
+   api/settings
+   api/testing
+   api/threadlocal
+   api/traversal
+   api/url
+   api/view
+   api/wsgi
+
+
+ZCML Directives
+@@@@@@@@@@@@@@@@
 
 .. toctree::
    :maxdepth: 1
 
-   api
-   zcml
+   zcml/aclauthorizationpolicy
+   zcml/adapter
+   zcml/authtktauthenticationpolicy
+   zcml/configure
+   zcml/forbidden
+   zcml/include
+   zcml/notfound
+   zcml/remoteuserauthenticationpolicy
+   zcml/renderer
+   zcml/repozewho1authenticatiohnpolicy
+   zcml/resource
+   zcml/route
+   zcml/scan
+   zcml/static
+   zcml/subscriber
+   zcml/utility
+   zcml/view
 
 .. backmatter::
 
diff --git a/docs/zcml.rst b/docs/zcml.rst
deleted file mode 100644
index 995b1bed9..000000000
--- a/docs/zcml.rst
+++ /dev/null
@@ -1,1505 +0,0 @@
-.. _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
-in this chapter.
-
-.. _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://namespaces.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` 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`.  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.
-
-``context``
-
-  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.  An
-  alternate name for this attribute is ``for`` (this is an older
-  spelling).
-
-``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
-           context=".models.MyModel"
-           view=".views.hello_world"
-         />
-
-.. topic:: Registering A View With a Predicate
-
-  .. code-block:: xml
-     :linenos:
-
-        <view
-           context=".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_context``
-
-  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 ``view_for`` or ``for_``;
-  these are valid older spellings.
-
-``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_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. This 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.
-
-
diff --git a/docs/zcml/aclauthorizationpolicy.rst b/docs/zcml/aclauthorizationpolicy.rst
new file mode 100644
index 000000000..f4df1dce1
--- /dev/null
+++ b/docs/zcml/aclauthorizationpolicy.rst
@@ -0,0 +1,35 @@
+.. _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`.
diff --git a/docs/zcml/adapter.rst b/docs/zcml/adapter.rst
new file mode 100644
index 000000000..48ed49f6c
--- /dev/null
+++ b/docs/zcml/adapter.rst
@@ -0,0 +1,51 @@
+.. _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.
+
diff --git a/docs/zcml/authtktauthenticationpolicy.rst b/docs/zcml/authtktauthenticationpolicy.rst
new file mode 100644
index 000000000..de1bcdcd6
--- /dev/null
+++ b/docs/zcml/authtktauthenticationpolicy.rst
@@ -0,0 +1,110 @@
+.. _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`.
diff --git a/docs/zcml/configure.rst b/docs/zcml/configure.rst
new file mode 100644
index 000000000..20c0ed76a
--- /dev/null
+++ b/docs/zcml/configure.rst
@@ -0,0 +1,96 @@
+.. _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://namespaces.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`.
+
diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst
new file mode 100644
index 000000000..7540c28cb
--- /dev/null
+++ b/docs/zcml/forbidden.rst
@@ -0,0 +1,76 @@
+.. _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`.
diff --git a/docs/zcml/include.rst b/docs/zcml/include.rst
new file mode 100644
index 000000000..5e22f584a
--- /dev/null
+++ b/docs/zcml/include.rst
@@ -0,0 +1,73 @@
+.. _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`.
+
diff --git a/docs/zcml/notfound.rst b/docs/zcml/notfound.rst
new file mode 100644
index 000000000..76846d770
--- /dev/null
+++ b/docs/zcml/notfound.rst
@@ -0,0 +1,76 @@
+.. _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`.
+
diff --git a/docs/zcml/remoteuserauthenticationpolicy.rst b/docs/zcml/remoteuserauthenticationpolicy.rst
new file mode 100644
index 000000000..61f519e4c
--- /dev/null
+++ b/docs/zcml/remoteuserauthenticationpolicy.rst
@@ -0,0 +1,53 @@
+.. _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`.
diff --git a/docs/zcml/renderer.rst b/docs/zcml/renderer.rst
new file mode 100644
index 000000000..1a3942ede
--- /dev/null
+++ b/docs/zcml/renderer.rst
@@ -0,0 +1,53 @@
+.. _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`.
diff --git a/docs/zcml/repozewho1authenticatiohnpolicy.rst b/docs/zcml/repozewho1authenticatiohnpolicy.rst
new file mode 100644
index 000000000..a41ae08e0
--- /dev/null
+++ b/docs/zcml/repozewho1authenticatiohnpolicy.rst
@@ -0,0 +1,55 @@
+.. _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`.
diff --git a/docs/zcml/resource.rst b/docs/zcml/resource.rst
new file mode 100644
index 000000000..45aa1ce53
--- /dev/null
+++ b/docs/zcml/resource.rst
@@ -0,0 +1,64 @@
+.. _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`.
diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst
new file mode 100644
index 000000000..d3181bdf6
--- /dev/null
+++ b/docs/zcml/route.rst
@@ -0,0 +1,233 @@
+.. _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_context``
+
+  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 ``view_for`` or ``for_``;
+  these are valid older spellings.
+
+``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`.
diff --git a/docs/zcml/scan.rst b/docs/zcml/scan.rst
new file mode 100644
index 000000000..d48cf66b4
--- /dev/null
+++ b/docs/zcml/scan.rst
@@ -0,0 +1,35 @@
+.. _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_using_a_decorator_section`.
diff --git a/docs/zcml/static.rst b/docs/zcml/static.rst
new file mode 100644
index 000000000..23cd57538
--- /dev/null
+++ b/docs/zcml/static.rst
@@ -0,0 +1,78 @@
+.. _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. This 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`.
diff --git a/docs/zcml/subscriber.rst b/docs/zcml/subscriber.rst
new file mode 100644
index 000000000..ef56d2b1c
--- /dev/null
+++ b/docs/zcml/subscriber.rst
@@ -0,0 +1,48 @@
+.. _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`.
diff --git a/docs/zcml/utility.rst b/docs/zcml/utility.rst
new file mode 100644
index 000000000..88198eaa0
--- /dev/null
+++ b/docs/zcml/utility.rst
@@ -0,0 +1,50 @@
+.. _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.
diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst
new file mode 100644
index 000000000..ea55352a8
--- /dev/null
+++ b/docs/zcml/view.rst
@@ -0,0 +1,295 @@
+.. _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` 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`.  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.
+
+``context``
+
+  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.  An
+  alternate name for this attribute is ``for`` (this is an older
+  spelling).
+
+``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
+           context=".models.MyModel"
+           view=".views.hello_world"
+         />
+
+.. topic:: Registering A View With a Predicate
+
+  .. code-block:: xml
+     :linenos:
+
+        <view
+           context=".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`.