Classic Shell Scripting - Arnold Robbins [227]
The last bit of manual-page markup that we need to know shows up in the last paragraph, where we want to show indented lines in a fixed-width font indicative of computer input and output, without the normal paragraph filling. The font change is similar to what we have seen before, \fC...\fP. We prefix it with a troff no-op command, \&, when it appears at the beginning of the line, because that no-op is necessary when the text that follows begins with a period. It does not here, but general rules are easier to remember than special cases. We want the computer samples to be indented, so we put them in an indented region bounded by Begin Right Shift (.RS) and End Right Shift (.RE) commands. Furthermore, we need to stop paragraph filling, so we surround the text with no fill (.nf) and fill (.fi) commands:
For example,
.RS
.nf
\&\fCpathfind PATH ls\fP
.fi
.RE
reports
.RS
.nf
\&\fC/bin/ls\fP
.fi
.RE
on most Unix systems, and
.RS
.nf
\&\fCpathfind --all PATH gcc g++\fP
.fi
.RE
reports
.RS
.nf
\&\fC/usr/local/bin/gcc
/usr/bin/gcc
/usr/local/gnat/bin/gcc
/usr/local/bin/g++
/usr/bin/g++\fP
.fi
.RE
on some systems.
.PP
Wildcard patterns also work:
.RS
.nf
\&\fCpathfind --all PATH '??tex'\fP
.fi
.RE
reports
.RS
.nf
\&\fC/usr/local/bin/detex
/usr/local/bin/dotex
/usr/local/bin/latex
/usr/bin/latex\fP
.fi
.RE
on some systems.
The final section provides cross references to other related commands; this information can be extremely useful to readers, so it is important to do a thorough job of it. Its format is simple: just a single paragraph of alphabetically ordered bold command names with parenthesized manual section numbers, separated by commas, and ending with a period:
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH "SEE ALSO"
.BR find (1),
.BR locate (1),
.BR slocate (1),
.BR type (1),
.BR whence (1),
.BR where (1),
.BR whereis (1).
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
We've introduced almost all of the markup that is required for virtually any manual page. The only significant omission is the Subsection Heading command (.SS), but it is comparatively rare, showing up only in long manual-page files. It works just like the .SH command, but uses a somewhat smaller font in the typeset output. There is no visible difference in the ASCII output from nroff. Two other inline commands that are occasionally needed are .\|.\|. for an ellipsis (...), and \(bu for a bullet (·), often used as the label in a list of labeled paragraphs, like this:
.TP \w'\(bu'u+2n
\(bu
We have now examined the anatomy of a manual page. The complete troff input for our example is collected in Example A-1, and the typeset output (from groff -man, which produces PostScript by default) is shown as a half-size page in Figure A-1. With our description as a guide, you should be ready to document your own programs in manual pages.
Figure A-1. Typeset manual-page markup for pathfind
Example A-1. troff manual-page markup for pathfind
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.TH PATHFIND 1 "" "1.00"
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH NAME
pathfind \(em find files in a directory path
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH SYNOPSIS
.B pathfind
[
.B \-\^\-all
]
[
.B \-\^\-?
]
[
.B \-\^\-help
]
[
.B \-\^\-version
]
.if n .ti +9n
.\" .if t .ti +\w'\fBpathfind\fP\ 'u
envvar [ files-or-patterns ]
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH OPTIONS
.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