mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-09-27 12:55:35 +00:00
219 lines
5.6 KiB
Groff
219 lines
5.6 KiB
Groff
.TH MAKEWHATIS 1 "Commands and Applications" "29 May 1994" "Version 1.1"
|
|
.SH NAME
|
|
.B makewhatis
|
|
\- generate the whatis database file
|
|
.SH SYNOPSIS
|
|
.B makewhatis
|
|
[
|
|
.I -c
|
|
|
|
|
.I -C
|
|
] [
|
|
.I "-f outfile"
|
|
] [
|
|
.I "-l logfile"
|
|
] [
|
|
.I "-o dbfile"
|
|
] [
|
|
.I "-p path"
|
|
] [
|
|
.I "-v n"
|
|
] [
|
|
.I "-V"
|
|
]
|
|
.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. Invoking
|
|
.I "-f"
|
|
without
|
|
.I "-v2"
|
|
produces no output.
|
|
.LP
|
|
.I "-l logfile"
|
|
will cause any error messages to be printed to \fIlogfile\fR. Invoking
|
|
.I "-l"
|
|
without either
|
|
.I "-v1"
|
|
or
|
|
.I "-v2"
|
|
produces no output.
|
|
.LP
|
|
.I "-o dbfile"
|
|
will make
|
|
.B makewhatis
|
|
use
|
|
.I dbfile
|
|
as the name for the generated whatis databases. While it is possible to
|
|
use a full pathname for
|
|
.I dbfile
|
|
, this will result in that file being overwritten for each space-delimited
|
|
entry in \fIMANPATH\fR.
|
|
.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 n"
|
|
creates verbose status messages during execution. For n=1 only error
|
|
messages are printed out. For n=2, both error and status messages are
|
|
printed.
|
|
.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
|
|
.B Makewhatis
|
|
assumes that the programs
|
|
.BR aroff ,
|
|
.BR compress ", and"
|
|
.BR freeze
|
|
are available to the executing shell via the \fIsystem\fR(2) call.
|
|
Nroff is not used and need not be available.
|
|
.LP
|
|
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 underlined by repeated backspace-_ sequences, then the generated
|
|
description for that particular man page is unpredictable,
|
|
though usually blank. When parsing man pages,
|
|
.B makewhatis
|
|
will understand the common double- and quadruple-boldfaced
|
|
subheadings, provided
|
|
that the backspace character (control-H) is used to achieve this effect.
|
|
.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
|
|
Man pages must be CR-deliminated.
|
|
.LP
|
|
If aroff source is compressed or frozen, the database entry for that
|
|
page 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.
|
|
.LP
|
|
Any text appearing after
|
|
.I NAME
|
|
on the NAME header line will be ignored.
|
|
.SH BUGS
|
|
.B Makewhatis
|
|
reads files in blocks of 1024 characters.
|
|
If formatting information is split by the end
|
|
of the input buffer, you may see formatting infomation such as
|
|
.I .BR
|
|
in the output. This was not fixed due to the overhead of having to
|
|
check for such a condition.
|
|
.SH FILES
|
|
.nf
|
|
/usr/sbin/makewhatis -- whatis database generator
|
|
man/whatis -- the whatis database
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR apropos (1),
|
|
.BR aroff (1),
|
|
.BR catman (1),
|
|
.BR compress (1),
|
|
.BR freeze (1),
|
|
.BR man (1),
|
|
.BR nroff (1),
|
|
.BR whatis (1)
|
|
.SH AUTHOR
|
|
Written by Devin Reade <glyn@cs.ualberta.ca> for the Apple IIgs and Gno.
|