bug#14189: ls -d bug ??

[Bob Proulx]

Bernhard Voelker wrote:
> Bob Proulx wrote:
> >   `-d'
> >   `--directory'
> >      List only the name of directories, not the contents.  This is
> >      most typically used with `-l' to list the information for the
> >      directory itself instead of its contents.  Do not follow symbolic
> >      links unless the `--dereference-command-line' (`-H'),
> >      `--dereference' (`-L'), or
> >      `--dereference-command-line-symlink-to-dir' options are
> >      specified.  Overrides `--recursive', (`-R').
> 
> Not bad, but I'm still missing the point that `-d' changes ls's behavior
> for *directory arguments* only.

Hmm...  "If an argument is a directory then list only the name of the
directory not the contents.  Otherwise list the name of the file
normally."

Showing this around I had one person who was shocked to learn that
directories were files.  They really wanted this written so that it
acted as if directories and files were completely different things.
I countered that since directores were files, special files, that we
shouldn't make the documentation lead people astray just to make it
fit a wrong model of the machine.

> Furthermore, I don't think mentioning `-l' is of much relevance here.
> So this would melt down the first two sentences as follows:
> 
>   `-d'
>   `--directory'
>      For directory arguments, list only the information for the
>      directory itself instead of its contents.  Do not follow symbolic
>      links unless the `--dereference-command-line' (`-H'),
>      `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are
>      specified.  Overrides `--recursive', (`-R').
> 

That comment made the person who I worked with wordsmithing that line
very sad.  She was adamant that that tidbit about -l was the only
useful part of the option description.  And I think I agree that for
someone reading the documentation and learning about it that the
connection between -d and -l is important to point out explicitly.
Maybe not this way but in some way I think we need to tie those two
concepts together.

> And what about the usage() string?  I'd bet this is still 95% where
> users are looking for. Something like the following perhaps?
> 
> -  -d, --directory            list directory entries instead of contents,
> -                               and do not dereference symbolic links
> +  -d, --directory            for directory arguments, list the entry itself
> +                               instead of contents, and do not dereference
> +                               symbolic links

I think that is definitely an improvement.  Because "entries" in the
original I think isn't descriptive enough and makes people think
contents instead of just the argument name.  But frankly I still don't
think it flows very well.

If we are already pushed into three lines then let's make use of them.

 -d, --directory              for directory arguments, list the name
                                instead of contents, and do not
                                dereference symbolic links

Or perhaps better is:

 -d, --directory              for directory arguments, list the directory
                                name instead of directory contents,
                                and do not dereference symbolic links

Looking through other options for style I see:

  -L, --dereference          when showing file information for a symbolic
                               link, show information for the file the link
                               references rather than for the link itself

That entry has the same challenge.  It is much wordier.  The "when
showing file information for a symbolic link" is the same task as our
"when showing file information for a directory".  I like the shorter
version "for symbolic link arguments" form.  Perhaps as a separate
improvement we could change it to:

  -L, --dereference          for symbolic link arguments, show information
                               for the target instead of for the link itself

And then perhaps while gaining consistency of description without
decreasing the usefulness of either entry we would gain back the line
that we used above.

Bob