- Minimally explain usage of custom regular expressions in URL dispatch

  replacement markers within URL Dispatch chapter.

3 files changed, 15 insertions, 6 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index cf502f7e1..48557e780 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -53,6 +53,9 @@ Documentation
 
 - Slightly improved interface docs for ``IAuthorizationPolicy``.
 
+- Minimally explain usage of custom regular expressions in URL dispatch
+  replacement markers within URL Dispatch chapter.
+
 Deprecations
 -------------
 
diff --git a/TODO.txt b/TODO.txt
index c8f8bf2e7..1dbf1419d 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,12 +1,6 @@
 Pyramid TODOs
 =============
 
-Must-Have (before 1.0)
-----------------------
-
-- Explain ``{foo:<regex>}`` pattern formatting and purpose better in
-  within URL dispatch chapter.
-
 Should-Have
 -----------
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 39e97ab8e..8b127924b 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -252,6 +252,18 @@ the match result will be ``{'name': 'biz', 'ext': 'html'}``. This occurs
 because there is a literal part of ``.`` (period) between the two replacement
 markers ``{name}`` and ``{ext}``.
 
+Replacement markers can optionally specify a regular expression which will be
+used to decide whether a path segment should match the marker.  To specify
+that a replacement marker should match only a specific set of characters as
+defined by a regular expression, you must use a slightly extended form of
+replacement marker syntax.  Within braces, the replacement marker name must
+be followed by a colon, then directly thereafter, the regular expression.
+For example, under the hood, the replacement marker ``{foo}`` can more
+verbosely be spelled as ``{foo:[^/]+}``.  The *default* regular expression
+associated with a replacement marker ``[^/]+`` matches one or more characters
+which are not a slash.  You can use an arbitrary regular expression here to
+match a sequence of characters.
+
 It is possible to use two replacement markers without any literal characters
 between them, for instance ``/{foo}{bar}``. However, this would be a
 nonsensical pattern without specifying a custom regular expression to