More pass overhaul based on making contextfinding explicit within documentation.

1 files changed, 58 insertions, 46 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 604eb6814..8a7b86f2d 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -11,9 +11,11 @@ augment or replace :term:`traversal` as a :term:`context finding`
 mechanism, allowing URL pattern matching to have the "first crack" at
 resolving a given URL to :term:`context` and :term:`view name`.
 
-Using URL dispatch exclusively allows you to avoid thinking about your
-application in terms of "contexts" and "view names" entirely.  Many
-applications don't need :mod:`repoze.bfg` features -- such as
+Although it is a "context-finding" mechanism, ironically, using URL
+dispatch exclusively allows you to avoid thinking about your
+application in terms of "contexts" and "view names" entirely.
+
+Many applications don't need :mod:`repoze.bfg` features -- such as
 declarative security via an :term:`authorization policy` -- that
 benefit from having any visible separation between :term:`context
 finding` and :term:`view lookup`.  To this end, URL dispatch provides
@@ -51,7 +53,7 @@ provided to :mod:`repoze.bfg`, a route-specific :term:`context` and
 :term:`view name` will be generated.  In this circumstance,
 :mod:`repoze.bfg` will shortcut :term:`traversal`, and will invoke
 :term:`view lookup` using the context and view name generated by URL
-dispatch.  If the route named a :term:`view callable` in its
+dispatch.  If the matched route names a :term:`view callable` in its
 configuration, that view callable will be invoked when view lookup is
 performed.
 
@@ -97,8 +99,11 @@ registry`.  Here's an example:
 Configuring a Route via ZCML
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of using the imperative method of adding a route, you can use
-:term:`ZCML` for the same purpose.  For example:
+Instead of using the imperative
+:meth:`repoze.bfg.configuration.Configurator.add_route` method to add
+a new route, you can alternately use :term:`ZCML`.  For example, the
+following :term:`ZCML declaration` causes a route to be added to the
+application.
 
 .. code-block:: xml
    :linenos:
@@ -153,7 +158,7 @@ invoked when the associated route path pattern matches during a
 request.  
 
 The purpose of making it possible to specify a view callable within a
-route configuration is to avoid the need for developers to deeply
+route configuration is to prevent developers from needing to deeply
 understand the details of :term:`context finding` and :term:`view
 lookup`.  When a route names a view callable, and a request enters the
 system which matches the path of the route, the result is simple: the
@@ -190,12 +195,13 @@ matched during a request.  To do so:
   callable registered using that interface by the route configuration
   to service requests that match the route path pattern.
 
-In this way, we supply a system that still consumes the :term:`context
-finding` and :term:`view lookup` services provided by
-:mod:`repoze.bfg`, but which does not require that a developer
-understand either of them if he doesn't want to.  It also means that
-we can allow a developer to combine :term:`URL dispatch` and
-:term:`traversal` in exceptional cases (see :ref:`hybrid_chapter`).
+In this way, we supply a shortcut to the developer.  Under the hood,
+:mod:`repoze.bfg` still consumes the :term:`context finding` and
+:term:`view lookup` subsystems provided by :mod:`repoze.bfg`, but in a
+way which does not require that a developer understand either of them
+if he doesn't want or need to.  It also means that we can allow a
+developer to combine :term:`URL dispatch` and :term:`traversal` in
+various exceptional cases as documented in :ref:`hybrid_chapter`.
 
 .. index::
    pair: URL dispatch; path pattern syntax
@@ -280,15 +286,15 @@ not need to be preceded by a slash.  For example:
 
 .. code-block:: text
 
-   foo/:baz/:bar*traverse
+   foo/:baz/:bar*fizzle
 
 The above pattern will match these URLs, generating the following
 matchdicts:
 
 .. code-block:: text
 
-   foo/1/2/           -> {'baz':1, 'bar':2, 'traverse':()}
-   foo/abc/def/a/b/c  -> {'baz':abc, 'bar':def, 'traverse':('a', 'b', 'c')}
+   foo/1/2/           -> {'baz':1, 'bar':2, 'fizzle':()}
+   foo/abc/def/a/b/c  -> {'baz':abc, 'bar':def, 'fizzle':('a', 'b', 'c')}
 
 Note that when a ``*stararg`` remainder match is matched, the value
 put into the matchdict is turned into a tuple of path segments
@@ -298,7 +304,7 @@ the following pattern:
 
 .. code-block:: text
 
-   foo/*traverse
+   foo/*fizzle
 
 When matching the following path:
 
@@ -310,7 +316,7 @@ Will generate the following matchdict:
 
 .. code-block:: text
 
-   {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
+   {'fizzle':(u'La Pe\xf1a', u'a', u'b', u'c')}
 
 .. index::
    triple: ZCML directive; route; examples
@@ -328,12 +334,12 @@ declaration ordering is very important.
 
 The order that routes declarations are evaluated is the order in which
 they are added to the application at startup time.  This is unlike
-:term:`traversal`, which depends on the emergent behavior which
-happens as a result of traversing a graph.
+:term:`traversal`, which depends on emergent behavior which happens as
+a result of traversing a graph.
 
-For routes configured via ZCML, the order that routes are evaluated is
-the order in which they appear in the ZCML relative to each other.
-For routes added via the
+The order that route are evaluated when they are defined via
+:term:`ZCML` is the order in which they appear in the ZCML relative to
+each other.  For routes added via the
 :mod:`repoze.bfg.configuration.Configurator.add_route` method, the
 order that routes are evaluated is the order in which they are added
 to the configuration imperatively.
@@ -344,12 +350,13 @@ to the configuration imperatively.
 Route Factories
 ~~~~~~~~~~~~~~~
 
-A "route" configuration declaration can mention a "factory".  When a
-factory is attached to a route, the :term:`root factory` passed at
-startup time to the :term:`Configurator` is ignored; instead the
-factory associated with the route is used to generate a :term:`root`
-object.  This object will usually be used as the :term:`context` of
-the view callable ultimately found via :term:`view lookup`.
+A "route" configuration declaration can mention a "factory".  When
+that route matches a request, and a factory is attached to a route,
+the :term:`root factory` passed at startup time to the
+:term:`Configurator` is ignored; instead the factory associated with
+the route is used to generate a :term:`root` object.  This object will
+usually be used as the :term:`context` of the view callable ultimately
+found via :term:`view lookup`.
 
 .. code-block:: xml
 
@@ -367,10 +374,10 @@ related to each particular route.
 Supplying a different context for each route is useful when you're
 trying to use a :mod:`repoze.bfg` :term:`authorization policy` to
 provide declarative "context-sensitive" security checks; each context
-can maintain a separate :term:`ACL` (as in
-:ref:`using_security_with_urldispatch`).  It is also useful when you
-wish to combine URL dispatch with :term:`traversal` (as in
-:ref:`hybrid_chapter`).
+can maintain a separate :term:`ACL`, as in
+:ref:`using_security_with_urldispatch`.  It is also useful when you
+wish to combine URL dispatch with :term:`traversal` as documented
+within :ref:`hybrid_chapter`.
 
 Route Matching
 --------------
@@ -391,7 +398,7 @@ name` are generated, and the context, the view name, and the resulting
 request are handed off to :term:`view lookup`.  This process is
 otherwise known as :term:`context finding`.  During view lookup, if
 any ``view`` argument was provided within the matched route
