doc string of `format' - FLAGS unexplained

doc string of `format' - FLAGS unexplained

[Drew Adams]

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>.
 
 
 

In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600)
 of 2007-06-02 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/gnuwin32/include'
 

Re: doc string of `format' - FLAGS unexplained

[Chong Yidong]

"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)

Re: doc string of `format' - FLAGS unexplained

[Andreas Schwab]

Chong Yidong <cyd@stupidchicken.com> writes:

> 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.

This is wrong.  '-' and '0' are real flags that can be freely mixed with
other flags, eg. "%0#10d" is valid and the same as "%#010d".  They are
never considered part of the width.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: doc string of `format' - FLAGS unexplained

[Lennart Borgman (gmail)]

Chong Yidong wrote:
> 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?

How nice with a readable description of those formats. But

> !   %<flags><width><precision>character
> ! 
> ! where flags is [+ #]+, width is [0-9]+, and precision is .[0-9]+

   ! where <flags> is [+ #0]+, width is [1-9][0-9]*, and precision is
   .[0-9]+

is perhaps more accurate. `0' is a flag that gives leading 0:s, isn't it?

And perhaps is it more logical to write <flags> then just flags?

Re: doc string of `format' - FLAGS unexplained

[Chong Yidong]

Andreas Schwab <schwab@suse.de> writes:

> Chong Yidong <cyd@stupidchicken.com> writes:
>
>> 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.
>
> This is wrong.  '-' and '0' are real flags that can be freely mixed with
> other flags, eg. "%0#10d" is valid and the same as "%#010d".  They are
> never considered part of the width.

The question is, do we regard this as an undocumented side-effect of
the implementation?  Treating '-' and '0' as part of the width
specifier is conceptually simpler, and the elisp manual documents
these as such.  If we treat '0' as a real flag, then maybe the
description in the elisp manual should be revised.

Re: doc string of `format' - FLAGS unexplained

[Andreas Schwab]

Chong Yidong <cyd@stupidchicken.com> writes:

> Andreas Schwab <schwab@suse.de> writes:
>
>> Chong Yidong <cyd@stupidchicken.com> writes:
>>
>>> 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.
>>
>> This is wrong.  '-' and '0' are real flags that can be freely mixed with
>> other flags, eg. "%0#10d" is valid and the same as "%#010d".  They are
>> never considered part of the width.
>
> The question is, do we regard this as an undocumented side-effect of
> the implementation?

It works the same as in C, which is widely understood.  Gratuitous
differences only confuse people.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: doc string of `format' - FLAGS unexplained

[Chong Yidong]

Andreas Schwab <schwab@suse.de> writes:

> Chong Yidong <cyd@stupidchicken.com> writes:
>
>> Andreas Schwab <schwab@suse.de> writes:
>>
>>> Chong Yidong <cyd@stupidchicken.com> writes:
>>>
>>>> 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.
>>>
>>> This is wrong.  '-' and '0' are real flags that can be freely mixed with
>>> other flags, eg. "%0#10d" is valid and the same as "%#010d".  They are
>>> never considered part of the width.
>>
>> The question is, do we regard this as an undocumented side-effect of
>> the implementation?
>
> It works the same as in C, which is widely understood.  Gratuitous
> differences only confuse people.

True enough.  I've checked in a corrected docstring that treats - and
0 as flags.