4.6.3 Output of `--help'

There is no parallel node in GNU Standards.

The output of the `--help' option is meant to be a meaningful reminder of the more comprehensive documentation available for any single program. It should be meaningful enough to go beyond a crude list of unexplained option letters. Even long option names are not really helpful when completely bare. It should also be only meant as a clear, concise, yet complete reminder, not trying in any way to replace the comprehensive documentation or make it unnecessary. However, users having already read the manual, or having a good level of familiarity with the program itself, should be usually satisfied with only the `--help' output, for day to day usage.

Some programs necessarily have an extensive `--help' output, because they have really many options, ls and stty come to mind. Others have very few options, like true. Despite these differences, all GNU programs respecting Gnits Standards have similar behaviour. The `--help' output is produced only through an explicit usage of the `--help' option, and is never produced as a side-effect of detecting bad usage, or missing arguments. The proper behaviour for usage errors is producing a possible diagnostic on standard error, followed by a one-line message, still on standard error, saying something like:

     Try `program --help' for more information.

with program replaced by the program name, of course. The diagnostic line preceding the `Try...' line should ideally mention the offending argument. It doesn't matter so much interactively, but when debugging shell scripts, where the arguments might be specified through several layers of variables and nested calls, it can really help pinpoint the culprit (letter from Karl, 1994-09-10).

The `--help' output from various programs should share a similar structure, which may contain the following items, usually in the order given:

• A synopsis of the program call, telling the overall syntax of the command. Suggestions for writing the synopsis are detailed below.
• A short reminder of the purpose of the program, explaining what it basically does, in very few lines. A single line is best. The synopsis comes first because the explanation may refer to variables in the synopsis (letter from Karl, 1995-05-11). If there are many synopsis, they may be referred to by expression like `the first form', `the second form', etc.
• A tabular presentation of all program options. This is usually the bulk of the `--help' output, and is also detailed further down.
• One or more paragraphs succintly describing default or implied values for various options, if not already stated above. This is also where is explained the meaning of missing files, or files being `-'.
• A quick sentence should introduce the main bug reporting address for this program, usually a generic bug reporting list, more than the individual address of the current maintainer. Like:

            Report bugs to <bug-gnu-utils@gnu.org>.
       

  Only for translated versions of this `--help' output, a second sentence might tell where to report linguistic problems for this translation, usually pointing to a whole translation team rather than to the precise author of the translation.

Here are some more rules applying to the whole `--help' output:

