Final review layout.

3 files changed, 6 insertions, 78 deletions

diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 9bbe0d70a..158cb2a56 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -636,14 +636,14 @@ completely equivalent:
 We've now configured a :mod:`repoze.bfg` helloworld application
 declaratively.  More information about this mode of configuration is
 available in :ref:`declarative_configuration` and within
-:ref:`zcml_directives`.
+:ref:`zcml_reference`.
 
 References
 ----------
 
 For more information about the API of a :term:`Configurator` object,
 see :class:`repoze.bfg.configuration.Configurator` .  The equivalent
-ZCML declaration tags are introduced in :ref:`zcml_directives`.
+ZCML declaration tags are introduced in :ref:`zcml_reference`.
 
 For more information about :term:`view configuration`, see
 :ref:`views_chapter`.
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 84a02f114..25149f30f 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -171,7 +171,7 @@ we'll explain how it *does* work in the following section.  You can
 skip it if you're uninterested.
 
 Route View Callable Registration and Lookup Details
-+++++++++++++++++++++++++++++++++++++++++++++++++++
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 When a ``view`` attribute is attached to a route configuration,
 :mod:`repoze.bfg` ensures that a :term:`view configuration` is
@@ -409,35 +409,29 @@ Other arguments are ``name`` and ``factory``.  These are required
 arguments but represent neither a predicate nor view configuration
 information.
 
-Non-Predicate Arguments
-+++++++++++++++++++++++
+**Non-Predicate Arguments**
 
 ``name``
-
   The name of the route, e.g. ``myroute``.  This attribute is
   required.  It must be unique among all defined routes in a given
   application.
 
 ``factory``
-
   A reference to a Python object (often a function or a class) that
   will generate a :mod:`repoze.bfg` :term:`context` object when this
   route matches. For example, ``mypackage.models.MyFactoryClass``.  If
   this argument is not specified, the traversal root factory will be
   used.
 
-Predicate Arguments
-+++++++++++++++++++
+**Predicate Arguments**
 
 ``path``
-
   The path of the route e.g. ``ideas/:idea``.  This argument is
   required.  See :ref:`route_path_pattern_syntax` for information
   about the syntax of route paths.  If the path doesn't match the
   current URL, route matching continues.
 
 ``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
@@ -446,21 +440,18 @@ Predicate Arguments
   predicate returns ``False``, route matching continues.
 
 ``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.
 
 ``path_info``
-
   This value represents a regular expression pattern that will be
   tested against the ``PATH_INFO`` WSGI environment variable.  If the
   regex matches, this predicate will return ``True``.  If this
   predicate returns ``False``, route matching continues.
 
 ``request_param``
-
   This value can be any string.  A view declaration with this argument
   ensures that the associated route will only match when the request
   has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
@@ -473,7 +464,6 @@ Predicate Arguments
   route matching continues.
 
 ``header``
-
   This argument represents an HTTP header name or a header name/value
   pair.  If the argument contains a ``:`` (colon), it will be
   considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` or
@@ -492,7 +482,6 @@ Predicate Arguments
   continues.
 
 ``accept``
-
   This value 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
@@ -503,7 +492,6 @@ Predicate Arguments
   ``False``, route matching continues.
 
 ``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
@@ -516,16 +504,13 @@ Predicate Arguments
   matching continues.  Note that the value ``context`` will always be
   ``None`` when passed to a custom route predicate.
 
-View-Related Arguments
-++++++++++++++++++++++
+**View-Related Arguments**
 
 ``view``
-
   A reference to a Python object that will be used as a view callable
   when this route matches. e.g. ``mypackage.views.my_view``.
   
 ``view_context``
-
   A reference to a class or an :term:`interface` that the
   :term:`context` of the view should match for the view named by the
   route to be used.  This argument is only useful if the ``view``
@@ -538,7 +523,6 @@ View-Related Arguments
   This attribute can also be spelled as ``for_`` or ``view_for``.
 
 ``view_permission``
-
   The permission name required to invoke the view associated with this
   route.  e.g. ``edit``. (see :ref:`using_security_with_urldispatch`
   for more information about permissions).
@@ -549,7 +533,6 @@ View-Related Arguments
   This argument 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
@@ -570,7 +553,6 @@ View-Related Arguments
   This argument can also be spelled as ``renderer``.
 
 ``view_request_type``
-
   A reference to an :term:`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.
@@ -581,7 +563,6 @@ View-Related Arguments
   This argument can also be spelled as ``request_type``.
 
 ``view_containment``
-
   This value should be a reference to a Python class or
   :term:`interface` that a parent object in the :term:`lineage` must
   provide in order for the view related to this route to be found and
@@ -593,7 +574,6 @@ View-Related Arguments
   effect.
 
 ``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
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 9af12dd4e..28b8b4290 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -531,27 +531,22 @@ values on the ``request`` object via ``setattr`` within the view
 callable to influence associated response attributes.
 
 ``response_content_type``
-
   Defines the content-type of the resulting response,
   e.g. ``text/xml``.
 
 ``response_headerlist``
-
   A sequence of tuples describing cookie values that should be set in
   the response, e.g. ``[('Set-Cookie', 'abc=123'), ('X-My-Header',
   'foo')]``.
 
 ``response_status``
-
   A WSGI-style status code (e.g. ``200 OK``) describing the status of
   the response.
 
 ``response_charset``
-
   The character set (e.g. ``UTF-8``) of the response.
 
 ``response_cache_for``
