[PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Vincent Lefevre]

Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
---
 man3/printf.3 | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/man3/printf.3 b/man3/printf.3
index 4fa1f11f3..63ea3092f 100644
--- a/man3/printf.3
+++ b/man3/printf.3
@@ -502,7 +502,17 @@ argument, or a following
 .B s
 conversion corresponds to a pointer to
 .I wchar_t
-argument.
+argument. In C99, on a following
+.BR a ,
+.BR A ,
+.BR e ,
+.BR E ,
+.BR f ,
+.BR F ,
+.BR g ,
+or
+.B G
+conversion, this length modifier is ignored.
 .TP
 .B ll
 (ell-ell).
-- 
2.36.1

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Alejandro Colomar]

Hi Vincent,

On 5/20/22 16:10, Vincent Lefevre wrote:
> Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
> ---
>   man3/printf.3 | 12 +++++++++++-
>   1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/printf.3 b/man3/printf.3
> index 4fa1f11f3..63ea3092f 100644
> --- a/man3/printf.3
> +++ b/man3/printf.3
> @@ -502,7 +502,17 @@ argument, or a following
>   .B s
>   conversion corresponds to a pointer to
>   .I wchar_t
> -argument.
> +argument. In C99, on a following


Why "in C99"?  Is there a different meaning for non-C99?
Do we need to specify?

Also, see man-pages(7):

    Use semantic newlines
        In the source of a manual page, new sentences  should  be
        started on new lines, long sentences should be split into
        lines  at  clause breaks (commas, semicolons, colons, and
        so on), and long clauses should be split at phrase bound‐
        aries.  This convention,  sometimes  known  as  "semantic
        newlines",  makes it easier to see the effect of patches,
        which often operate at the level of individual sentences,
        clauses, or phrases.

Thanks,

Alex

> +.BR a ,
> +.BR A ,
> +.BR e ,
> +.BR E ,
> +.BR f ,
> +.BR F ,
> +.BR g ,
> +or
> +.B G
> +conversion, this length modifier is ignored.
>   .TP
>   .B ll
>   (ell-ell).

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Vincent Lefevre]

On 2022-05-20 16:44:42 +0200, Alejandro Colomar wrote:
> Hi Vincent,
> 
> On 5/20/22 16:10, Vincent Lefevre wrote:
> > Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
> > ---
> >   man3/printf.3 | 12 +++++++++++-
> >   1 file changed, 11 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man3/printf.3 b/man3/printf.3
> > index 4fa1f11f3..63ea3092f 100644
> > --- a/man3/printf.3
> > +++ b/man3/printf.3
> > @@ -502,7 +502,17 @@ argument, or a following
> >   .B s
> >   conversion corresponds to a pointer to
> >   .I wchar_t
> > -argument.
> > +argument. In C99, on a following
> 
> Why "in C99"?

According to GCC with "-Wformat -pedantic", this is new in C99:

  warning: ISO C90 does not support the ‘%le’ gnu_printf format

The printf(3) man page already mentions features that appeared in
C99. For instance: "a, A   (C99; not in SUSv2, but added in SUSv3)"
That's why I mentioned that for consistency.

I could also check that this is not in SUSv2:
  https://pubs.opengroup.org/onlinepubs/7990989775/xsh/fprintf.html

Perhaps this should be rephrased. Something like:

  On a following a, A, e, E, f, F, g, or G conversion, this
  length modifier is ignored (C99; not in SUSv2).

What do you think?

I don't know about SUSv3 (I could just see that this feature was
also supported in POSIX:2004).

> Also, see man-pages(7):
> 
>    Use semantic newlines
>        In the source of a manual page, new sentences  should  be
>        started on new lines, long sentences should be split into
>        lines  at  clause breaks (commas, semicolons, colons, and
>        so on), and long clauses should be split at phrase bound‐
>        aries.  This convention,  sometimes  known  as  "semantic
>        newlines",  makes it easier to see the effect of patches,
>        which often operate at the level of individual sentences,
>        clauses, or phrases.

Thanks for the information.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Alejandro Colomar]

Hi Vincent,

On 5/20/22 18:11, Vincent Lefevre wrote:
>> Why "in C99"?
> 
> According to GCC with "-Wformat -pedantic", this is new in C99:
> 
>    warning: ISO C90 does not support the ‘%le’ gnu_printf format

Ok.

> 
> The printf(3) man page already mentions features that appeared in
> C99. For instance: "a, A   (C99; not in SUSv2, but added in SUSv3)"
> That's why I mentioned that for consistency.
> 
> I could also check that this is not in SUSv2:
>    https://pubs.opengroup.org/onlinepubs/7990989775/xsh/fprintf.html
> 
> Perhaps this should be rephrased. Something like:
> 
>    On a following a, A, e, E, f, F, g, or G conversion, this
>    length modifier is ignored (C99; not in SUSv2). >
> What do you think?

Makes sense.  Since SUSv3 should be identical to POSIX.2001, which 
itself should be aligned with C99 (see standards(7)), we can just ignore 
it, or we can add it if you want.


> 
> I don't know about SUSv3 (I could just see that this feature was
> also supported in POSIX:2004).
> 

Please send a new patch.

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Vincent Lefevre]

Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
---
 man3/printf.3 | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/man3/printf.3 b/man3/printf.3
index 4fa1f11f3..a231d626c 100644
--- a/man3/printf.3
+++ b/man3/printf.3
@@ -503,6 +503,17 @@ argument, or a following
 conversion corresponds to a pointer to
 .I wchar_t
 argument.
+On a following
+.BR a ,
+.BR A ,
+.BR e ,
+.BR E ,
+.BR f ,
+.BR F ,
+.BR g ,
+or
+.B G
+conversion, this length modifier is ignored (C99; not in SUSv2).
 .TP
 .B ll
 (ell-ell).
