Interactive command usage reference: do you generally have that on Unix?

Question

The question of why some commands rely on manpages whereas others rely on something like the --help flag for providing command usage reference is not new. There is usually a difference in scope between documentation for a command and a command usage synopsis. The latter is often a subset of the former. But even when most commands and utilities have manpages for instance, there exists differences in their formatting of the synopsis section which have very practical implications when trying to extract such information. In other cases one might find clues with the strings utility when a command has seemingly no documentation.

I was interested with the commands I have on this QNX platform and discovered the use command¹ to display usage information. As explained in usemsg, the framework involves setting a standard usage record in the utilities source and once compiled this can be accessed with the use command and you can also wrap the native functionality etc. It is quite convenient as I could simply do

use -d dir >>file

on /base and /proc/boot to extract all the usage for all the commands on the system basically.

So I then briefly looked at the source for GNU coreutils ls and FreeBSD ls to see if they did something like that and the former puts usage information in some usage named function(for --help I guess) while the latter doesn't seem to put it anywhere at all(?).

---

• Is this sort of solution(use) typical of what you find with commercial Unix to present command usage reference interactively?
• Does POSIX/SUS recommend or suggest anything about presenting/implementing command usage reference in commands(as opposed to specifying notation for shell utilities)?

---

^{1.use command:}

use
Print a usage message (QNX Neutrino)

Syntax:
use [-aeis] [-d directory] [-f filelist] files

Options:
-a
    Extract all usage information from the load module in its source form, suitable for piping into usemsg. 
-d directory
    Recursively display information for all files under directory. 
-e
    Include only ELF files. 
-f filelist
    Read a list of files, one per line, from the specified filelist file, and display information for each. 
-i
    Display build properties about a load module. 
-s
    Display the version numbers of the source used in the executable. 
files
    One or more executable load modules or shell scripts that contain usage messages. 

Answer 1

Commercial unices generally present usage information only in man pages. Having the command itself display usage information is not a traditional Unix feature (except for displaying the list of supported options, but without any explanation, on a usage error). POSIX and its relatives don't talk about anything like this.

Having a --help option that displays a usage summary (typically a list of options, one per line, with a ~60 characters max description for each option) is a GNU standard. As far as I know, this convention was initiated by the GNU project, as part of the double-dash convention for multi-letter option names. There are other utilities, such as X11 utilities, that use multi-letter option names with a single dash and support -help; I don't know which one came first.

The use command is a QNX thing.

Answer 2

You refer to the GNU tools in your example. These are available on Linux, and many other platforms, and are somewhat unusual in terms of documentation.

The GNU tools, actually seem to have three levels of increasingly detailed interactive reference:

--help as a common command option - a short usage summary,
man - the classic man pages, a "quick reference", and
info - a more detailed, GNU-speciffic manual - the full, official documentation.

Often, one just uses the man page as the defauls documentation - even when knowing thay "they say" the GNU info documentation is more detailed and official.

It will be varry a little based on preferences, but I think the following usage pattern is pretty common:

• using man foo by default,
  • with an explanation of all options
  • sometimes feels a little terse, but good enough
• use foo --help sometimes, for small questions, as being unsure about an option name,
  
  • with a short summary in compact layout
• and use info foo... almost never.
  • which would probably provide some more context details, and links to other commands
  • but nobody can use the emacs-style info browser UI, so we'll not find out exactly.
• and otherwise network based documentation,
  • like if the man page was too terse.

There is, however, one catch:

For the most often used commands, from the package coreutils, like ls, cp, mkdir, csplit and many more,

the man page man foo contains exactly the same information as foo --help. ⁽¹⁾

That means the 'real documentation', in fact, not in the man pages - as we thought...
It is actually in the GNU info files we did not read!

Now, looking at both man page and (the lower part of) --help, it's hard to notice that the content is the same, because the man page looks so "more detailed". It's because the difference in text layout density is very large between the two variants. Extremely compressed in --help, compared to extremely relaxed spacing in man.

Compare for yourself, it's impressive:

ls --help | less

man ls | less

info --subnodes ls | less

(The option --subnodes renders the page lineary, for comparison. In itself, info shows hypertext, linked between documents similar to HTML. The man command includes less to force non-colored output for easier comparison.)

---

Some related hints:

There are more comfortable alternatives to the default info viewer info, like - for the terminal - pinfo, or - for the GUI - konqueror. Example use like this:
pinfo ls or konqueror info:ls or using info:ls in the url bar of konqueror.

As a special case, the documentation of the internal commands of GNU bash,
which are called shell builtins, can be accessed with the help command.
For example, on the command line of bash, try
help cd

---

_{1) Fortunately, @PádraigBrady pointed that out in his answer}

Answer 3

Note GNU coreutils man pages are generated from $cmd --help

Also note that bash builtins at least don't support --help. There you need to use help umask for example. Now POSIX allows, and ksh at least uses umask --help. It was proposed recently that bash might also accept this syntax