-
   A value in seconds which will influence ``Cache-Control`` and
   ``Expires`` headers in the returned response.  The same can also be
   achieved by returning various values in the ``response_headerlist``,
@@ -969,8 +964,6 @@ rendered in a request that has a ``;charset=utf-8`` stanza on its
    to Unicode objects implicitly in :mod:`repoze.bfg`'s default
    configuration.  The keys are still strings.
 
-
-
 .. index::
    single: view configuration
    pair: view; configuration
@@ -1042,7 +1035,6 @@ Non-Predicate Arguments
 +++++++++++++++++++++++
 
 ``permission``
-
   The name of a :term:`permission` that the user must possess in order
   to invoke the :term:`view callable`.  See
   :ref:`view_security_section` for more information about view
@@ -1052,7 +1044,6 @@ Non-Predicate Arguments
   this view (it's accessible by any caller).
 
 ``attr``
-
   The view machinery defaults to using the ``__call__`` method of the
   :term:`view callable` (or the function itself, if the view callable
   is a function) to obtain a response.  The ``attr`` value allows you
@@ -1068,7 +1059,6 @@ Non-Predicate Arguments
   attribute if the view is a class).
 
 ``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``) naming a :term:`renderer`
@@ -1101,7 +1091,6 @@ Non-Predicate Arguments
   implementation is never called.
 
 ``wrapper``
-
   The :term:`view name` of a different :term:`view configuration`
   which will receive the response body of this view as the
   ``request.wrapped_body`` attribute of its own :term:`request`, and
@@ -1123,7 +1112,6 @@ Predicate Arguments
 +++++++++++++++++++
 
 ``name``
-
   The :term:`view name` required to match this view callable.  Read
   :ref:`traversal_chapter` to understand the concept of a view name.
 
@@ -1131,7 +1119,6 @@ Predicate Arguments
   default view).
 
 ``context``
-
   An object representing 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
@@ -1143,7 +1130,6 @@ Predicate Arguments
   any model, is used.
 
 ``route_name``
-
   If ``route_name`` is supplied, the view callable will be invoked
   only when the named route has matched.
 
@@ -1160,7 +1146,6 @@ Predicate Arguments
   request object that does not indicate it matched a route.
 
 ``request_type``
-
   This value should be an :term:`interface` that the :term:`request`
   must provide in order for this view to be found and called.
 
@@ -1170,7 +1155,6 @@ Predicate Arguments
   *This is an advanced feature, not often used by "civilians"*.
 
 ``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 argument ensures
@@ -1183,7 +1167,6 @@ Predicate Arguments
   environment.
 
 ``request_param``
-
   This value can be any string.  A view declaration with this argument
   ensures that the view will only be called when the :term:`request`
   has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
@@ -1200,7 +1183,6 @@ Predicate Arguments
   dictionary.
 
 ``containment``
-
   This value should be a reference to a Python class or
   term:`interface` that a parent object in the :term:`lineage` must
   provide in order for this view to be found and called.  The nodes in
@@ -1214,7 +1196,6 @@ Predicate Arguments
   location-awareness.
 
 ``xhr``
-
   This value should be either ``True`` or ``False``.  If this value is
   specified and is ``True``, the :term:`WSGI` environment must possess
   an ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that
@@ -1227,7 +1208,6 @@ Predicate Arguments
   to invoke the associated view callable.
 
 ``accept``
-
   The value of this argument 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
@@ -1241,7 +1221,6 @@ Predicate Arguments
   the associated view callable.
 
 ``header``
-
   This value represents an HTTP header name or a header name/value
   pair.
 
@@ -1268,7 +1247,6 @@ Predicate Arguments
   whether or not to invoke the associated view callable.
 
 ``path_info``
-
   This value represents a regular expression pattern that will be
   tested against the ``PATH_INFO`` WSGI environment variable to decide
   whether or not to call the associated view callable.  If the regex
@@ -1279,7 +1257,6 @@ Predicate Arguments
   associated view callable.
 
 ``custom_predicates``
-
   If ``custom_predicates`` is specified, it must be a sequence of
   references to custom predicate callables.  Use custom predicates
   when no set of predefined predicates do what you need.  Custom
@@ -1839,35 +1816,6 @@ the user's browser, representing a "not found" (404) page.  See
 :ref:`changing_the_notfound_view` for more information about changing
 the default notfound view.
 
-There are a several exceptions to the the rule which says that view
-configuration attributes represent "narrowings".  Several attributes
-of the ``view`` directive are *not* narrowing predicates.  These are
-``permission``, ``name``, ``renderer``, and ``attr``.
-
-The value of the ``permission`` attribute represents the permission
-that must be possessed by the user to invoke any found view.  When a
-view is found that matches all predicates, but the invoking user does
-not possess the permission implied by any associated ``permission`` in
-the current context, processing stops, and an
-:exc:`repoze.bfg.exception.Forbidden` error is raised, usually
-resulting in the :term:`forbidden view` being shown to the invoking
-user.  No further view narrowing or view lookup is done.
-
-.. note:: 
-
-   See :ref:`changing_the_forbidden_view` for more information about
-   changing the default forbidden view.
-
-The value of the ``name`` attribute represents a direct match of the
-view name returned via traversal.  It is part of initial view lookup
-rather than a predicate/narrower.
-
-The value of the ``renderer`` attribute represents the renderer used
-to convert non-response return values from a view.
-
-The value of the ``attr`` attribute represents the attribute name
-looked up on the view object to return a response.
-
 .. index::
    pair: debugging; not found errors