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.