• There is a difficult equilibrium between concision and clarity, to the point writing proper `--help' output is a little art in itself. In favor of concision, keep in mind that `--help' output is no more than a reminder, and never aims to free users from reading the full documentation for the program. Users should feel `--help' output is concentrated information, with no verbiage ever in them. Clarity should be attained through very careful wording and illuminating disposition of the graphical output masses, more than through extended explanations.
• All text is left-justified. Avoid any centering. Never ever use double left-right justification for avoiding ragged right: with fixed width fonts as those use for `--help' output, this is known to decrease readability. Use only single spaces between words in sentences, and use exactly two spaces for a full stop, separating sentences in a paragraph. In a word, concision should never go as far as squeezing out spaces that are usual in writing text, as appropriate for the language being used.
• The `--help' output should not contain `--version' output (but it states the existence and purpose of the `--version' option). Since `--help' is usually called interactively, it is not useful to overly insist in the output about which program is being documented.
• Logical parts of the `--help' output should be separated with a single white line. Single white lines should also be used whenever it is felt their presence would subtantially increase readability.
• Feel comfortable using a tabular presentation for options or explanations, and assume that all program output may ask for a fixed width font display. That is, do not care about varying width fonts. However, for moving from one tabular margin to another, use only spaces and never <TAB>s, since tabulations are not always set the same way on all terminals.

  Also assume user displays have at least 79 characters, by having no line in your `--help' output which uses more than 79 characters.

• Tabulated material should always be introduced by one (or more) complete lines, would it be by a single word, like `Options:'. Most of non-tabulated text, as well as introduction to tables, should use no margin (and start all in column 0). Tabulated material should use an overall sub-margin of two spaces of margin (and start in column 2).
• For tabulated material using two columns, two margins are necessary. The first margin is set after two spaces from the far left, as stated above. The second margin should ideally be set exactly three spaces to the right of the rightmost character of the left column, yielding the visual impact that both columns are solid rectangular blocks separated by a white vertical line having three characters of thickness.

  A global table often have many subtables of two columns each, each subtable having its short introductory line. Each subtable should be set independantly, with no attempt to line up the second margin of all subtables. Having each subtable having its own second margin has the global effect of bolding the overall structure for the reader.

• In tabulated enumerations, use the comma as meaning alternative writings, rather than `|' or just spaces. It's better let the user feel that the comma systematically means alternation in all our `--help'. For example:

            The backup suffix is ~, unless set with SIMPLE_BACKUP_SUFFIX.  The
            version control may be set with VERSION_CONTROL, values are:
            
              t, numbered     make numbered backups
              nil, existing   numbered if numbered backups exist, simple otherwise
              never, simple   always make simple backups
       

Here are some rules for the synopsis:

• Begin with `Usage: ', with a mandatory capital, and a space after the colon. If there are several alternative syntaxes, begin the other lines with exactly ` or: '.
• The program name as extracted from argv[0]. Maybe we should consider systematically removing the path.

  The GNU standards dictate that most programs should not consider argv[0] for deciding their behavior. So it seems also reasonable that the name of a program be fixed, whatever its installed name. However, using argv[0] could help a little users on sites where binprefix is defined non empty, because a fixed name could be a little misleading on these sites.

• Keep the synopsis simple. Options will be detailed later, so do not detail right away all possible option letters or long names. Do not even stress that options start with an hyphen. Use nothing more than `[OPTION]...', after the program name, for announcing all options.
• In the synopsis, use capital letters for representing meta-variables and exact case for representing the rest. Do not use meta angle brackets for meta-variable. Do not just cluster meta-variables made of many words, as this often make them difficult to read. Use hyphens, rather than underlines, for separating words in meta-variable names (prefer `FROM-FILE' over `FROM_FILE' or `FROMFILE'). The context is such that there is almost no risk of ambiguity, as in practice, the hyphen never stands for itself.

  Using hyphens rather than underlines in this context has another free advantage: it eases separating between meta-variables and environment variables, later down in the `--help' output.

• Use square brackets for indicating that a parameter is optional, use ellipsis (three consecutive dots) after a symbol for indicating that it may be repeated one or more time. For indicating it may be repeated zero, one or many times, use brackets first, than ellipsis, as in:

            Usage: m4 [OPTION]... [FILE]...
       

• Avoid braces, asterisks, plusses, or vertical bars if you can.

The detailed list of options follow many principles, given here.

• Every option listed, long or short, must be listed with its argument if any (letter from Richard, 1994-03-31). In fact, the description should make clear whether options accept arguments or not. It might not be that useful repeating argument options both for short and long forms. 79 characters is often tight, and the problems we would create ourselves by spoiling the horizontal space needed for repetition is not reasonable. We could of course divert horizontal space into vertical space, somewhat loosing density and concision, but this is not a good choice.

  We want to really keep the `--help' output as concise as possible, yet being useful. In practice, this constraint can be a bit alleviated by an initial statement to the effect Mandatory or optional arguments to long options are mandatory or optional for short options too. The precise formulation has been much debated, yet it is difficult to keep it short. It really wants to mean that For any long option having a mandatory argument, the corresponding short option has a mandatory argument. For any long option allowing an optional argument, the corresponding short option allows an optional argument. Another good sentence would be: If an argument to a long option is mandatory, it's also mandatory for the corresponding short option; the same is true for optional arguments. (letter from Karl, 1995-02-15).

• When a program has many options, try regrouping options logically, instead of listing them all alphabetically (say), as the mere regrouping is a succint way to convey much information. Present each group of options in its own subtable, suitably introduced by some few words. Separate groups by white lines for making the overall structure more easy to grasp by the reader. Here is an excerpt from a relatively big `--help' output:

            Main operation mode:
              -t, --list              list the contents of an archive
              -x, --extract, --get    extract files from an archive
              -c, --create            create a new archive
              -d, --diff, --compare   find differences between archive and file system
              -r, --append            append files to the end of an archive
              -u, --update            only append files newer than copy in archive
              -A, --catenate          append tar files to an archive
                  --concatenate       same as -A
                  --delete            delete from the archive (not on mag tapes!)
            
            Device blocking:
              -b, --blocking-factor=BLOCKS   BLOCKS x 512 bytes per record
                  --record-size=SIZE         SIZE bytes per record, multiple of 512
              -i, --ignore-zeros             ignore zeroed blocks in archive (means EOF)
              -B, --read-full-records        reblock as we read (for 4.2BSD pipes)
       

• Some options have a value. Put `=' followed by a metavariable for the value, after the long option. If you have to document a short option with a value, do not use use such `=', prefer a space for the value to be a separate, or nothing if you prefer the value clustered with the option.
• When possible, use imperative sentences to document options' effects.
• Describe options even if they are deprecated, ignored, or useless. For example, some POSIX options may not really usable, but they are still available (letter from Ulrich, 1996-09-17). The user should be able to evaluate compatibility with non-GNU versions, or understand possible abbreviations of options, without having to do any great research.