style/options —
command line options
.
Fl 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
Nm macro, list those options not taking
arguments first, in alphabetical order, in one single
Fl argument. After that, list all options
taking arguments, each option using one
Fl
and
Ar 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:
.Sh SYNOPSIS
.Nm ping
.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
.Ar host
If there are long options, list them after the short options that take
arguments, just before the command line arguments. If an option requires
two dashes at the beginning, the argument to the
respective
Fl macro starts with
one hyphen-minus character, for example:
.Sh SYNOPSIS
.Nm grep
.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
.Op Ar
In this case, using the plain hyphen-minus character
‘
-’ instead of the hyphen-minus escape
sequence ‘
\-’ 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
traditional
mdoc(7)
macro sets use for rendering the
Fl macro.
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:
.Nm command
.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:
.Bl -tag -width Ds
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
ping(8)
manual:
.It Fl L
Disable the loopback, so the transmitting host doesn't see the ICMP
requests.
For multicast pings.
.It Fl l Ar preload
If
.Ar preload
is specified,
.Nm
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
mdoc(7)
manual.