the SYNOPSIS section in general
The purpose of the SYNOPSIS section is to provide a first overview of the syntax
of the topic. Never attempt to explain semantics there.
Since the SYNOPSIS is the first part of a manual page every user will look at,
extra care to make it useful is well spent.
If the syntax of the topic is very simple, it may be possible for the SYNOPSIS
to exhaustively document the syntax. Doing so is desirable unless it makes the
SYNOPSIS unduly long or complicated.
language intentionally does not provide a complete or formal metasyntax
notation like, for example, the Backus-Naur Form does. The idea is to make
reading manual pages easy without formal mathematical training. Consequently,
it is sometimes impossible to express all aspects of the syntax in the
SYNOPSIS. In such cases, a properly written DESCRIPTION will resolve all the
ambiguities that the SYNOPSIS may contain.
Sometimes, even if the
language does provide the tools to unambiguously express all aspects of the
syntax in the SYNOPSIS, it may be better to refrain from doing so if that
would result in a lengthy, cumbersome SYNOPSIS. Keep in mind that brevity and
simplicity are the most important assets of the SYNOPSIS and should not be
disturbed by minor details; the place to fully explain all the details is the
Very often, there is more than one way to write an acceptable SYNOPSIS. Choose
the way most helpful as a first overview.
not attempt to provide a complete or formal metasyntax notation, some
metasyntax conventions do exist that make reading manual pages easier without
causing formal clutter.
The most important metasyntax convention probably is the representation of
optional and alternative syntax elements.
If any syntax element is optional, always indicate that by enclosing it in an
block. Usually, where that is easily feasible, prefer
Where any one of two or more syntax elements can be used, put the vertical bar
delimiter (‘|’) between them. Use the plain ASCII vertical bar
character, put it into its own macro argument, and do not escape it in any
way, neither with a zero-width space nor with a backslash. Do not use an
escape sequence like \(ba or a predefined string like \*(Ba. Since the
vertical bar is treated as a middle delimiter, it is not necessary to repeat
the previous in-line macro after it; the previous in-line macro scope will
automatically resume after the vertical bar.
In most cases, sequences of alternatives are part of optional syntax elements,
in which case they are enclosed in an optional block and there is little
ambiguity where the sequence of alternatives begins and ends. In rarer cases,
in particular for mandatory alternatives, ambiguity may arise. The
language does not provide a way to resolve such ambiguities. Do not borrow
metasyntax from other languages, and don't invent your own metasyntax. For
example, do not use curly braces or the
macro in this context. Instead, make sure the text in the DESCRIPTION resolves
In case an alternative looks particularly misleading when marked up as described
above, it may sometimes be possible to informally provide visual hints where
the alternative is intended to begin and end by suppressing white space with
macros; use this possibility sparingly.
Placing line breaks wisely may also provide informal visual cues in a few cases.
In simple cases, alternatives can be used to express that options are mutually
.Op Fl H | L | P
In complicated cases, it's better to leave the details to the DESCRIPTION:
.Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
.Fl a | Ar path
.Op Fl fv
.Ar special | node
Alternative command modifiers:
.Fl s Cm all | peers | Sensors | status
The spacing trick to reduce visual ambiguity:
.Op Fl m Ar mode
.Cm b Ns | Ns Cm c
.Ar major minor
A typical example where trying to resolve ambiguities would be a bad idea
because it would just make the SYNOPSIS less readable:
.Op Fl abCefhimnuvx
.Op Fl o Ar option
.Op Fl c Ar string | Fl s | Ar file