printf: support the %q format to quote for shell

* src/printf.c (usage): Mention the new format.
(print_formatted): Handle the quoting by calling
out to the quotearg module with "shell-escape" mode.
* doc/coreutils.texi (printf invocation): Document %q.
* tests/misc/printf-quote.sh: New test.
* tests/local.mk: Reference new test.
* NEWS: Mention the new feature.

1 files changed, 9 insertions, 1 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 177379b38..8618a6457 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12075,7 +12075,7 @@ one.
 
 @item
 @kindex %b
-@command{printf} has an additional directive, @samp{%b}, which prints its
+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
@@ -12084,6 +12084,14 @@ If a precision is also given, it limits the number of bytes printed
 from the converted string.
 
 @item
+@kindex %q
+An additional directive @samp{%q}, prints its argument string
+in a format that can be reused as input by most shells.
+Non-printable characters are escaped with the POSIX proposed @samp{$''} syntax,
+and shell metacharacters are quoted appropriately.
+This is an equivalent format to @command{ls --quoting=shell-escape} output.
+
+@item
 Numeric arguments must be single C constants, possibly with leading
 @samp{+} or @samp{-}.  For example, @samp{printf %.4d -3} outputs
 @samp{-0003}.