Command line help, as often provided through --help is an important means of communication with the user. It provides a shorthand for more detailed documentation and feature discovery.
Help documentation must include:
Help documentation may additional include the following sections (as needed):
Each section of this example is described in detail later in this document. (Note that blast is not a real tool).
Usage: blast [-f] [-s <scribble>] <command> [<args>] Destroy the contents of <file>. Options: -f force, ignore minor errors. This description is so long that it wraps to the next line. -s <scribble> write <scribble> repeatedly -v, --verbose say more. Defaults to $BLAST_VERBOSE. Commands: blow-up explosively separate grind make smaller by many small cuts help get help on other commands e.g. `blast help grind` Examples: Scribble 'abc' and then run |grind|. $ blast -s 'abc' grind old.txt taxes.cp Notes: Use `blast help <command>` for details on [<args>] for a subcommand. Error codes: 2 The blade is too dull. 3 Out of fuel.
See above for an example that follows these requirements.
Several sections call for English prose. This means writing in proper sentences using English grammar with US English spelling (as opposed to British English or others). Use one space between sentences, and adhere to the “Oxford comma” style. E.g. “The Description, Examples, and Notes sections are written in English prose.”
Layout
Usage: blast <file>”.Style
--verbose when running --help or direct them to the full documentation.Usage is required and includes the “Usage:” header.
Usage: blast [-f] [-s <scribble>] <command> [<args>]
Usage will commonly be a single line, though multiple lines can be used to clarify when options are mutually exclusive. If the number of lines needed to present all the mutually exclusive scenarios becomes excessive, limit the lines to some common cases and give more details in the full docs. If there are many mutually exclusive options, consider making subcommands or separate tools to reduce the complexity.
The command name is listed first. The command name is not hardcoded: it will be dynamically pulled from the command name, i.e. the last element on the argv[0] path. This allows a single binary to operate as multiple different tools.
The name and usage text will contain portable ASCII characters only. All long form commands are entirely lowercase, i.e. never all-caps or mixed-case. Single letter switches should prefer lowercase, but uppercase is allowed.
Use meaningful words for options and placeholders. Avoid abbreviations. Prefer single words. When more than one word is used, separate words with a hyphen (-), i.e. do not use underscores, camel-case, or run words together.
Aside from the command name there are several kinds of arguments (as described in Fuchsia Tool Requirements).
Exact text is written as-is in the usage line. In the example “Usage: copy <from> to <destination>”, the word to is required exact text. If exact text is optional, it will be enclosed in brackets ([]) in the usage line: “Usage: copy <from> [to] <destination>”.
Arguments are enclosed in angle brackets (<>) to differentiate them from explicit text. In the example Usage: copy <from> <destination>, both <from> and <destination> are arguments. If an argument is optional, it will be enclosed in brackets ([]) such as: Usage: copy <from> [<destination>]. See also Option Delimiter.
There are a couple choices when illustrating mutually exclusive options.
If more than one usage line is provided, each will show a mutually exclusive set of commands. For example:
Usage: swizzle [-z] <file> swizzle --reset
Indicates that --reset and usage with a <file> are mutually exclusive options.
Another way to specify mutually exclusive options is using a vertical bar (‘|’) between the options. Note that when a vertical bar is used to indicate data flow between processes it is called a “Pipe.” When used to separate options it is read as “Or”.
For example:
Usage: froth [-y|-z] <file>
Indicates that -y or -z switches can be used (or neither, since they are optional), but it's senseless to use both together (they are mutually exclusive options). To indicate that either value must be used, but not both, wrap the choices in parentheses, e.g. “Usage: froth (-a|-b) <file>” means that -a or -b must be passed.
Note that it's common that --version or --help causes other arguments to be ignored and is seldom listed as such. Listing them as separate usage lines is considered unnecessary.
There is no specific syntax to indicate when enabling one option will also affect another option. When an option implies that another option is enabled or disabled, specify that in the Options. E.g. “passing -e implies -f” means that if -e is enabled, -f will be enabled as if it were passed on the command line (regardless of whether -f was explicitly passed). The redundant passing of the implied value is harmless (not an error).
Document the implication in the primary switch. E.g. if -x implies -c and -p place that note in the description of -x but not in -c and -p. This is to keep the --help output concise (this rule can be relaxed in the full documentation).
To create the appearance of a keyed option with an optional Key, create optional exact text followed by an argument. For example “Usage: copy [from] <from> [to] <destination>”. In the example, all of these are valid: “copy a b”, “copy from a b”, “copy from a to b”, “copy a to b”.
If the same positional argument may be repeated, indicate that with an ellipsis (‘...’). Rather than a Unicode ellipsis, use three consecutive periods. For example: “Usage: copy <from> [<from>...] <to>” means the last argument is always interpreted as the <to>, while the preceding values are multiple <from> entries. Note that “<from> [<from>...]” means there is one or more <from> entries, while “Usage: copy [<from>...] <to>” means zero or more <from> entries are accepted.
For Key/Value pairs that may be repeated, group them with brackets (if the pair is optional) or parentheses (if the pair is not optional) and add an ellipsis to the group, e.g. [--input <file>]... or (--input <file>)... respectively.
Angle brackets (<>), brackets ([]), and parentheses (()) will not have spaces immediately inside.
[from] # correct <to> # correct (-a|-b) # correct [ from ] # incorrect < to > # incorrect ( -a|-b ) # incorrect
Angle brackets (<>) wrap Arguments or Key values.
Brackets ([]) wrap optional elements. With nested angle brackets, such as [<file>], interpret the <file> as an Argument that is optional. The nested “[<” is not a separate bracket style, it is a “[” with a “<” within it. When nesting, the brackets ([) will be outermost (do not use <[file]>).
Parentheses (()) are used to group elements. Use parentheses when they improve clarity, such as with required mutually exclusive options.
Braces ({}) are reserved for future use. This guide intentionally leaves open the possibility for braces to have special meaning in a future revision of this document.
The description is required and does not include a header. I.e. the description area is not labeled “description”. E.g.
Destroy the contents of <file>.
The description is written in US English prose (complete sentences using US English grammar, spelling, and punctuation).
Every tool should tell you what it does and this is the section to do that.
The Description section should describe
The Description section can also contain a “see also” referring to another tool by name (avoid using a URL).
What not to put in the Description section
--help)--help)help subcommand)An Options section is required if the program accepts arguments. E.g.
Options: -f force, ignore minor errors -s <scribble> write <scribble> repeatedly. Defaults to $BLAST_SCRIBBLE.
The listed options apply to the tool itself and not to a subcommand. Options for individual subcommands are listed when requesting help for that subcommand, e.g. when using blast help grind or blast grind --help.
Try to keep options to a single, complete word. If two words are needed, separate the words with a hyphen (-). Avoid uncommon abbreviations.
Present the list of options in alphabetical order.
Options will list each argument, switch, and keyed option on separate lines with the exception of arguments that have both a short and long form. If an argument has both a short and long form they are listed on the same line, short form first, and separated by , (comma space), e.g. -f, --force.
Exact text arguments will not be listed in the Options section. They are shown in the Usage section.
Text that will be typed as-is is not wrapped in brackets, while variable entries appear in angle brackets (<>) and optional entries appear in square brackets ([]). When listing options, the Key is never optional. For example:
-a a good example [-b] a bad example, to use -b it must be typed as-is
A short description will follow each option. There's no limit on the length of this description, but be concise. Try to put more details in the overall tool description, the Examples, or the Notes instead of creating a lengthy option description.
What to describe
ignore minor errors-x implies -c and -pdefaults to $BLAST_SCRIBBLEThe column on which the description sentence fragment begins may vary depending on the needs of the tool. Use 20 characters from the left edge if it looks okay, but adjust if a bit more or less reads better.
If there is a large number of options, consider showing a useful subset and explaining how to get further help to see all of them, e.g. by passing --verbose along with --help.
A commands section is required if the program has subcommands. If present it will be labeled, “Commands:”. E.g.
Commands: blow-up explosively separate grind make smaller by many small cuts help get help on other commands e.g. `blast help grind`
If the program does not have subcommands, the commands section will not be present.
When a tool has subcommands, it will also have a help command to get further help on the subcommands, i.e. blast help grind.
Try to keep subcommands to a single, complete word. If two words are needed, separate the words with a hyphen (-). Avoid uncommon abbreviations. Present the list of commands in alphabetical order.
Each command name appears with a short description on a separate line. For a more lengthy command description, the user will specifically ask for help on that command. This description serves as a short reminder of the command and to assist in discovery of commands.
If there is a large number of commands, consider showing a useful subset and explaining how to get further help to see all of them, e.g. by passing --verbose along with --help.
An examples section is optional. If present it will be labeled, “Examples:”. E.g.
Examples: Scribble 'abc' and then run |grind|. $ blast -s 'abc' grind old.txt taxes.cp
Each example will have US English prose (i.e. complete sentences using US English grammar, spelling, and punctuation) describing the example, followed by an example command line. Each line that would be entered on the command line literally will be prefixed with a “$ ” to mimic a command prompt.
To wrap an example that is overly long, end the previous line with “\ ” and begin subsequent lines with “ ” (spaces) to indicate line continuation.
This example wraps onto multiple lines. $ blast -s 2332 some/long/path/cats.o \ more/long/path/dogs.o more/long/path/bears.o \ more/long/path/deer.o
If it is helpful to show some of the output from the example command, write the output immediately following the example.
Separate examples with one blank line.
If the Examples section is getting overly long, move examples to a help doc. Interactive help examples are for quick reference and discoverability rather than exhaustive documentation.
Notes are optional and begin with a “Notes:” header. E.g.
Notes: Use `blast help <command>` for details on [<args>] for a subcommand.
The notes are written in US English prose (i.e. complete sentences using US English grammar, spelling, and punctuation).
What to put in the Notes
What not to put in the Notes
--help)--help)help subcommand)The Error codes section is required if codes other than 0 or 1 are generated. E.g.
Error codes: 2 The blade is too dull. 3 Out of fuel.
This section is omitted if only 0 or 1 results are generated by the program.
Error code 0 is always treated as “no error” and error code 1 is always a “general error”. Neither are documented in the --help output. Every error code other than 0 or 1 that may be generated by the tool must be documented.
Some platforms (e.g. DOS) use a different option prefix (e.g. /) or may allow case insensitive switches. Tools will use a dash prefix (-) and case sensitive options regardless of the platform. This means that the documentation for a tool generally doesn't need to consider the platform being used.
Do not show Key/Value pairs with an equals sign (=), e.g. --scribble=abc. The Key and Value are parsed using whitespace as a delimiter (--scribble abc). Showing the equals in the help is potentially confusing.
Do not implement a pager (something like the more program that pauses output on each screenful of text).
Do not include
--version).0 or 1 (put in .md docs).