[Bug 55371] New: printf: a conversion specifier doesn't necessarily ask for an argument

[Bug 55371] New: printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

           Summary: printf: a conversion specifier doesn't necessarily ask
                    for an argument
           Product: Documentation
           Version: unspecified
          Platform: All
        OS/Version: Linux
              Tree: Mainline
            Status: NEW
          Severity: low
          Priority: P1
         Component: man-pages
        AssignedTo: documentation_man-pages-ztI5WcYan/vQLgFONoPN62D2FQJk+8+b@public.gmane.org
        ReportedBy: chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
        Regression: No


The format string of printf is quite complicated, and while its documentation
is extensive, it has a bit too many errors and needs some cleanup for
comprehensibility.

In particular, man 3 printf contains:

By default, the arguments are used in the order given, where each '*' and each
conversion specifier asks for the next argument (and it is an error if
insufficiently many arguments are given).

This is inexact, as "%" is defined as a conversion specifier and doesn't
consume any argument.

It's also unclear in that sentence what "next argument" refers to. And "*"
hasn't been introduced at that point, so that part is hard to follow ("*" is
defined in section The precision).

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Alan <alan-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |alan-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org
         Resolution|---                         |INVALID

--- Comment #1 from Alan <alan-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org> ---
That would be from glibc not the kernel I think ?

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Alan <alan-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |CLOSED

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|CLOSED                      |REOPENED
         Resolution|INVALID                     |---

--- Comment #2 from Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
printf() is provided by the C library. This report is about printf's manual
page, shipped in man-pages. man-pages is hosted on kernel.org (
https://www.kernel.org/doc/man-pages/reporting_bugs.html ).

This persists in man-pages 3.54.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|REOPENED                    |RESOLVED
                 CC|                            |mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
         Resolution|---                         |CODE_FIX

--- Comment #3 from Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
(In reply to Filipus Klutiero from comment #0)
> The format string of printf is quite complicated, and while its
> documentation is extensive, it has a bit too many errors and needs some
> cleanup for comprehensibility.
> 
> In particular, man 3 printf contains:
> 
> By default, the arguments are used in the order given, where each '*' and
> each conversion specifier asks for the next argument (and it is an error if
> insufficiently many arguments are given).
> 
> This is inexact, as "%" is defined as a conversion specifier and doesn't
> consume any argument.

Yes, but that's explained no less than twice further down the page.

> It's also unclear in that sentence what "next argument" refers to. 

It seems clear enough to me. But, if you have a better proposal let me know.

> And "*"
> hasn't been introduced at that point, so that part is hard to follow ("*" is
> defined in section The precision).

For this piece, I changed the text to:

       By default, the arguments are used in the order
       given, where each '*' (see Field width and Pre‐
       cision below)  and  each  conversion  specifier
       asks  for the next argument

-- 
You are receiving this mail because:
You are watching the assignee of the bug.--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
         Resolution|CODE_FIX                    |---

--- Comment #4 from Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
Thanks for the change.

Regarding "%", I agree it is explained later, but the sentence remains
incorrect (and the topic is complicated enough that each error is one too
many).

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|REOPENED                    |RESOLVED
         Resolution|---                         |CODE_FIX

--- Comment #5 from Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
Sorry. Please do not reopen this bug, unless you have a concrete proposal for a
fix--i.e., a patch. As far as I'm concerned the text is adequate, and I'm not
doing further work on the page, but if you want you can propose a patch on the
mailing list.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
         Resolution|CODE_FIX                    |---

--- Comment #6 from Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
Please do not close this ticket until the issue has been solved.

A simple patch for this issue is trivial - just rectify that only some
conversion specifiers ask for the next arguments, for example:

By default, the arguments are used in the order given, where each '*' and each
conversion specifier (except for some) asks for the next argument (and it is an
error if insufficiently many arguments are given).


A patch which would keep the current sentence's precision would have to list
the exceptions.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|REOPENED                    |RESOLVED
         Resolution|---                         |WILL_NOT_FIX

--- Comment #7 from Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
So, I've stepped back from this a little, to think about it more. I don't agree
with the characterization of this problem as an error. The sentence you refer
to is a generalization. The exceptions are clarified later. I don't think it
help comprehensibility, nor readability, to clutter the initial discussion with
a note that there are some exceptions. By the time folk get to the point in the
page where %% is discussed, it's also noted as an exception to the general
rule; problem solved. printf() is a complex API. It's reasonable to expect that
people should read the documentation with some care.

Summary: there's nothing to fix here, so I'm not fixing it.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=55371

--- Comment #8 from Filipus Klutiero <chealer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
Few students will be given man printf to read in school. The vast majority of
consultations will happen when people try to interpret or write a call to
printf(). It is unlikely that these readers will read the entire page at once.

If the documentation says each conversion specifier asks for the next argument,
it is reasonable to expect that readers - whether careful or not - will
conclude that each conversion specifier asks for the next argument, unless they
read up to the point where this is contradicted.

If you think a note about exceptions would clutter, terminology can be used,
for example "regular conversion specifier" versus "special conversion
specifier".

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html