mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-10-12 07:23:41 +00:00
191 lines
4.9 KiB
Groff
191 lines
4.9 KiB
Groff
|
.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.
|