Subject: Re: bug#14189: ls -d bug ??

From: Bob Proulx <[email-masked]>
Date: Thu, 11 Apr 2013 23:42:37 -0600

Bob Proulx wrote:
>   10.1 `ls': List directory contents
>   ==================================
> 
>   The `ls' program lists information about files (of any type, including
>   directories).  Options and file arguments can be intermixed
>   arbitrarily, as usual.
> 
>      For non-option command-line arguments that are directories, by
>   default `ls' lists the contents of directories, not recursively, and
>   omitting files with names beginning with `.'.  For other non-option
>   arguments, by default `ls' lists just the file name.  If no non-option
>   argument is specified, `ls' operates on the current directory, acting
>   as if it had been invoked with a single argument of `.'.

That does seem like it could use some improvement.  It makes the
mistake of "burying the lead" by putting that last sentence so far
down.  I like the BSD man page version much better.  Is there a way we
can simplify this but still keep it descriptive?  The FreeBSD man page
is much better for this description.

How about this?  (I will work it up into a texinfo patch afterward.)

  The `ls' program lists information about files.  If the file being
  listed is a directory then the contents of the directory is listed.

  If no non-option command-line arguments are specified then 'ls'
  operates on the current directory, acting as if it had been invoked
  with a single argument of `.'.  `ls' is the same as `ls .'.

  For each non-option command-line argument that is not a directory
  `ls' lists the file name.  For each non-option command-line argument
  that is a directory `ls' lists the names of files in the directory.
  Files starting with a '.' are ignored and hidden.

WDYT?

> `-d'
> `--directory'
>      List just the names of directories, as with other types of files,
>      rather than listing their contents.  Do not follow symbolic links
>      listed on the command line unless the `--dereference-command-line'
>      (`-H'), `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are specified.

And then perhaps this following.  Also the above does not describe the
interaction with -R.

Option 1:

  `-d'
  `--directory'
     Do not list the contents of directories.  List only the name.  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').

Option 2 with much more description:

  `-d'
  `--directory'
     Do not list the contents of directories.  List only the name.
     Without this option any non-option command-line arguments that
     are directories are treated specially and instead of the name the
     contents are listed.  This option turns that behavior off and
     directories are only listed by name, the same as any
     non-directory file.  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').

I like the conciseness of the first.  But the extra description in the
second seems useful.

WDYT?

Bob