catman(1M)                                                System Administration Commands                                                catman(1M)

NAME

       catman - create the formatted files for the reference manual

SYNOPSIS

       /usr/bin/catman [-c] [-n] [-p] [-t] [-w] [-M directory] [-T macro-package] [sections]

DESCRIPTION

       The  catman  utility  creates the preformatted versions of the on-line manual from the nroff(1) or sgml(5) input files. This feature allows
       easy distribution of the preformatted manual pages among a group of associated machines (for example, with rdist(1)), since  it  makes  the
       directories of preformatted manual pages self-contained and independent of the unformatted entries.

       catman also creates the  windex database file in the directories specified by the  MANPATH or the  -M option. The windex database file is a
       three column list consisting of a keyword, the reference page that the keyword points to, and a line of text that describes the purpose  of
       the  utility  or interface  documented on the reference page. Each keyword is taken from the comma separated list of words on the NAME line
       before the `-' (dash). The reference page that the keyword points to is the first word on the  NAME line. The text after the - on the  NAME
       line  is  the  descriptive text in the third column. The NAME line must be immediately preceded by the page heading line created by the .TH
       macro (see NOTES for required format).

       Each manual page is examined and those whose preformatted versions are missing or out of date are recreated. If any changes are made,  cat-
       man recreates the windex database.

       If  a  manual  page is a shadow page, that is, it sources another manual page for its contents, a symbolic link is made in the catx or fmtx
       directory to the appropriate preformatted manual page.

       Shadow files in an unformatted nroff source file are identified by the first line being of the form .so manx/yyy.x.

       Shadow files in the SGML sources are identified by the string SHADOW_PAGE. The file entity declared in the shadow file identifies the  file
       to be sourced.

OPTIONS

       The following options are supported:

       -c                      Create  unformatted  nroff  source  files in the appropriate man subdirectories from the  SGML sources. This option
                               will overwrite any existing file in the man directory of the same name as the  SGML file.

       -n                      Do not create (or recreate) the windex database. If the -n option is specified, the windex database is not  created
                               and the apropos, whatis, man -f, and man -k commands will fail.

       -p                      Print what would be done instead of doing it.

       -t                      Create troffed entries in the appropriate fmt subdirectories instead of nroffing into the cat subdirectories.

       -w                      Only create the windex database that is used by whatis(1) and the man(1) -f and -k options.  No manual reformatting
                               is done.

       -M directory            Update manual pages located in the specified directory, (/usr/share/man by default). If the  -M  option  is  speci-
                               fied,  the  directory  argument must not contain a `,' (comma), since a comma is used to delineate section numbers.
                               See man(1).

       -T macro-package        Use macro-package in place of the standard manual page macros, ( man(5) by default).

OPERANDS

       The following operand is supported:

       sections        If there is one parameter not starting with a `-', it is taken to be a space separated list of manual sections to  be  pro-
                       cessed by catman. If this operand is specified, only the manual sections in the list will be processed.  For example,

                       catman 1 2 3

                       only updates manual sections 1, 2, and 3. If specific sections are not listed, all sections in the  man directory specified
                       by the environment variable MANPATH are processed.

ENVIRONMENT VARIABLES

       TROFF           The name of the formatter to use when the -t flag is given. If not set, troff(1) is used.

       MANPATH         A colon-separated list of directories that are processed by catman and man(1). Each directory can be followed by  a  comma-
                       separated list of sections. If set, its value overrides /usr/share/man as the default directory search path, and the man.cf
                       file as the default section search path. The -M and -s flags, in turn, override these values.

FILES

       /usr/share/man                  default manual directory location

       /usr/share/man/man*/*.*         raw nroff input files

       /usr/share/man/sman*/*.*        raw  SGML input files

       /usr/share/man/cat*/*.*         preformatted nroffed manual pages

       /usr/share/man/fmt*/*.*         preformatted troffed manual pages

       /usr/share/man/windex           table of contents and keyword database

       /usr/lib/makewhatis             command script to make  windex database

       /usr/share/lib/tmac/an          default macro package

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWdoc                      |
       +-----------------------------+-----------------------------+
       |CSI                          |Enabled                      |
       +-----------------------------+-----------------------------+

SEE ALSO

       apropos(1), man(1), nroff(1), rdist(1), rm(1), troff(1), whatis(1), attributes(5), man(5), sgml(5)

DIAGNOSTICS

       man?/xxx.? (.so'ed from man?/yyy.?): No such file or directory

           The file outside the parentheses is missing, and is referred to by the file inside them.

       target of .so in man?/xxx.? must be relative to /usr/man

           catman only allows references to filenames that are relative to the directory /usr/man.

       opendir:man?: No such file or directory

           A harmless warning message indicating that one of the directories catman normally looks for is missing.

       *.*: No such file or directory

           A harmless warning message indicating catman came across an empty directory.

WARNINGS

       If a user, who has previously run catman to install the cat* directories, upgrades the operating system, the entire cat*  directory  struc-
       ture should be removed prior to running catman. See rm(1).

       Do  not  re-run  catman  to re-build the whatis database unless the complete set of man* directories is present. catman builds this  windex
       file based on the  man* directories.

NOTES

       To generate a valid windex index file, catman has certain requirements. Within the individual man page  file,  catman  requires  two  macro
       lines to have a specific format. These are the .TH page heading line and the .SH NAME line.

       The  .TH  macro  requires at least the first three arguments, that is, the filename, section number, and the date.  The .TH line starts off
       with the .TH macro, followed by a space, the man page filename, a single space, the section number, another single space, and the date. The
       date  should  appear  in  double  quotes and is specified as "day month year," with the month always abbreviated to the first three letters
       (Jan, Feb, Mar, and so forth).

       The .SH NAME macro, also known as the NAME line, must immediately follow the .TH line, with nothing in between those lines. No font changes
       are  permitted  in the NAME line. The NAME line is immediately followed by a line containing the man page filename; then shadow page names,
       if applicable, separated by commas; a dash; and a brief summary statement. These elements should all be on one line;  no  carriage  returns
       are permitted.

       An example of proper coding of these lines is:

       .TH nismatch 1M "10 Apr 1998"
       .SH NAME
       nismatch, nisgrep - utilities for searching NIS+ tables

SunOS 5.10                                                          27 Feb 1998                                                         catman(1M)