catman - create the formatted files for the reference manual


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


     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 exam-
     ple, with rdist(1)), since it makes the directories of  pre-
     formatted manual pages self-contained and independent of the
     unformatted entries.

     catman also creates the  windex database file in the  direc-
     tories specified by the  MANPATH or the  -M option. The win-
     dex 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 key-
     word 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, catman 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  pre-
     formatted manual page.

     Shadow files in an unformatted nroff source file are identi-
     fied 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.


     The following options are supported:

     -c    Create unformatted nroff source files in the appropri-
           ate  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  sub-
           directories instead of nroffing into the cat subdirec-

     -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  direc-
           tory,  (/usr/share/man  by default). If the  -M option
           is specified, the directory argument must not  contain
           a `,' (comma), since a comma is used to delineate sec-
           tion numbers. See man(1).

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


     The following operand is supported:

           If there is one parameter not starting with a `-',  it
           is  taken  to be a space separated list of manual sec-
           tions to be processed 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  MAN-
           PATH are processed.


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

           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  file  as  the
           default  section  search path. The -M and -s flags, in
           turn, override these values.


           default manual directory location

           raw nroff input files

           raw  SGML input files

           preformatted nroffed manual pages

           preformatted troffed manual pages

           table of contents and keyword database

           command script to make  windex database

           default macro package


     See attributes(5) for descriptions of the  following  attri-

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


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


     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.


     If a user, who has previously run catman to install the cat*
     directories,  upgrades the operating system, the entire cat*
     directory structure should be removed prior to running  cat-
     man. 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.


     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  applica-
     ble, separated by commas; a dash; and a brief summary state-
     ment. 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

Man(1) output converted with man2html