For `format', make source and documentation match.

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

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 */
-	  minlen = atoi (format);
-	  if (minlen < 0)
-	    minlen = - minlen, negative = 1;
+	  while (index("-0# ", *format))
+	    {
+	      if (*format == '-')
+		{
+		  negative = 1;
+		}
+	      discarded[format - format_start] = 1;
+	      ++format;
+	    }
 
-	  /* 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 == '.')
+	  minlen = atoi (format);
+
+	  while ((*format >= '0' && *format <= '9') || *format == '.')
 	    {
 	      discarded[format - format_start] = 1;
 	      format++;