Compiling and Formatting Man Pages

Man pages are stored as bzip or gzip files. You can prepare a man page in several ways, including Perl's pod2man script. However, most methods use some variant of the troff/groff document formatting systems, which are even older than man in Unix-like systems. These commands are a subject in themselves, but using them to create man pages requires little knowledge.

Write the man page in a text editor or nroff/groff, remembering to spell check. If your editor does not support spell checking, you can copy and paste it to one that does. The first parts of the file name should be the page name, separated by a period from the man section number. As you write, you can check your formatting with the command:

nroff -man FILE | less

When you have finished entering, enter the basic command:

ngroff -man FILE > OUTPUTFILE

Compress the output file with gzip or bzip, and place the compressed file in a directory in the MANPATH environment variable. To access the new file, add it to the man database with mandb -c or, in some distributions, make what is.

You can also convert the output file to Postscript with:

groff -man -Tps FILE > FILE.ps

Similarly, the command to produce a PDF file is

groff -man -Tpdf FILE > FILE.pdf

Another option for PDF conversion is to use the command-line utility ps2pdf to produce the PDF file from the Postscript file.

Converting to HTML is even simpler. With the man2html utility installed, enter:

man2html FILE

The output is an HTML file of the same name in the output file's directory

Reading man Pages

Reading man pages requires no more than the basic command followed by the topic (e.g., man ls). However, what many users don't know is that the man command can be modified by several options.

To start with, if you prefer to memorize options rather than command names, -f replaces the whatis command, giving a short description of the topic. Similarly, the -k (--apropos) option gives the same results as the apropos command, searching the man page names and descriptions for the topic. Using -K (--global-apropos), however, searches the entire content of all man pages – a process that takes several minutes on most systems.

Another set of options helps you control the man command's search. With -i (--ignore case) added, man ignores the distinction between lower and upper case, whereas with -I (--match-case), the command observes the distinction. With --regex, you can use regular expressions in the topic, and with --wildcard, you can use standard wild cards. However, because --regex and --wildcard can return long lists of results, you can use --names to ensure that they only search the names of man pages. In some cases, you may be able to save time by adding -a (--all), so that all results are listed, instead of the one that the command evaluates as most appropriate.

Other options help you to choose where to find a man page. With -w (--where, --path, --location), you can track down where man pages are stored. Using -S LIST (-s LIST, --sections=list), you can limit your search to a comma-separated list of man sections, starting with the first section in the list.

If you know of directories that are not listed in man's environment path, you can direct the command's search to that alternate path with -M PATH (--manpath=PATH). On a network, -m SYSTEM extends the man command's search to connected systems, instead of confining itself to the local one.

Man's results can also be formatted without hyphenation (--no-hyphenation, --nh), or without the default full justification (--no-justification, --nj), producing a ragged right margin that prevents awkward word breaks at the end of lines. You can display man results in a browser with -H BROWSER (--html=BROWSER), which creates HTML-formatted output.

Man Endures

The man command and the pages written for it are 45 years old; yet, their simplicity means that they continue to be adequate for the task of producing help files. You may find other standards in a particular project – for example, Debian man pages almost always include AUTHORS – but, overall, the basics of man pages have changed little since they first appeared. The largest changes over the years have been to the selection of section headings, and those details are so minor that Dennis Ritchie and Ken Thompson, the writers of the first man pages, would have no trouble using one written today (although they might be appalled by some of the headings and the general verbosity today).

Clearly, man pages are not going away any time soon. Sometimes, parts of them, like the SYNOPSIS, can be intimidating in their detail, but the better you understand them, the more useful they can be.