catman

- create the formatted files for the reference manual

用法概要

/usr/bin/catman [-c] [-n] [-p] [-t] [-w] [-M directory] 
     [-T macro-package] [sections]

/usr/bin/catman [-M directory] -w

描述

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, since it makes the directories of preformatted manual pages self-contained and independent of the unformatted entries.

With the -w option, catman also creates index files, in the directories specified by the MANPATH or the -M option. If there is no MANPATH or -M option specified, unless -n is specified, catman creates index files at the /usr/share/man/ and /usr/gnu/share/man/ directories by default. When any specified or default directory is read-only, catman fails and displays an error message to stderr, indicating that writing is not allowed to the directory.

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 index files.

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.

选项

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 index files. If the -n option is specified, the index files are not created and the apropos(1) and whatis(1) commands might run more slowly than otherwise.

-p

Dry—run option. That is, display 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

Create the index files that are used by apropos(1), whatis(1) and the man(1) -f, -k, and -K options, in the directories specified by the MANPATH environment variable or the -M option. If no MANPATH or -M option is specified, index files are created in the /usr/share/man/ and /usr/gnu/share/man/ directories by default. 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 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.

环境变量

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.

示例

示例 1 Creating an Index File

The following command creates an index file in the /usr/local/share/man directory.

# catman -M /usr/local/share/man -w

文件

/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/lib/tmac/an

default macro package

/usr/share/man/man_index/*

/usr/share/man/man_index/man.idx

/usr/share/man/man_index/man.dic

/usr/share/man/man_index/man.frq

/usr/share/man/man_index/man.pos

index file for -K query

属性

See attributes(5) for descriptions of the following attributes:

另请参见

apropos(1), man(1), nroff(1), rm(1), troff(1), whatis(1), attributes(5), man(5), sgml(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 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.

警告

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 rebuild the index files unless the complete set of man* directories is present. catman builds the index files based on the man* directories.

附注

The windex database has been replaced by index files. Unlike the case with windex, index file generation does not pose any specific restrictions or prerequisites on what can be indexed.