"printf" documentation clarifications

[Paul Eggert]

I installed this documentation to clarify how "printf" behave.

2004-08-18  Paul Eggert  <address@hidden>

        * coreutils.texi (printf invocation): Clarify how "printf" is
        supposed to work with extra arguments, missing arguments, etc.

Index: coreutils.texi
===================================================================
RCS file: /home/eggert/coreutils/cu/doc/coreutils.texi,v
retrieving revision 1.199
retrieving revision 1.200
diff -p -u -r1.199 -r1.200
--- coreutils.texi      10 Aug 2004 22:07:31 -0000      1.199
+++ coreutils.texi      18 Aug 2004 20:22:32 -0000      1.200
@@ -9101,9 +9101,60 @@ printf @var{format} address@hidden@dot
 @end example
 
 @command{printf} prints the @var{format} string, interpreting @samp{%}
-directives and @samp{\} escapes in the same way as the C @command{printf}
-function.  The @var{format} argument is re-used as necessary to convert
-all of the given @var{argument}s.
+directives and @samp{\} escapes to format numeric and string arguments
+in a way that is mostly similar to the C @samp{printf} function.  The
+differences are as follows:
+
address@hidden @bullet
+
address@hidden
+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}
+outputs @samp{ab}.
+
address@hidden
+Missing @var{argument}s are treated as null strings or as zeros,
+depending on whether the context expects a string or a number.  For
+example, the command @samp{printf %sx%d} prints @samp{x0}.
+
address@hidden
address@hidden \c
+An additional escape, @samp{\c}, causes @command{printf} to produce no
+further output.  For example, the command @samp{printf 'A%sC\cD%sF' B
+E} prints @samp{ABC}.
+
address@hidden
+The hexadecimal escape sequence @address@hidden has at most two
+digits, as opposed to C where it can have an unlimited number of
+digits.  For example, the command @samp{printf '\x07e'} prints two
+bytes, whereas the C statement @samp{printf ("\x07e")} prints just
+one.
+
address@hidden
address@hidden %b
address@hidden has an additional directive, @samp{%b}, which prints its
+argument string with @samp{\} escapes interpreted in the same way as in
+the @var{format} string, except that octal escapes are of the form
address@hidden@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
+If a precision is also given, it limits the number of bytes printed
+from the converted string.
+
address@hidden
+Numeric arguments must be single C constants, possibly with leading
address@hidden or @samp{-}.  For example, @samp{printf %.4d -3} outputs
address@hidden
+
address@hidden
address@hidden POSIXLY_CORRECT
+If the leading character of a numeric argument is @samp{"} or @samp{'}
+then its value is the numeric value of the immediately following
+character.  Any remaining characters are silently ignored if the
address@hidden environment variable is set; otherwise, a
+warning is printed.  For example, @samp{printf "%d" "'a"} outputs
address@hidden on hosts that use the @acronym{ASCII} character set, since
address@hidden has the numeric value 97 in @acronym{ASCII}.
+
address@hidden itemize
 
 @vindex LC_NUMERIC
 A floating-point argument must use a period before any fractional
@@ -9112,14 +9163,8 @@ current locale.  For example, in a local
 comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
 the command @samp{printf %g 3,14} is an error.
 
address@hidden has one additional directive, @samp{%b}, which prints its
-argument string with @samp{\} escapes interpreted in the same way as in
-the @var{format} string, except that octal escapes are of the form
address@hidden@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
-
 @kindex address@hidden
 @kindex address@hidden
-
 @command{printf} interprets @address@hidden in @var{format} as an octal number
 (if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
 and @address@hidden as a hexadecimal number (if @var{hh} is 1 to 2 hex
@@ -9139,10 +9184,6 @@ The processing of @samp{\u} and @samp{\U
 @code{iconv} facility.  It is activated on systems with glibc 2.2 (or newer),
 or when @code{libiconv} is installed prior to this package.  Otherwise the
 use of @samp{\u} and @samp{\U} will give an error message.
-
address@hidden \c
-An additional escape, @samp{\c}, causes @command{printf} to produce no
-further output.
 
 The only options are a lone @option{--help} or
 @option{--version}.  @xref{Common options}.