rearrange traversal and urldispatch chapters

4 files changed, 80 insertions, 102 deletions

diff --git a/docs/index.rst b/docs/index.rst
index d1b256e43..77587d2f1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -39,8 +39,8 @@ Narrative documentation in chapter form explaining how to use
    narr/project
    narr/startup
    narr/resourcelocation
-   narr/traversal
    narr/urldispatch
+   narr/traversal
    narr/hybrid
    narr/views
    narr/handlers
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 6855a1d23..2a8ee1532 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -32,8 +32,8 @@ Narrative Documentation
    narr/firstapp
    narr/project
    narr/resourcelocation
-   narr/traversal
    narr/urldispatch
+   narr/traversal
    narr/hybrid
    narr/views
    narr/handlers
diff --git a/docs/narr/resourcelocation.rst b/docs/narr/resourcelocation.rst
index aa8eaf23a..401d439fd 100644
--- a/docs/narr/resourcelocation.rst
+++ b/docs/narr/resourcelocation.rst
@@ -6,45 +6,27 @@
 Resource Location and View Lookup
 ---------------------------------
 
-As a primary job, :app:`Pyramid` provides a mechanism to find and invoke code
-written by the application developer based on parameters present in the
-:term:`request`.
-
 :app:`Pyramid` uses two separate but cooperating subsystems to find and
-invoke code written by the application developer: :term:`resource location`
-and :term:`view lookup`.
+invoke :term:`view callable` code written by the application developer:
+:term:`resource location` and :term:`view lookup`.
 
-- A :app:`Pyramid` :term:`resource location` subsystem is given a
+- First, a :app:`Pyramid` :term:`resource location` subsystem is given a
   :term:`request`; it is responsible for finding a :term:`resource` object
   based on information present in the request.  When a resource is found via
   resource location, it becomes known as the :term:`context`.
 
-- Using the context provided by :term:`resource location`, the :app:`Pyramid`
-  :term:`view lookup` subsystem is provided with a :term:`request` and
-  :term:`context`.  It is then responsible for finding and invoking a
-  :term:`view callable`.  A view callable is a specific bit of code written
-  and registered by the application developer which receives the
+- Next, using the context resource found by :term:`resource location` and the
+  :term:`request`, :term:`view lookup` is then responsible for finding and
+  invoking a :term:`view callable`.  A view callable is a specific bit of
+  code written and registered by the application developer which receives the
   :term:`request` and which returns a :term:`response`.
 
 These two subsystems are used by :app:`Pyramid` serially: first, a
-:term:`resource location` subsystem does its job.  Then the result of context
-finding is passed to the :term:`view lookup` subsystem.  The view lookup
-system finds a :term:`view callable` written by an application developer, and
-invokes it.  A view callable returns a :term:`response`.  The response is
-returned to the requesting user.
-
-.. sidebar::  What Good is A Resource Location Subsystem?
-
-   The :term:`URL dispatch` mode of :app:`Pyramid` as well as many other web
-   frameworks such as :term:`Pylons` or :term:`Django` actually collapse the
-   two steps of resource location and view lookup 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 resource and find a view.  However, explicitly finding a resource
-   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 resource.
+:term:`resource location` subsystem does its job.  Then the result of
+resource location is passed to the :term:`view lookup` subsystem.  The view
+lookup system finds a :term:`view callable` written by an application
+developer, and invokes it.  A view callable returns a :term:`response`.  The
+response is returned to the requesting user.
 
 There are two separate :term:`resource location` subsystems in
 :app:`Pyramid`: :term:`traversal` and :term:`URL dispatch`. They can be used
@@ -60,8 +42,11 @@ finding.  One chapter which follows describes :term:`view lookup`:
 Should I Use Traversal or URL Dispatch for Resource Location?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since :app:`Pyramid` provides support for both approaches, you can use either
-exclusively or combine them as you see fit.
+When you use :app:`Pyramid`, you have a choice about how you'd like to
+resolve URLs to code: you can use either :term:`traversal` or :term:`URL
+dispatch`.  The choice to use traversal vs. URL dispatch is largely
+"religious".  Since :app:`Pyramid` provides support for both approaches, you
+can use either exclusively or combine them as you see fit.
 
 :term:`URL dispatch` is very straightforward.  When you limit your
 application to using URL dispatch, you know every URL that your application
