style/optionscommand 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.

SYNOPSIS section

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:
.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:
.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 
For multicast pings. 
.It Fl l Ar preload 
.Ar preload 
is specified, 
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.
October 11, 2016 bsd.lv