MAKEWHATIS(8)                System Administration               MAKEWHATIS(8)




NAME

       makewhatis - generate the whatis database file


SYNOPSIS

       makewhatis [ -c | -C ] [ -f outfile ] [ -l logfile ] [ -o dbfile ] [ -p
       path ] [ -v n ] [ -V ]


DESCRIPTION

       This manual page documents makewhatis version 3.1.

       makewhatis generates the whatis database for  apropos(1),  man(1),  and
       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.

       Makewhatis  makes use of one of the environment variables MANPATH, USR-
       MAN, or 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 -p flag.

       By  default,  makewhatis  will  generate its database from manual pages
       existing in the manpath_component/manX subdirectories (where X  is  the
       section  number) that are either aroff or nroff source files.  However,
       since many GNO programmers are providing only  preformatted  text  ver-
       sions  of  their  man pages, using the -c flag will cause makewhatis to
       also use manual pages in the manpath_component/catX subdirectories when
       building the database.  If there is a corresponding manual page in both
       the manX and catX subdirectory, then only the page in the  manX  subdi-
       rectory will be used.

       Manual  pages which are nroff source files in the manX subdirectory, or
       are preformatted text in the catX subdirectory  may  be  compressed  by
       either  compress(1),  freeze(1), or gzip(1), provided that the suffixes
       on the compressed file are .Z, .F, and .gz, respectively.  The case  of
       the  suffix  is significant.  Aroff source files must not be compressed
       by any method.

       All aroff link files are ignored.  A file is assumed  to  be  an  aroff
       link  file  if  it  ends in .l (dot lower-case ell) and is not within a
       manl (man-ell) or a catl (cat-ell) subdirectory.

       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 makewhatis is finished.  See sort(1) or msort(1).


OPTIONS

       -c     will check catX subdirectories as well as manX subdirectories.

       -C     will check only catX subdirectories, not manX subdirectories.

       -f outfile
              causes  the  makewhatis  status  output to be placed in outfile.
              Invoking -f without -v2 produces no output.

       -l logfile
              will cause any error messages to be printed to logfile.   Invok-
              ing -l without either -v1 or -v2 produces no output.

       -o dbfile
              will  make  makewhatis  use dbfile as the name for the generated
              whatis databases.  While it is possible to use a  full  pathname
              for  dbfile, this will result in that file being overwritten for
              each colon- or space-delimited entry in MANPATH.

       -p path
              overrides the environment variables MANPATH et al for  determin-
              ing for which manual page hierarchies the databases must be gen-
              erated.

       -v n   creates verbose status messages during execution.  For n=1  only
              major  error  messages  are  printed out.  For n=2, the names of
              processed files are also printed.  For n=3, the  output  becomes
              very  verbose with excessive status information, including list-
              ing any missing subdirectores.

       -V     will show version and usage information, then exit.


ENVIRONMENT

       MANPATH
       USRMAN
       MANDIR
              Unless the -p flag is used, 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 makewhatis will correctly handle '~' and '.'
              being part of these paths, it will not correctly handle '..'.

              Either colons or spaces can be used to  delimit  the  individual
              paths.   If  the value of the selected environment variable con-
              tains no spaces nor / characters (such as :usr:local:man), it is
              assumed to be a single path, not a list of paths.

              Although makewhatis allows USRMAN and MANDIR to be each a colon-
              or space-separated list of pathnames, it is recommended that for
              compatibility  with  man  (version  2.1 and earlier) these vari-
              ables, if used, should be a single pathname.


CAVEATS

       Makewhatis assumes that the programs aroff, compress, freeze, and  gzip
       are  available to the executing shell via the system(2) call.  Nroff is
       not used and need not be available.

       Because makewhatis looks for the string NAME and one of .SH,  SYNOPSIS,
       or  DESCRIPTION  when  processing  files, it can be confused by missing
       fields or some methods of formatting.  For example, if in a  preformat-
       ted  manual  page NAME is underlined by repeated backspace-_ sequences,
       then the generated description for that particular man page  is  unpre-
       dictable,  though  usually  blank.   When  parsing  preformatted manual
       pages, makewhatis will understand the  common  double-  and  quadruple-
       boldfaced  subheadings, provided that the backspace character (control-
       H) is used to achieve this effect.

       Similarily, makewhatis expects the subheading NAME to be in the format:
               NAME
                   command_name [...] - brief description
       If  this  is  not  so  (ignoring whitespace), then the output is unpre-
       dictable.

       Man pages must be CR-delimited (ASCII 015, or control-M).

       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 does not mean that system integrity or that
       the remainder of the database file has been affected.

       Any  text appearing after NAME on the NAME header line will be ignored.


BUGS

       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 .BR in the output.  This  was  not  fixed
       due to the overhead of having to check for such a condition.

       Please report any additional bugs to Devin Reade, <gdr@trenco.gno.org>.


FILES

       /usr/[share/]man/whatis -- the whatis database


SEE ALSO

       apropos(1),  aroff(1),  catman(1),  compress(1),  freeze(1),   gzip(1),
       man(1), nroff(1), whatis(1)



GNO                              28 March 1998                   MAKEWHATIS(8)

Man(1) output converted with man2html