apropos, whatis and makewhatis

To search the whatis database on your system, just type:

apropos \keyword

inserting your criteria as the keyword for the search. Let's try one out. I've never used my CD-ROM player for anything more than mounting a data disk and accessing files, but I'd like to play some music while I'm working (or playing xtetris because it doesn't have music accompaniment, etc.). So I type:

apropos cdrom

and I see:

xplaycd (1)          - X based audio cd player for cdrom drives (END)

apropos uses the less pager unless your PAGER environment variable says otherwise. To exit this screen, press q. To scroll, use the up and down arrow keys, or the space bar to go down a screen at a time.

Now I'm not sure, but I believe other programs for accessing the CD exist on my system. Yes, this will work, but how about a choice? Let's try again. This time, I'll try with just CD:

apropos cd

survey says:

Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete
(3) - handle asynchronous events
cd (3)              - Change working directory
curs_window: newwin, delwin, mvwin, subwin, derwin, mvderwin,
dupwin, wsyncup, syncok, wcursyncup, wsyncdown (3) - create curses
windows
eject (1)           - eject CD-ROM disc from drive
mcd (1)             - change MSDOS directory
rexecd (8)          - remote execution server
termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush,
tcflow, cfgetospeed, cfget
ispeed, cfsetispeed, cfsetospeed, tcgetpgrp, tcsetpgrp (2)
               - get and set terminal attrib
utes, line control, get and set baud rate, get and set terminal
foreground process group ID
tin, rtin, cdtin, tind (1) - A Netnews reader
cda (1)              Compact disc digital audio player utility
wm2xmcd (1)         - workman-to-xmcd CD database file converter
xmcd (1)            - CD digital audio player utility for X11/Motif
xplaycd (1)         - X based audio cd player for cdrom drives

Now we have a problem. We can be overwhelmed with inappropriate items. If this didn't give you a long listing, try giving cat as a keyword for apropos. You'll get pages of output. (Read on to find out why.)

If you look, you can see that we got what we wanted, and a whole lot more. How can we narrow it down? Can we put two keywords on the apropos command line? Yes. Unfortunately, the keywords are logical ORed and not ANDed together, making the output even longer. But if we scan the listing, it appears most of the commands we're interested in contain the term audio. We could try "apropos audio". But let's search the previous list instead. Type:

apropos cd | grep -i audio

Our reward:

cda (1)  - Compact disc digital audio player
utility xmcd (1 - CD digital audio player utility
for X11/Motif xplaycd (1)     - X based audio cd
player for cdrom drives

Now, that's more like it! We can try these programs to see which we like best. And we know they have manual pages to help us out.

A good exercise for the reader might be to use “mail” as a keyword (this will return a very long list), then grep the list for audio to see which programs might help you e-mail sound files.

A slightly less obvious, but identical command for apropos exists. The command man -k <keyword> is synonymous, though not as mnemonic.

Finally, let's take a look at whatis. We've been accessing the whatis database files during the apropos (aka man -k) searches. Let's try our cd search using whatis instead.

whatis cd

Now we get:

cd (3)               - Change working directory

So what's the difference? Why only one entry? Think of the whatis database as columnar and containing two columns. The left column contains the program name (the command used to invoke the program) and the right side contains the first line of the manual's program synopsis. apropos searches both columns using the keyword as a regular expression to find all occurrences of the keyword. These occurrences may be embedded in the command word or the words of the synopsis. For example, apropos cat returns lines containing the word catalog, category, duplicate, application, etc. whatis, on the other hand, searches only the left hand column, which contains only the program name. This feature is helpful if you know the name of a command, but not its function.

These commands do have limitations. If a command has no corresponding manual page, it will not be listed in the database. makewhatis does not include a manual page, at least not on the author's system. If a synopsis does not contain a keyword you have chosen to search on, it will not show up. As with all tools, you may need to compare the results of several different searches or grep long search results to find the best program for your needs.