mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-12-21 23:29:16 +00:00
73ce022151
original makewhatis repository. Earlier versions of man, apropos, and whatis were by other authors (these are written from scratch). Catman is new.
304 lines
6.7 KiB
Groff
304 lines
6.7 KiB
Groff
.TH MAKEWHATIS 8 "System Administration" "24 July 1995" "Version 1.2"
|
|
.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
|
|
.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@myrias.com>.
|
|
.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)
|