Classic Shell Scripting

Manual-Page Installation

Historically, the man command expected to find manual pages in subdirectories of a search path defined by the environment variable MANPATH, typically something like /usr/man:/usr/local/man.

Some recent man versions simply assume that each directory in the program search path, PATH, can be suffixed with the string /../man to identify a companion manual-page directory, eliminating the need for MANPATH.

In each manual-page directory, it is common to find pairs of subdirectories prefixed man and cat and suffixed with the section number. Within each subdirectory, filenames are also suffixed by the section number. Thus, /usr/man/man1/ls.1 is the troff file that documents the ls command, and /usr/man/cat1/ls.1 holds nroff's formatted output. man use the latter, when it exists, to avoid rerunning the formatter unnecessarily.

While some vendors have since adopted quite different organization of the manual-page trees, their man implementations still recognize the historical practice. Thus, installation of most GNU software puts executables in $prefix/bin and manual pages in $prefix/man/man1, where prefix defaults to /usr/local, and that seems to work nicely everywhere.

System managers normally arrange to run catman or makewhatis at regular intervals to update a file containing the one-line descriptions from the manual-page NAME sections. That file is used by the apropos, man -k, and whatis commands to provide a simple index of manual pages. If that doesn't turn up what ...