Make traversal and urldispatch into subchapters.

3 files changed, 22 insertions, 24 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 8bd7c812b..9e31a053f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,8 +49,6 @@ Narrative documentation in chapter form explaining how to use
    narr/project
    narr/startup
    narr/urlmapping
-   narr/traversal
-   narr/urldispatch
    narr/views
    narr/webob
    narr/templates
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 653e3c918..7f37b8143 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -29,10 +29,7 @@ Narrative Documentation
    narr/configuration
    narr/scanning
    narr/project
-   narr/startup
    narr/urlmapping
-   narr/traversal
-   narr/urldispatch
    narr/views
    narr/webob
    narr/templates
@@ -47,6 +44,7 @@ Narrative Documentation
    narr/extending
    narr/resources
    narr/router
+   narr/startup
    narr/threadlocals
 
 Tutorials
diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst
index 1f094d452..60bb09079 100644
--- a/docs/narr/urlmapping.rst
+++ b/docs/narr/urlmapping.rst
@@ -1,7 +1,11 @@
+.. index::
+   triple: differences; URL dispatch; traversal
+   pair: mapping; URLs
+
 .. _url_mapping_chapter:
 
 Mapping URLs to Code
-====================
+--------------------
 
 Many popular web frameworks today use :term:`URL dispatch` to
 associate a particular URL with a bit of code.  In these systems, the
@@ -21,19 +25,13 @@ 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.
 
-Like :term:`Zope`, :mod:`repoze.bfg`, in contrast to URL dispatch, can
-also map URLs to code slightly differently, by using using object
-graph :term:`traversal`.  Graph-traversal based dispatching is useful
-if you like your URLs to represent an arbitrary hierarchy of
-potentially heterogeneous items, or if you need to attach
-"instance-level" security (akin to "row-level" security in relational
-parlance) declarations to :term:`model` instances.
-
-.. index::
-   triple: differences; URL dispatch; traversal
-
-Differences Between Traversal and URL Dispatch
-----------------------------------------------
+Like :term:`Zope`, :mod:`repoze.bfg` can also map URLs to code
+slightly differently, by using using object graph :term:`traversal`.
+Graph-traversal based dispatching is useful if you like your URLs to
+represent an arbitrary hierarchy of potentially heterogeneous items,
+or if you need to attach "instance-level" security (akin to
+"row-level" security in relational parlance) declarations to
+:term:`model` instances.
 
 :term:`URL dispatch` can easily handle URLs such as
 ``http://example.com/members/Chris``, where it's assumed that each
@@ -90,12 +88,16 @@ to code in terms of traversing the graph.  (How's *that* for
 self-referential! ;-) ) 
 
 In essence, the choice to use graph traversal vs. URL dispatch is
-largely religious in some sense.  Graph traversal dispatch probably
-just doesn't make any sense when you possess completely "square" data
-stored in a relational database.  However, when you have a
-hierarchical data store, it can provide advantages over using
-URL-based dispatch.
+largely religious.  Graph traversal dispatch probably just doesn't
+make any sense when you possess completely "square" data stored in a
+relational database.  However, when you have a hierarchical data
+store, it can provide advantages over using URL-based dispatch.
 
 :mod:`repoze.bfg` provides support for both approaches.  You can use
 either as you see fit.
 
+.. toctree::
+   :maxdepth: 2
+
+   traversal
+   urldispatch