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, 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 5/12/88 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, catman will abort. Printed 5/12/88 2
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN) 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 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 Printed 5/12/88 3
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN) 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. 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. Printed 5/12/88 4
CATMAN(8MAN) COMMAND REFERENCE CATMAN(8MAN) 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), and cron(8). Printed 5/12/88 5
%%index%% na:360,106; sy:466,508; de:974,3423;4829,3029; op:8290,1832; ex:10122,914;11468,308; fi:11776,616; va:12392,196; rv:12588,663; ca:13251,515; se:14198,529; %%index%%000000000188