bring docs up to date with code

1 files changed, 44 insertions, 15 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 7e485f8ae..6d9dfdd92 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -267,11 +267,12 @@ pattern like this:
 
    /La Pe\xc3\xb1a/{x}
 
-But that probably won't match as you expect it to.  You'll want to use a
-Unicode value as the pattern instead rather than raw bytestring escapes.  You
-can use a high-order Unicode value as the pattern by using `Python source
-file encoding <http://www.python.org/dev/peps/pep-0263/>`_ plus the "real"
-character in the Unicode pattern in the source, like so:
+But this will either cause an error at startup time or it won't match
+properly.  You'll want to use a Unicode value as the pattern instead rather
+than raw bytestring escapes.  You can use a high-order Unicode value as the
+pattern by using `Python source file encoding
+<http://www.python.org/dev/peps/pep-0263/>`_ plus the "real" character in the
+Unicode pattern in the source, like so:
 
 .. code-block:: text
 
@@ -664,7 +665,7 @@ based on route patterns.  For example, if you've configured a route with the
 This would return something like the string ``http://example.com/1/2/3`` (at
 least if the current protocol and hostname implied ``http://example.com``).
 
-To get only the *path* of a route, use the
+To generate only the *path* portion of a URL from a route, use the
 :meth:`pyramid.request.Request.route_path` API instead of
 :meth:`~pyramid.request.Request.route_url`.
 
@@ -674,8 +675,14 @@ To get only the *path* of a route, use the
 
 This will return the string ``/1/2/3`` rather than a full URL.
 
+Replacement values passed to ``route_url`` or ``route_path`` must be Unicode
+or bytestrings encoded in UTF-8.  One exception to this rule exists: if
+you're trying to replace a "remainder" match value (a ``*stararg``
+replacement value), the value may be a tuple containing Unicode strings or
+UTF-8 strings.
+
 Note that URLs and paths generated by ``route_path`` and ``route_url`` are
-always URL-quoted string types (which contain no non-ASCII characters).
+always URL-quoted string types (they contain no non-ASCII characters).
 Therefore, if you've added a route like so:
 
 .. code-block:: python
@@ -690,19 +697,41 @@ And you later generate a URL using ``route_path`` or ``route_url`` like so:
 
 You will wind up with the path encoded to UTF-8 and URL quoted like so:
 
-.. code-block:: python
+.. code-block:: text
 
    /La%20Pe%C3%B1a/Qu%C3%A9bec
 
-.. note::
+If you have a ``*stararg`` remainder dynamic part of your route pattern:
+
+.. code-block:: python
+
+   config.add_route('abc', 'a/b/c/*foo')
+
+And you later generate a URL using ``route_path`` or ``route_url`` using a
+*string* as the replacement value:
+
+.. code-block:: python
+
+   url = request.route_path('abc', foo=u'Québec/biz')
 
-   Generating URL-quoted URLs and paths is new as of Pyramid 1.3 (and Pyramid
-   1.2 after 1.2.6).  Previous versions generated unquoted URLs and paths
-   (which was broken).
+The value you pass will be URL-quoted except for embedded slashes in the
+result:
+
+.. code-block:: text
+
+   /a/b/c/Qu%C3%A9bec/biz
+
+You can get a similar result by passing a tuple composed of path elements:
+
+.. code-block:: python
+
+   url = request.route_path('abc', foo=(u'Québec', u'biz'))
+
+Each value in the tuple will be url-quoted and joined by slashes in this case:
+
+.. code-block:: text
 
-See the :meth:`~pyramid.request.Request.route_url` and
-:meth:`~pyramid.request.Request.route_path` API documentation for more
-information.
+   /a/b/c/Qu%C3%A9bec/biz
 
 .. index::
    single: static routes