'\" te
.\" Copyright (c) 1998, 2015, Oracle and/or its affiliates.All rights reserved.
.TH catman 1M "2015 年 5 月 20 日" "SunOS 5.11" "系统管理命令"
.SH 名称
catman \- 创建参考手册的格式化文件
.SH 用法概要
.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 描述
.sp
.LP
\fBcatman\fR 实用程序基于 \fBgroff\fR(1) 或 \fBsgml\fR(5) 输入文件创建联机手册的预格式化版本。通过此功能，可以轻松地在一组关联的计算机之间分发预格式化手册页，因为此功能使预格式化手册页的目录成为自包含目录，独立于未格式化的条目。
.sp
.LP
通过 \fB-w\fR 选项，\fBcatman\fR 还可在 \fBMANPATH\fR 或 \fB-M\fR 选项指定的目录中创建索引文件。如果未指定 \fBMANPATH\fR 或 \fB- M\fR 选项，且未指定 \fB-n\fR，\fBcatman \fR 缺省情况下会在 \fB/usr/share/man/\fR 和 \fB /usr/gnu/share/man/\fR 目录中创建索引文件。如果任何指定或缺省目录为只读目录，则 \fBcatman\fR 会失败，并在标准错误中显示一条错误消息，指出不允许写入该目录。
.sp
.LP
系统会检查每个手册页，并对预格式化版本缺失或过期的手册页进行重新创建。如果进行了任何更改，则 \fBcatman\fR 将重新创建索引文件。
.sp
.LP
如果手册页为 \fIshadow\fR 页，即该手册页将另一手册页作为其内容源，则会在 \fBcat\fR\fIx\fR 或 \fBfmt\fR\fI x\fR 目录中创建指向相应预格式化手册页的符号链接。
.sp
.LP
未格式化 nroff 源文件中的阴影文件由第一行标识，其形式如下：\fB\&.so man\fR\fIx\fR\fB /yyy.\fR\fIx\fR\fB。\fR
.sp
.LP
\fBSGML\fR 源中的阴影文件由字符串 \fBSHADOW_PAGE\fR 标识。在阴影文件中声明的文件实体标识要作为源的文件。
.SH 选项
.sp
.LP
支持以下选项：
.sp
.ne 2
.mk
.na
\fB\fB-c\fR\fR
.ad
.sp .6
.RS 4n
基于 \fBSGML\fR 源在相应 \fB man\fR 子目录中创建未格式化的 nroff 源文件。此选项将覆盖 \fBman\fR 目录中与 \fBSGML\fR 文件具有相同名称的任何现有文件。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
不创建（或重新创建）索引文件。如果指定了 \fB-n\fR 选项，则不会创建索引文件，并且 \fBapropos\fR(1) 和 \fBwhatis\fR(1) 命令可能比其他情况下运行速度慢。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fR
.ad
.sp .6
.RS 4n
模拟运行选项。即显示将执行的操作，而不实际执行。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
在相应 \fB fmt\fR 子目录中创建经过 \fBtroff\fR 处理的条目，而不是通过 \fBnroff\fR 置入 \fBcat\fR 子目录。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-w\fR\fR
.ad
.sp .6
.RS 4n
在 \fBMANPATH\fR 环境变量或 \fB-M\fR 选项指定的目录中，创建供 \fBapropos\fR(1)、\fBwhatis\fR(1) 以及 \fBman\fR(1) \fB-f\fR、\fB-k\fR 和 \fB-K\fR 选项使用的索引文件。如果未指定 \fBMANPATH\fR 或 \fB-M\fR 选项，则缺省情况下会在 \fB/usr/share/man/\fR 和 \fB /usr/gnu/share/man/\fR 目录中创建索引文件。不会执行手册重新格式化。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-M\fR \fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
更新位于指定 \fIdirectory \fR（缺省情况下为 \fB/usr/share/man\fR）中的手册页。如果指定了 \fB-M\fR 选项，则目录参数不能包含 `,'（逗号），因为逗号用于分隔节编号。请参见 \fBman\fR(1)。
.RE

.sp
.ne 2
.mk
.na
\fB\fB-T\fR \fImacro-package\fR\fR
.ad
.sp .6
.RS 4n
使用 \fImacro-package\fR 而非标准手册页宏。
.RE

.SH 操作数
.sp
.LP
支持下列操作数：
.sp
.ne 2
.mk
.na
\fB\fIsections\fR\fR
.ad
.sp .6
.RS 4n
如果有一个不以 `\fB-\fR' 开头的参数，则将其作为要由 \fBcatman\fR 处理的手册节的空格分隔列表。如果指定了此操作数，则仅处理列表中的手册节。例如，
.sp
.in +2
.nf
\fBcatman 1 2 3\fR
.fi
.in -2
.sp

