catman(1M) System Administration Commands catman(1M)
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 example, with rdist(1)), since it
makes the directories of preformatted manual pages self-contained and independent of the
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 key-
word, 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, catman recreates the windex database.
If a manual page is a shadow page, that is, it sources another manual page for its con-
tents, a symbolic link is made in the catx or fmtx directory to the appropriate preformat-
ted 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.
The following options are supported:
-c Create unformatted nroff source files in the appropriate man subdirec-
tories 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 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 manual page macros, (
man(5) by default).
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 processed by catman. If this operand
is specified, only the manual sections in the list will be processed. For
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.
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.
/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
See attributes(5) for descriptions of the following attributes:
| 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),
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
target of .so in man?/xxx.? must be relative to /usr/man
catman only allows references to filenames that are relative to the directory
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
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.
To generate a valid windex index file, catman has certain requirements. Within the indi-
vidual 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"
nismatch, nisgrep \- utilities for searching NIS+ tables
SunOS 5.11 27 Feb 1998 catman(1M)