catman(1M) System Administration Commands catman(1M)NAMEcatman - create the formatted files for the reference manual
SYNOPSIS
/usr/bin/catman [-c] [-n] [-p] [-t] [-w] [-M directory] [-T macro-pack‐
age] [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 speci‐
fied 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 immedi‐
ately 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 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 exist‐
ing file in the man directory of the same name
as the SGML file.
-n Do not create (or recreate) the windex data‐
base. 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 specified, 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 man‐
ual 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 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 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 pro‐
cessed by catman and man(1). Each directory can be fol‐
lowed 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 ALSOapropos(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* directo‐
ries, 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 com‐
plete 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 fol‐
low 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 per‐
mitted.
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)
