Document '%F' format specifier

  The '%F' specifier was implemented in commit 6c46718f9f0 on
2000-08-23, but remains undocumented in the manual.
https://stackoverflow.com/questions/75157669/format-specifier-f-missing-from-glibcs-documentation

Fix that.
  

On 2023-01-18 21:43, Paul Pluzhnikov via Libc-alpha wrote:
> The '%F' specifier was implemented in commit 6c46718f9f0 on
> 2000-08-23, but remains undocumented in the manual.
> https://stackoverflow.com/questions/75157669/format-specifier-f-missing-from-glibcs-documentation
> 
> Fix that.
> 

The patch fails to apply on master.  Also, the specifier needs to be 
mentioned in the Floating-Point Conversions section alongside %f 
wherever applicable.  Other than the first line that mentions all format 
specifiers, there are lines like:

The @samp{%g} and @samp{%G} conversions print the argument in the style
of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
than -4 or greater than or equal to the precision; otherwise they use
the @samp{%f} style.

where I think mentioning @samp{%F} would be useful.  i.e. wherever the 
lower and upper options are mention together, do the same for %f too.

Please also review other sections in stdio.texi that mention %f and add 
%F wherever applicable, e.g. input conversions.

Thanks,
Sid
  

On Mon, Jan 23, 2023 at 8:42 AM Siddhesh Poyarekar <siddhesh@gotplt.org> wrote:
>
> On 2023-01-18 21:43, Paul Pluzhnikov via Libc-alpha wrote:
> > The '%F' specifier was implemented in commit 6c46718f9f0 on
> > 2000-08-23, but remains undocumented in the manual.
> > https://stackoverflow.com/questions/75157669/format-specifier-f-missing-from-glibcs-documentation
> >
> > Fix that.
> >
>
> The patch fails to apply on master.

Sorry about that -- I've attached a revised patch.

> Please also review other sections in stdio.texi that mention %f and add
> %F wherever applicable, e.g. input conversions.

I think I got all the instances of '%f' updated now.

Thanks,
  

On 2023-01-24 12:49, Paul Pluzhnikov wrote:
> On Mon, Jan 23, 2023 at 8:42 AM Siddhesh Poyarekar <siddhesh@gotplt.org> wrote:
>>
>> On 2023-01-18 21:43, Paul Pluzhnikov via Libc-alpha wrote:
>>> The '%F' specifier was implemented in commit 6c46718f9f0 on
>>> 2000-08-23, but remains undocumented in the manual.
>>> https://stackoverflow.com/questions/75157669/format-specifier-f-missing-from-glibcs-documentation
>>>
>>> Fix that.
>>>
>>
>> The patch fails to apply on master.
> 
> Sorry about that -- I've attached a revised patch.
> 
>> Please also review other sections in stdio.texi that mention %f and add
>> %F wherever applicable, e.g. input conversions.
> 
> I think I got all the instances of '%f' updated now.
> 
> Thanks,

Just one nit, please send an update with that (see below) and I'll add a 
Reviewed-by.

> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index f6319a4b8a..2aba957873 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -1845,8 +1845,9 @@ Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
>  lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
>  Conversions}, for details.
>  
> -@item @samp{%f}
> +@item @samp{%f}, @samp{%F}
>  Print a floating-point number in normal (fixed-point) notation.
> +@samp{%f} uses lower-case letters and @samp{%F} uses upper-case.
>  @xref{Floating-Point Conversions}, for details.
>  
>  @item @samp{%e}, @samp{%E}
> @@ -2073,11 +2074,11 @@ various format options, using the template string:
>  @subsection Floating-Point Conversions
>  
>  This section discusses the conversion specifications for floating-point
> -numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
> -conversions.
> +numbers: the @samp{%f}, @samp{%F}, @samp{%e}, @samp{%E}, @samp{%g}, and
> +@samp{%G} conversions.
>  
> -The @samp{%f} conversion prints its argument in fixed-point notation,
> -producing output of the form
> +The @samp{%f} and @samp{%F} conversions print their argument in fixed-point
> +notation, producing output of the form
>  @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
>  where the number of digits following the decimal point is controlled
>  by the precision you specify.
> @@ -2093,7 +2094,7 @@ the precision.  The exponent always contains at least two digits.  The
>  The @samp{%g} and @samp{%G} conversions print the argument in the style
>  of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
>  than -4 or greater than or equal to the precision; otherwise they use
> -the @samp{%f} style.  A precision of @code{0}, is taken as 1.
> +the @samp{%f} of @same{%F} style.  A precision of @code{0}, is taken as 1.

