Remove resource location chapter and move intro parts to url dispatch. The new much ado about traversal chapter takes care of selling traversal now

8 files changed, 26 insertions, 121 deletions

diff --git a/docs/index.rst b/docs/index.rst
index ecd401ddb..2f3589499 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,7 +38,6 @@ Narrative documentation in chapter form explaining how to use
    narr/firstapp
    narr/project
    narr/startup
-   narr/resourcelocation
    narr/urldispatch
    narr/muchadoabouttraversal
    narr/traversal
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index e2433746c..9635e6e8a 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -31,7 +31,6 @@ Narrative Documentation
    narr/configuration
    narr/firstapp
    narr/project
-   narr/resourcelocation
    narr/urldispatch
    narr/muchadoabouttraversal
    narr/traversal
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index cb1e54b19..1a81134f5 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -10,7 +10,7 @@ more detail how it works.
 .. note::
 
    If you're a "theory-first" kind of person, you might choose to read
-   :ref:`resourcelocation_chapter` and :ref:`views_chapter` before diving into
+   :ref:`urldispatch_chapter` and :ref:`views_chapter` before diving into
    the code that follows, but it's not necessary if -- like many programmers
    -- you're willing to "go with the flow".
 
diff --git a/docs/narr/resourcelocation.rst b/docs/narr/resourcelocation.rst
deleted file mode 100644
index 8ddc890ed..000000000
--- a/docs/narr/resourcelocation.rst
+++ /dev/null
@@ -1,103 +0,0 @@
-.. index::
-   single: resource location
-
-.. _resourcelocation_chapter:
-
-Resource Location and View Lookup
----------------------------------
-
-:app:`Pyramid` uses two separate but cooperating subsystems to find and
-invoke :term:`view callable` code written by the application developer:
-:term:`resource location` and :term:`view lookup`.
-
-- 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`.
-
-- 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
-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
-separately or they can be combined.  Three chapters which follow describe
-:term:`resource location`: :ref:`traversal_chapter`,
-:ref:`urldispatch_chapter` and :ref:`hybrid_chapter`.
-
-There is only one :term:`view lookup` subsystem present in :app:`Pyramid`.
-Where appropriate, we will describe how view lookup interacts with context
-finding.  One chapter which follows describes :term:`view lookup`:
-:ref:`views_chapter`.
-
-Should I Use Traversal or URL Dispatch for Resource Location?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
-might generate or respond to, all the URL matching elements are listed in a
-single place, and you needn't think about :term:`resource location` or
-:term:`view lookup` at all.
-
-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}``.
-
-However, URL dispatch is not very convenient if you'd like your URLs to
-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
-
-   http://example.com/members/Chris/document
-   http://example.com/members/Chris/stuff/page
-
-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.
-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 easier 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 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.
-
-We'll examine both :term:`URL dispatch` and :term:`traversal` in the next two
-chapters.
-
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index d3d5bd370..f9e98373c 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -133,6 +133,6 @@ processing?
 This is a very high-level overview that leaves out various details.
 For more detail about subsystems invoked by the :app:`Pyramid` router
 such as traversal, URL dispatch, views, and event processing, see
-:ref:`resourcelocation_chapter`, :ref:`views_chapter`, and
+:ref:`urldispatch_chapter`, :ref:`views_chapter`, and
 :ref:`events_chapter`.
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index c5262faa2..62a4727bc 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -18,8 +18,7 @@ works at a high level:
   :term:`resource location`.  A context is located differently depending on
   whether the application uses :term:`traversal` or :term:`URL dispatch`, but
   a context is ultimately found in either case.  See
-  :ref:`resourcelocation_chapter` for more information about resource
-  location.
+  the :ref:`urldispatch_chapter` chapter for more information.
 
 - A :term:`view callable` is located by :term:`view lookup` using the
   context as well as other attributes of the request.
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 0d28a0e96..d9228bf52 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -9,13 +9,24 @@ URL Dispatch
 :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`.
+associated with a request, a particular :term:`view callable` is invoked.  
+
+:term:`URL dispatch` is one of two ways to perform :term:`resource
+location` in :app:`Pyramid`; the other way is using :term:`traversal`.
+If no route is matched using :term:`URL dispatch`, :app:`Pyramid` falls
+back to :term:`traversal` to handle the :term:`request`.
+
+It is the responsibility of the :term:`resource location` subsystem
+(i.e., :term:`URL dispatch` or :term:`traversal`) to find the resource
+object that is the :term:`context` of the :term:`request`. Once the
+:term:`context` is determined, :term:`view lookup` is then responsible
+for finding and invoking a :term:`view callable`.  A view callable is a
+specific bit of code, defined in your application, that receives the
+:term:`request` and returns a :term:`response` object.
+
+Where appropriate, we will describe how view lookup interacts with 
+:term:`resource location`.  The :ref:`views_chapter` describes the
+details of :term:`view lookup`.
 
 High-Level Operational Overview
 -------------------------------
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index ad28e48d4..81f3e644f 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -17,11 +17,11 @@ request made to your application.
    that implements a view *callable*, and the process of view
    *lookup*.
 
-The chapter :ref:`resourcelocation_chapter` describes how, using information
-from the :term:`request`, a :term:`context` resource is computed.  But the
-context resource itself isn't very useful without an associated :term:`view
-callable`.  A view callable returns a response to a user, often using the
-context resource to do so.
+The :ref:`urldispatch_chapter`, and :ref:`traversal_chapter` describes how,
+using information from the :term:`request`, a :term:`context` resource is
+computed.  But the context resource itself isn't very useful without an
+associated :term:`view callable`.  A view callable returns a response to a
+user, often using the context resource to do so.
 
 The job of actually locating and invoking the "best" :term:`view callable` is
 the job of the :term:`view lookup` subsystem.  The view lookup subsystem