mirror of https://github.com/GnoConsortium/gno.git
308 lines
6.7 KiB
Groff
308 lines
6.7 KiB
Groff
.TH MAKEWHATIS 8 "28 March 1998" GNO "System Administration"
|
|
.SH NAME
|
|
.B makewhatis
|
|
\- generate the whatis database file
|
|
.SH SYNOPSIS
|
|
.B makewhatis
|
|
[
|
|
.B -c
|
|
|
|
|
.B -C
|
|
] [
|
|
.BI -f " outfile"
|
|
] [
|
|
.BI -l " logfile"
|
|
] [
|
|
.BI -o " dbfile"
|
|
] [
|
|
.BI -p " path"
|
|
] [
|
|
.BI -v " n"
|
|
] [
|
|
.B -V
|
|
]
|
|
.SH DESCRIPTION
|
|
This manual page documents
|
|
.B makewhatis
|
|
version 3.1.
|
|
.LP
|
|
.B makewhatis
|
|
generates the whatis database for
|
|
.BR apropos (1),
|
|
.BR man (1),
|
|
and
|
|
.BR 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.
|
|
.LP
|
|
.B Makewhatis
|
|
makes use of one of the environment variables
|
|
.BR MANPATH ,
|
|
.BR USRMAN ,
|
|
or
|
|
.BR 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 databases will be generated
|
|
in all of the specified paths. This may be overridden by the
|
|
.BR -p
|
|
flag.
|
|
.LP
|
|
By default,
|
|
.BR makewhatis
|
|
will generate its database from manual pages existing in the
|
|
.IB manpath_component /man X
|
|
subdirectories (where
|
|
.I X
|
|
is the section number)
|
|
that are either
|
|
.BR aroff
|
|
or
|
|
.BR nroff
|
|
source files.
|
|
However, since many GNO programmers are providing only preformatted
|
|
text versions of their man pages, using the
|
|
.I -c
|
|
flag will cause
|
|
.B makewhatis
|
|
to also use manual pages in the
|
|
.IB manpath_component /cat X
|
|
subdirectories when building the database.
|
|
If there is a corresponding manual page in both the
|
|
.BI man X
|
|
and
|
|
.BI cat X
|
|
subdirectory, then only the page in the
|
|
.BI man X
|
|
subdirectory will be used.
|
|
.LP
|
|
Manual pages which are
|
|
.BR nroff
|
|
source files in the
|
|
.BI man X
|
|
subdirectory, or are preformatted text in the
|
|
.BI cat X
|
|
subdirectory may be compressed by either
|
|
.BR compress (1),
|
|
.BR freeze (1),
|
|
or
|
|
.BR gzip (1),
|
|
provided that the suffixes on the compressed file are
|
|
.BR ".Z" ,
|
|
.BR ".F" ,
|
|
and
|
|
.BR ".gz" ,
|
|
respectively. The case of the suffix is significant.
|
|
.BR Aroff
|
|
source files
|
|
.I "must not"
|
|
be compressed by any method.
|
|
.LP
|
|
All
|
|
.BR aroff
|
|
link files are ignored. A file is assumed to be an
|
|
.BR aroff
|
|
link file if it ends in
|
|
.B ".l"
|
|
(dot lower-case ell) and is not within a
|
|
.BR manl
|
|
(man-ell) or a
|
|
.BR catl
|
|
(cat-ell) subdirectory.
|
|
.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 files
|
|
be sorted after
|
|
.B makewhatis
|
|
is finished. See
|
|
.BR sort (1)
|
|
or
|
|
.BR msort (1) .
|
|
.SH OPTIONS
|
|
.IP "\fB\-c\fP"
|
|
will check
|
|
.BI cat X
|
|
subdirectories as well as
|
|
.BI man X
|
|
subdirectories.
|
|
.IP \fB\-C\fP
|
|
will check
|
|
.I only
|
|
.BI cat X
|
|
subdirectories,
|
|
.I not
|
|
.BI man X
|
|
subdirectories.
|
|
.IP "\fB-f\fR \fIoutfile\fR"
|
|
causes the
|
|
.B makewhatis
|
|
status output to be placed in
|
|
.IR outfile .
|
|
Invoking
|
|
.B -f
|
|
without
|
|
.B -v2
|
|
produces no output.
|
|
.IP "\fB-l\fR \fIlogfile\fR"
|
|
will cause any error messages to be printed to
|
|
.IR logfile .
|
|
Invoking
|
|
.B -l
|
|
without either
|
|
.B -v1
|
|
or
|
|
.B -v2
|
|
produces no output.
|
|
.IP "\fB-o\fR \fIdbfile\fR"
|
|
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
|
|
.IR dbfile ,
|
|
this will result in that file being overwritten for each colon- or
|
|
space-delimited entry in
|
|
.BR MANPATH .
|
|
.IP "\fB-p\fR \fIpath\fR"
|
|
overrides the environment variables
|
|
.B MANPATH
|
|
et al for determining for which manual page hierarchies the databases must
|
|
be generated.
|
|
.IP "\fB-v\fR \fIn\fR"
|
|
creates verbose status messages during execution. For
|
|
.IR n =1
|
|
only major error messages are printed out. For
|
|
.IR n =2,
|
|
the names of processed files are also printed. For
|
|
.IR n =3,
|
|
the output becomes very verbose with excessive status information, including
|
|
listing any missing subdirectores.
|
|
.IP \fB-V\fR
|
|
will show version and usage information, then exit.
|
|
.SH ENVIRONMENT
|
|
.BR MANPATH
|
|
.br
|
|
.BR USRMAN
|
|
.br
|
|
.BR MANDIR
|
|
.RS
|
|
Unless the
|
|
.B -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. The search
|
|
is done in the order shown. While
|
|
.B makewhatis
|
|
will correctly handle
|
|
.RB ` ~ '
|
|
and
|
|
.RB ` . '
|
|
being part of these paths, it will not correctly handle
|
|
.RB ` .. '.
|
|
.sp 1
|
|
Either colons or spaces can be used to delimit the individual paths.
|
|
If the value of the selected environment variable contains no spaces
|
|
nor
|
|
.B /
|
|
characters (such as
|
|
.BR :usr:local:man ),
|
|
it is assumed to be a single path, not a list of paths.
|
|
.sp 1
|
|
Although
|
|
.B makewhatis
|
|
allows
|
|
.BR USRMAN
|
|
and
|
|
.BR MANDIR
|
|
to be each a colon- or space-separated list of pathnames,
|
|
it is recommended that for compatibility with
|
|
.BR man
|
|
(version 2.1 and earlier) these variables, if used, should be
|
|
a single pathname.
|
|
.RE
|
|
.SH CAVEATS
|
|
.B Makewhatis
|
|
assumes that the programs
|
|
.BR aroff ,
|
|
.BR compress ,
|
|
.BR freeze ,
|
|
and
|
|
.BR gzip
|
|
are available to the executing shell via the
|
|
.BR system (2)
|
|
call.
|
|
.BR Nroff
|
|
is not used and need not be available.
|
|
.LP
|
|
Because
|
|
.B makewhatis
|
|
looks for the string
|
|
.B NAME
|
|
and one of
|
|
.BR .SH ,
|
|
.BR SYNOPSIS ,
|
|
or
|
|
.B DESCRIPTION
|
|
when processing files, it can be confused by missing fields or
|
|
some methods of formatting. For example, if in a preformatted manual page
|
|
.B NAME
|
|
is underlined by repeated backspace-_ sequences, then the generated
|
|
description for that particular man page is unpredictable,
|
|
though usually blank. When parsing preformatted manual 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
|
|
.B NAME
|
|
to be in the format:
|
|
.nf
|
|
NAME
|
|
\fIcommand_name\fR [...] - \fIbrief description\fR
|
|
.fi
|
|
If this is not so (ignoring whitespace), then the output is unpredictable.
|
|
.LP
|
|
Man pages must be CR-delimited (ASCII 015, or control\-M).
|
|
.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
|
|
.B 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
|
|
.B .BR
|
|
in the output. This was not fixed due to the overhead of having to
|
|
check for such a condition.
|
|
.LP
|
|
Please report any additional bugs to Devin Reade, <gdr@trenco.gno.org>.
|
|
.SH FILES
|
|
.nf
|
|
/usr/[share/]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 gzip (1),
|
|
.BR man (1),
|
|
.BR nroff (1),
|
|
.BR whatis (1)
|