CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN)
NAME
catman - format manual pages and build auxiliary files
SYNOPSIS
/etc/catman [ -f command ] [ -i ] [ -p ] [ -n ] [ -s ] [ -v
] [ -w ] [ -number ] [ directory ... ]
DESCRIPTION
Catman is used to format manual pages which have been
changed and build whatis databases and index format tables.
In order to find pages in need of formatting, catman
compares the modification dates of the files in the
subdirectories man[1-8] (or only the sections specified)
against those in the corresponding cat subdirectory (see
man(5man) for the directory structure requirements). If the
man file is newer than the cat file, or the cat file is
empty or nonexistent, the file is formatted (see Formatting
below).
Usage
There are three ways to use catman. The first, and most
often used, way is to execute catman nightly to format the
system manual page files. This can be done by having an
entry in /usr/lib/crontab (see EXAMPLES). In this case,
directory names are obtained from the file
/usr/lib/man/directories. If the actions field of the entry
(see man(5man)) contains the character f, the manual pages
are formatted. If the actions field contains an i, the
pages are formatted and the program /usr/lib/buildif is
invoked for each page to build and add index format tables
(for use by the commands help(1man) and section(1man)) to
the manual page. If the actions field contains a w, the
pages are formatted and the program /usr/lib/makewhatis is
invoked in order to rebuild the whatis database. In these
last two cases, the action is only taken if pages were
reformatted.
The second use of catman is to process personal manual page
directories. When the -p option is given, the file
$HOME/.manrc is read to obtain the names of personal manual
page directories. Each of these directories is checked for
manual pages in need of formatting, and those pages are
formatted. In addition, the index format tables and whatis
database are rebuilt.
The third use of catman is to only reformat certain
directories. In this case, the directories are listed on
the command line and are formatted just as in the case of
personal manual page directories (see EXAMPLES).
Printed 10/17/86 1
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN)
Formatting
By default, all manual pages are formatted using the command
nroff -man < source > formatted
(The command line is executed by /bin/sh.) If the -f option
is given, the given command replaces the ``nroff -man''.
If the first 1024 characters of the manual page source file
contains the word $Compile:, the text following the : up to
a newline or the sequence $$ is used in place of nroff-man.
This command may contain a %f, which is replaced by the
source file name. In this case, the < source portion is not
included in the command line. This feature is very useful
for manual pages which require preprocessing by commands
such as tbl and neqn and postprocessing by col.
Examples of $Compile lines are:
\" $Compile: tbl | nroff -man | col
\" $Compile: neqn %f | tbl | nroff -man | col $$
The Sections File
When all directories have been processed, the set of
sections seen is compiled. If personal or command-line
specified directories were processed, the list of known
sections is printed (this information can be used to update
the $HOME/.manrc file or system sections file). If the
system directories were processed, the data is used to
rebuild the file /usr/lib/man/sections. In this case, the
section ordering is preserved. All new sections are placed
before the `+' entry for that section number. If there is
no `+' entry for the section number, the new section is
placed at the end of the file. Sections that no longer
exist are deleted. For example, if the sections file
contains `2 2x 2+' and manual pages whose sections are `2d'
and `2n' are seen and no section `2x' manual pages were
seen, the sections file will contain `2 2d 2n 2+'.
It is very important to note that giving sections to format
on the command line inhibits the rebuilding of the sections
file and causes the sections to be printed.
Directory Creation
If a cat directory does not exist, an attempt is made to
create it. If the file exists but is not a directory,
Printed 10/17/86 2
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN)
catman will abort.
OPTIONS
-f command
Format all files using the given command. This
overrides the default use of nroff -man and any $Compile
directives in the source.
-i Don't build index format tables. This overrides the i
in the actions field of entries in
/usr/lib/man/directories.
-p Format "personal" directories found in $HOME/.manrc.
-n Print commands to be executed but do not execute them.
This results in a list of commands that can be executed,
including creation of directories. Double quotes will
surround each file name.
-v Versbose. Print commands as they are executing. When
executing makewhatis, the -v is also given so that any
errors will be reported.
-w Don't build whatis databases. This overrides the w in
the actions field of entries in
/usr/lib/man/directories.
-number
Format only the given section. There may be more than
one of these options. Use of this option with the
system directories inhibits rebuilding of the sections
file.
EXAMPLES
Catman is usually used to format the system directories.
The following entry, when placed in /usr/lib/crontab, will
cause the changed files to be reformatted each night at
2:30am.
30 02 * * * /etc/catman -v
This invocation will cause sections 1, 2, and 3 of the
directories listed in "personal" entries of the file
$HOME/.manrc to be formatted. The commands executed and
known sections list will be printed.
/etc/catman -p -v -1 -2 -3
Printed 10/17/86 3
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN)
The following command will print the commands required to
bring the manual pages in /usr/tman up to date. The known
suffix list will not be printed.
/etc/catman -n -s /usr/tman
The following command will execute commands to bring the
manual pages in /usr/man/man1 up to date. The known suffix
list will be printed, but /usr/lib/man/sections will have to
be updated by hand.
/etc/catman -1 /usr/man
FILES
/usr/lib/man/directories Manual page search directory
information.
/usr/lib/man/sections Known manual page sections
list.
$HOME/.manrc Searched for "personal" manual
page directory names.
/usr/lib/makewhatis Whatis database-building
command.
/usr/lib/buildif Index format file builder.
VARIABLES
PATH The user's execution path.
HOME The user's home directory.
RETURN VALUE
[NO_ERRS] Command completed without error.
[USAGE] Incorrect command line syntax. Execution
terminated.
[NP_WARN] An error warranting a warning message
occurred. Execution continues.
[NP_ERR] An error occurred that was not a system
error. Execution terminated.
[P_WARN] A system error occurred. Execution continues.
Printed 10/17/86 4
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN)
See intro(2) for more information on system
errors.
CAVEATS
Only manual pages with proper suffixes for the section are
checked for reformatting. For example, the file
/usr/man/man3/at.1 would not be formatted since it has a
section specifier of 1 instead of 3.
Manual pages preprocessed by tbl and/or eqn should always be
postprocessed by col.
SEE ALSO
apropos(1man), buildif(1man), col(1), help(1man), more(1),
neqn(1), nroff(1), section(1man), tbl(1), whatis(1man),
man(5man), manindex(5man), whatis(5man), cron(8).
Printed 10/17/86 5
%%index%%
na:72,90;
sy:162,367;
de:529,3024;3697,2682;6523,61;
op:6584,1620;
ex:8204,643;8991,533;
fi:9524,697;
va:10221,160;
rv:10381,514;11039,105;
ca:11144,451;
se:11595,485;
%%index%%000000000201