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
