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

Hello Padraig,

This response means the world to me.

I would love to see more in the man page regarding octal (|%o|) and hex 
(|%x|) in the examples. Especially considering that while Bash can do 
hex math, it cannot natively format the output into those bases for display.

|printf| seems to be the only standard tool that can do this reliably.

|bc| does not get installed everywhere, so writing scripts that rely on 
it can be a liability. Being stuck on a certification exam on a 3rd 
party PC with no internet and no |bc| is definitely going to make you sweat!

Kind Regards,

Dmitri Seletski


On 20/07/2026 17:10, Pádraig Brady wrote:
> 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
>