System Admin  «Prev  Next»
Lesson 7 Adding new manual pages
Objective Two Strategies for Adding new manual Pages to a Unix System

Two Strategies for Adding new manual Pages to Unix System

List the two strategies for adding new manual pages to the system.
The two strategies for adding new manual pages to the system are:
  1. Copy the new manual pages into the appropriate section. For example, if you install a new program named cool to the system, you would copy the supplied manual page to the appropriate directory; for example, you would copy the supplied manual page file to /usr/man/man1/cool.1.
  2. Leave the manual page in a separate location (probably with the program distribution) but modify the manual search path. This is controlled by the MANPATH environment variable[1]. By adding directories to the MANPATH environment variable in a system-wide initialization file (such as /etc/profile), you can make the new manual pages accessible to all users. We will look at updating MANPATH in the next lesson.

Update the database

In either event, after adding new files, you will need to update the database that the man –k keyword search uses. This database is stored in the file /usr/man/whatis (/usr/man/windex on Solaris). To rebuild this file under Linux, you must run the command

/usr/sbin/makewhatis

whereas under Solaris and HP-UX, you must run the command
catman -w

Alternatives to man

AIX treats the entire documentation differently.
In addition, other types of documentation are available on various UNIX systems.

Adding Local man Pages

There is an old 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.
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.
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:

[1] environment variable: An environment variable is a system variable that contains information about some aspect of the system's environment. For example, the PATH environment variable describes the search path that is used whenever a command name is entered without an explicit directory location.