Stray text.

3 files changed, 58 insertions, 70 deletions

diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 812861412..08375d599 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -10,7 +10,8 @@ graph*, starting from a :term:`root` object, using a :term:`request`
 object as a source of path information.
 
 In this chapter, we'll provide a high-level overview of traversal,
-explain the concept of an *object graph*,
+explain the concept of an *object graph*, and show how traversal might
+be used within an application.
 
 .. index::
    pair: traversal; high-level overview
@@ -62,28 +63,39 @@ The Object Graph
 When your application uses :term:`traversal` to resolve URLs to code,
 your application must supply an *object graph* to :mod:`repoze.bfg`.
 
-Users interact with your :mod:`repoze.bfg` -based application via a
-:term:`router`, which is just a fancy :term:`WSGI` application.  At
-system startup time, the router is configured with a callback known as
-a :term:`root factory`, supplied by the application developer.  The
-root factory is passed a :term:`request` object and it is expected to
-return an object which represents the root of the object graph.  All
-:term:`traversal` will begin at this root object.  The root object is
-usually a *mapping* object (such as a Python dictionary).
-
-.. note:: If a :term:`root factory` is passed to the :mod:`repoze.bfg`
-   :term:`Configurator` constructor as the value ``None``, a *default*
-   root factory is used.  This is most useful when you're using
-   :term:`URL dispatch` and you don't care very much about traversing
-   any particular graph to resolve URLs to code.  It is also possible
-   to use traversal and URL dispatch together.  When both a root
-   factory (and therefore traversal) *and* "routes" declarations (and
-   therefore url dispatch) are used, the url dispatch routes are
-   checked first, and if none match, :mod:`repoze.bfg` will fall back
-   to using traversal to attempt to map the request to a view.  If the
-   name ``*traverse`` is in a route's ``path`` pattern, when it is
-   matched, it is also possible to do traversal *after* a route has
-   been matched.  See :ref:`hybrid_chapter` for more information.
+At system startup time, the :mod:`repoze.bfg` :term:`Router` is
+configured with a callback known as a :term:`root factory`, supplied
+by the application developer as the ``root_factory`` argument to a
+:term:`Configurator`.
+
+Here's an example of a simple root factory:
+
+.. code-block:: python
+   :linenos:
+
+   class Root(dict):
+       def __init__(self, request):
+           pass
+
+Here's an example of using this root factory within startup
+configuration, by passing it to an instance of a :term:`Configurator`
+named ``config``:
+
+   config = Configurator(root_factory=Root)
+
+Making a declaration like this at startup means that your
+:mod:`repoze.bfg` application will call the root factory (in this
+case, the class ``Root``) to generate a root object whenever a request
+enters the application.  Usually a root factory for a traversal-based
+application will be more complicated than the above ``Root`` object;
+in particular it may be associated with a database connection or
+another persistence mechanism.
+
+A root factory is passed a :term:`request` object and it is expected
+to return an object which represents the root of the object graph.
+All :term:`traversal` will begin at this root object.  The root object
+is usually a *mapping* object (such as a Python dictionary, or at
+least a class which has many of the same methods as a dictionary).
 
 .. warning:: In :mod:`repoze.bfg` 1.0 and prior versions, the root
    factory was passed a term WSGI *environment* object (a dictionary)
@@ -93,6 +105,10 @@ usually a *mapping* object (such as a Python dictionary).
    emulates the WSGI environment, so code expecting the argument to be
    a dictionary will continue to work.
 
+If a :term:`root factory` is passed to the :mod:`repoze.bfg`
+:term:`Configurator` constructor as the value ``None``, a *default*
+root factory is used.
+
 .. sidebar:: Emulating the Default Root Factory
 
    For purposes of understanding the default root factory better,
@@ -109,35 +125,10 @@ usually a *mapping* object (such as a Python dictionary).
       config = Configurator(root_factory=Root)
 
    The default root factory is just a really stupid object that has no
