Classic Shell Scripting - Arnold Robbins [226]
It is now time for a paragraph break:
.PP
In nroff output, a blank line and a paragraph break are identical, but troff uses less vertical space for a paragraph break. It is considered good form to use .PP between paragraphs; in general, manual-page input files should never contain blank lines.
The next paragraph follows:
To avoid confusion with options, if a filename begins with a
hyphen, it must be disguised by a leading absolute or
relative directory path, e.g.,
.I /tmp/-foo
or
.IR ./-foo .
We are now ready for the option descriptions. Their markup is about the most complex that is used in manual pages, but it soon becomes familiar. Essentially, we want to have labeled indented paragraphs, with the label normally set at the left of the first paragraph line. More recent markup systems would structure this as a list of items: begin-option-list, begin-option, end-option, begin-option, end-option, and so on, ending with end-option-list. The manual-page markup doesn't quite do that. It just starts the items, and they end at the next paragraph break (.PP) or section heading (.SH).
The command to start an item (.TP) takes an optional width argument that sets the indentation of the description paragraph from the left margin. If the argument is omitted, a default indentation is used. If a label is longer than the indentation, a new line is started immediately after the label. The paragraph indentation remains in effect for subsequent .TP commands, so only the first in the option list needs it. As with the indentation of a wrapped command line in the SYNOPSIS section, we use a dynamic indentation that depends on the length of the longest option name. Also, since we have several options to describe, we set them off with a comment line of dashes:
.\" --------------------------------------------------------
.TP \w'\fB\-\^\-version\fP'u+3n
The line following the .TP command provides the item label:
.B \-all
The label is followed by the option description:
Search all directories for each specified file, instead of
reporting just the first instance of each found in the
search path.
If the description needs a paragraph break, use the Indented Paragraph command (.IP) instead of the ordinary paragraph break command (.PP), so as not to terminate the list. This manual page is short enough that we don't require .IP.
The remaining option descriptions require no new markup, so here they are, completing the options section:
.\" --------------------------------------------------------
.TP
.B \-?
Same as
.BR \-help .
.\" --------------------------------------------------------
.TP
.B \-help
Display a brief help message on
.IR stdout ,
giving a usage description, and then terminate immediately
with a success return code.
.\" --------------------------------------------------------
.TP
.B \-version
Display the program version number and release date on
.IR stdout ,
and then terminate immediately with a success return code.
The fourth manual-page section is the program description. It can be as long as you like: the shell's runs on for dozens of pages. Nevertheless, brevity is desirable, since manual pages are consulted often. pathfind is simple enough that just three paragraphs suffice. The first two have markup that should be familiar by now:
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH DESCRIPTION
.B pathfind
searches a colon-separated directory search path defined by
the value of the environment variable, \fIenvvar\fP, for
specified files or file patterns, reporting their full path on
.IR stdout ,
or complaining \fIfilename: not found\fP on
.I stderr
if a file cannot be found anywhere in the search path.
.PP
.BR pathfind 's
exit status is 0 on success, and otherwise is the number of
files that could not be found, possibly capped at the
exit code limit of 125.
.PP