Eric Blake writes: > > 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).
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. -- Alan Curry