Improve the documentation for template strings (#856)

bpo-19824
bpo-20314
bpo-12518

3 files changed, 28 insertions, 15 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 9cf8767..a9877ba 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2076,10 +2076,11 @@ expression support in the :mod:`re` module).
 
    The formatting operations described here exhibit a variety of quirks that
    lead to a number of common errors (such as failing to display tuples and
-   dictionaries correctly).  Using the newer :ref:`formatted
-   string literals <f-strings>` or the :meth:`str.format` interface
-   helps avoid these errors.  These alternatives also provide more powerful,
-   flexible and extensible approaches to formatting text.
+   dictionaries correctly).  Using the newer :ref:`formatted string literals
+   <f-strings>`, the :meth:`str.format` interface, or :ref:`template strings
+   <template-strings>` may help avoid these errors.  Each of these
+   alternatives provides their own trade-offs and benefits of simplicity,
+   flexibility, and/or extensibility.
 
 String objects have one unique built-in operation: the ``%`` operator (modulo).
 This is also known as the string *formatting* or *interpolation* operator.
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 03eaf3b..8176a81 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.
-
diff --git a/Misc/NEWS b/Misc/NEWS
index b41fd8d..9ff9481 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -879,6 +879,10 @@ C API
 Documentation
 -------------
 
+- bpo-19824, bpo-20314, bpo-12518: Improve the documentation for, and links
+  to, template strings by emphasizing their utility for internationalization,
+  and by clarifying some usage constraints.
+
 - bpo-28929: Link the documentation to its source file on GitHub.
 
 - bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to