bug#7433: ls: [manual] description for --directory is insufficient

[Jari Aalto]

Package: coreutils
Version: 8.5-1
Severity: normal

[Forwarded from http://bugs.debian.org/603895 ]

Manual page of ls(1) reads:

       -d, --directory
              list directory entries instead of contents, and do not  derefer-
              ence symbolic links

"info ls" reads:

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

None of these is helpful in understanding how the option is supposed
to work:

    ls -d
    ls -dR
    ls -dr
    ls --directory -R
    ls --directory -r
    ls --directory

    => They all just return '.'

After lot of Google, a miracle command syntax is found:

    ls -d */

Please improve the documentation and give examples. Btw, the command
syntax "*/" is counterintuitive to rest of the ls(1) behavior:

       ls -a    vs.    ls -d

-- System Information
Debian Release: squeeze/sid
  APT Prefers testing
  APT policy: (990, testing) (500, unstable) (1, experimental)
Architecture: amd64
Kernel: Linux picasso 2.6.32-5-amd64 #1 SMP Fri Sep 17 21:50:19 UTC 2010 x86_64 
GNU/Linux
Locale: LANG=en_DK.UTF-8

-- Versions of packages `coreutils depends on'.
Pre-Depends:
libacl1         2.2.49-4        This package contains the libacl.so dynamic l
libattr1        1:2.4.44-2      Contains the runtime environment required by 
libc6           2.11.2-7        Contains the standard libraries that are used
libselinux1     2.0.96-1        This package provides the shared libraries fo