doc: printf: provide usage examples

* src/printf.c (usage): List examples for each supported
conversion specifier.
* doc/coreutils.texi (printf invocation): Likewise.
Addresses https://bugs.gnu.org/81442

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 50afa99fc179b322f9961a0fca70146293980842..e90fb3e14c2713bbdfb3efd803d4377eb898b20a 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12951,12 +12951,39 @@ and C language escape sequence processing.
 @xref{Output Conversion Syntax,, @command{printf} format directives,
 libc, The GNU C Library Reference Manual}, for details.
 See also @uref{https://en.cppreference.com/w/c/language/escape,
-C99 string escapes:}.  The differences are listed below.
+C99 string escapes:}.
+
+Examples of supported conversion specifiers and flags are:
+
+@example
+CONVERSION  Shell format example        Output
+
+%s          '[%10s]' 'left pad'         [  left pad]
+%s          '[%-10s]' 'right pad'       [right pad ]
+%c %s       '%c %.3s' un unibyte        u uni
+
+%d %i       "%'d ;%i04i" 1234 '-1'      1,234 ;-001
+%o          '%#o' $((2#110100100))      0644
+%u          '%u' 0xFFFFFFFF             4294967295
+%x          '0x%08x' 11259375           0x00abcdef
+
+%a %f       '%1$a %1$f' 0.0009765625    0x8p-13 0.000977
+%e %f       '%1$e %1$f' 123.45678       1.234568e+02 123.456789
+%g          '%1$g %1$.2g' 1.2345678e3   1234.57 1.2e+03
+
+%b          '%bfoo' 'bar\cbaz' qux      bar
+%q          '%q ' 'a' ';b' $'c\n'       a ';b' 'c'$'\n'
+@end example
 
 @mayConflictWithShellBuiltIn{printf}
 
+The differences from the C @samp{printf} function are:
+
 @itemize @bullet
 
+@item
+Only the @samp{diouxXfaAeEgGcs} conversion specifiers are supported.
+
 @item
 The @var{format} argument is reused as necessary to convert all the
 given @var{argument}s.  For example, the command @samp{printf %s a b}

diff --git a/src/printf.c b/src/printf.c
index 5fb4c7c86ff783d3eb4174844792a169301848fc..09abe6a9413c95e897970e5a50a1b74ba9d43000 100644 (file)
--- a/src/printf.c
+++ b/src/printf.c
@@ -86,14 +86,39 @@ FORMAT controls the output as in C printf.  Interpreted sequences are:\n\
   \\UHHHHHHHH  Unicode character with hex value HHHHHHHH (8 digits)\n\
 "), stdout);
       fputs (_("\
+\n\
   %%      a single %\n\
   %b      ARGUMENT as a string with '\\' escapes interpreted,\n\
           except that octal escapes should have a leading 0 like \\0NNN\n\
   %q      ARGUMENT is printed in a format that can be reused as shell input,\n\
           escaping non-printable characters with the POSIX $'' syntax\
 \n\n\
-and all C format specifications ending with one of diouxXfeEgGcs, with\n\
-ARGUMENTs converted to proper type first.  Variable widths are handled.\n\
+and all C printf(3) format specifications ending with one of diouxXfaAeEgGcs,\n\
+with ARGUMENTs converted to proper type first.\n\
+"), stdout);
+      fputs (_("\
+FORMAT is reused to convert all specified arguments.\n\
+"), stdout);
+      fputs (_("\
+The following table shows supported conversion specifiers,\n\
+with examples including usage of width, precision, and flags.\n\
+\n\
+  CONVERSION  Shell format example        Output\n\
+  %s          '[%10s]' 'left pad'         [  left pad]\n\
+  %s          '[%-10s]' 'right pad'       [right pad ]\n\
+  %c %s       '%c %.3s' un unibyte        u uni\n\
+\n\
+  %d %i       \"%'d ;%i04i\" 1234 '-1'      1,234 ;-001\n\
+  %o          '%#o' $((2#110100100))      0644\n\
+  %u          '%u' 0xFFFFFFFF             4294967295\n\
+  %x          '0x%08x' 11259375           0x00abcdef\n\
+\n\
+  %a %f       '%1$a %1$f' 0.0009765625    0x8p-13 0.000977\n\
+  %e %f       '%1$e %1$f' 123.45678       1.234568e+02 123.456789\n\
+  %g          '%1$g %1$.2g' 1.2345678e3   1234.57 1.2e+03\n\
+\n\
+  %b          '%bfoo' 'bar\\cbaz' qux      bar\n\
+  %q          '%q ' 'a' ';b' $'c\\n'       a ';b' 'c'$'\\n'\n\
 "), stdout);
       printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
       emit_ancillary_info (PROGRAM_NAME);