We've seen how a man page is found. We have also discussed that the manual is organized in sections, and that the default behavior is to output the first page found on the name requested. However, we still need some additional skills to effectively use the system. These skills include controlling the search of sections, trees, and searching for man pages on a particular topic.

Controlling section and tree search

You can contol where man looks for pages by 

• setting an environment variable MANPATH to a colon-separated list of man trees you want to search, in the order you want them searched.

• using the -M manpath option to man to set the MANPATH for this single invocation

• providing a path to a particular page. This can be especially useful when you are modifying a page if you want to display it.  For example, if you have a page foo.1 in the current directory that you want to display, use 

man ./foo.1

This works on linux. On all systems, of course, you can always place foo.1 in your own man tree's man1 directory and add your tree to the front of the current MANPATH

On linux you can control the order of section search as well by either setting an environment variable MANSECT to a list of sections or by using man -S sectlist to control the section search for a particular invocation. Using this technique, the following will preferentially display the man page on the system call write(2) rather than the man page on the command write(1):

man -S 2:1 write

or

The only mechanism for controlling section search available on all systems relies on knowing which section the target page is in. If this is known, you can restrict the search for xxx to section N only using

man N xxx

for example, in the case above you could use man 2 write

man's configuration file

As we have mentioned, /etc/man.config (or /etc/man_db.conf) can be modified to construct the default MANPATH using the MANPATH and MANPATH_MAP directives. We will see in the next section how it controls the caching of man pages. It also contains the default MANSECT setting and several other configuration parameters:

• how uncompression is configured when pages with particular extensions are found

• the default PAGER and other tools

• a variable to give man default options

• the location of man's documentation processors, including nroff and

• tbl is used to generate tables. (It actually converts tbl directives into low-level nroff)

• eqn is used to generate math equations.

tbl and eqn are rarely used in man pages.

man keywords

One simple common task that often stumps new users of Unix is how to find out the name of a command if you can't remember it. An associated issue is needing to find a command to do a task that you can describe, but for which you have never used a command. The only facility for providing this type of information with man pages is the whatis database.

The whatis database is simply a database of man page keywords constructed from the page's terse one-line description (the contents of the NAME section at the start of the man page) created by the author.

The keywords for each page will simply be the list of words in the one-line description shown with its name. Depending on how well the author's description matches your query, your query may or may not result in a list that includes the page you desire. Even more exasperating to the average user, common queries result in a flood of output:

The hapless user above has forgotten the name of the command to make a new directory. Since keyword queries are limited to a single keyword, and given she has a choice between make and directory, she has chosen the less common word directory (or so she thought).

The problem, of course, is the sheer volume of man pages. On our linux system there are currently 18907 man pages in the standard man tree alone! Clearly, our help needs some help. 

As with any output that is verbose, we must resort to our old friend grep to pare it back. Let's consider a few issues that grep could help us with.

First, man -k outputs any man page in any section that matches. The user certainly knows what section he is interested in. In the example above, mkdir must be in section 1, so, let's use grep to choose section 1 man pages:

That is much better. But we can do even more if we add a second keyword. There is no way to get man -k to do this, but the output of the command above contains the second keyword, so we just add another search

There's our man page! Let's look:

Kind of insulting, don't you think? Believe it or not, we are using the right ideas. There is one unfortunate problem, however. There are two ways to describe the task of mkdir(1)

mkdir                (1)  - make directories

and

mkdir(1)                - make a directory

Believe it or not, one of these examples is from hills, and one is from linux! No matter which of directory or directories you use as the keyword, your search will return the correct result on only one of these systems!
However, we can devise a simple trick to get around this once we know how man -k matches the keywords:

The page will be listed if the initial part of any word in its terse description matches your query exactly, or if the page name contains your query.

This results in one more 'trick' to help us find the man page we need: avoid word endings. Remember, your query will match if the initial part of any keyword matches. Since the -y or -ies is simply a choice of singular or plural, suppress it:

The corresponding command on hills results in four man pages, and mkdir(1) is one of them.

Let's reiterate our tricks to make man -k useful

• grep the output for the section, e.g., grep '(1)'. (Make sure you enclose the parenthesis in quotes.)
• look for multiple keywords using cascaded greps
• suppress word endings like verb tenses and endings that mean singular or plural
• choose the least common keyword you can think of. Remember, all words in the terse description (the NAME section, as we shall see) are keywords. man -k a returns 21142 pages.

man -k is called apropos on BSD systems

makewhatis

If you use man -k with a keyword that should show some man pages and the result is a message like this:

your system probably does not have a whatis database. To build the whatis database, use the following command as root

$ makewhatis -w

on 6.5 or the following command on 7:

$ mandb

and sit back (or just run it in the background and forget about it) - it may take a while.

The whatis database should be updated (the -u option should be added!) whenever you install new man pages. On our linux systems a cron job does this nightly.

The whatis database is currently at /var/cache/man/whatis