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:
/usr/share/man:/usr/dt/share/man:/usr/local/man
The -M option, unlike the MANPATH setting, overrides
the default placement of the whatis database
(in /usr/share/man). When the -M option is
included in a command that builds the whatis
database, catman creates the database in the first
directory included in search_path.
Refer to the man(1) reference page for more information
on the MANPATH variable. See DESCRIPTION for
a list of locale directives that can be included in
search_path. Uses the gzip command to compress
preformatted output files. The -c option has no
effect when used with the -w option. Prevents creation
of the whatis database. Displays what would
be done instead of doing it. Displays the name of
each reference page file as it is being processed.
Causes only the whatis database to be created. No
reformatting is done.
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 section operand affects creation of preformatted
files, not the whatis database. The catman
command always searches all section directories in
its search path when creating the whatis database.
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 option 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 option 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 options. The vf options 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.
These directives allow catman to use the current
locale setting to find translated source files and
create translated output files in an appropriate
and predictable location. Refer to the
i18n_intro(5) reference page for more information
about locales and associated environment variables.
The following subsections discuss restrictions associated
with both catman and its input and output files.
Reference Page Pointers [Toc] [Back]
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 directives specifying partial
pathnames do not start with man?/.
Optional Section Directories [Toc] [Back]
The /usr/share/man/man? directories for sections C, L, F,
n, l, p, o, and 0 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 Database [Toc] [Back]
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 option, in
the search path specified with that option.
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 option. You can also
specify the -w option 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.
Default Formatting Is Not Appropriate for All Devices [Toc] [Back]
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 HewlettPackard
Company 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 video terminals from other vendors.
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).
Success. An error occurred.
To create or update compressed preformatted files for reference
pages and also create or rebuild the whatis
database, enter: catman -c To create uncompressed preformatted
files only for sections 1, 2, and 3, enter: catman
123
This command also creates or rebuilds the whatis
database. The new database contains entries for
reference pages in all sections (not just 1, 2, and
3) that are found in the search path. To create or
rebuild the whatis database without creating or
updating formatted files, enter: catman -w To create
compressed preformatted files for all reference
pages in the search path but not rebuild the whatis
database, enter: catman -c -n
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 option 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)
catman(8)
[ Back ] |
