Re: doc string of `format' - FLAGS unexplained

[Chong Yidong <cyd@stupidchicken.com>]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc string includes this:
>  
>  The basic structure of a %-sequence is
>    % <flags> <width> <precision> character
>  where flags is [-+ #0]+, width is [0-9]+, and precision is .[0-9]+
>  
> But there is absolutely no explanation of what FLAGS, WIDTH, and
> PRECISION mean.  One might be able to guess for WIDTH and PRECISION,
> but not for FLAGS.  Please include some of the explanation from the
> Elisp manual, adapting it as needed.
>  
> Also, the EMACS convention for doc strings is to use uppercase: FLAGS,
> not angle brackets: <flags>.

I'd like to propose the following change to the doc string of
`format'.

In particular, the statement "flags is [-+ #0]+" is misleading; it
should be [+ #]+, since the - and 0 characters are actually used to
identify the width specifier instead.

Any thoughts?


*** emacs/src/editfns.c.~1.439.2.10.~	2008-01-10 10:26:25.000000000 -0500
--- emacs/src/editfns.c	2008-02-25 18:12:57.000000000 -0500
***************
*** 3383,3389 ****
         doc: /* Format a string out of a format-string and arguments.
  The first argument is a format control string.
  The other arguments are substituted into it to make the result, a string.
! It may contain %-sequences meaning to substitute the next argument.
  %s means print a string argument.  Actually, prints any object, with `princ'.
  %d means print as number in decimal (%o octal, %x hex).
  %X is like %x, but uses upper case.
--- 3383,3392 ----
         doc: /* Format a string out of a format-string and arguments.
  The first argument is a format control string.
  The other arguments are substituted into it to make the result, a string.
! 
! The format control string may contain %-sequences meaning to substitute
! the next available argument:
! 
  %s means print a string argument.  Actually, prints any object, with `princ'.
  %d means print as number in decimal (%o octal, %x hex).
  %X is like %x, but uses upper case.
***************
*** 3393,3404 ****
    or decimal-point notation, whichever uses fewer characters.
  %c means print a number as a single character.
  %S means print any object as an s-expression (using `prin1').
!   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)
--- 3396,3428 ----
    or decimal-point notation, whichever uses fewer characters.
  %c means print a number as a single character.
  %S means print any object as an s-expression (using `prin1').
! 
! The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.
  Use %% to put a single % into the output.
  
! A %-sequence may contain optional flag, width, and precision
! specifiers, as follows:
! 
!   %<flags><width><precision>character
! 
! where flags is [+ #]+, width is [0-9]+, and precision is .[0-9]+
! 
! The + flag character inserts a + before any positive number, while a
! space inserts a space before any positive number; these flags only
! affect %d, %e, %f, and %g sequences, and + takes precedence if both
! flags are present.  The # flag means to use an alternate display form
! for %o, %x, %X, %e, %f, and %g sequences.
! 
! The width specifier supplies a lower limit for the length of the
! printed representation.  The padding, if any, goes on the left if the
! width specifier is positive or starts with a 0, and on the right if it
! is negative.  The padding character is normally a space, and 0 if the
! width specifier starts with the character 0.
! 
! For %e, %f, and %g sequences, the number after the "." in the
! precision specifier says how many decimal places to show; if zero, the
! decimal point itself is omitted.  For %s and %S, the precision
! specifier truncates the string to the given width.
  
  usage: (format STRING &rest OBJECTS)  */)
       (nargs, args)