Classic Shell Scripting - Arnold Robbins [224]
Before we begin, some explanatory remarks about nroff/troff markup are in order. nroff built on the lessons of earlier text-formatting systems, such as DEC's runoff, and produced output for ASCII printing devices. When Bell Labs acquired a phototypesetter, a new program, troff, was created to produce typeset pages. troff was one of the earliest successful attempts at computer-based typesetting. Both programs accept the same input, so from now on, when we say troff, we usually also mean nroff.
Early Unix systems ran on small-memory minicomputers, and those severe constraints cramped the design of these formatters. Like many Unix commands, troff commands are short and cryptic. Most appear at the beginning of a line, in the form of a dot followed by one or two letters or digits. The font choice is limited: just roman, bold, italic, and later, fixed-width, styles in only a few sizes. Unlike later systems, in troff documents, spaces and blank lines are significant: two input spaces produce (approximately) two output spaces. That fact, plus the command position, prevent indentation and spacing from being used to make input more readable.
However, the simple command format makes it easy to parse troff documents, at least superficially, and several frontend processors have been developed that provide for easy specification of equations, graphs, pictures, and tables: they consume a troff data stream, and output a slightly augmented one.
While the full troff command repertoire is large, the manual-page style, selected by the -man option, has only a few commands. No frontend processors are required, so there are no equations or pictures in manual pages, and tables are rare.
A manual-page document has a simple layout, with a half-dozen standard top-level section headings, interspersed with formatted paragraphs of text, and occasionally, indented, and often labeled, blocks. You've seen that layout every time you've used the man command.
Examination of manual pages from a broad range of historical and current sources shows considerable stylistic variation, which is to be expected when the markup is visual, rather than logical. Our font choices therefore should be taken as recommendations, rather than as rigid requirements.
It's now time to get started writing the manual page for pathfind, which is simple enough that the text doesn't overwhelm the markup.
We begin with a comment statement, since every computer language should have one: troff comments begin with backslash-quote and continue up to, but not including, end-of-line. However, when they follow an initial dot, their line terminator disappears from the output as well:
.\" = = = = = = = = = = = = = = = = = = = = = = = = =
= =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
Because troff input cannot be indented, it looks awfully dense. We find that a comment line of equals signs before section headings makes them much easier to spot, and we often use comparatively short input lines.
Every manual-page document starts with a Text Header command (.TH) containing up to four arguments: an uppercased command name, a manual section number (1 [digit one] for user commands), and optionally, a revision date and version number. These arguments are used to construct the running page headers and footers in the formatted output document:
.TH PATHFIND 1 "" "1.00"
The Section Heading command (.SH) takes a single argument, quoted if it contains spaces, and uppercased to follow manual-page conventions:
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH NAME
The body of the NAME section provides fodder for the apropos (or equivalently, man -k) command, and should be exactly one line long, without trailing punctuation. It takes the form command -- description:
pathfind \(em find files in a directory path
The markup \(em is one of the few inline troff commands seen in manual pages: it stands for an em dash, a horizontal line about the width of