There’s an old and somewhat scatological saying about a job not being finished until thepaperwork is done. 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
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
nroff text formatting system, 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 ...