14.7 Adding Local man Pages

There's an old and somewhat scatological saying about a job not being finished until thepaperwork is done.^[12] In the case of creating scripts and programs, this means writing some sort ofdocumentation. Tools you create can be documented in many different ways, but the usual Unix practice is to produce an online manual page. We'll conclude this chapter with a brief look at creating manual pages for the tools you develop.

^[12] Imagine how it applies to writing a book.

Manual-page files are named for the command or utility that they describe, and they are given an extension that matches the number or letter of the man subdirectory in which they reside. For example, a manual-page file for the wgrep command placed into man1 subdirectory would be named wgrep.1.^[13]

^[13] Perl programs are traditionally documented withPOD, a scheme for embedding the documentation in the Perl source. Ugh.

The simplest possible manual page is just a text file describing a command or topic. However, if you'd like to create something a bit more elaborate, and more like the other manual pages typically found on Unix systems, it is very easy to do so. Manual-page source files are designed for the nroff text formatting system,^[14] and they combine the text of the manual page with nroff directives specifying how to format the text. (Not all Unix versions provide the text formatting utilities by default or at all.)

^[14] Or the GNU equivalent, groff.

The best way to figure out what the various nroff directives do is to see them in context. In general, they are placed at the beginning of a line and start with a period. Here is a brief manual page source file for the wgrep command, which can also serve as a template for manual pages you might create:

.TH wgrep l 
.SH NAME 
wgrep - windowed grep utility 
.SH SYNOPSIS 
wgrep [options] regexp file(s) 
.SH DESCRIPTION 
.B wgrep 
is a 
.B grep 
utility which prints a window of lines surrounding 
each matching line that it finds in the list of files.
By default, the window is three lines before and after
each matching line. 
.PP 
.B wgrep 
has many options which control how its output looks. 
It can range from plain to painfully excessive. 
.SH OPTIONS 
.TP 5 
.B -w 
Specifies the window size in the form 
.B before:after Either one can be omitted. 
.TP 5 
.B -n 
Include line numbers before each printed line. 
.TP 5 
.B -s 
Include asterisks in front of matching lines. 
.PP 
.SH BUGS 
None of course. 
.SH SEE ALSO 
egrep(1), VMS SEARCH command

Here is how the formatted version might look:

wgrep(l)                                                  wgrep(l)
NAME 
        wgrep - windowed grep utility

SYNOPSIS 
        wgrep  [options]  regexp  file(s)

DESCRIPTION 
        wgrep is a grep utility which prints a window of lines surrounding each
        matching line that it finds in the list of files. By default, the window is
        three lines before and after each matching line.
        wgrep has many options which control how its output looks. It can range from
        plain to painfully excessive.

OPTIONS 
        -w   Specifies the window size in the form before:after.
             Either one can be omitted.
        -n   Include line numbers before each printed line.
        -s   Include asterisks in front of matching lines.

BUGS 
        None, of course.

SEE ALSO 
        egrep(1), VMS SEARCH command

Table 14-3 lists the nroff directives used in the sample manual page along with other related and useful directives.

Table 14-3. Useful nroff constructs

Directive	Explanation
.TH name section	Title heading.
.SH NAME	Section heading (names are uppercase by convention).
.TP [n]	Tagged paragraph: use hanging indent (of n spaces if specified).
.PP	Start new filled paragraph.
.IP	Indented paragraph.
.nf	Stop text filling (adjusting words on lines).
.fi	Start text filling.
.B text	Use bold type for text given as its argument.
.I text	Italicize text given as its argument.
.R text	Use roman type for text given as its argument.

You can simulate a man command for a manual page you are developing with a command like this one:

$ nroff -man file
 | more

If you want a printed version of this (or any other) manual page, you'll need to use the troff command as well as other printing-related typesetting utilities provided on the system.