Re: Undocumented values of ls --color

[Bjoern Voigt]

Hello Matthew,

> Bjoern Voigt wrote:
> >  Hello,
> >
> >  as I played a bit with the "--color" option of "ls" I found, that some
> >  values of "--color=WHEN" are undocumented.
> >
> >  The valid options of "--color=WHEN" are according to the source code
> >
> >  coreutils-7.0/src/ls.c:828:
> >
> >      static char const *const color_args[] =
> >      {
> >        /* force and none are for compatibility with another color-ls
> >  version */
> >          "always", "yes", "force",
> >      "never", "no", "none",
> >      "auto", "tty", "if-tty", NULL
> >      };
> >
> >  But "ls --help" only shows:
> >
> >        --color[=WHEN]         control whether color is used to distinguish
> >  file
> >                                 types.  WHEN may be `never', `always', or
> >  `auto'
> >        [...]
>
> I don't think this is an issue. The preferred values are 'never', 'always' 
> and 'auto'. The others have the same effect as one of these, and are provided 
> solely for compatibility with old aliases/shell scripts. Therefore I think 
> not documenting them is intentional, and not harmful.
>
> (In particular, '--color=tty' seems to be a common convention; my own aliases 
> even use that spelling of 'auto'.)
>
> >  Also the manual page is incomplete:
>
> The manpage is generated from --help, so it is not surprising they are the 
> same.

Thank you for the explanation.

But I don't think that having undocumented options (here: option
arguments) is a good option for Open Source software. We are not making
closed source software like Microsoft where undocumented options which
switch on hidden functionality and where hundreds of authors write
articles about hidden registry keys, options etc. Open souce users
expect that especially basic commands like coreutil commands work
perfectly and every behavior of this commands should be predictable and
well documented.

In my case I got the question "What do the colors mean in ls?" in nearly
all of my Linux courses. Of course documenting this is a task for the
Linux distributions (openSUSE in my case), because they setup the
dircolors. In the last course someone looked deeper into this and asked
me what "alias ls='ls $LS_OPTIONS'" and LS_OPTIONS="-N --color=tty -T 0"
mean. The answer I gave him was, that manual page editors may have
forgotten the value "tty" and that "tty" probably means the same like
"auto". But I did not really like my answer, and this was the reason why
I tried to explain you this issue.

One solution which is consistent to other coreutils commands may be to
accept the undocumented values of "--color", but print a warning. "cp
--reply=..." behaves like this.

I still would prefer to document the values "yes", "force", "no",
"none", "tty" and "if-tty" maybe with the hint, that this values are
deprecated.

But this is only a suggestion. I would not say, that this issue is
important, because the option arguments do not switch on hidden
functionality. And I do not really like big discussions about things
which could be fixed which 1-2 lines of text or code. :-)

Regards,
Björn