Issue #25179: Preparatory cleanup of existing docs on string formatting

* Various sections were pointing to the section on the string.Formatter
  class, when the section on the common format string syntax is probably more
  appropriate
* Fix references to various format() functions and methods
* Nested replacement fields may contain conversions and format specifiers,
  and this is tested; see Issue #19729 for instance

1 files changed, 15 insertions, 12 deletions

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 2bd8dfdc96..5b917d939b 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -75,14 +75,14 @@ The constants defined in this module are:
 
 .. _string-formatting:
 
-String Formatting
------------------
+Custom String Formatting
+------------------------
 
 The built-in string class provides the ability to do complex variable
-substitutions and value formatting via the :func:`format` method described in
+substitutions and value formatting via the :meth:`~str.format` method described in
 :pep:`3101`.  The :class:`Formatter` class in the :mod:`string` module allows
 you to create and customize your own string formatting behaviors using the same
-implementation as the built-in :meth:`format` method.
+implementation as the built-in :meth:`~str.format` method.
 
 
 .. class:: Formatter
@@ -91,9 +91,9 @@ implementation as the built-in :meth:`format` method.
 
    .. method:: format(format_string, *args, **kwargs)
 
-      :meth:`format` is the primary API method.  It takes a format string and
+      The primary API method.  It takes a format string and
       an arbitrary set of positional and keyword arguments.
-      :meth:`format` is just a wrapper that calls :meth:`vformat`.
+      It is just a wrapper that calls :meth:`vformat`.
 
       .. deprecated:: 3.5
          Passing a format string as keyword argument *format_string* has been
@@ -267,8 +267,9 @@ Most built-in types support a common formatting mini-language, which is
 described in the next section.
 
 A *format_spec* field can also include nested replacement fields within it.
-These nested replacement fields can contain only a field name; conversion flags
-and format specifications are not allowed.  The replacement fields within the
+These nested replacement fields may contain a field name, conversion flag
+and format specification, but deeper nesting is
+not allowed.  The replacement fields within the
 format_spec are substituted before the *format_spec* string is interpreted.
 This allows the formatting of a value to be dynamically specified.
 
@@ -306,8 +307,10 @@ The general form of a *standard format specifier* is:
 
 If a valid *align* value is specified, it can be preceded by a *fill*
 character that can be any character and defaults to a space if omitted.
-Note that it is not possible to use ``{`` and ``}`` as *fill* char while
-using the :meth:`str.format` method; this limitation however doesn't
+It is not possible to use a literal curly brace ("``{``" or "``}``") as
+the *fill* character when using the :meth:`str.format`
+method.  However, it is possible to insert a curly brace
+with a nested replacement field.  This limitation doesn't
 affect the :func:`format` function.
 
 The meaning of the various alignment options is as follows:
@@ -496,8 +499,8 @@ The available presentation types for floating point and decimal values are:
 Format examples
 ^^^^^^^^^^^^^^^
 
-This section contains examples of the new format syntax and comparison with
-the old ``%``-formatting.
+This section contains examples of the :meth:`str.format` syntax and
+comparison with the old ``%``-formatting.
 
 In most of the cases the syntax is similar to the old ``%``-formatting, with the
 addition of the ``{}`` and with ``:`` used instead of ``%``.