What's in a Name Ns ...
The manual domain macro names are derived from the day to day informal language used to describe commands, subroutines and related files. Slightly different variations of this language are used to describe the three different aspects of writing a man page. First, there is the description of
-mdoc macro command usage. Second is the description of a
UNIX command
with -mdoc macros, and third, the description of a command to a user in the verbal sense; that is, discussion of a command in the text of a man page.
In the first case,
troff(1) macros are themselves a type of command; the general syntax for a troff command is:
.Xx argument1 argument2 ...
‘.Xx' is a macro command, and anything following it are arguments to be processed. In the second case, the description of a
UNIX command using the content macros is a bit more involved; a typical
SYNOPSIS command line might be displayed as:
filter [-flag] <infile> <outfile>
Here,
filter is the command name and the bracketed string
-flag is a
flag argument designated as optional by the option brackets. In
-mdoc terms, <
infile> and <
outfile> are called
meta arguments; in this example, the user has to replace the meta expressions given in angle brackets with real file names. Note that in this document meta arguments are used to describe
-mdoc commands; in most man pages, meta variables are not specifically written with angle brackets. The macros which formatted the above example:
.Nm filter
.Op Fl flag
.Ao Ar infile Ac Ao Ar outfile Ac
In the third case, discussion of commands and command syntax includes both examples above, but may add more detail. The arguments <
infile> and <
outfile> from the example above might be referred to as
operands or
file arguments. Some command line argument lists are quite long:
make
[-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I directory] [-j max_jobs] [variable=value] [target ...]
Here one might talk about the command
make and qualify the argument,
makefile, as an argument to the flag,
-f, or discuss the optional file operand
target. In the verbal context, such detail can prevent confusion, however the
-mdoc package does not have a macro for an argument
to a flag. Instead the ‘Ar' argument macro is used for an operand or file argument like
target as well as an argument to a flag like
variable. The make command line was produced from:
.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Op Fl I Ar directory
.Op Fl j Ar max_jobs
.Op Ar variable Ns = Ns Ar value
.Bk
.Op Ar target ...
.Ek
The ‘.Bk' and ‘.Ek' macros are explained in
Keeps.