Classic Shell Scripting - Arnold Robbins [225]
The second section gives a brief synopsis of the command line that invokes the program. It begins with the expected heading:
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH SYNOPSIS
and is followed with a sometimes lengthy markup display that provides mostly font information:
.B pathfind
[
.B \-\^\-all
]
[
.B \-\^\-?
]
[
.B \-\^\-help
]
[
.B \-\^\-version
]
The option hyphen is marked with \- to get a minus sign, which looks better typeset than the shorter ordinary hyphen does. We use the half-narrow space command, \^, to prevent the hyphens from running together in troff output. The space disappears from nroff output. The program name, and options, are set in a bold font. The font-switching commands, such as .B, expect up to six arguments (quoted if they contain spaces), and then typeset them adjacent to one another. When there are multiple arguments, this means that any spacing needed must be explicitly supplied. Here, the square brackets are in the default roman font; in manual pages, they delimit optional values. Although we could have put the closing and opening brackets of consecutive options on the same line, we prefer not to because having each option complete on three consecutive lines facilitates editing. The font-pair commands to be introduced shortly could shrink them to a single line, but they are rarely used in option lists.
Despite the line breaks, troff is still typesetting in filled-paragraph mode, so everything so far fits on one line. By experiment, we find that the nroff ASCII output has a line break after the —version option, but since we are in paragraph mode, the next line continues at the left margin. That is objectionable here, so we put in a conditional statement that applies only to nroff, and is ignored by troff. It uses the temporary indentation command (.ti) with an argument of +9n, meaning to indent nine spaces, which is the width of the command name, plus a trailing space, in a fixed-width font:
.if n .ti +9n
The command line is short enough to fit on a single typeset line, so we don't need a similar command for troff. Here is what it would look like, but hidden inside a comment until then, in case we need it when the program is extended with more options:
.\" .if t .ti +\w'\fBpathfind\fP\ 'u
The indentation amount is more complex because with a proportional font, we don't know the width of the command name and one following space. The \w'...'u command measures the width of the material inside the single quotes. Because that text is set in a bold font, we use an inline font wrapper, \fB...\fP, meaning switch to a bold font, and then switch back to the previous font. There are similar font-switching commands for roman (\fR), italic (\fI), and fixed-width (\fC) fonts. The C stands for Courier, a widely used fixed-width font dating back to the days of manual typewriters.
The remainder of the command line comes next:
envvar [ files-or-patterns ]
The third section describes the program's options. It appears before any further description because it is the most-frequently read section of most manual pages:
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH OPTIONS
A few short remarks apply to the options, so they come next:
.B pathfind
options can be prefixed with either one or two hyphens, and
can be abbreviated to any unique prefix. Thus,
.BR \-v ,
.BR \-ver ,
and
.B \-\^\-version
are equivalent.
That fragment exhibits a new feature: the font-pair command (.BR), which sets its arguments alternately in bold and roman text, without intervening space. There are similar commands .IR and .RI for the italic-roman pair, .IB and .BI for the bold-italic pair, and of course, .RB for the mate of the one that we used. There are no analogues