Re: doc string of `format' - FLAGS unexplained

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.