-   behavior or state.
-
-Using :term:`traversal` against an application that uses the object
-graph supplied by the default root object is not very interesting,
-because the default root object has no children.  In a more complex
-:mod:`repoze.bfg` application, a root factory would be supplied which
-would return an object that had children capable of being traversed,
-and therefore there might be many :term:`context` objects to which
-URLs might resolve, depending on the URL path.  However, in this toy
-application, there's exactly one object in our object graph; the
-default root object.  Therefore, there can only ever be one context:
-the :term:`root` object itself.
-
-We have only a single :term:`default view` registered (the
-registration for the ``hello_world`` view callable).  Due to this set
-of circumstances, you can consider the sole possible URL that will
-resolve to a :term:`default view` in this application the root URL
-``'/'``.  It is the only URL that will resolve to the :term:`view
-name` of ``''`` (the empty string) when the default object graph is
-traversed.
-
-We have only a single view registered for the :term:`view name`
-``goodbye`` (the registration for the ``goodbye_world`` view
-callable).  Due to this set of circumstances, you can consider the
-sole possible URL that will resolve to the ``goodbye_world`` in this
-application the URL ``'/goodbye'`` because it is the only URL that
-will result in the :term:`view name` of ``goodbye`` when the default
-object graph is traversed.
-
+   behavior or state.  Using :term:`traversal` against an application
+   that uses the object graph supplied by the default root object is
+   not very interesting, because the default root object has no
+   children.
 
 Items contained within the object graph are sometimes analogous to the
 concept of :term:`model` objects used by many other frameworks (and
@@ -479,6 +470,5 @@ model object during traversal.
 References
 ----------
 
-For a contextual example of how :term:`traversal` can be used to
-create a :mod:`repoze.bfg` application, see the
-:ref:`bfg_wiki_tutorial`.
+A tutorial showing how :term:`traversal` can be used to create a
+:mod:`repoze.bfg` application exists in :ref:`bfg_wiki_tutorial`.
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 44515cd54..604eb6814 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -857,7 +857,6 @@ See :ref:`request_and_context_view_definitions` for more information.
 References
 ----------
 
-For a contextual example of how :term:`URL dispatch` can be used to
-create a :mod:`repoze.bfg` application, see the
-:ref:`bfg_sql_wiki_tutorial`.
+A tutorial showing how :term:`URL dispatch` can be used to create a
+:mod:`repoze.bfg` application exists in :ref:`bfg_sql_wiki_tutorial`.
 
diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst
index b7ba7021b..da8d6ab9f 100644
--- a/docs/narr/urlmapping.rst
+++ b/docs/narr/urlmapping.rst
@@ -36,18 +36,17 @@ application developer, and invokes it.  A view callable returns a
 
 .. sidebar::  What Good is A Context Finding Subsystem?
 
-   Many other web frameworks such as :term:`Pylons` or :term:`Django`
+   The :term:`URL dispatch` mode of :mod:`repoze.bfg` as well as many
+   other web frameworks such as :term:`Pylons` or :term:`Django`
    actually collapse the two steps of context finding and view lookup
-   into a single step.  In such systems, a URL maps *directly* to a
-   view callable.  These systems possess no analogue to a
-   context finding subsystem: they are "context-free".  This makes
-   them simpler to understand than systems which use "context".
-   However, using an explicit context finding step provides extra
-   flexibility.  For example, it makes it possible to protect your
-   application with declarative context-sensitive instance-level
-   :term:`authorization`, which is not well supported in frameworks
-   that do not provide a notion of a context.  See the
-   :ref:`security_chapter` for more information.
+   into a single step.  In these systems, a URL can map *directly* to
+   a view callable.  This makes them simpler to understand than
+   systems which use distinct subsystems to locate a context and find
+   a view.  However, explicitly using context finding step provides
+   extra flexibility.  For example, it makes it possible to protect
+   your application with declarative context-sensitive instance-level
+   :term:`authorization`, which is not well-supported in frameworks
+   that do not provide a notion of a context.
 
 There are two separate context finding subsystems in
 :mod:`repoze.bfg`: :term:`traversal` and :term:`URL dispatch`.  The
@@ -55,7 +54,7 @@ subsystems are documented within this chapter.  They can be used
 separately or they can be combined.
 
 There is only one view lookup subsystem present in :mod:`repoze.bfg`.
-It is not documented in this chapter.  Instead, it is documented
+It is not documented within this chapter.  Instead, it is documented
 within :ref:`views_chapter`.
 
 .. toctree::