Some of the key things to notice about manual pages are:
- The Synopsis section summarizes the command and all its options.
- If several versions of a command are available (for example, a System V and BSD-compatible version) both pathnames to the command will be given.
- Optional arguments to the command are indicated by brackets. For example,
/usr/bin/ls [ -aAbcCdfFgilLmnopqrRstux1 ] [ file... ] means that none of the options to the command are mandatory.
- The command is described in the Description section.
- The options are all described in the Options section.
- Files used by the command (for example, configuration files) are listed in the Files section.
There is an old and somewhat scatological saying about a job not being finished until the paperwork 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 will 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. The simplest possible manual page is just a text file describing a command or topic. However, if you would 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, and they combine the text of the manual page with nroff directives specifying how to format the text.
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.
