catman - create the formatted files for the reference manual
/usr/bin/catman [-c] [-n] [-p] [-t] [-w] [-M directory] [-T macro-package] [sections]
The catman utility creates the preformatted versions of the on-line manual from the nroff(1) or sgml(5) input files. This feature allows easy distribution of the preformatted manual pages among a group of associated machines (for example, with rdist(1)), since it makes the directories of preformatted manual pages self-contained and independent of the unformatted entries.
catman also creates the windex database file in the directories specified by the MANPATH or the -M option. The windex database file is a three column list consisting of a keyword, the reference page that the keyword points to, and a line of text that describes the purpose of the utility or interface documented on the reference page. Each keyword is taken from the comma separated list of words on the NAME line before the `-' (dash). The reference page that the keyword points to is the first word on the NAME line. The text after the - on the NAME line is the descriptive text in the third column. The NAME line must be immediately preceded by the page heading line created by the .TH macro (see NOTES for required format).
Each manual page is examined and those whose preformatted versions are missing or out of date are recreated. If any changes are made, catman recreates the windex database.
If a manual page is a shadow page, that is, it sources another manual page for its contents, a symbolic link is made in the catx or fmtx directory to the appropriate preformatted manual page.
Shadow files in an unformatted nroff source file are identified by the first line being of the form .so manx/yyy.x.
Shadow files in the SGML sources are identified by the string SHADOW_PAGE. The file entity declared in the shadow file identifies the file to be sourced.
The following options are supported:
The following operand is supported:
catman 1 2 3
only updates manual sections 1, 2, and 3. If specific sections are not listed, all sections in the man directory specified by the environment variable MANPATH are processed.
See attributes(5) for descriptions of the following attributes:
apropos(1), man(1), nroff(1), rdist(1), rm(1), troff(1), whatis(1), attributes(5), man(5), sgml(5)
man?/xxx.? (.so'ed from man?/yyy.?): No such file or directory
target of .so in man?/xxx.? must be relative to /usr/man
opendir:man?: No such file or directory
*.*: No such file or directory
If a user, who has previously run catman to install the cat* directories, upgrades the operating system, the entire cat* directory structure should be removed prior to running catman. See rm(1).
Do not re-run catman to re-build the whatis database unless the complete set of man* directories is present. catman builds this windex file based on the man* directories.
To generate a valid windex index file, catman has certain requirements. Within the individual man page file, catman requires two macro lines to have a specific format. These are the .TH page heading line and the .SH NAME line.
The .TH macro requires at least the first three arguments, that is, the filename, section number, and the date. The .TH line starts off with the .TH macro, followed by a space, the man page filename, a single space, the section number, another single space, and the date. The date should appear in double quotes and is specified as "day month year," with the month always abbreviated to the first three letters (Jan, Feb, Mar, and so forth).
The .SH NAME macro, also known as the NAME line, must immediately follow the .TH line, with nothing in between those lines. No font changes are permitted in the NAME line. The NAME line is immediately followed by a line containing the man page filename; then shadow page names, if applicable, separated by commas; a dash; and a brief summary statement. These elements should all be on one line; no carriage returns are permitted.
An example of proper coding of these lines is:
.TH nismatch 1M "10 Apr 1998" .SH NAME nismatch, nisgrep \- utilities for searching NIS+ tables
Закладки на сайте
Проследить за страницей
Created 1996-2022 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру