- New argument to ``repoze.bfg.configuration.Configurator.add_route``

  and the ``route`` ZCML directive: ``traverse``.  If you would like
  to cause the ``context`` to be something other than the ``root``
  object when this route matches, you can spell a traversal pattern as
  the ``traverse`` argument.  This traversal pattern will be used as
  the traversal path: traversal will begin at the root object implied
  by this route (either the global root, or the object returned by the
  ``factory`` associated with this route).

  The syntax of the ``traverse`` argument is the same as it is for
  ``path``. For example, if the ``path`` provided is
  ``articles/:article/edit``, and the ``traverse`` argument provided
  is ``/:article``, when a request comes in that causes the route to
  match in such a way that the ``article`` match value is '1' (when
  the request URI is ``/articles/1/edit``), the traversal path will be
  generated as ``/1``.  This means that the root object's
  ``__getitem__`` will be called with the name ``1`` during the
  traversal phase.  If the ``1`` object exists, it will become the
  ``context`` of the request.  The Traversal narrative has more
  information about traversal.

  If the traversal path contains segment marker names which are not
  present in the path argument, a runtime error will occur.  The
  ``traverse`` pattern should not contain segment markers that do not
  exist in the ``path``.

  A similar combining of routing and traversal is available when a
  route is matched which contains a ``*traverse`` remainder marker in
  its path.  The ``traverse`` argument allows you to associate route
  patterns with an arbitrary traversal path without using a a
  ``*traverse`` remainder marker; instead you can use other match
  information.

  Note that the ``traverse`` argument is ignored when attached to a
  route that has a ``*traverse`` remainder marker in its path.

2 files changed, 37 insertions, 0 deletions

diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 75592572c..368d44626 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -188,6 +188,8 @@ match is straightforward.  When a route is matched:
    root factory were explained previously within
    :ref:`the_object_graph`.  
 
+.. _using_traverse_in_a_route_path:
+
 Using ``*traverse`` In a Route Path
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 4e49ac4b3..59bcde13f 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -422,6 +422,41 @@ represent neither predicates nor view configuration information.
   this argument is not specified, the traversal root factory will be
   used.
 
+``traverse``
+  If you would like to cause the :term:`context` to be something other
+  than the :term:`root` object when this route matches, you can spell
+  a traversal pattern as the ``traverse`` argument.  This traversal
+  pattern will be used as the traversal path: traversal will begin at
+  the root object implied by this route (either the global root, or
+  the object returned by the ``factory`` associated with this route).
+
+  The syntax of the ``traverse`` argument is the same as it is for
+  ``path``. For example, if the ``path`` provided is
+  ``articles/:article/edit``, and the ``traverse`` argument provided
+  is ``/:article``, when a request comes in that causes the route to
+  match in such a way that the ``article`` match value is '1' (when
+  the request URI is ``/articles/1/edit``), the traversal path will be
+  generated as ``/1``.  This means that the root object's
+  ``__getitem__`` will be called with the name ``1`` during the
+  traversal phase.  If the ``1`` object exists, it will become the
+  :term:`context` of the request.  :ref:`traversal_chapter` has more
+  information about traversal.
+
+  If the traversal path contains segment marker names which are not
+  present in the path argument, a runtime error will occur.  The
+  ``traverse`` pattern should not contain segment markers that do not
+  exist in the ``path``.
+
+  A similar combining of routing and traversal is available when a
+  route is matched which contains a ``*traverse`` remainder marker in
+  its path (see :ref:`using_traverse_in_a_route_path`).  The
+  ``traverse`` argument allows you to associate route patterns with an
+  arbitrary traversal path without using a a ``*traverse`` remainder
+  marker; instead you can use other match information.
+
+  Note that the ``traverse`` argument is ignored when attached to a
+  route that has a ``*traverse`` remainder marker in its path.
+
 **Predicate Arguments**
 
 ``path``