catman - Creates or rebuilds formatted reference pages and the whatis database
/usr/sbin/catman [ -M search_path ] [ -cnpvw ] [ section ... ]
Creates formatted versions of reference pages only in the set of directories specified by search_path. The search_path argument has the form of a colon-separated list of directory names. The default search path (assuming MANPATH has not been set) is the following:
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 for reference page source files in all section directories encountered in its search path.
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).
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 formats all reference pages in the search path. 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 areas in the search path.
If a .../man/cat? directory does not exist for a section, catman creates the directory.
The command recognizes and appropriately processes either compressed or uncompressed source files. By default, the command creates formatted files in uncompressed form; however, you can specify the -c flag to direct catman to compress its output files. When catman processes an uncompressed source file, any corresponding pointers are generated as symbolic links. When catman processes a compressed source file, any corresponding pointers are generated as hard links. Refer to man(1) for more information, including restrictions, that apply to pointers and compressed files.
A reference page source file can include 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 also includes the subsection suffix in its name.
The catman command assumes that reference page source files can contain unprocessed tables and equations. Therefore, it automatically processes source files through tbl and neqn before invoking nroff. When catman processes a compressed file, the command automatically executes the gunzip -c command to uncompress the file before piping output to the other commands.
Processing reference pages always invokes nroff with the -Tlp flag to format output for the term(4) lp device. See RESTRICTIONS for information appropriate for printers and some display devices.
When you view preformatted reference page files directly with the more command, you should invoke more with the -svf flags. The vf flags ensure that the pages display properly in cases where the nroff lp device driver generates special device control codes.
The following locale directives can be included in the pathnames in search_path: The current locale name, for example, ja_JP.eucJP, that is defined for the LC_MESSAGES environment variable. The same as %L except that any "@" modifier on the locale name is removed. The language element of the current locale name, for example, ja. The territory element of the current locale name, for example, JP. The codeset element from the current locale name, for example, eucJP. A single % (percent sign) character.
The following subsections discuss restrictions associated with both catman and its input and output files.
Refer to man(1) for introductory information on reference page pointers and general pointer restrictions.
When processing reference page files, the catman command changes its directory to each reference page area in the search path. Some reference pages assume this change of directory. Therefore, an attempt to format uncompressed reference pages can fail if any .so directives specifying partial pathnames do not start with man?/.
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 can optionally install a /usr/share/man/whatis file that is useful during system configuration tasks. However, you must recreate this file manually if you install reference pages that are not included in subsets for 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 -n flag. You can also specify the -w flag to create the whatis file without creating or updating preformatted reference pages in the cat? directories.
An update installation procedure or a setld command that processes reference page subsets for the operating system itself may selectively remove or add specific whatis database entries to help keep the database up to date. However, this feature is of limited use in making sure that the whatis database remains current with respect to the reference pages that are actually available on the system. As already mentioned, selective update is not supported by most of the optional software products that can load reference pages to the system. Furthermore, selective update has database location dependencies. For selective update to work, the whatis entries for all operating system product reference pages (including those for CDE) must reside in /usr/share/man/whatis. In other words, automatic and selective revision of the whatis database does not work correctly if the whatis database is rebuilt in a directory other than /usr/share/man or if the system administrator creates a CDE-specific whatis database in the /usr/dt/share/man directory.
Therefore, do not rely on automatic update of the whatis database to ensure that its entries reflect the current set of reference pages installed on the system. It is strongly recommended that you always use the catman command to manually rebuild the database as the last task following a completed series of software product installations.
The catman command formats reference pages for the nroff lp device. The lp device driver, as supplied by the operating system, is set to generate output for Digital Equipment Corporation video terminals, but not for all printers or third-party terminals. 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 then 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 area and issue a command such as the following:
% cd /usr/share/man % gunzip -c man1/ls.1.gz |tbl |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). The lpr device setting, because it supports primitive line printers, is least likely to cause problems that are related to escape sequences that the device cannot handle. On the other hand, if the reference page has tables and the device is not capable of reverse line movements, column entries intended to be in the same row may not align correctly.
Preformatted reference pages also might not be in a format suitable for display on non-Digital video terminals. To format a reference page for a specific display device, move to the reference page directory and issue a command such as the following:
% cd /usr/share/man % gunzip -c man1/ls.1 |tbl |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 catman command returns 0 (zero) on success and >0 (greater than zero) on failure.
Main reference page area Directories containing source files for most reference pages Directories containing preformatted files for most reference pages Reference page area for the Common Desktop Environment (CDE) Directories containing source files for CDE reference pages Directories containing preformatted files for CDE reference pages Local (site-specific) reference page area Directories containing source files for local reference pages Directories containing preformatted files for local reference pages The whatis database created or modified by catman unless the -M flag is specified Command script to make the whatis database Program used by the mkwhatis command to extract data from reference pages
Commands: man(1), neqn(1), nroff(1), tbl(1)
Files: term(4), man(5), rsml(5) delim off