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
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 two
dashes at the beginning, the argument to the respective Fl
macro starts with one
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 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
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:
.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)
.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.