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 preformattedmanual 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 istaken 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 anychanges 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 ismade 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 thestring SHADOW_PAGE. The file entity declared in the shadow
file identifies the file to be sourced.SunOS 5.11 Last change: 10 Dec 2009 1
System Administration Commands catman(1M)
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 com-
mands will fail.-p
Print what would be done instead of doing it.-t
Create troffed entries in the appropriate fmt subdirec-
tories instead of nroffing into the cat subdirectories.-w
Only create the windex database that is used bywhatis(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).SunOS 5.11 Last change: 10 Dec 2009 2
System Administration Commands catman(1M)
OPERANDS The following operand is supported: sectionsIf there is one parameter not starting with a `-', it is
taken to be a space separated list of manual sections tobe 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 specificsections are not listed, all sections in the man direc-
tory specified by the environment variable MANPATH are processed. ENVIRONMENT VARIABLES TROFFThe name of the formatter to use when the -t flag is
given. If not set, troff(1) is used. MANPATHA 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 searchpath. 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 filesSunOS 5.11 Last change: 10 Dec 2009 3
System Administration Commands catman(1M)
/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 packageATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | text/doctools ||_____________________________|_____________________________|
| CSI | Enabled ||_____________________________|_____________________________|
SEE ALSO
apropos(1), man(1), nroff(1), rdist(1), rm(1), troff(1), whatis(1), attributes(5), man(5), sgml(5) DIAGNOSTICSman?/xxx.? (.so'ed from man?/yyy.?): No such file or direc-
tory The file outside the parentheses is missing, and is referred to by the file inside them.SunOS 5.11 Last change: 10 Dec 2009 4
System Administration Commands catman(1M)
target of .so in man?/xxx.? must be relative to /usr/mancatman 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 thedirectories catman normally looks for is missing.
*.*: No such file or directoryA harmless warning message indicating catman came across
an empty directory. WARNINGSIf 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. NOTESTo 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. Theseare 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 betweenthose 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 summarySunOS 5.11 Last change: 10 Dec 2009 5
System Administration Commands catman(1M)
statement. These elements should all be on one line; no car-
riage 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.11 Last change: 10 Dec 2009 6