Minor improvements to format field numbers

* src/editfns.c (styled_format): Allow field numbers in a %% spec.
No need for a special diagnostic for field numbers greater than
PTRDIFF_MAX.  Reword diagnostic for field 0.
* test/src/editfns-tests.el (format-with-field): Adjust to match.

1 files changed, 55 insertions, 64 deletions

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 526b1fb4ebc..4d33e55b018 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -864,15 +864,6 @@ below, as the first argument, and the string as the second, like this:
   (format "%s" @var{arbitrary-string})
 @end example
 
-  If @var{string} contains more than one format specification and none
-of the format specifications contain an explicit field number, the
-format specifications correspond to successive values from
-@var{objects}.  Thus, the first format specification in @var{string}
-uses the first such value, the second format specification uses the
-second such value, and so on.  Any extra format specifications (those
-for which there are no corresponding values) cause an error.  Any
-extra values to be formatted are ignored.
-
   Certain format specifications require values of particular types.  If
 you supply a value that doesn't fit the requirements, an error is
 signaled.
@@ -962,68 +953,33 @@ operation} error.
 @end group
 @end example
 
+  By default, format specifications correspond to successive values from
+@var{objects}.  Thus, the first format specification in @var{string}
+uses the first such value, the second format specification uses the
+second such value, and so on.  Any extra format specifications (those
+for which there are no corresponding values) cause an error.  Any
+extra values to be formatted are ignored.
+
 @cindex field numbers in format spec
-  A specification can have a @dfn{field number}, which is a decimal
-number after the initial @samp{%}, followed by a literal dollar sign
-@samp{$}.  If you provide a field number, then the argument to be
-printed corresponds to the given field number instead of the next
-argument.  Field numbers start at 1.
+  A format specification can have a @dfn{field number}, which is a
+decimal number immediately after the initial @samp{%}, followed by a
+literal dollar sign @samp{$}.  It causes the format specification to
+convert the argument with the given number instead of the next
+argument.  Argument 1 is the argument just after the format.
 
-You can mix specifications with and without field numbers.  A
+  You can mix specifications with and without field numbers.  A
 specification without a field number that follows a specification with
 a field number will convert the argument after the one specified by
 the field number:
 
 @example
-(format "First argument %2$s, then %s, then %1$s" 1 2 3)
-     @result{} "First argument 2, then 3, then 1"
-@end example
-
-You can't use field numbers in a @samp{%%} specification.
-
-@cindex field width
-@cindex padding
-  A specification can have a @dfn{width}, which is a decimal number
-between the @samp{%} and the specification character.  If the printed
-representation of the object contains fewer characters than this
-width, @code{format} extends it with padding.  The width specifier is
-ignored for the @samp{%%} specification.  Any padding introduced by
-the width specifier normally consists of spaces inserted on the left:
-
-@example
-(format "%5d is padded on the left with spaces" 123)
-     @result{} "  123 is padded on the left with spaces"
-@end example
-
-@noindent
-If the width is too small, @code{format} does not truncate the
-object's printed representation.  Thus, you can use a width to specify
-a minimum spacing between columns with no risk of losing information.
-In the following two examples, @samp{%7s} specifies a minimum width
-of 7.  In the first case, the string inserted in place of @samp{%7s}
-has only 3 letters, and needs 4 blank spaces as padding.  In the
-second case, the string @code{"specification"} is 13 letters wide but
-is not truncated.
-
-@example
-@group
-(format "The word '%7s' has %d letters in it."
-        "foo" (length "foo"))
-     @result{} "The word '    foo' has 3 letters in it."
-(format "The word '%7s' has %d letters in it."
-        "specification" (length "specification"))
-     @result{} "The word 'specification' has 13 letters in it."
-@end group
+(format "Argument %2$s, then %s, then %1$s" "x" "y" "z")
+     @result{} "Argument y, then z, then x"
 @end example
 
-If you want to use both a field number and a width, place the field
-number before the width.  For example, in @samp{%2$7s}, @samp{2} is
-the field number and @samp{7} is the width.
-
 @cindex flags in format specifications
-  After the @samp{%} and before the optional width specifier, you can
-also put certain @dfn{flag characters}.  The flag characters need to
-come directly after a potential field number.
+  After the @samp{%} and any field number, you can put certain
+@dfn{flag characters}.
 
   The flag @samp{+} inserts a plus sign before a positive number, so
 that it always has a sign.  A space character as flag inserts a space
@@ -1048,8 +1004,8 @@ specification characters like @samp{%s}, @samp{%S} and @samp{%c}.
 These specification characters accept the @samp{0} flag, but still pad
 with @emph{spaces}.
 
-  The flag @samp{-} causes the padding inserted by the width
-specifier, if any, to be inserted on the right rather than the left.
+  The flag @samp{-} causes any padding inserted by the width,
+if specified, to be inserted on the right rather than the left.
 If both @samp{-} and @samp{0} are present, the @samp{0} flag is
 ignored.
 
@@ -1067,9 +1023,44 @@ ignored.
 @end group
 @end example
 
+@cindex field width
+@cindex padding
+  A specification can have a @dfn{width}, which is a decimal number
+that appears after any field number and flags.  If the printed
+representation of the object contains fewer characters than this
+width, @code{format} extends it with padding.  The width is
+ignored for the @samp{%%} specification.  Any padding introduced by
+the width normally consists of spaces inserted on the left:
+
+@example
+(format "%5d is padded on the left with spaces" 123)
+     @result{} "  123 is padded on the left with spaces"
+@end example
+
+@noindent
+If the width is too small, @code{format} does not truncate the
+object's printed representation.  Thus, you can use a width to specify
+a minimum spacing between columns with no risk of losing information.
+In the following two examples, @samp{%7s} specifies a minimum width
+of 7.  In the first case, the string inserted in place of @samp{%7s}
+has only 3 letters, and needs 4 blank spaces as padding.  In the
+second case, the string @code{"specification"} is 13 letters wide but
+is not truncated.
+
+@example
+@group
+(format "The word '%7s' has %d letters in it."
+        "foo" (length "foo"))
+     @result{} "The word '    foo' has 3 letters in it."
+(format "The word '%7s' has %d letters in it."
+        "specification" (length "specification"))
+     @result{} "The word 'specification' has 13 letters in it."
+@end group
+@end example
+
 @cindex precision in format specifications
   All the specification characters allow an optional @dfn{precision}
-before the character (after the width, if present).  The precision is
+after the field number, flags and width, if present.  The precision is
 a decimal-point @samp{.} followed by a digit-string.  For the
 floating-point specifications (@samp{%e} and @samp{%f}), the
 precision specifies how many digits following the decimal point to