Recorded merge of revisions 74614 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74614 | georg.brandl | 2009-09-01 09:40:54 +0200 (Di, 01 Sep 2009) | 1 line

  #6813: better documentation for numberless string formats.
........

Doc/library/string.rst

@@ -194,7 +194,7 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
 The grammar for a replacement field is as follows:
 
    .. productionlist:: sf
-      replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
+      replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
       field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
       arg_name: (`identifier` | `integer`)?
       attribute_name: `identifier`
@@ -202,7 +202,7 @@ The grammar for a replacement field is as follows:
       conversion: "r" | "s" | "a"
       format_spec: <described in the next section>
 
-In less formal terms, the replacement field starts with a *field_name* that specifies
+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  *conversion* field, which is
@@ -223,7 +223,7 @@ 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}"
+   "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'.
@@ -243,6 +243,7 @@ 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
 
 The *format_spec* field contains a specification of how the value should be
 presented, including such details as field width, alignment, padding, decimal

Doc/tutorial/inputoutput.rst

@@ -126,12 +126,12 @@ with zeros.  It understands about plus and minus signs::
 
 Basic usage of the :meth:`str.format` method looks like this::
 
-   >>> print('We are the {0} who say "{1}!"'.format('knights', 'Ni'))
+   >>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
    We are the knights who say "Ni!"
 
 The brackets and characters within them (called format fields) are replaced with
-the objects passed into the :meth:`~str.format` method.  The number in the
-brackets refers to the position of the object passed into the
+the objects passed into the :meth:`~str.format` method.  A number in the
+brackets can be used to refer to the position of the object passed into the
 :meth:`~str.format` method. ::
 
    >>> print('{0} and {1}'.format('spam', 'eggs'))
@@ -152,6 +152,15 @@ Positional and keyword arguments can be arbitrarily combined::
                                                           other='Georg'))
    The story of Bill, Manfred, and Georg.
 
+``'!a'`` (apply :func:`ascii`), ``'!s'`` (apply :func:`str`) and ``'!r'``
+(apply :func:`repr`) can be used to convert the value before it is formatted::
+
+   >>> import math
+   >>> print('The value of PI is approximately {}.'.format(math.pi))
+   The value of PI is approximately 3.14159265359.
+   >>> print('The value of PI is approximately {!r}.'.format(math.pi))
+   The value of PI is approximately 3.141592653589793.
+
 An optional ``':'`` and format specifier can follow the field name. This allows
 greater control over how the value is formatted.  The following example
 truncates Pi to three places after the decimal.