gno/usr.bin/man/makewhatis.8

.TH MAKEWHATIS 1 "Commands and Applications" "15 May 1994" "Version 1.0"
.SH NAME
.B makewhatis
\- generate the whatis database file
.SH SYNOPSIS
.B makewhatis
[
.I -c
|
.I -C
] [
.I -ovV
] [
.I "-f outfile"
] [
.I "-l logfile"
] [
.I "-p path"
]
.SH DESCRIPTION
.B makewhatis
generates the whatis database for
.BR whatis "(1) and " apropos "(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.
.LP
By default,
.B makewhatis
makes use of one of the environment variables \fIMANPATH\fR, \fIUSRMAN\fR,
or \fIMANDIR\fR, 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 spaces), then whatis databases will be generated
in all of the specified paths.
.LP
The routines used are compatible with man pages in
.BR nroff ,
.BR aroff ,
.BR compress ", or"
.BR freeze
format, as well as text versions of manual pages in the man/catX hierarchy.
.B Makewhatis
assumes that the suffixes \fI.Z\fR and \fI.F\fR are are appended to the
chapter number on file names when those files are in
.BR compress " or " freeze
format, respectively.  (For example, a compressed file would be expected
to have a file name similar to
.I foo.3.Z
or \fIbar.3v.Z\fR.)
Any files using the
.I ".l"
(ell) suffix are ignored.  All suffix tests are case insensitive.
.LP
By default,
.B makewhatis
will only use files in the man/manX hierarchy in the creation of the
database.  However, since many Gno programmers are providing only text
versions of their man pages, invoking
.B makewhatis
with the
.I -c
flag will add descriptions for all files in the man/catX hierarchy that
don't have a counterpart in the man/manX hierarchy.  This conditional
eliminates the parsing of files in man/catX generated by
.BR catman (1).
.LP
Note that the lines in the whatis database file are created in the order
that the man pages are found.  It is suggested that the database be sorted
after
.B makewhatis
is finished.  See
.BR sort (1).
.SH OPTIONS
.I -c
will check man/catX sub-directories as well as man/manX
.LP
.I -C
will check
.BR only
man/catX sub-directories, not man/manX sub-directories.
.LP
.I "-f outfile"
causes the
.B makewhatis
status output to be placed in \fIoutfile\fR.
.LP
.I "-l logfile"
will cause any error messages to be printed to \fIlogfile\fR.
.LP
.I "-o dbfile"
will make
.B makewhatis
use
.I dbfile
as the name for the generated whatis databases.
.LP
.I "-p path"
overrides the environment variables
.I MANPATH
et al for determining for which manual page hierarchies the databases must
be generated.
.LP
.I -v
creates verbose status messages during execution.
.LP
.I -V
will show version and usage information, then exit.
.SH ENVIRONMENT
\fIMANPATH\fR, \fIUSRMAN\fR, \fIMANDIR\fR:
.br
Unless the
.I -p
flag is used,
.B makewhatis
will use the first that it finds of these environment variables for
determining where database files should be generated.  While
.B makewhatis
will correctly handle
.I ~
and
.I .
being part of these paths, it will not correctly handle \fI..\fR.
.SH CAVEATS
Because
.B makewhatis
looks for the string
.I NAME
and one of \fI.SH\fR, \fISYNOPSIS\fR, or
.I DESCRIPTION
when processing files, it can be confused by missing fields or
some methods of formatting.  For example, if in a man/catX page
.I NAME
is boldfaced by repeated backspace characters as in \fIN^HNA^HAM^HME^HE\fR,
then the generated description for that particular man page is unpredictable,
though usually blank.  For any diehards who like placing such information
in their hand-coded man/catX pages, using a string similar to
.I "NAME^H^H^H^HNAME"
will create a proper description in the database file.
.LP
Similarily,
.B makewhatis
expects the subheading
.I NAME
to be in the format:
.nf
        NAME
            <command> - <brief description>
.fi
If this is not so (ignoring whitespace), then the output is unpredictable.
.LP
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
.I "does not"
mean that system integrity or that the remainder of the database file
has been affected.
.SH BUGS
If a man page describes multiple items and has a NAME subheading such as
.nf

NAME
       item1, item2, item3 - This is the description.

.fi
Then
.B makewhatis
should create a database record that reads:
.nf

       item1 (3), item2 (3), item3 (3) - This is the description.

.fi
Instead, if item2.l and item3.l are links to item1.3, the created record reads
.nf

       item1 (3) - This is the description.

.fi
.SH FILES
.nf
/usr/sbin/makewhatis -- whatis database generator
man/whatis           -- the whatis database
.fi
.SH SEE ALSO
.BR apropos (1),
.BR catman (1),
.BR man (1),
.BR whatis (1),
.SH AUTHOR
Written by Devin Reade <glyn@cs.ualberta.ca> for the Apple IIgs and Gno.