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