New: printf: a conversion specifier doesn't necessarily ask for an argument
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/[email protected]
ReportedBy: [email protected]
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).
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Alan <alan-qBU/[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |RESOLVED
CC| |alan-qBU/[email protected]
Resolution|--- |INVALID--- Comment #1 from Alan <alan-qBU/[email protected]> --- That would be from glibc not the kernel I think ?
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Alan <alan-qBU/[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |CLOSED
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Filipus Klutiero <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|CLOSED |REOPENED
Resolution|INVALID |------ Comment #2 from Filipus Klutiero <[email protected]> --- 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.
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
CC| |[email protected]
Resolution|--- |CODE_FIX--- Comment #3 from Michael Kerrisk <[email protected]> --- (In reply to Filipus Klutiero from comment #0)
Quoted 4 lines
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.
Quoted 8 lines
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.
Quoted 1 line
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.
Quoted 3 lines
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
Signature · 5 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Filipus Klutiero <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |REOPENED
Resolution|CODE_FIX |------ Comment #4 from Filipus Klutiero <[email protected]> --- 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).
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |CODE_FIX--- Comment #5 from Michael Kerrisk <[email protected]> --- 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.
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Filipus Klutiero <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |REOPENED
Resolution|CODE_FIX |------ Comment #6 from Filipus Klutiero <[email protected]> --- 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.
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |WILL_NOT_FIX--- Comment #7 from Michael Kerrisk <[email protected]> --- 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.
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 55371] printf: a conversion specifier doesn't necessarily ask for an argument
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=55371
--- Comment #8 from Filipus Klutiero <[email protected]> --- 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".
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html