makewhatis(ADM)

makewhatis -- generate man keyword database

Syntax

/usr/man/bin/makewhatis [-hvD]

Description

makewhatis generates keyword databases of manual pages. It writes one set of data in whatis(F) format for use by the utilities apropos(C) (man -k) and whatis to locate man pages by their description. It writes another set of data in index(F) format for use by man(C) to speed up searches for man page names.

makewhatis is run automatically during installation of the operating system. If man page are added subsequently, then an adminstrator should run it again to update the database files. Only root may use makewhatis. It always generates complete database files for all sections. It writes the database files to /usr/man/whatis and /usr/man/index.

makewhatis looks for man directories using MANPATH. See man(C) for details on MANPATH. If MANPATH is not specified as an environment variable when the command is run, then the default value is used from /usr/default/man. The man page directories must be subdirectories of an entry in the MANPATH value.

makewhatis can process man pages in several forms, including troff source, nroff-formatted pages, and HTML. Man page files compressed with compress(C), pack(C), gzip, and bzip2 can be handled as well.

The options to the command are:

-h: Help. Display usage syntax and exit.
-v: Verbose. Display directories being processed.
-d: Debug. Display details of processing each page.

Each entry in whatis consists of a line specifying a manual page name, its section, and a short description. Each type of manual page must be scanned for the information.

A troff source file must contain the following standard man key lines in this order:

   .TH name section
   .SH NAME
   name \- single-line description

makewhatis is flexible in what it will accept in the manual page source:

the case of the string ``NAME'' is arbitrary
the amount of whitespace between the elements of a key line is arbitrary as long as there is some
there may be any number of blank or non-blank lines between the key lines
the dash separating the manual page name and its description may be one of ``'', ``'', ``\'', ``\\'', ``\(mi'', or ``\(em''

For nroffed man pages, it looks for a name line by using any content following a NAME heading and before a blank line or another man section heading.

For HTML man pages, it will make use of the following meta tags embedded in the HEAD section of the HTML file:

   <META name="manwhatis"  content="name - description">

The keyword manwhatis identifies that the line is for man page indexing, and the content attribute provides the name and description data to be indexed. Multiple meta tags can be included to provide multiple names and descriptions for a commands on a man page.

Examples

The source for this manual page might look like:

   .TH	makewhatis ADM
   .\" Note the mixed case of NAME below
   .SH NaMe
   .\" This comment line is ignored
   makewhatis 	\ add entries to the keyword database
   .
   .
   .

This would produce the keyword database entry:

   makewhatis (ADM)	- add entries to the keyword database

Files

/usr/man/bin/makewhatis: Command executable.
/etc/default/man/: File containing default MANPATH which locates man directories.
/usr/man/whatis /usr/man/index: Keyword databases.

Standards conformance