document nonempty segment rule

1 files changed, 19 insertions, 5 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 3c7555636..916715bec 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -233,11 +233,14 @@ and:
 
 A path segment (an individual item between ``/`` characters in the
 path) may either be a literal string (e.g. ``foo``) *or* it may be a
-segment replacement marker (e.g. ``:foo``).  A segment replacement
-marker is in the format ``:name``, where this means "accept any
-characters up to the next slash and use this as the ``name`` matchdict
-value."  For example, the following pattern defines one literal
-segment ("foo") and two dynamic segments ("baz", and "bar"):
+segment replacement marker (e.g. ``:foo``) or a certain combination of
+both.
+
+A segment replacement marker is in the format ``:name``, where this
+means "accept any characters up to the next nonalphaunumeric character
+and use this as the ``name`` matchdict value."  For example, the
+following pattern defines one literal segment ("foo") and two dynamic
+segments ("baz", and "bar"):
 
 .. code-block:: text
 
@@ -276,6 +279,17 @@ This does not mean, however, that you can use two segment replacement
 markers in the same segment.  For instance, ``/:foo:bar`` is a
 nonsensical route pattern.  It will never match anything.
 
+Segments must contain at least one character in order to match a
+segment replacement marker.  For example, for the URL ``/abc/``:
+
+- ``/abc/:foo`` will not match.
+
+- ``/:foo/`` will match.
+
+.. warning:: Due to a bug, the
+   must-be-one-character-to-match-segment-marker rule new to version
+   1.3.  It is untrue for older releases.
+
 Note that values representing path segments matched with a
 ``:segment`` match will be url-unquoted and decoded from UTF-8 into
 Unicode within the matchdict.  So for instance, the following