command line options
This page explains the standard way to document the command line options of a
command line utility program, typically in a section 1, 6 or 8 manual.
All options are mentioned in the SYNOPSIS section. Right after the
macro, list those options not taking
arguments first, in alphabetical order, in one single
argument. After that, list all options
taking arguments, each option using one
macro pair. When the same option
letter occurs in both cases, the uppercase letter precedes the lowercase
letter. Arguments follow the last option.
Here is an example:
.Op Fl DdEefLnqRv
.Op Fl c Ar count
.Op Fl I Ar ifaddr
.Op Fl i Ar wait
.Op Fl l Ar preload
.Op Fl p Ar pattern
.Op Fl s Ar packetsize
.Op Fl T Ar toskeyword
.Op Fl t Ar ttl
.Op Fl V Ar rtable
.Op Fl w Ar maxwait
If there are long options, list them after the short options that take
arguments, just before the command line arguments. If an option requires
dashes at the beginning, the argument to the
macro starts with
hyphen-minus character, for example:
.Op Fl abcEFGHhIiLlnoqRsUVvwxZ
.Op Fl A Ar num
.Op Fl B Ar num
.Op Fl C Ns Op Ar num
.Op Fl e Ar pattern
.Op Fl f Ar file
.Op Fl \-binary\-files Ns = Ns Ar value
.Op Fl \-context Ns Op = Ns Ar num
.Op Fl \-line\-buffered
.Op Ar pattern
In this case, using the plain hyphen-minus character
’ instead of the hyphen-minus escape
’ is also acceptable, and
both will usually render in the same way. Using the escape sequence may be
minimally more likely to avoid occasional uneven rendering because that's what
macro sets use for rendering the
If there are many long options that are just aliases for short options, drop the
long versions from the SYNOPSIS for better readability.
Avoid postponing the listing of the actual options and arguments to the
DESCRIPTION, do not use this bad idiom:
.Op Ar options \" BAD IDEA!
.Op Ar arguments
This bad idiom defeats the whole purpose of the SYNOPSIS.
Only for badly designed programs where the number of long options not having
short aliases is extremely large, such that listing them all would render the
SYNOPSIS almost unreadable, it may be acceptable to use “.Op Ar
options”. But even in this case, list all supported command line
arguments individually in the SYNOPSIS.
Introduce the list of options with these two lines:
The options are as follows:
Here, all options are listed alphabetically, no matter whether or not they take
arguments. Again, uppercase letters precede lowercase letters.
Here is an excerpt from the
.It Fl L
Disable the loopback, so the transmitting host doesn't see the ICMP
For multicast pings.
.It Fl l Ar preload
sends that many packets as fast as possible before falling into its normal
mode of behavior.
Only root may set a preload value.
The MACRO REFERENCE section in the