bug#81442: Documentation Deficiency: printf man page lacks definition of format specifiers

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