Essential System Administration, 3rd Edition

Adding Local man Pages

There’s an old and somewhat scatological saying about a job not being finished until thepaperwork is done.^[11] In the case of creating scripts and programs, this means writing some sort of documentation. 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.^[12]

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,^[13] 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 ...