Improve the documentation for template strings (#856)

bpo-19824
bpo-20314
bpo-12518

1 files changed, 19 insertions, 11 deletions

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 03eaf3b9cd..8176a81d4c 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -657,9 +657,15 @@ Nesting arguments and more complex examples::
 Template strings
 ----------------
 
-Templates provide simpler string substitutions as described in :pep:`292`.
-Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
--based substitutions, using the following rules:
+Template strings provide simpler string substitutions as described in
+:pep:`292`.  A primary use case for template strings is for
+internationalization (i18n) since in that context, the simpler syntax and
+functionality makes it easier to translate than other built-in string
+formatting facilities in Python.  As an example of a library built on template
+strings for i18n, see the
+`flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>`_ package.
+
+Template strings support ``$``-based substitutions, using the following rules:
 
 * ``$$`` is an escape; it is replaced with a single ``$``.
 
@@ -735,14 +741,17 @@ Here is an example of how to use a Template::
    >>> Template('$who likes $what').safe_substitute(d)
    'tim likes $what'
 
-Advanced usage: you can derive subclasses of :class:`Template` to customize the
-placeholder syntax, delimiter character, or the entire regular expression used
-to parse template strings.  To do this, you can override these class attributes:
+Advanced usage: you can derive subclasses of :class:`Template` to customize
+the placeholder syntax, delimiter character, or the entire regular expression
+used to parse template strings.  To do this, you can override these class
+attributes:
 
-* *delimiter* -- This is the literal string describing a placeholder introducing
-  delimiter.  The default value is ``$``.  Note that this should *not* be a
-  regular expression, as the implementation will call :meth:`re.escape` on this
-  string as needed.
+* *delimiter* -- This is the literal string describing a placeholder
+  introducing delimiter.  The default value is ``$``.  Note that this should
+  *not* be a regular expression, as the implementation will call
+  :meth:`re.escape` on this string as needed.  Note further that you cannot
+  change the delimiter after class creation (i.e. a different delimiter must
+  be set in the subclass's class namespace).
 
 * *idpattern* -- This is the regular expression describing the pattern for
   non-braced placeholders (the braces will be added automatically as
@@ -787,4 +796,3 @@ Helper functions
    or ``None``, runs of whitespace characters are replaced by a single space
    and leading and trailing whitespace are removed, otherwise *sep* is used to
    split and join the words.
-