Adapt "Format String Syntax" for the format library.

doc/string.rst

+.. highlight:: c++
+
 .. ifconfig:: False
 
    .. _string-formatting:
@@ -120,63 +122,27 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
 The grammar for a replacement field is as follows:
 
    .. productionlist:: sf
-      replacement_field: "{" [`field_name`] [":" `format_spec`] "}"
-      field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
-      arg_name: [`identifier` | `integer`]
-      attribute_name: `identifier`
-      element_index: `integer` | `index_string`
-      index_string: <any source character except "]"> +
+      replacement_field: "{" [`arg_index`] [":" `format_spec`] "}"
+      arg_index: `integer`
       format_spec: <described in the next section>
 
-In less formal terms, the replacement field can start with a *field_name* that specifies
-the object whose value is to be formatted and inserted
-into the output instead of the replacement field.
-The *field_name* is optionally followed by a *format_spec*, which is preceded
+In less formal terms, the replacement field can start with an *arg_index*
+that specifies the argument whose value is to be formatted and inserted into
+the output instead of the replacement field.
+The *arg_index* is optionally followed by a *format_spec*, which is preceded
 by a colon ``':'``.  These specify a non-default format for the replacement value.
 
 See also the :ref:`formatspec` section.
 
-The *field_name* itself begins with an *arg_name* that is either a number or a
-keyword.  If it's a number, it refers to a positional argument, and if it's a keyword,
-it refers to a named keyword argument.  If the numerical arg_names in a format string
-are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
-and the numbers 0, 1, 2, ... will be automatically inserted in that order.
-Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
-dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
-The *arg_name* can be followed by any number of index or
-attribute expressions. An expression of the form ``'.name'`` selects the named
-attribute using :func:`getattr`, while an expression of the form ``'[index]'``
-does an index lookup using :func:`__getitem__`.
-
-.. versionchanged:: 3.1
-   The positional argument specifiers can be omitted, so ``'{} {}'`` is
-   equivalent to ``'{0} {1}'``.
+If the numerical arg_indexes in a format string are 0, 1, 2, ... in sequence,
+they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be
+automatically inserted in that order.
 
 Some simple format string examples::
 
-   "First, thou shalt count to {0}" # References first positional argument
-   "Bring me a {}"                  # Implicitly references the first positional argument
-   "From {} to {}"                  # Same as "From {0} to {1}"
-   "My quest is {name}"             # References keyword argument 'name'
-   "Weight in tons {0.weight}"      # 'weight' attribute of first positional arg
-   "Units destroyed: {players[0]}"  # First element of keyword argument 'players'.
-
-The *conversion* field causes a type coercion before formatting.  Normally, the
-job of formatting a value is done by the :meth:`__format__` method of the value
-itself.  However, in some cases it is desirable to force a type to be formatted
-as a string, overriding its own definition of formatting.  By converting the
-value to a string before calling :meth:`__format__`, the normal formatting logic
-is bypassed.
-
-Three conversion flags are currently supported: ``'!s'`` which calls :func:`str`
-on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls
-:func:`ascii`.
-
-Some examples::
-
-   "Harold's a clever {0!s}"        # Calls str() on the argument first
-   "Bring out the holy {name!r}"    # Calls repr() on the argument first
-   "More {!a}"                      # Calls ascii() on the argument first
+   "First, thou shalt count to {0}" // References first positional argument
+   "Bring me a {}"                  // Implicitly references the first positional argument
+   "From {} to {}"                  // Same as "From {0} to {1}"
 
 The *format_spec* field contains a specification of how the value should be
 presented, including such details as field width, alignment, padding, decimal
@@ -187,10 +153,11 @@ 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
-format_spec are substituted before the *format_spec* string is interpreted.
-This allows the formatting of a value to be dynamically specified.
+These nested replacement fields can contain only an argument index;
+format specifications are not allowed.  Formatting is performed as if 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.
 
 See the :ref:`formatexamples` section for some examples.