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

Thanks for the report.

Which is generated from the 'ls --help' output.

The wording for -d may not mention it, but the wording at the very
beginning of the --help and man page is clear that:

| Usage: ls [OPTION]... [FILE]...
| List information about the FILEs (the current directory by default).

That is, 'ls -d' is the same as 'ls -d .', as required by POSIX, at
which point you are listing the current directory as a file, and not the
contents of the current directory.

When listing directories as files (-d), no recursion (-R) takes place
because no directories are encountered, just files.  Again, this
behavior is required by POSIX.

What wording change, if any, can you propose for the --help output that
would not make things too verbose for what is supposed to be a quick
reference?

Yes, that says list all directories (and symlinks to directories) in the
current directory, that don't start with leading ., as a file.

Yes, comparing these two in the info pages would be a useful addition
(although I'm not sure that we should bloat the already-long --help
output for this).  Could you propose a patch?

"*/" is not a required aspect of -d. A trivial example is the difference
between "ls /" and "ls -d /".

Mike Stone

Eric Blake writes:

In other words, to correctly predict the behavior of "ls -d" you must
read two pieces of information that are not immediately adjacent to each
other, and use a minimal amount of thought to decide whether and how
they influence each other.

For people who read documentation all the way through, knowing that a
thorough understanding of the available tools will be a long-term
benefit, this is not a problem. Let's call these people the "smart
bears". They'll get the garbage can open easily because they're patient.

For people who only skim documentation, and not even that until they
have a problem, the obstacle is larger. If there isn't a single sentence
that tells them everything they need to know, they're not going to get
it. Let's call these people the "dumb tourists". They're impatient with
the garbage can latch, because they're holding a smelly bag of garbage.

Smart bears see a thick instruction manual and say "Hooray! Proper
documentation! I won't have to guess how it works." Dumb tourists see a
thick instruction manual and say "Screw that, reading sucks, I can guess
how it works."

man pages are written by and for smart bears. Dumb tourists don't write
documentation. Sometimes they write web pages which they optimistically
call "documentation".

Making documentation dumb-tourist-friendly inevitably makes it longer,
because it has to have a clause for each goal that the reader might want
to achieve, instead of just listing the facts and expecting the reader
to be able to put them together. The increased length bothers the smart
bears since it increases the time required to read the documentation
all the way through.

In the case of ls, I suggest that -d is special enough (since it affects
how the non-option arguments are used, unlike other ls options) that a
little extra length is justified. It would be reasonable to provide 2
separate SYNOPSIS lines, something like this:

SYNOPSIS
        ls [OPTION]... [FILE]...
        ls -d [OPTION]... [FILE]...

DESCRIPTION
        The first form lists the given FILEs, and if any of them are
        directories, the directory contents are listed. If no FILEs are
        given, the contents of the current directory are listed.

        The second form (with -d) lists the given FILEs, but any FILE
        that is a directory will not have its contents listed. With no
        FILEs given, the current directory (not its contents) is listed.

I don't care how you'd translate that to/from --help. I care about man
pages, not --help.

If that seems like giving too much attention to -d, how about this
alternative: add an EXAMPLES section. Dumb tourists love EXAMPLES
sections, and smart bears can safely skip them. It's a little bit
ridiculous that cat(1) has examples and ls(1) doesn't. ls has a lot more
options.

And the conflict between -R and -d should be explicitly mentioned. One
of them makes the other meaningless, and we should say which one.