or @samp{%F}

>  Trailing zeros are removed from the fractional portion of the result and
>  a decimal-point character appears only if it is followed by a digit.
>  
> @@ -2123,7 +2124,7 @@ If the value to be printed represents infinity or a NaN, the output is
>  @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
>  specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
>  @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
> -@samp{%A}, @samp{%E}, or @samp{%G}.  On some implementations, a NaN
> +@samp{%A}, @samp{%E}, @samp{%F} or @samp{%G}.  On some implementations, a NaN
>  may result in longer output with information about the payload of the
>  NaN; ISO C2X defines a macro @code{_PRINTF_NAN_LEN_MAX} giving the
>  maximum length of such output.
> @@ -2162,8 +2163,8 @@ specified.
>  @end table
>  
>  The precision specifies how many digits follow the decimal-point
> -character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
> -these conversions, the default precision is @code{6}.  If the precision
> +character for the @samp{%f}, @samp{%F}, @samp{%e}, and @samp{%E} conversions.
> +For these conversions, the default precision is @code{6}.  If the precision
>  is explicitly @code{0}, this suppresses the decimal point character
>  entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
>  specifies how many significant digits to print.  Significant digits are
> @@ -3535,7 +3536,7 @@ Matches an unsigned integer written in decimal radix.
>  Matches an unsigned integer written in hexadecimal radix.
>  @xref{Numeric Input Conversions}.
>  
> -@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
> +@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F}, @samp{%G}
>  Matches an optionally signed floating-point number.  @xref{Numeric Input
>  Conversions}.
>  
> @@ -3691,7 +3692,7 @@ Specifies that the argument is a @code{size_t *}.
>  This modifier was introduced in @w{ISO C99}.
>  @end table
>  
> -All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
> +All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F} and @samp{%G}
>  input conversions are interchangeable.  They all match an optionally
>  signed floating point number, in the same syntax as for the
>  @code{strtod} function (@pxref{Parsing of Floats}).
  

On Tue, Jan 24, 2023 at 1:32 PM Siddhesh Poyarekar <siddhesh@gotplt.org> wrote:

> > -the @samp{%f} style.  A precision of @code{0}, is taken as 1.
> > +the @samp{%f} of @same{%F} style.  A precision of @code{0}, is taken as 1.
>
> or @samp{%F}

Two typos in a row :-(
Done (attached).

I should still have commit-after-approval rights (I think).
Just to confirm, it looks like ChangeLog has finally been abandoned?

Thanks,

--
Paul Pluzhnikov
diff --git a/manual/stdio.texi b/manual/stdio.texi
index f6319a4b8a..d7eab1843a 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -1845,8 +1845,9 @@ Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
 lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
 Conversions}, for details.
 
-@item @samp{%f}
+@item @samp{%f}, @samp{%F}
 Print a floating-point number in normal (fixed-point) notation.
+@samp{%f} uses lower-case letters and @samp{%F} uses upper-case.
 @xref{Floating-Point Conversions}, for details.
 
 @item @samp{%e}, @samp{%E}
@@ -2073,11 +2074,11 @@ various format options, using the template string:
 @subsection Floating-Point Conversions
 
 This section discusses the conversion specifications for floating-point
-numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
-conversions.
+numbers: the @samp{%f}, @samp{%F}, @samp{%e}, @samp{%E}, @samp{%g}, and
+@samp{%G} conversions.
 
