Each component of the colon-delimited manpath is interpreted to be the root of a new tree containing directories of the form man*, within which are unformatted man pages of the form *.*. A separate whatis file and corresponding dbm files, whatis.pag and whatis.dir, will be placed at the root of that man tree. Files or directories ending in tilde (~) or in .bak or .old (in either case) will be skipped, as will a section named man0, should it exist.
In general, files in section manX should end in .X*, where X is a section of the manual like 1 or 3x11. This means it's ok to put things ending in 1c in man1, but not things ending in 3s. Any man page whose name doesn't match these criteria will generate a warning, but will be processed anyway. The exception to this is the mano subdirectory, which has traditionally been the receptacle of all obsolete man pages irrespective of their file extension. A better way to do that would be to have an entire man tree dedicated to this, as in /usr/old/man/.
Multiple entries occurring in the NAME section or as links (hard, soft, or via .so inclusion) will all be stored under the same man page name. This method can save significant amounts of disk space because it guarantees that only one cat page need be generated, regardless of how many ways you can get at the corresponding man page. Maintaining aliases as links or via a one-line file that .so's the real man page (once the only way to do this) is still supported although no longer required; mere inclusion in the NAME section is sufficient.
Embedded point and font changes will be removed from the output, and troff string macros for hyphens and underscores will be translated into their corresponding ASCII representations. In general, all that can be done will be done to produce nicely readable output for
The -v flag will generate verbose output, reporting such things as each new man tree examined, each subdirectory, each file that is opened, and each entry in the NAME section that is found and stored. Simple tracing information is printed to the standard output, while to standard error are directed more serious warnings.
The -n option can be used to check whether the database needs rebuilding. It will report on the first file in each man path that is out of date. Note that this is the only automated way to determine this; neither makewhatis nor man will realize that the database is out of date, so you should be careful to rebuild it whenever new man pages are added.
The -y option is similar, but after finding something out of date, makewhatis will automatically rebuild its database.
Support for compressed man pages is provided in the following way: if the name of the subdirectory itself ends in .Z, as in man8.Z, then all its files are assumed to have been compressed with Alternatively, individual files ending in .Z are also considered to be compressed. Compressed files are processed with
% makewhatis -y # build /usr/man database only if out of date % makewhatis /usr/local/man # make local man page database % makewhatis -v ~/man # make personal man page database verbosely % makewhatis -n $MANPATH # tell if any dbase in $MANPATH out of date
/usr/man/whatis default whatis database, text version /usr/man/whatis.pag dbm index file for default whatis database /usr/man/whatis.dir dbm data file for default whatis database /usr/man/man*/*.* default (unformatted) man pages /usr/man/cat*/*.* formatted man pages
``Skipping non-man file: %s '' A file was found in a man directory that has no dot in its name.
``%s has a funny extension to be in %s '' An apparent man file was found whose extension doesn't match the name of the man file in which it was found. This restriction does not apply to mano subdirectories.
``can't stat %s: %m '' The call returned an error. This can be caused by a symbolic link pointing to a non-existent file.
``can't open %s: %m '' The call returned an error, which is listed.
``can't chdir back to %s: %m '' After changing directory to one of the man subdirectories, makewhatis couldn't return to the initial root man tree. This is a fatal error.
``makewhatis: %s: found %d entries in %d files '' For the given root man directory, this many separate entry points were found for this many different files.
``%s .so references non-existent %s '' A file contains a .so reference to a missing man page.
``%s's .TH thinks it's in %s '' The man page's internal TH section has a different idea of where it lives than the actual file name.
``trimmed troff string macro in NAME section of %s '' An irresolvable troff string macro was found within the NAME section of the man page. This may cause peculiar whatis output.
``%s: no separated dash in %s '' The NAME section contained no dash in it to separate the list of man entries from their descriptions. This will also cause odd whatis output.
``%s: truncating cmdlist from %d to %d bytes for DBM's sake '' The NAME section contained too many characters. Due to built-in limitations of data entries, this entry was truncated. It will appear in whatis output with a trailing ``... '' at the point of truncation.
``%s: forgot my own name! '' A man page is stored in a file name that doesn't correspond to any of the entries in its NAME section.
``%s: no NAME lines, so has no whatis description! '' No parsable entries in the NAME section were discovered.
``%s was a .so alias for %s, but %s's NAME section doesn't know it! '' A .so reference was found to point to a man page whose own NAME section didn't contain the name of the .so file. This may be due to old man page aliases that were never de-installed when the base man page changed.
``can't store %s: would break DBM '' There were too many entries for a topic for it to be stored without exceeding inherent data size limitations.
Man pages should be formatted using the macro set. The only exceptions to this are the man pages from the Rand MH Message Handling System, whose own internal macro set is also recognized, and Larry Wall's .Sh section header macro.
makewhatis takes much longer to run if man pages are stored in compressed form.