catman(8) — Maintenance
NAME
catman − Creates formatted reference pages
SYNOPSIS
/usr/sbin/catman [ -M pathname ] [ -npw ] [ section ... ]
FLAGS
-M pathname
Updates reference pages located in the set of directories specified by pathname (/usr/share/man by default). The pathname argument has the form of a colon-separated list of directory names. For example:
/usr/local/man:/usr/share/man
If the environment variable MANPATH is set, its value is used for the default path.
-nPrevents creation of the whatis database.
-pDisplays what would be done instead of doing it.
-wCauses only the whatis database to be created. No reformatting is done.
PARAMETERS
section...Specifies one or more reference page sections whose corresponding directories are to be searched for files. If you do not specify this parameter, the command searches man? directories for the default sections, which are 1 to 8.
DESCRIPTION
The catman command creates formatted versions of the online reference pages from the nroff source files. The command also creates from the NAME entries in source files the whatis database that is used by the whatis and apropos commands.
When catman is invoked, each reference page is examined and those whose preformatted versions are missing or out of date are created by nroff using the -man macro package. See man(5). If any preformatted reference pages are created, catman also creates or recreates the whatis database in the first .../man directory specified by the argument to the −M flag. By default, catman creates the whatis database in the /usr/share/man directory. Note that setting the MANPATH variable specifies the locations where catman searches for reference pages and places preformatted files, but does not affect placement of the whatis database. Specifying the −M flag overrides any setting of the MANPATH variable and specifies both the file search path and the whatis database location.
An argument not starting with a − (single minus sign) is assumed to be a list of the reference sections to look in. If you do not specify a list, catman uses the default, which is the complete list of the numbered sections (12345678). In general, sections are referenced by a single digit in the range 1 through 8. But, you can use any section allowed by the man command. The list of sections is applied to all reference page directories that you want formatted.
If a .../man/cat? directory does not exist for a section, the directory is created.
If the first line of a reference page is similar to either of the following lines, catman creates a symbolic link file in the reference page’s corresponding cat? directory:
.so man?/title2.section
.soman?/title2.section
The link is made to the appropriate reference page file:
.../cat?/title2.section
As an example, the /usr/share/man/man1/egrep.1 file contains the line .so man1/grep.1. When catman runs, it creates the following soft link:
/usr/share/man/cat1/egrep.1 ---> ../cat1/grep.1
The remainder of the reference page is ignored. Such ".so man" source reference pages are known as cross-reference reference pages.
A source reference page file can have a multicharacter 7-bit ASCII subsection suffix appended to its name, following the section character. The subsection suffix, if it exists, must start with a letter. The formatted reference page file will include the subsection suffix in its name.
The catman command assumes that nroff source files can contain unprocessed tables and equations. Therefore, it automatically processes source files through tbl and neqn before invoking nroff.
Processing reference pages always invokes nroff with the -Tlp flag to format output for the term(4) lp device.
When you view preformatted reference page files directly with the more command, you should invoke more with the -svf flags. You should use the vf flags to have the pages display properly in cases where the nroff lp device driver generates special device control codes. The following symbols can be used in the MANPATH environment variable:
%LThe current locale name, for example, ja_JP.eucJP, that is defined for the LC_MESSAGES environment variable or the LANG environment variable (if LC_MESSAGES is not defined).
%PThe same as %L except that any "@" modifier is removed.
%lThe language element of the current locale name, for example, ja.
%tThe territory element of the current locale name, for example, JP.
%cThe codeset element from the current locale name, for example, eucJP.
%%A single % (percent sign) character.
RESTRICTIONS
The catman command changes its directory to /usr/share/man or to any directories specified with the -M flag or in the MANPATH environment variable. Some reference pages assume this change of directory. Therefore, an attempt to format some reference pages can fail if any .so directives specifying partial pathnames do not start with man?/.
The /usr/share/man/man? directories for sections C, L, F, n, l, p, o, 0, and 9 are optional. Only your system administrator can create them. Once they are created, however, catman will create the corresponding .../man/cat? directories whenever it receives a request to format reference pages in one of those sections.
The whatis (man -f) and apropos (man -k) commands fail unless the whatis database exists in the /usr/share/man directory or, if the command includes the −M flag, in the search path specified with that flag. The operating system does provide an initial /usr/share/man/whatis file; however, you must recreate this file manually if you install reference pages that are not included with the operating system product; otherwise, entries for the additional reference pages are not included in the whatis database.
You create or recreate the whatis file when you invoke catman without specifying the −w or −n flags. You can also specify the −w flag to create the whatis file without creating preformatted reference pages in the cat? directories.
Source reference pages are formatted for the nroff lp device. The lp device driver, as supplied by the operating system, is set to generate output for Digital Equipment Corporation terminals as specified in term(4). If your system administrator changes the supplied setting for the lp device, all preformatted reference page files created by man or catman should be deleted and reformatted for the new lp device.
Preformatted reference pages may not be in a format suitable for printing on your hardcopy printers. To format a reference page for a specific printer, move to the reference page directory and issue a command such as the following:
% cd /usr/share/man
% tbl man1/ls.1 |neqn |nroff -Tdevice -man -h | lpr -Pmyprinter
Replace the device argument with /usr/share/lib/term/tabdevice, where device is the name of a device listed in term(4).
If the reference page has tables and the hardcopy device is not capable of reverse line movements, the reference page might not print properly.
If the MORE environment variable is set, it should include the v and f flags in order for preformatted reference pages to display properly.
However, preformatted reference pages might not be in a format suitable for display on non-Digital terminals. To format a reference page for a specified terminal, move to the reference page directory and issue a command such as the following:
% cd /usr/share/man
% tbl man1/ls.1 |neqn |nroff -Tdevice -man -h | more -svf
Replace the device argument with /usr/share/lib/term/tabdevice, where device is the name of a device listed in term(4).
The operating system contains no nroff support for non-Digital terminals or printers.
EXAMPLES
To update sections 1, 2, and 3 only, enter:
catman 123
FILES
/usr/share/manDefault reference page directory.
/usr/share/man/man?
Directories containing nroff sources for reference pages.
/usr/share/man/cat?/∗
Directories containing standard preformatted reference pages.
/usr/share/man/cat?/.z
Packed preformatted reference pages (if any).
/usr/local/man/man?
Directories containing nroff sources for local reference pages.
/usr/local/man/cat?/∗
Directories containing local reference pages.
/usr/share/man/whatis
The whatis keyword database created by catman.
/usr/lbin/mkwhatisCommand script to make the whatis database.
/usr/lbin/getNAMEProgram used by the mkwhatis command to extract data from reference pages.
/usr/local/man/whatis
Local whatis keyword database created by catman.
pathname/manDirectory containing reference page information to be searched when the -M flag is specified or when the MANPATH environment variable is set. This directory is assumed to have the same organization as /usr/share/man.