Issue #25179: Preparatory cleanup of existing docs on string formatting
* There was a link pointing to the section on the string.Formatter class (and
multiple links in Python 3), 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 in Python 3; see Issue #19729 for instance
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index b0ffb6a..af13ee4 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -105,8 +105,8 @@
.. _new-string-formatting:
-String Formatting
------------------
+Custom String Formatting
+------------------------
.. versionadded:: 2.6
@@ -115,7 +115,7 @@
: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.
+:meth:`~str.format` method.
.. class:: Formatter
@@ -123,9 +123,9 @@
.. 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`.
.. method:: vformat(format_string, args, kwargs)
@@ -293,8 +293,9 @@
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.
@@ -332,8 +333,10 @@
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:
@@ -508,8 +511,8 @@
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 ``%``.