Review.

1 files changed, 26 insertions, 45 deletions

diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst
index 491113e62..74d9e3cc5 100644
--- a/docs/narr/contextfinding.rst
+++ b/docs/narr/contextfinding.rst
@@ -70,57 +70,40 @@ describe how view lookup interacts with context finding.
 Should I Use Traversal or URL Dispatch for Context Finding?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:term:`URL dispatch` can easily handle URLs such as
-``http://example.com/members/Chris``, where it's assumed that each
-item "below" ``members`` in the URL represents a member in the system.
-You just match everything "below" ``members`` to a particular
-:term:`view callable`.  For example, you might configure URL dispatch
-within :mod:`repoze.bfg` to match against the following URL patterns:
-
-.. code-block:: text
-
-   members/:membername
-   archives/:year/:month/:day
+:term:`URL dispatch` is very straightforward.  When you limit your
+application to using URL dispatch, you know every URL that your
+application might generate or respond to, all the URL matching
+elements are listed in a single place, and you needn't think about
+:term:`context finding` or :term:`view lookup` at all.
 
-In this configuration, there will be exactly two types of URLs that
-will be meaningful to your application: URLs that start with
-``/members`` which are followed by a path segment containing a
-member's name.  And URLs that start with ``/archives`` and have
-subsequent path elements that represent a year, month, and day.  Each
-route pattern will be mapped to a specific :term:`view callable`.
-
-URL dispatch is very straightforward.  When you limit your application
-to using URL dispatch, you know every URL that your application might
-generate or respond to, and all the URL matching elements are listed
-in a single place.
+URL dispatch can easily handle URLs such as
+``http://example.com/members/Chris``, where it's assumed that each
+item "below" ``members`` in the URL represents a single member in some
+system.  You just match everything "below" ``members`` to a particular
+:term:`view callable`, e.g. ``/members/:memberid``.
 
-URL dispatch is not very good, however, at inferring the difference
-between sets of URLs such as these:
+However, URL dispatch is not very convenient if you'd like your URLs
+to represent an arbitrary hierarchy.  For example, if you need to
+infer the difference between sets of URLs such as these, where the
+``document`` in the first URL represents a PDF document, and
+``/stuff/page`` in the second represents an OpenOffice document in a
+"stuff" folder.
 
 .. code-block:: text
 
    http://example.com/members/Chris/document
    http://example.com/members/Chris/stuff/page
 
-If you'd like the ``document`` in the first URL above to represent a
-PDF document, and ``/stuff/page`` in the second to represent an
-OpenOffice document in a "stuff" folder, it's hard to express this
-using URL dispatch.  It takes more pattern matching assertions to be
-able to make hierarchies like these work in URL-dispatch based
-systems, and some assertions just aren't possible.  Essentially,
-URL-dispatch based systems just don't deal very well with URLs that
-represent arbitrary-depth hierarchies.
-
-However, the other URL mapping mode supported by :mod:`repoze.bfg`,
-named :term:`traversal`, *does* work well for URLs that represent
-arbitrary-depth hierarchies.  When traversal is used, each URL segment
-represents a single traversal step through an edge of a graph, so a
-URL like ``http://example.com/a/b/c`` can be thought of as a graph
-traversal on the ``example.com`` site through the edges ``a``, ``b``,
-and ``c``.  Since the path segments that compose a URL are addressed
-separately, it becomes very easy to form URLs that represent arbitrary
-depth hierarchies in a system that uses traversal.
+It takes more pattern matching assertions to be able to make
+hierarchies work in URL-dispatch based systems, and some assertions
+just aren't possible.  Essentially, URL-dispatch based systems just
+don't deal very well with URLs that represent arbitrary-depth
+hierarchies.
 
+But :term:`traversal`, *does* work well for URLs that represent
+arbitrary-depth hierarchies.  Since the path segments that compose a
+URL are addressed separately, it becomes very easy to form URLs that
+represent arbitrary depth hierarchies in a system that uses traversal.
 When you're willing to treat your application models as a graph that
 can be traversed, it also becomes easy to provide "instance-level
 security": you just attach a security declaration to each instance in
@@ -136,6 +119,4 @@ hierarchical data store, using traversal can provide significant
 advantages over using URL-based dispatch.
 
 Since :mod:`repoze.bfg` provides support for both approaches, you can
-use either as you see fit; you can even combine them together if
-necessary.
-
+use either exclusively or combine them as you see fit.