For `format', make source and documentation match.

2 files changed, 55 insertions, 36 deletions

diff --git a/lispref/strings.texi b/lispref/strings.texi
index 7cc182cc058..60a74313a85 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -798,19 +798,18 @@ operation} error.
 @cindex numeric prefix
 @cindex field width
 @cindex padding
-  All the specification characters allow an optional numeric prefix
-between the @samp{%} and the character.  The optional numeric prefix
-defines the minimum width for the object.  If the printed
-representation of the object contains fewer characters than this, then
-it is padded.  The padding is on the left if the prefix is positive
-(or starts with zero) and on the right if the prefix is negative.  The
-padding character is normally a space, but if the numeric prefix
-starts with a zero, zeros are used for padding.  Some of these
-conventions are ignored for specification characters for which they do
-not make sense.  That is, %s, %S and %c accept a numeric prefix
+  All the specification characters allow an optional ``width'', which
+is a digit-string between the @samp{%} and the character.  If the
+printed representation of the object contains fewer characters than
+this width, then it is padded.  The padding is on the left if the
+prefix is positive (or starts with zero) and on the right if the
+prefix is negative.  The padding character is normally a space, but if
+the width starts with a zero, zeros are used for padding.  Some of
+these conventions are ignored for specification characters for which
+they do not make sense.  That is, %s, %S and %c accept a width
 starting with 0, but still pad with @emph{spaces} on the left.  Also,
-%% accepts a numeric prefix, but ignores it.  Here are some examples
-of padding:
+%% accepts a width, but ignores it.  Here are some examples of
+padding:
 
 @example
 (format "%06d is padded on the left with zeros" 123)
@@ -820,10 +819,9 @@ of padding:
      @result{} "123    is padded on the right"
 @end example
 
-  @code{format} never truncates an object's printed representation, no
-matter what width you specify.  Thus, you can use a numeric prefix to
-specify a minimum spacing between columns with no risk of losing
-information.
+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 three examples, @samp{%7s} specifies a minimum width
 of 7.  In the first case, the string inserted in place of @samp{%7s} has
@@ -851,6 +849,28 @@ not truncated.  In the third case, the padding is on the right.
 @end group
 @end smallexample
 
+  All the specification characters allow an optional ``precision''
+before the character (after the width, if present).  The precision is
+a decimal-point @samp{.} followed by a digit-string.  For the
+floating-point specifications (%e, %f, %g), the precision specifies
+how many decimal places to show; if zero, the decimal-point itself is
+also omitted.  For %s and %S, the precision truncates the string to
+the given width, so @code{"%.3s"} shows only the first three
+characters of the representation for @var{object}.  Precision is
+ignored for other specification characters.
+
+Immediately after the % and before the optional width and precision,
+you can put certain ``flag'' characters.
+
+A space @var{" "} inserts a space for positive numbers (otherwise
+nothing is inserted for positive numbers).  This flag is ignored
+except for %d, %e, %f, %g.
+
+The flag @var{"#"} indicates ``alternate form''.  For %o it ensures
+that the result begins with a 0.  For %x and %X the result is prefixed
+with ``0x'' or ``0X''. For %e, %f, and %g a decimal point is always
+shown even if the precision is zero.
+
 @node Case Conversion
 @comment node-name, next, previous, up
 @section Case Conversion in Lisp
diff --git a/src/editfns.c b/src/editfns.c
index a636c35a464..d3039ca0273 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -3193,6 +3193,10 @@ It may contain %-sequences meaning to substitute the next argument.
   The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.
 Use %% to put a single % into the output.
 
+The basic structure of a %-sequence is
+  % <flags> <width> <precision> character
+where flags is [- #0]+, width is [0-9]+, and precision is .[0-9]+
+
 usage: (format STRING &rest OBJECTS)  */)
      (nargs, args)
      int nargs;
@@ -3300,7 +3304,7 @@ usage: (format STRING &rest OBJECTS)  */)
 
            where
 
-           flags        ::= [#-* 0]+
+           flags        ::= [- #0]+
            field-width  ::= [0-9]+
            precision    ::= '.' [0-9]*
 
@@ -3312,14 +3316,7 @@ usage: (format STRING &rest OBJECTS)  */)
            digits to print after the '.' for floats, or the max.
            number of chars to print from a string.  */
 
-        /* NOTE the handling of specifiers here differs in some ways
-           from the libc model.  There are bugs in this code that lead
-           to incorrect formatting when flags recognized by C but
-           neither parsed nor rejected here are used.  Further
-           revisions will be made soon.  */
-
-        /* incorrect list of flags to skip; will be fixed */
-        while (index ("-*# 0", *format))
+        while (index ("-0# ", *format))
           ++format;
 
         if (*format >= '0' && *format <= '9')
@@ -3403,7 +3400,7 @@ usage: (format STRING &rest OBJECTS)  */)
             if (*format == 'c')
               {
                 if (! SINGLE_BYTE_CHAR_P (XINT (args[n]))
-                    /* Note: No one can remeber why we have to treat
+                    /* Note: No one can remember why we have to treat
                        the character 0 as a multibyte character here.
                        But, until it causes a real problem, let's
                        don't change it.  */
@@ -3494,17 +3491,19 @@ usage: (format STRING &rest OBJECTS)  */)
           discarded[format - format_start] = 1;
           format++;
 
-          /* Process a numeric arg and skip it.  */
-          /* NOTE atoi is the wrong thing to use here; will be fixed */
+          while (index("-0# ", *format))
+            {
+              if (*format == '-')
+                {
+                  negative = 1;
+                }
+              discarded[format - format_start] = 1;
+              ++format;
+            }
+
           minlen = atoi (format);
-          if (minlen < 0)
-            minlen = - minlen, negative = 1;
-
-          /* NOTE the parsing here is not consistent with the first
-             pass, and neither attempt is what we want to do.  Will be
-             fixed. */
-          while ((*format >= '0' && *format <= '9')
-                 || *format == '-' || *format == ' ' || *format == '.')
+
+          while ((*format >= '0' && *format <= '9') || *format == '.')
             {
               discarded[format - format_start] = 1;
               format++;