仅更新手册节 \fB1\fR、\fB2\fR 和 \fB3\fR。如果未列出特定节，则处理由环境变量 \fB MANPATH\fR 指定的 \fBman\fR 目录中的所有节。
.RE

.SH 环境变量
.sp
.ne 2
.mk
.na
\fB\fBTROFF\fR\fR
.ad
.sp .6
.RS 4n
指定 \fB-t\fR 标志时要使用的格式化程序的名称。
.RE

.sp
.ne 2
.mk
.na
\fB\fBMANPATH\fR\fR
.ad
.sp .6
.RS 4n
供 \fB catman\fR 和 \fBman\fR(1) 处理的目录的冒号分隔列表。每个目录后面可以跟有节的逗号分隔列表。如果设置，则其值将覆盖作为缺省目录搜索路径的 \fB/usr/share/man\fR，以及作为缺省节搜索路径的 \fBman.cf\fR 文件。\fB-M\fR 和 \fB-s\fR 标志反过来会覆盖这些值。
.RE

.SH 示例
.LP
\fB示例 1 \fR创建索引文件
.sp
.LP
以下命令在 \fB/usr/local/share/man\fR 目录中创建索引文件。

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

.SH 文件
.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man\fR\fR
.ad
.sp .6
.RS 4n
缺省手册目录位置
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/man*/*.*\fR\fR
.ad
.sp .6
.RS 4n
原始 nroff 输入文件
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/sman*/*.*\fR\fR
.ad
.sp .6
.RS 4n
原始SGML输入文件
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/cat*/*.*\fR\fR
.ad
.sp .6
.RS 4n
预格式化的 \fBnroff\fR 手册页
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/groff/<\fIversion\fR>/tmac/mandoc.tmac\fR\fR
.ad
.sp .6
.RS 4n
groff 的缺省宏软件包
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/fmt*/*.*\fR\fR
.ad
.sp .6
.RS 4n
预格式化的已进行了 troff 处理的手册页
.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
\fB-K\fR 查询的索引文件
.RE

.SH 属性
.sp
.LP
有关下列属性的说明，请参见 \fBattributes\fR(5)：
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
属性类型属性值
_
可用性text/doctools
_
CSIEnabled（已启用）
_
接口稳定性Committed（已确定）
.TE

.SH 另请参见
.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 诊断
.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
括号外的文件缺失，括号内的文件引用了缺失的文件。
.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 只允许使用 \fB\&.so man?/xxx.?\fR 模式引用相对于目录 \fB/path/to/man\fR 的文件名，或者使用更简短的 \fB\&.so in xxx.?\fR 模式引用位于同一子目录中的文件名。
.RE

.sp
.ne 2
.mk
.na
\fB\fBopendir:man?:\fR \fBNo\fR \fB such\fR \fBfile\fR \fBor\fR \fBdirectory\fR\fR
.ad
.sp .6
.RS 4n
一条无害的警告消息，指出 \fB catman\fR 通常查找的目录之一缺失。
.RE

.sp
.ne 2
.mk
.na
\fB\fB*.*:\fR \fBNo\fR \fBsuch\fR \fB file\fR \fBor\fR \fBdirectory\fR\fR
.ad
.sp .6
.RS 4n
一条无害的警告消息，指出 \fBcatman\fR 遇到一个空目录。
.RE

.SH 警告
.sp
.LP
如果先前运行 \fBcatman\fR 安装 \fBcat*\fR 目录的用户升级操作系统，则应该在运行 \fBcatman\fR 之前删除整个 \fBcat*\fR 目录结构。请参见 \fBrm\fR(1)。
.sp
.LP
不要重新运行 \fBcatman\fR 以重建索引文件，除非存在完整的 \fBman*\fR 目录集。\fBcatman \fR 基于 \fBman*\fR 目录构建索引文件。
.SH 附注
.sp
.LP
\fBwindex\fR 数据库已由索引文件取代。与 \fBwindex\fR 不同，索引文件生成对可以编制索引的内容没有任何特定限制或先决条件。
.sp
.LP
将来的 Oracle Solaris 发行版中将不支持 SGML 格式的手册页。