'\" te
.\" Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights    reserved.
.TH catman 1M "20 May 2015" "SunOS 5.11" "System Administration Commands"
.SH NAME
catman \- create the formatted files for the reference manual
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/catman\fR [\fB-c\fR] [\fB-n\fR] [\fB-p\fR] [\fB-t\fR] [\fB-w\fR] [\fB-M\fR \fIdirectory\fR] 
     [\fB-T\fR \fImacro-package\fR] [\fIsections\fR]
.fi

.LP
.nf
\fB/usr/bin/catman\fR [\fB-M\fR \fIdirectory\fR] \fB-w\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcatman\fR utility creates the preformatted versions of the on-line manual from the \fBgroff\fR(1) or \fBsgml\fR(5) input files. This feature allows easy distribution of the preformatted manual pages among a group of associated machines, since it makes the directories of preformatted manual pages self-contained and independent of the unformatted entries.
.sp
.LP
With the \fB-w\fR option, \fBcatman\fR also creates index files, in the directories specified by the \fBMANPATH\fR or the \fB-M\fR option. If there is no \fBMANPATH\fR or \fB-M\fR option specified, unless \fB-n\fR is specified, \fBcatman\fR creates index files at the \fB/usr/share/man/\fR and \fB/usr/gnu/share/man/\fR directories by default. When any specified or default directory is read-only, \fBcatman\fR fails and displays an error message to stderr, indicating that writing is not allowed to the directory.
.sp
.LP
Each manual page is examined and those whose preformatted versions are missing or out of date are recreated. If any changes are made, \fBcatman\fR recreates the index files.
.sp
.LP
If a manual page is a \fIshadow\fR page, that is, it sources another manual page for its contents, a symbolic link is made in the \fBcat\fR\fIx\fR or \fBfmt\fR\fIx\fR directory to the appropriate preformatted manual page.
.sp
.LP
Shadow files in an unformatted nroff source file are identified by the first line being of the form \fB\&.so man\fR\fIx\fR\fB/yyy.\fR\fIx\fR\fB\&.\fR
.sp
.LP
Shadow files in the \fBSGML\fR sources are identified by the string \fBSHADOW_PAGE\fR. The file entity declared in the shadow file identifies the file to be sourced.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-c\fR\fR
.ad
.sp .6
.RS 4n
Create unformatted nroff source files in the appropriate \fBman\fR subdirectories from the \fBSGML\fR sources. This option will overwrite any existing file in the \fBman\fR directory of the same name as the \fBSGML\fR file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Do not create (or recreate) the index files. If the \fB-n\fR option is specified, the index files are not created and the \fBapropos\fR(1) and \fBwhatis\fR(1) commands might run more slowly than otherwise.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fR
.ad
.sp .6
.RS 4n
Dry\(emrun option. That is, display what would be done instead of doing it.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
Create \fBtroff\fRed entries in the appropriate \fBfmt\fR subdirectories instead of \fBnroff\fRing into the \fBcat\fR subdirectories.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-w\fR\fR
.ad
.sp .6
.RS 4n
Create the index files that are used by \fBapropos\fR(1), \fBwhatis\fR(1) and the \fBman\fR(1) \fB-f\fR, \fB-k\fR, and \fB-K\fR options, in the directories specified by the \fBMANPATH\fR environment variable or the \fB-M\fR option. If no \fBMANPATH\fR or \fB-M\fR option is specified, index files are created in the \fB/usr/share/man/\fR and \fB/usr/gnu/share/man/\fR directories by default. No manual reformatting is done.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-M\fR \fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
Update manual pages located in the specified \fIdirectory\fR, (\fB/usr/share/man\fR by default). If the \fB-M\fR option is specified, the directory argument must not contain a `,' (comma), since a comma is used to delineate section numbers. See \fBman\fR(1).
.RE

.sp
.ne 2
.mk
.na
\fB\fB-T\fR \fImacro-package\fR\fR
.ad
.sp .6
.RS 4n
Use \fImacro-package\fR in place of the standard manual page macros.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.mk
.na
\fB\fIsections\fR\fR
.ad
.sp .6
.RS 4n
If there is one parameter not starting with a `\fB\(mi\fR\&', it is taken to be a space separated list of manual sections to be processed by \fBcatman\fR. If this operand is specified, only the manual sections in the list will be processed. For example,
.sp
.in +2
.nf
\fBcatman 1 2 3\fR
.fi
.in -2
.sp

only updates manual sections \fB1\fR, \fB2\fR, and \fB3\fR. If specific sections are not listed, all sections in the \fBman\fR directory specified by the environment variable \fBMANPATH\fR are processed.
.RE

.SH ENVIRONMENT VARIABLES
.sp
.ne 2
.mk
.na
\fB\fBTROFF\fR\fR
.ad
.sp .6
.RS 4n
The name of the formatter to use when the \fB-t\fR flag is given.
.RE

.sp
.ne 2
.mk
.na
\fB\fBMANPATH\fR\fR
.ad
.sp .6
.RS 4n
A colon-separated list of directories that are processed by \fBcatman\fR and \fBman\fR(1). Each directory can be followed by a comma-separated list of sections. If set, its value overrides \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in turn, override these values.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating an Index File
.sp
.LP
The following command creates an index file in the \fB/usr/local/share/man\fR directory.

.sp
.in +2
.nf
# \fBcatman -M /usr/local/share/man -w\fR
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man\fR\fR
.ad
.sp .6
.RS 4n
default manual directory location
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/man*/*.*\fR\fR
.ad
.sp .6
.RS 4n
raw nroff input files
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/sman*/*.*\fR\fR
.ad
.sp .6
.RS 4n
raw SGML input files
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/cat*/*.*\fR\fR
.ad
.sp .6
.RS 4n
preformatted \fBnroff\fRed manual pages
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/groff/<\fIversion\fR>/tmac/mandoc.tmac\fR\fR
.ad
.sp .6
.RS 4n
default macro package for groff
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/fmt*/*.*\fR\fR
.ad
.sp .6
.RS 4n
preformatted troffed manual pages
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/man_index/*\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.idx\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.dic\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.req\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.pos\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.doc\fR\fR
.ad
.br
.na
\fB\fB/usr/share/man/man_index/term.exp\fR\fR
.ad
.sp .6
.RS 4n
index file for \fB-K\fR query
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitytext/doctools
_
CSIEnabled
_
Interface StabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBapropos\fR(1), \fBman\fR(1), \fBgroff\fR(1), \fBrm\fR(1), \fBgtroff\fR(1), \fBwhatis\fR(1), \fBattributes\fR(5), \fBsgml\fR(5)
.SH DIAGNOSTICS
.sp
.ne 2
.mk
.na
\fB\fBman?/xxx.? (.so'ed from man?/yyy.?): No such file or directory\fR\fR
.ad
.sp .6
.RS 4n
The file outside the parentheses is missing, and is referred to by the file inside them.
.RE

.sp
.ne 2
.mk
.na
\fB\fBtarget of .so in man?/xxx.? must be relative to /path/to/man or .so in xxx.? indicating shadow file and its reference is in the same section subdirectory (man*)\fR\fR
.ad
.sp .6
.RS 4n
\fBcatman\fR only allows references to filenames that are relative to the directory \fB/path/to/man\fR with a pattern, \fB\&.so man?/xxx.?\fR, or in the same subdirectory with a brief pattern, \fB\&.so in xxx.?\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBopendir:man?:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR \fBdirectory\fR\fR
.ad
.sp .6
.RS 4n
A harmless warning message indicating that one of the directories \fBcatman\fR normally looks for is missing.
.RE

.sp
.ne 2
.mk
.na
\fB\fB*.*:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR \fBdirectory\fR\fR
.ad
.sp .6
.RS 4n
A harmless warning message indicating \fBcatman\fR came across an empty directory.
.RE

.SH WARNINGS
.sp
.LP
If a user, who has previously run \fBcatman\fR to install the \fBcat*\fR directories, upgrades the operating system, the entire \fBcat*\fR directory structure should be removed prior to running \fBcatman\fR. See \fBrm\fR(1).
.sp
.LP
Do not re-run \fBcatman\fR to rebuild the index files unless the complete set of \fBman*\fR directories is present. \fBcatman\fR builds the index files based on the \fBman*\fR directories.
.SH NOTES
.sp
.LP
The \fBwindex\fR database has been replaced by index files. Unlike the case with \fBwindex\fR, index file generation does not pose any specific restrictions or prerequisites on what can be indexed.
.sp
.LP
Manual pages in SGML format will not be supported in future releases of Oracle Solaris.