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 PATH means 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 OPTIONS referring 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 and foo --help are the only valid commands.

• A word enclosed in square brackets means it’s optional. For example, the synopsis foo [PATH] means that both foo and 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 foo takes one or more PATH arguments, meaning foo ./first and foo ./first ./second are both valid, but foo is not.

• A pipe character separates mutually exclusive choices. For example, the synopsis foo --force|--dry-run means that foo --force and foo --dry-run are valid, but foo --force --dry-run is not.

• An equals sign separates an option name from its value. For example, the synopsis foo [--config=FILE] means that foo and foo --config=/etc/foo.conf are both valid, but foo --config and foo --config= are not.

• Complex commands sometimes have more than one synopsis, based on fundamentally different use cases.