How to read a synopsis
How to read a synopsis#
Also called “usage string” or simply “usage.”
The synopsis is a formatted string, usually a single line towards the beginning of the documentation, which shows how to write commands for a specific program. It starts with the program name. The words after that usually align with the following patterns:
A word in all uppercase is a placeholder for a word you have to provide. For example, the synopsis
foo PATHmeans a command like
foo './some file.txt'is valid, but
foo(no file) or
foo ./1.txt ./2.txt(two files) is not valid. This word can also reference several other parameters, such as
OPTIONSreferring to any of the options documented elsewhere.
A word in all lower case is literal – it should be entered verbatim in the command. For example, the synopsis
foo [--help]means that
foo --helpare the only valid commands.
A word enclosed in square brackets means it’s optional. For example, the synopsis
foo [PATH]means that both
foo './some file.txt'are both valid.
A word followed by an ellipsis means that the word can be repeated. For example, the synopsis
foo PATH…means that
footakes one or more
foo ./first ./secondare both valid, but
A pipe character separates mutually exclusive choices. For example, the synopsis
foo --force|--dry-runmeans that
foo --dry-runare valid, but
foo --force --dry-runis not.
An equals sign separates an option name from its value. For example, the synopsis
foo [--config=FILE]means that
foo --config=/etc/foo.confare both valid, but
foo --config=are not.
Complex commands sometimes have more than one synopsis, based on fundamentally different use cases.