-configuration, this view is called.
+configuration, the :term:`view callable` it points to is called.
 
 If no route matches after all route patterns are exhausted,
 :mod:`repoze.bfg` falls back to :term:`traversal` to do :term:`context
@@ -609,9 +616,9 @@ completely equivalent to this example provided in
     view="mypackage.views.site_view"
     />
 
-In fact the spelling in :ref:`urldispatch_example1` is just syntactic
-sugar for the more verbose spelling where the route declaration and
-the view declaration are spelled separately.
+In fact, the spelling which names a ``view`` attribute is just
+syntactic sugar for the more verbose spelling which contains separate
+view and route registrations.
 
 More uses for this style of associating views with routes are explored
 in :ref:`hybrid_chapter`.
@@ -780,6 +787,12 @@ Then in the ``configure.zcml`` of your package, inject the following:
 This will cause the DBSession to be removed whenever the WSGI
 environment is destroyed (usually at the end of every request).
 
+Alternate mechanisms for performing this sort of cleanup exist; an
+alternate mechanism which uses cleanup services offered by the
+``repoze.tm2`` package is used in the SQLAlchemy-related ``paster``
+templates generated by :mod:`repoze.bfg` and within
+:ref:`sql_tm2_cleanup` within the :ref:`bfg_sql_wiki_tutorial`.
+
 .. index::
    pair: URL dispatch; security
 
@@ -821,8 +834,8 @@ not very ambitious.
 .. note:: See :ref:`security_chapter` for more information about
    :mod:`repoze.bfg` security and ACLs.
 
-Context-and-Request View Callables
-----------------------------------
+Using Context Within a View Callable
+------------------------------------
 
 When using :term:`url dispatch` exclusively in an application (as
 opposed to using both url dispatch *and* :term:`traversal` in the same
@@ -832,9 +845,12 @@ your route definitions.
 
 However, if you do use a ``factory`` attribute on your route
 definitions, you may be very interested in the :term:`context` of the
-view.  :mod:`repoze.bfg` supports view callables defined with two
-arguments: ``context`` and ``request``.  For example, the below view
-statement is completely equivalent to the above view statement:
+view.  You can access the ``context`` of a view within the body of a
+view callable via ``request.context``
+
+:mod:`repoze.bfg` also supports view callables defined with two
+arguments: ``context`` and ``request``.  For example, the below
+function can be used as a view callable.
 
 .. code-block:: python
    :linenos:
@@ -848,10 +864,6 @@ The ``context`` passed to this view will be an instance returned by
 the default root factory or an instance returned by the ``factory``
 argument to your route definition.
 
-Even if you use the request-only argument format in view callables,
-you can still get to the ``context`` of the view (if necessary) by
-accessing ``request.context``.
-
 See :ref:`request_and_context_view_definitions` for more information.
 
 References