NAME

DESCRIPTION

Nm

the name of the command

Fl

for command line options (flags)

Ar

for placeholders for command line arguments

Op

to enclose optional syntax elements

 

 

Op Fl flag_letters (2380)

Since options are usually optional, Fl is very often preceded by Op.

 

 

Fl flag_letter Ar arg_placeholder (1680)

Most options take an argument, so Fl is very often followed by one letter, then by an Ar macro. Idioms can be combined. For example, combining the first two idioms yields this frequently used composed idiom:

Op Fl flag_letter Ar arg_placeholder

 

 

Op Ar arg_placeholder (440)

Command line arguments usually occur near the end of the command line, after the options. Sometimes, they are optional, so preceding Ar with Op is also common.

 

 

Ar arg_placeholder ... (210)

Some commands can optionally take more than one argument of the same kind. This is indicated by an ellipsis trailing the respective Ar macro.

 

 

Fl flag_letter Ns Ar arg_placeholder (95)

Some commands do not allow whitespace between an option letter and the associated argument. While such behaviour is discouraged by POSIX and should not be implemented in new software, it still occurs quite a bit in many older tools. The spacing between Fl and Ar can be suppressed with an interposed Ns (no space) macro.

 

 

Fl flag1 | flag2 [

| flag3 ...

] (90)

Sometimes, options are mutually exclusive. In simple cases, this can be indicated in the SYNOPSIS by grouping the respective options with vertical bars between them. In more complicated cases, expressing such details in the SYNOPSIS can result in a very long, complex SYNOPSIS, reducing readability. In such cases, just list all the options in a single Fl macro, ordered alphabetically, and postpone the information which ones are mutually exclusive to the DESCRIPTION.

 

 

Ar arg1 arg2 [

arg3 ...

] (65)

Some commands require multiple positional arguments, that is, the second argument serves a different purpose than the first one, the third might serve yet another purpose, and so on. To express this, one can provide multiple arguments to the Ar macro, or equivalently, but more wordily, provide multiple consecutive Ar macros with one argument each.

 

 

[

Fl letter

] Cm keyword1 | keyword2 ... (50)

Some utilities require specific fixed strings as arguments, usually performing a different function depending on which of these strings is passed. Such strings often occur as arguments to an option.

Strings that are not intended as placeholders but have to be typed verbatim on the command line are marked up with Cm (command modifier). Like with Fl, alternatives are indicated with vertical bars.

 

 

[

Fl letter

] Ar variable_placeholder Ns = Ns Ar value_placeholder (40)

Some utilities allow variable assignments to be passed on the command line, often in an argument to an option. These assignments are indicated by marking up both the placeholder for the variable name and for the value with Ar, joining both with a literal equal sign, and suppressing spacing with two Ns macros.

If the assignment is optional and a variable can also be named without a value, this idiom can be varied like this:

[

Fl letter

] Ar variable_placeholder Ns Op = Ns Ar value_placeholder (10)

If the name of the variable is a specific fixed string rather than arbitrarily chosen by the user, Cm is used for it instead of Ar:

[

Fl letter

] Cm variable_name Ns [

Op

] = Ns Ar value_placeholder (10)

 

 

[

Fl letter

] Ar argpart1 : Ns Ar argpart2 (15)

Some arguments consist of two parts that can vary independently and are joint by punctuation. For such cases, mark up both parts separately, using a syntax similar to the one for assignments. Note that trailing punctuation (for example, the colon) follows the preceding content without intervening whitespace on the output, so suppressing whitespace with Ns is not needed before trailing punctuation.

 

 

Oo [

Fl letter

] Ar arg_placeholder Oc more macros ... (10)

If a part of the syntax is optional but ends before or after the end of the input line, an Oo block can be used. Its meaning is equivalent to Op, but it extends to the matching Oc macro rather than to the end of the line. The matching Oc macro may be on the same line or on a later line, thus sortening or extending the scope with respect to what Op would do.

 

 

Fl Fl option_name [

Ns = Ns Ar value_placeholder

] (10)

GNU-style long options are not only tedious to type in at the command line, they are also awkward in documentation. The relatively best among various imperfect ways may be to use a double Fl macro. If the option takes an argument, syntax similar to what was described above for variable assigments is needed, which is not pretty either.

EXAMPLES

.Nm cat 
.Op Fl benstuv 
.Op Ar

SEE ALSO