12. How do I get `apropos' and `whatis' to work?

Suppose you wonder what compilers are installed on your system and how these can be invoked. To answer this (frequently asked) question you say

funnyprompt$ apropos compiler
f77 (1) - Fortran 77 compiler 
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler

Apropos and whatis are used to quickly report which man page has information on a certain topic. Both programs search a number of files named `whatis' that may be found in each of the manual base directories. As previously stated, the whatis data base files contain a one line entry for any man page in the respective directory tree. In fact, that line is exactly the NAME section (to be precise: joined on one line and with hyphenation removed; note that the section is mentioned within parentheses). The whatis database files are created with the makewhatis(8) program. There are several versions around, so please refer to the man page to determine what options are available. In order for makewhatis to be able to extract the NAME sections correctly it is important that you, the manual writer, adhere to the NAME section format described under question 3). The differences between apropos and whatis are simply where in the line they look, and what they are looking for. Apropos (which is equivalent to man -k) searches the argument string anywhere on the line, whereas whatis (equivalent to man -f) tries to match a complete command name only on the part before the dash. Consequently, `whatis cc' will report if there is a cc manual and remain quiet for gcc.

Corrections and suggestions welcome!