Re: [Bug-gnulib] quotearg styles (documentation patch for coreutils)

[Paul Eggert]

Jim Meyering <address@hidden> writes:

> Maybe it'd be better to let the quotearg.h documentation
> diverge a little from that of ls --quoting-style.

Yes, but in that case I'd like them to diverge as little as possible,
and I think the user documentation is more important to get "right" so
I'd rather focus on it first.

> I sort of liked `names'.
> Without something like that, a picky reader might
> ask whether this option makes ls output random strings.

But 'ls' sometimes does quote "random strings" that are not file names.

How about this patch instead?  It says that the strings are typically
file names, and then uses "strings" instead of "names" (and also
reflects most of Bruno's other comments too).

2004-02-10  Paul Eggert  <address@hidden>

        * doc/coreutils.texi (Formatting the file names):
        Improve wording for --quoting-style documentation.
        Suggestions by Bruno Haible.

Index: coreutils.texi
===================================================================
RCS file: /home/meyering/coreutils/cu/doc/coreutils.texi,v
retrieving revision 1.153
diff -p -u -r1.153 coreutils.texi
--- coreutils.texi      2 Feb 2004 13:20:52 -0000       1.153
+++ coreutils.texi      10 Feb 2004 18:10:05 -0000
@@ -5922,29 +5922,38 @@ in C.
 @item address@hidden
 @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
address@hidden, 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
address@hidden this'} instead of @t{"like
 this"} in the default C locale.  This looks nicer on many displays.
 @end table