Add documentation for *subpath.

Switch back to using a route with a subpath in the bfgalchemy paster template.

3 files changed, 30 insertions, 2 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index e5cb81aa9..9d3f35b3d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -186,7 +186,8 @@ Documentation
   and authorization policies to the "Security" narrative chapter.
 
 - Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter
-  to the narrative documentation.
+  to the narrative documentation.  This explains the usage of
+  ``*traverse`` and ``*subpath`` in routes URL patters.
 
 - A "router" chapter explaining the request/response lifecycle at a
   high level was added.
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index c3e61d906..73648a129 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -215,6 +215,32 @@ In this way, each route can use a different factory, making it
 possible to traverse different graphs based on some routing parameter
 within the same application.
 
+Using ``*subpath`` in a Route Path
+----------------------------------
+
+There are certain (extremely rare) cases when you'd like to influence
+the traversal :term:`subpath` when a route matches without atually
+performing traversal.  For instance, the ``repoze.bfg.wsgi.wsgiapp2``
+decorator and the ``repoze.bfg.view.static`` helper attempt to compute
+``PATH_INFO`` from the request's subpath, so it's useful to be able to
+influence this value.  When ``*subpath`` exists in a path pattern, no
+path is actually traversed, but the traversal algorithm will return a
+:term:`subpath` list implied by the capture value of ``*subpath``.
+You'll see this pattern most commonly in route declarations that look
+like this:
+
+.. code-block:: xml
+
+   <route
+    path="/static/*subpath"
+    name="static"
+    view=".views.static_view"
+    />
+
+Where ``.views.static_view`` is an instance of
+``repoze.bfg.view.static``.  This effectively tells the static helper
+to traverse everything in the subpath as a filename.
+
 Corner Cases
 ------------
 
diff --git a/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml b/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml
index 13f4e2531..14bb95cd6 100644
--- a/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml
+++ b/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml
@@ -12,7 +12,8 @@
     view=".views.my_view"
     />
 
-  <view 
+  <route
+    path="/static/*subpath"
     name="static"
     view=".views.static_view"
     />