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 command1 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:

Print a usage message (QNX Neutrino)

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

    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. 
    Include only ELF files. 
-f filelist
    Read a list of files, one per line, from the specified filelist file, and display information for each. 
    Display build properties about a load module. 
    Display the version numbers of the source used in the executable. 
    One or more executable load modules or shell scripts that contain usage messages. 

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.

  • 1
    So we've been spoiled with the extra GNU features on user-friendly Linux and surprisingly here with QNX! They had the plus sign before for the long options. I had not distinguished --help vs. displaying options on errors i.e. sometimes I enter --help but it's because a command may not understand the option that it lists them. I cannot do +2. Thanks! – user44370 Jul 29 '14 at 21:41

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. (1)

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

  • +1 wc puts it into perspective i.e. what's required to use a command vs. a full text vs. a text which expands on the features...Thanks! – user44370 Jul 29 '14 at 3:30
  • It might also be useful to include something like a 3.5 - GNU Emacs provides support for Emacs specific info extensions like the colorization added by their source-highlight libraries and contextually aware menus and expandable content. At least, that's what my boring monochrome info info tells me as I read it in frustration. – mikeserv Jul 29 '14 at 3:59
  • It's generated directly from the output of --help after compiling, with help2man. See this... – user44370 Jul 30 '14 at 8:54
  • 1
    @illuminÉ Thanks, interesting. I should make another question from all that, to not hide the interesting parts down here ;) And, btw, I like you style of making your statements and citing your sources. – Volker Siegel Jul 30 '14 at 11:22

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

  • Thanks, I see... at first, I did not think that is the case at least with ls - but after a closer look, that's right, the man page and the --help output actually contain the same text! Just in either light or compressed layout. So, my numbers just were invalidated... let's see... ;) – Volker Siegel Jul 29 '14 at 22:05
  • 1
    The sections "author", "copyright" and "see also" are generated by the manpage template system - not really content. The interesting point is, that not man ls was used to write ls --help, but the other way around. The whole nice manpage, feeling like "some real piece of documentattion", is exactly the same as the usage message of the command. As you can see in my answer, I did not expect that! – Volker Siegel Jul 30 '14 at 2:35
  • @VolkerSiegel I now see what you mean with the command.x files in the coreutils source tree. Many seem to be build by leveraging the content from the usage() in the .c files or elsewhere. It is not something static. I did not know this either! Thanks for explaining! – user44370 Jul 30 '14 at 3:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy