.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 - .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 for the Apple IIgs and Gno.