-The @samp{%f} conversion prints its argument in fixed-point notation,
-producing output of the form
+The @samp{%f} and @samp{%F} conversions print their argument in fixed-point
+notation, producing output of the form
 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
 where the number of digits following the decimal point is controlled
 by the precision you specify.
@@ -2093,7 +2094,7 @@ the precision.  The exponent always contains at least two digits.  The
 The @samp{%g} and @samp{%G} conversions print the argument in the style
 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
 than -4 or greater than or equal to the precision; otherwise they use
-the @samp{%f} style.  A precision of @code{0}, is taken as 1.
+the @samp{%f} or @samp{%F} style.  A precision of @code{0}, is taken as 1.
 Trailing zeros are removed from the fractional portion of the result and
 a decimal-point character appears only if it is followed by a digit.
 
@@ -2123,7 +2124,7 @@ If the value to be printed represents infinity or a NaN, the output is
 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
-@samp{%A}, @samp{%E}, or @samp{%G}.  On some implementations, a NaN
+@samp{%A}, @samp{%E}, @samp{%F} or @samp{%G}.  On some implementations, a NaN
 may result in longer output with information about the payload of the
 NaN; ISO C2X defines a macro @code{_PRINTF_NAN_LEN_MAX} giving the
 maximum length of such output.
@@ -2162,8 +2163,8 @@ specified.
 @end table
 
 The precision specifies how many digits follow the decimal-point
-character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
-these conversions, the default precision is @code{6}.  If the precision
+character for the @samp{%f}, @samp{%F}, @samp{%e}, and @samp{%E} conversions.
+For these conversions, the default precision is @code{6}.  If the precision
 is explicitly @code{0}, this suppresses the decimal point character
 entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
 specifies how many significant digits to print.  Significant digits are
@@ -3535,7 +3536,7 @@ Matches an unsigned integer written in decimal radix.
 Matches an unsigned integer written in hexadecimal radix.
 @xref{Numeric Input Conversions}.
 
-@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
+@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F}, @samp{%G}
 Matches an optionally signed floating-point number.  @xref{Numeric Input
 Conversions}.
 
@@ -3691,7 +3692,7 @@ Specifies that the argument is a @code{size_t *}.
 This modifier was introduced in @w{ISO C99}.
 @end table
 
-All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
+All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F} and @samp{%G}
 input conversions are interchangeable.  They all match an optionally
 signed floating point number, in the same syntax as for the
 @code{strtod} function (@pxref{Parsing of Floats}).
  

On 2023-01-24 17:20, Paul Pluzhnikov wrote:
> On Tue, Jan 24, 2023 at 1:32 PM Siddhesh Poyarekar <siddhesh@gotplt.org> wrote:
> 
>>> -the @samp{%f} style.  A precision of @code{0}, is taken as 1.
>>> +the @samp{%f} of @same{%F} style.  A precision of @code{0}, is taken as 1.
>>
>> or @samp{%F}
> 
> Two typos in a row :-(
> Done (attached).

LGTM.

Reviewed-by: Siddhesh Poyarekar <siddhesh@sourceware.org>

> I should still have commit-after-approval rights (I think).
> Just to confirm, it looks like ChangeLog has finally been abandoned?

Right, no need for ChangeLog.  Unfortunately however, since you replied 
with the patch (and did not do a git-send-email), patchwork[1] didn't 
pick this latest one up.  We like to have a 1:1 match for commits with 
patchwork but it's not enforced yet.

This won't affect your ability to push the patch but please make sure 
you have a coherent git commit message (your original message is fine) 
with the Reviewed-by line above when you push.  If you send your patch 
afresh as [committed] with git-send-email, we'll have a proper patchwork 
record too.

Thanks,
Sid


[1] 
https://patchwork.sourceware.org/project/glibc/patch/CALoOobNE_v1z7WM5Js8-zpbuiFRr37Si0gCk13=wN2yBwDge_g@mail.gmail.com/