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

[Paul Eggert]

Bruno Haible <address@hidden> writes:

> Can you improve the wording here and in coreutils simultaneously?

OK, but let's start with coreutils since it's the user documentation
and is more visible.  Once this is done the gnulib patch should be
straightforward.

> > in the default C locale
> 
> But the code does it differently: It uses quotes `like this' also if not
> in the C locale and the two strings "`" "'" are not translated in the message
> catalog.

Surely that is an implementation detail that is unimportant to the
user.  From the user's point of view, if the strings are not
translated, that's the same as saying that "`" and "'" are appropriate
for the locale.

Here's the proposed patch to the coreutils documentation, which
reflects your other comments:

2004-02-09  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      9 Feb 2004 20:47:23 -0000
@@ -5922,29 +5922,39 @@ 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 names.  The quoting-style algorithm
+takes a file name as input, and outputs a quoted version of the input
+name.  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 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 for the shell if the input contains 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 for the shell, even if the input would normally not require
+quoting.
 @item c
-Quote names as for a C language string; this is the same as the
+Output a C character string literal, 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
+Output a C character string literal, 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
-locale.
+Output a C character string literal, 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
+Output a C character string literal, 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