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

[Jim Meyering]

Paul Eggert <address@hidden> wrote:
> 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

How about saying `name' or `file name' instead of `input' here -- and below?
`input' doesn't really mean what we want.

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

>  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.

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