Writing and reading man pages

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.