@@ -76,9 +61,9 @@ You just match everything "below" ``members`` to a particular :term:`view
 callable`, e.g. ``/members/{memberid}``.
 
 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
+represent an arbitrary-depth 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
@@ -88,22 +73,31 @@ represents an OpenOffice document in a "stuff" folder.
 
 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
+URL-dispatch based systems just don't deal very well with URLs that represent
+arbitrary-depth hierarchies.
+
+:term:`URL dispatch` tends to collapse the two steps of :term:`resource
+location` and :term:`view lookup` into a single step.  Thus, a URL can map
+*directly* to a view callable.  This makes URL dispatch eaiser to understand
+than traversal, because traversal makes you understand how :term:`resource
+location` works.  But explicitly locating a resource provides extra
+flexibility.  For example, it makes it possible to protect your application
+with declarative context-sensitive instance-level :term:`authorization`.
+
+Unlike URL dispatch, :term:`traversal` works 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 resources as a tree that can be traversed,
-it also becomes easy to provide "instance-level security": you just attach a
-security declaration to each resource in the tree.  This is not nearly as
-easy to do when using URL dispatch.
-
-In essence, the choice to use traversal vs. URL dispatch is largely
-religious.  Traversal dispatch probably just doesn't make any sense when you
-possess completely "square" data stored in a relational database because it
-requires the construction and maintenance of a tree and requires that the
+it also becomes easy to provide "instance-level security": you just attach an
+:term:`ACL` security declaration to each resource in the tree.  This is not
+nearly as easy to do when using URL dispatch.
+
+Traversal probably just doesn't make any sense when you possess completely
+"square" data stored in a relational database because it requires the
+construction and maintenance of a resource tree and requires that the
 developer think about mapping URLs to code in terms of traversing that tree.
-However, when you have a hierarchical data store, using traversal can provide
-significant advantages over using URL-based dispatch.
+
+We'll examine both :term:`URL dispatch` and :term:`traversal` in the next two
+chapters.
+
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index fb5b97e54..9a9769d23 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -6,42 +6,17 @@
 URL Dispatch
 ============
 