-- 
2.36.1

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Alejandro Colomar]

Hi Vincent,

On 5/20/22 19:30, Vincent Lefevre wrote:
> Signed-off-by: Vincent Lefevre <vincent@vinc17.net>

Patch applied!

Thanks,

Alex

> ---
>   man3/printf.3 | 11 +++++++++++
>   1 file changed, 11 insertions(+)
> 
> diff --git a/man3/printf.3 b/man3/printf.3
> index 4fa1f11f3..a231d626c 100644
> --- a/man3/printf.3
> +++ b/man3/printf.3
> @@ -503,6 +503,17 @@ argument, or a following
>   conversion corresponds to a pointer to
>   .I wchar_t
>   argument.
> +On a following
> +.BR a ,
> +.BR A ,
> +.BR e ,
> +.BR E ,
> +.BR f ,
> +.BR F ,
> +.BR g ,
> +or
> +.B G
> +conversion, this length modifier is ignored (C99; not in SUSv2).
>   .TP
>   .B ll
>   (ell-ell).

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Stefan Puiu]

Hi Vincent,

On Sat, May 21, 2022 at 8:33 AM Vincent Lefevre <vincent@vinc17.net> wrote:
>
> Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
> ---
>  man3/printf.3 | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/man3/printf.3 b/man3/printf.3
> index 4fa1f11f3..a231d626c 100644
> --- a/man3/printf.3
> +++ b/man3/printf.3
> @@ -503,6 +503,17 @@ argument, or a following
>  conversion corresponds to a pointer to
>  .I wchar_t
>  argument.
> +On a following
> +.BR a ,
> +.BR A ,
> +.BR e ,
> +.BR E ,
> +.BR f ,
> +.BR F ,
> +.BR g ,
> +or
> +.B G
> +conversion, this length modifier is ignored (C99; not in SUSv2).

I'm not a native English speaker, but I think "Following a ...
conversion" sounds better, unless I misunderstand the phrase.

My 2 cents,
Stefan.

>  .TP
>  .B ll
>  (ell-ell).
> --
> 2.36.1
>

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Vincent Lefevre]

Hi Stefan,

On 2022-05-24 10:07:43 +0300, Stefan Puiu wrote:
> On Sat, May 21, 2022 at 8:33 AM Vincent Lefevre <vincent@vinc17.net> wrote:
> > diff --git a/man3/printf.3 b/man3/printf.3
> > index 4fa1f11f3..a231d626c 100644
> > --- a/man3/printf.3
> > +++ b/man3/printf.3
> > @@ -503,6 +503,17 @@ argument, or a following
> >  conversion corresponds to a pointer to
> >  .I wchar_t
> >  argument.
> > +On a following
> > +.BR a ,
> > +.BR A ,
> > +.BR e ,
> > +.BR E ,
> > +.BR f ,
> > +.BR F ,
> > +.BR g ,
> > +or
> > +.B G
> > +conversion, this length modifier is ignored (C99; not in SUSv2).
> 
> I'm not a native English speaker, but I think "Following a ...
> conversion" sounds better, unless I misunderstand the phrase.

"Following a ... conversion" would mean the opposite, while it is
the conversion that follows the length modifier. Moreover, I wrote
"a following ... conversion" because this is what is always written
in this section on the length modifier, under the form "A following
... conversion corresponds to ...".

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Stefan Puiu]

On Tue, May 24, 2022 at 10:39 AM Vincent Lefevre <vincent@vinc17.net> wrote:
>
> Hi Stefan,
>
> On 2022-05-24 10:07:43 +0300, Stefan Puiu wrote:
> > On Sat, May 21, 2022 at 8:33 AM Vincent Lefevre <vincent@vinc17.net> wrote:
> > > diff --git a/man3/printf.3 b/man3/printf.3
> > > index 4fa1f11f3..a231d626c 100644
> > > --- a/man3/printf.3
> > > +++ b/man3/printf.3
> > > @@ -503,6 +503,17 @@ argument, or a following
> > >  conversion corresponds to a pointer to
> > >  .I wchar_t
> > >  argument.
> > > +On a following
> > > +.BR a ,
> > > +.BR A ,
> > > +.BR e ,
> > > +.BR E ,
> > > +.BR f ,
> > > +.BR F ,
> > > +.BR g ,
> > > +or
> > > +.B G
> > > +conversion, this length modifier is ignored (C99; not in SUSv2).
> >
> > I'm not a native English speaker, but I think "Following a ...
> > conversion" sounds better, unless I misunderstand the phrase.
>
> "Following a ... conversion" would mean the opposite, while it is
> the conversion that follows the length modifier. Moreover, I wrote
> "a following ... conversion" because this is what is always written
> in this section on the length modifier, under the form "A following
> ... conversion corresponds to ...".

OK, now I think I understand what you mean. I guess "a following ...
conversion" (used all over that man page, as you said) sounds a bit
weird to me, though it might be proper English, I don't know.

Sorry for the noise.
Stefan.

>
> --
> Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
> 100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
> Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Re: [PATCH] printf.3: Document 'l' length modifier for a, A, e, E, f, F, g, and G

[Vincent Lefevre]

On 2022-05-24 15:23:33 +0300, Stefan Puiu wrote:
> OK, now I think I understand what you mean. I guess "a following ...
> conversion" (used all over that man page, as you said) sounds a bit
> weird to me, though it might be proper English, I don't know.

It also sounds a bit weird to me (though this is grammatically
correct), but FYI, the ISO C standard uses the same words: "Specifies
that a following d, i, o, u, x, or X conversion specifier applies to
[...]", etc. So I suppose that there isn't any problem with this.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)