On 20/07/2026 11:46, Dmitri Seletski wrote:
Hello Devs of Coreutils,* * *Product:* Coreutils *Component:* Documentation *Summary:* Documentation Deficiency: |printf| man page lacks definitions for C format specifiers and fails to declare C-knowledge prerequisites. *Description:* The current |printf| man page contains a significant usability barrier in the DESCRIPTION section. The man page states: "...and all C format specifications ending with one of diouxXfeEgGcs, with ARGUMENTs converted to proper type first." This documentation is flawed for two specific reasons: 1. *Undefined Shorthand:* The string of characters |diouxXfeEgGcs| is presented without any definitions. A user cannot know which character corresponds to which data type without searching external sources. 2. *Undisclosed Prerequisites:* While it may be expected that a user of command-line utilities has some technical background, the manual fails to explicitly state that a working knowledge of C format specifications is a prerequisite for understanding this command. It assumes the user understands the jargon without warning them or providing a reference to the C standard. This creates a "knowledge trap" where the manual is no longer self-contained. It forces the user to leave the terminal and consult a different manual (the C standard) just to perform basic tasks with a core system utility. *Steps to reproduce:* 1. Run |man printf| in a terminal. 2. Navigate to the DESCRIPTION section. 3. Observe that |diouxXfeEgGcs| is used as a shorthand without any provided definitions or an explicit statement regarding the required prerequisite knowledge of C. *Suggested Fix:* Include a brief table or a descriptive list within the man page that defines these specifiers (e.g., d = signed decimal, s = string, etc.). Additionally, provide a clear reference or link to the C standard/format specification so users can understand the context of the command.
The "see also" has a reference to printf(3), which you can drill down to directly depending on you man page viewer, or view directly with `man 3 printf`. But I agree we should show that reference directly in the text. We need to be careful not to repeat too much info from the (large) printf(3) page, but I also agree that we could provide a little more info here. I'll look at: Using our recently improved man table formatting to present a conversion summary. Including at least mentioning that flags are supported. Also an EXAMPLES section would be useful here I think to show supported combinations. thanks, Padraig
