From 296cc3ed96ed4924e75e4fbddd493c42b11a4f25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <P@draigBrady.com>
Date: Sun, 11 Aug 2024 14:36:21 +0100
Subject: [PATCH] doc: printf %b: clarify octal processing

* src/printf.c: Remove redundant comment.
State explicitly that the leading 0 is the exception
from normal escape processing.  Remove a full stop for consistency.
* doc/coreutils.texi (printf invocation): Add a reference
to C99 string escapes since these are not mentioned
in the referenced glibc printf info. Also explicitly state
the leading 0 exception.  Also use NNN rather than OOO
to be consistent with the --help documentation.
Also remove and extraneous '\' and fix grammar in the info
regarding the ninth bit.
Addresses https://bugs.gnu.org/72657
---
 doc/coreutils.texi | 12 +++++++-----
 src/printf.c       | 40 ++--------------------------------------
 2 files changed, 9 insertions(+), 43 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 00e401cbd..c1d0937af 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -13401,10 +13401,12 @@ printf @var{format} [@var{argument}]@dots{}
 
 @command{printf} prints the @var{format} string, interpreting @samp{%}
 directives and @samp{\} escapes to format numeric and string arguments
-in a way that is mostly similar to the C @samp{printf} function.
+in a way that is mostly similar to the C @samp{printf} function,
+and C language escape sequence processing.
 @xref{Output Conversion Syntax,, @command{printf} format directives,
 libc, The GNU C Library Reference Manual}, for details.
-The differences are listed below.
+See also @uref{https://en.cppreference.com/w/c/language/escape,
+C99 string escapes:}.  The differences are listed below.
 
 @mayConflictWithShellBuiltIn{printf}
 
@@ -13437,9 +13439,9 @@ one.
 @kindex %b
 An additional directive @samp{%b}, 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
-@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.  If
-@samp{\@var{ooo}} is nine-bit value, ignore the ninth bit.
+the @var{format} string, except that octal escapes should have a leading
+@samp{0} like @samp{\0@var{nnn}}.
+If @samp{@var{nnn}} is a nine-bit value, ignore the ninth bit.
 If a precision is also given, it limits the number of bytes printed
 from the converted string.
 
diff --git a/src/printf.c b/src/printf.c
index 7ac7a76ce..de3507925 100644
--- a/src/printf.c
+++ b/src/printf.c
@@ -14,42 +14,6 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
 
-/* Usage: printf format [argument...]
-
-   A front end to the printf function that lets it be used from the shell.
-
-   Backslash escapes:
-
-   \" = double quote
-   \\ = backslash
-   \a = alert (bell)
-   \b = backspace
-   \c = produce no further output
-   \e = escape
-   \f = form feed
-   \n = new line
-   \r = carriage return
-   \t = horizontal tab
-   \v = vertical tab
-   \ooo = octal number (ooo is 1 to 3 digits)
-   \xhh = hexadecimal number (hhh is 1 to 2 digits)
-   \uhhhh = 16-bit Unicode character (hhhh is 4 digits)
-   \Uhhhhhhhh = 32-bit Unicode character (hhhhhhhh is 8 digits)
-
-   Additional directive:
-
-   %b = print an argument string, interpreting backslash escapes,
-     except that octal escapes are of the form \0 or \0ooo.
-
-   %q = print an argument string in a format that can be
-     reused as shell input.  Escaped characters used the
-     POSIX $'' syntax supported by most shells.
-
-   The 'format' argument is re-used as many times as necessary
-   to convert all of the given arguments.
-
-   David MacKenzie <djm@gnu.ai.mit.edu> */
-
 #include <config.h>
 #include <stdio.h>
 #include <sys/types.h>
@@ -124,9 +88,9 @@ FORMAT controls the output as in C printf.  Interpreted sequences are:\n\
       fputs (_("\
   %%      a single %\n\
   %b      ARGUMENT as a string with '\\' escapes interpreted,\n\
-          except that octal escapes are of the form \\0 or \\0NNN\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.\
+          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\