(Formatting the file names):

Improve wording for --quoting-style documentation.
Suggestions by Bruno Haible.

1 files changed, 17 insertions, 8 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index d1ddc117e..8734108e3 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -5922,29 +5922,38 @@ in C.
 @item --quoting-style=@var{word}
 @opindex --quoting-style
 @cindex quoting style
-Use style @var{word} to quote output names.  The @var{word} should
+Use style @var{word} to quote file names and other strings that may
+contain arbitrary characters.  The @var{word} should
 be one of the following:
 @table @samp
 @item literal
-Output names as-is; this is the same as the @option{-N} or
+Output strings as-is; this is the same as the @option{-N} or
 @option{--literal} option.
 @item shell
-Quote names for the shell if they contain shell metacharacters or would
+Quote strings for the shell if they contain shell metacharacters or would
 cause ambiguous output.
+The quoting is suitable for @acronym{POSIX}-compatible shells like
+@command{bash}, but it does not always work for incompatible shells
+like @command{csh}.
 @item shell-always
-Quote names for the shell, even if they would normally not require quoting.
+Quote strings for the shell, even if they would normally not require quoting.
 @item c
-Quote names as for a C language string; this is the same as the
+Quote strings as for C character string literals, including the
+surrounding double-quote characters; this is the same as the
 @option{-Q} or @option{--quote-name} option.
 @item escape
-Quote as with @samp{c} except omit the surrounding double-quote
+Quote strings as for C character string literals, except omit the
+surrounding double-quote
 characters; this is the same as the @option{-b} or @option{--escape} option.
 @item clocale
-Quote as with @samp{c} except use quotation marks appropriate for the
+Quote strings as for C character string literals, except use
+surrounding quotation marks appropriate for the
 locale.
 @item locale
 @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
-Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like
+Quote strings as for C character string literals, except use
+surrounding quotation marks appropriate for the locale, and quote
+@t{`like this'} instead of @t{"like
 this"} in the default C locale.  This looks nicer on many displays.
 @end table