MAKEWHATIS(8) System Administration MAKEWHATIS(8)
NAME
makewhatis - generate the whatis database file
SYNOPSIS
makewhatis [ -c | -C ] [ -f outfile ] [ -l logfile ] [ -o dbfile ] [ -p
path ] [ -v n ] [ -V ]
DESCRIPTION
This manual page documents makewhatis version 3.1.
makewhatis generates the whatis database for apropos(1), man(1), and
whatis(1). This database is a text file containing line oriented
records. Each record contains a man page name, the section number, and
the brief description.
Makewhatis makes use of one of the environment variables MANPATH, USR����
MAN, or MANDIR, in the listed order of preference. It will use this
environment variable to determine for which manual pages the whatis
database should be built. If the environment variable contains more
than one path (delimited by either colons or spaces), then whatis data‐
bases will be generated in all of the specified paths. This may be
overridden by the -p flag.
By default, makewhatis will generate its database from manual pages ex‐
isting in the manpath_component/manX subdirectories (where X is the
section number) that are either aroff or nroff source files. However,
since many GNO programmers are providing only preformatted text ver‐
sions of their man pages, using the -c flag will cause makewhatis to
also use manual pages in the manpath_component/catX subdirectories when
building the database. If there is a corresponding manual page in both
the manX and catX subdirectory, then only the page in the manX subdi‐
rectory will be used.
Manual pages which are nroff source files in the manX subdirectory, or
are preformatted text in the catX subdirectory may be compressed by ei‐
ther compress(1), freeze(1), or gzip(1), provided that the suffixes on
the compressed file are .Z, .F, and .gz, respectively. The case of the
suffix is significant. Aroff source files must not be compressed by
any method.
All aroff link files are ignored. A file is assumed to be an aroff
link file if it ends in .l (dot lower-case ell) and is not within a
manl (man-ell) or a catl (cat-ell) subdirectory.
Note that the lines in the whatis database file are created in the or‐
der that the man pages are found. It is suggested that the database
files be sorted after makewhatis is finished. See sort(1) or msort(1).
OPTIONS
-c will check catX subdirectories as well as manX subdirectories.
-C will check only catX subdirectories, not manX subdirectories.
-f outfile
causes the makewhatis status output to be placed in outfile.
Invoking -f without -v2 produces no output.
-l logfile
will cause any error messages to be printed to logfile. Invok‐
ing -l without either -v1 or -v2 produces no output.
-o dbfile
will make makewhatis use dbfile as the name for the generated
whatis databases. While it is possible to use a full pathname
for dbfile, this will result in that file being overwritten for
each colon- or space-delimited entry in MANPATH.
-p path
overrides the environment variables MANPATH et al for determin‐
ing for which manual page hierarchies the databases must be gen‐
erated.
-v n creates verbose status messages during execution. For n=1 only
major error messages are printed out. For n=2, the names of
processed files are also printed. For n=3, the output becomes
very verbose with excessive status information, including list‐
ing any missing subdirectores.
-V will show version and usage information, then exit.
ENVIRONMENT
MANPATH
USRMAN
MANDIR
Unless the -p flag is used, makewhatis will use the first that
it finds of these environment variables for determining where
database files should be generated. The search is done in the
order shown. While makewhatis will correctly handle `~' and `.'
being part of these paths, it will not correctly handle `..'.
Either colons or spaces can be used to delimit the individual
paths. If the value of the selected environment variable con‐
tains no spaces nor / characters (such as :usr:local:man), it is
assumed to be a single path, not a list of paths.
Although makewhatis allows USRMAN and MANDIR to be each a colon-
or space-separated list of pathnames, it is recommended that for
compatibility with man (version 2.1 and earlier) these vari‐
ables, if used, should be a single pathname.
CAVEATS
Makewhatis assumes that the programs aroff, compress, freeze, and gzip
are available to the executing shell via the system(2) call. Nroff is
not used and need not be available.
Because makewhatis looks for the string NAME and one of .SH, SYNOPSIS,
or DESCRIPTION when processing files, it can be confused by missing
fields or some methods of formatting. For example, if in a preformat‐
ted manual page NAME is underlined by repeated backspace-_ sequences,
then the generated description for that particular man page is unpre‐
dictable, though usually blank. When parsing preformatted manual
pages, makewhatis will understand the common double- and quadruple-
boldfaced subheadings, provided that the backspace character (control-
H) is used to achieve this effect.
Similarily, makewhatis expects the subheading NAME to be in the format:
NAME
command_name [...] - brief description
If this is not so (ignoring whitespace), then the output is unpre‐
dictable.
Man pages must be CR-delimited (ASCII 015, or control-M).
Where unpredictable output has been mentioned above, this means that
the description in the database file will either be blank or random
text from the man page. It does not mean that system integrity or that
the remainder of the database file has been affected.
Any text appearing after NAME on the NAME header line will be ignored.
BUGS
Makewhatis reads files in blocks of 1024 characters. If formatting in‐
formation is split by the end of the input buffer, you may see format‐
ting infomation such as .BR in the output. This was not fixed due to
the overhead of having to check for such a condition.
Please report any additional bugs to Devin Reade, <gdr@trenco.gno.org>.
FILES
/usr/[share/]man/whatis -- the whatis database
SEE ALSO
apropos(1), aroff(1), catman(1), compress(1), freeze(1), gzip(1),
man(1), nroff(1), whatis(1)
GNO 28 March 1998 MAKEWHATIS(8)
Man(1) output converted with
man2html