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.
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]
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.)
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.
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. |