-The URL dispatch feature of :app:`Pyramid` allows you to either augment or
-replace :term:`traversal` as a :term:`resource location` mechanism, allowing
-URL pattern matching to have the "first crack" at resolving a given URL to
-:term:`context` resource.
-
-Although it is a "resource-location" mechanism, ironically, using URL
-dispatch exclusively allows you to avoid thinking about your application in
-terms of resources entirely.
-
-Many applications don't need :app:`Pyramid` features -- such as
-context-sensitive declarative security via an :term:`authorization policy` --
-that benefit from having any visible separation between :term:`resource
-location` and :term:`view lookup`.  To this end, URL dispatch provides a
-handy syntax that allows you to effectively map URLs *directly* to
-:term:`view` code in such a way that you needn't think about your application
-in terms of "resource location" at all.  This makes developing a
-:app:`Pyramid` application seem more like developing an application in a
-system that is "resource-free", such as :term:`Pylons` or :term:`Django`.
-
-Whether or not you care about "resources", it often makes a lot of sense to
-use :term:`URL dispatch` instead of :term:`traversal` in an application that
-has no natural data hierarchy.  For instance, if all the data in your
-application lives in a relational database, and that relational database has
-no self-referencing tables that form a natural hierarchy, URL dispatch is
-easier to use than traversal, and is often a more natural fit for creating an
-application that manipulates "flat" data.
+:term:`URL dispatch` provides a simple way to map URLs :term:`view` code
+using a simple pattern matching language.  An ordered set of patterns is
+checked one-by-one.  If one of the patterns matches the path information
+associated with a request, a particular :term:`view callable` is invoked.  If
+no route matches, :app:`Pyramid` falls back to trying to use
+:term:`traversal` to map the current request to a :term:`view callable`.
 
 The presence of calls to the :meth:`pyramid.config.Configurator.add_route`
 method within your application is a sign that you're using :term:`URL
 dispatch`.
 
-.. note::
-
-  Route configuration may also be added to the system via :term:`ZCML` (see
-  :ref:`zcml_route_configuration`).
-
 High-Level Operational Overview
 -------------------------------
 
@@ -50,27 +25,31 @@ If route configuration is present in an application, the :app:`Pyramid`
 matching patterns present in a *route map*.
 
 If any route pattern matches the information in the :term:`request` provided
-to :app:`Pyramid`, a route-specific :term:`context` resource will be
-generated.  When this happens, :app:`Pyramid` will shortcut
-:term:`traversal`, and will invoke :term:`view lookup` using the context
-resource and view name generated by URL dispatch.  If the matched route names
-a :term:`view callable` in its configuration, that view callable will be
-invoked when view lookup is performed.
+to :app:`Pyramid`, app:`Pyramid` will shortcut :term:`traversal`, and will
+invoke :term:`view lookup` using a :term:`context` resource generated by the
+route match.
 
 However, if no route pattern matches the information in the :term:`request`
 provided to :app:`Pyramid`, it will fail over to using :term:`traversal` to
 perform resource location and view lookup.
 
+Technically, URL dispatch is a :term:`resource location` mechanism (it finds
+a context object).  But ironically, using URL dispatch (instead of
+:term:`traversal`) allows you to avoid thinking about your application in
+terms of "resources" entirely, because it allows you to directly map a
+:term:`view callable` to a route.
+
 Route Configuration
 -------------------
 
 :term:`Route configuration` is the act of adding a new :term:`route` to an
 application.  A route has a *pattern*, representing a pattern meant to match
-against the ``PATH_INFO`` portion of a URL, and a *name*, which is used by
-developers within a :app:`Pyramid` application to uniquely identify a
-particular route when generating a URL.  It also optionally has a
-``factory``, a set of :term:`route predicate` parameters, and a set of
-:term:`view` parameters.
+against the ``PATH_INFO`` portion of a URL (the portion following the scheme
+and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``),
+and a *route name*, which is used by developers within a :app:`Pyramid`
+application to uniquely identify a particular route when generating a URL.
+It also optionally has a ``factory``, a set of :term:`route predicate`
+parameters, and a set of :term:`view` parameters.
 
 .. index::
    single: add_route
@@ -103,10 +82,11 @@ Route Configuration That Names a View Callable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When a route configuration declaration names a ``view`` attribute, the value
-of the attribute will reference a :term:`view callable`.  A view callable, as
-described in :ref:`views_chapter`, is developer-supplied code that "does
-stuff" as the result of a request.  For more information about how to create
-view callables, see :ref:`views_chapter`.
+of the attribute will reference a :term:`view callable`.  This view callable
+will be invoked when the route matches.  A view callable, as described in
+:ref:`views_chapter`, is developer-supplied code that "does stuff" as the
+result of a request.  For more information about how to create view
+callables, see :ref:`views_chapter`.
 
 Here's an example route configuration that references a view callable:
 
@@ -136,6 +116,9 @@ When a route configuration names a ``view`` attribute, the :term:`view
 callable` named as that ``view`` attribute will always be found and invoked
 when the associated route pattern matches during a request.
 
+Route View Callable Registration and Lookup Details
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
 The purpose of making it possible to specify a view callable within a route
 configuration is to prevent developers from needing to deeply understand the
 details of :term:`resource location` and :term:`view lookup`.  When a route
@@ -146,11 +129,8 @@ the invocation.
 
 For most usage, you needn't understand more than this; how it works is an
 implementation detail.  In the interest of completeness, however, 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
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+explain how it *does* work in the this section.  You can skip it if you're
+uninterested.
 
 When a ``view`` attribute is attached to a route configuration,
 :app:`Pyramid` ensures that a :term:`view configuration` is registered that
@@ -1257,3 +1237,7 @@ References
 
 A tutorial showing how :term:`URL dispatch` can be used to create a
 :app:`Pyramid` application exists in :ref:`bfg_sql_wiki_tutorial`.
+
+Route configuration may also be added to the system via :term:`ZCML` (see
+:ref:`zcml_route_configuration`).
+