1catman(1M) System Administration Commands catman(1M)
2
6 catman - create the formatted files for the reference manual
7
9 /usr/bin/catman [-c] [-n] [-p] [-t] [-w] [-M directory]
10 [-T macro-package] [sections]
11
14 The catman utility creates the preformatted versions of the on-line
15 manual from the nroff(1) or sgml(5) input files. This feature allows
16 easy distribution of the preformatted manual pages among a group of
17 associated machines (for example, with rdist(1)), since it makes the
18 directories of preformatted manual pages self-contained and independent
19 of the unformatted entries.
20 catman also creates the windex database file in the directories speci‐
23 fied by the MANPATH or the -M option. The windex database file is a
24 three column list consisting of a keyword, the reference page that the
25 keyword points to, and a line of text that describes the purpose of the
26 utility or interface documented on the reference page. Each keyword is
27 taken from the comma separated list of words on the NAME line before
28 the `−' (dash). The reference page that the keyword points to is the
29 first word on the NAME line. The text after the − on the NAME line is
30 the descriptive text in the third column. The NAME line must be immedi‐
31 ately preceded by the page heading line created by the .TH macro (see
32 NOTES for required format).
33 Each manual page is examined and those whose preformatted versions are
36 missing or out of date are recreated. If any changes are made, catman
37 recreates the windex database.
38 If a manual page is a shadow page, that is, it sources another manual
41 page for its contents, a symbolic link is made in the catx or fmtx
42 directory to the appropriate preformatted manual page.
43 Shadow files in an unformatted nroff source file are identified by the
46 first line being of the form .so manx/yyy.x.
47 Shadow files in the SGML sources are identified by the string
50 SHADOW_PAGE. The file entity declared in the shadow file identifies the
51 file to be sourced.
52
54 The following options are supported:
55 -c Create unformatted nroff source files in the appro‐
57 priate man subdirectories from the SGML sources.
58 This option will overwrite any existing file in the
59 man directory of the same name as the SGML file.
60 -n Do not create (or recreate) the windex database. If
63 the -n option is specified, the windex database is
64 not created and the apropos, whatis, man -f, and
65 man -k commands will fail.
66 -p Print what would be done instead of doing it.
69 -t Create troffed entries in the appropriate fmt sub‐
72 directories instead of nroffing into the cat subdi‐
73 rectories.
74 -w Only create the windex database that is used by
77 whatis(1) and the man(1) -f and -k options. No
78 manual reformatting is done.
79 -M directory Update manual pages located in the specified direc‐
82 tory, (/usr/share/man by default). If the -M
83 option is specified, the directory argument must
84 not contain a `,' (comma), since a comma is used to
85 delineate section numbers. See man(1).
86 -T macro-package Use macro-package in place of the standard manual
89 page macros, ( man(5) by default).
90
93 The following operand is supported:
94 sections If there is one parameter not starting with a `−', it is
96 taken to be a space separated list of manual sections to be
97 processed by catman. If this operand is specified, only the
98 manual sections in the list will be processed. For exam‐
99 ple,
100 catman 1 2 3
102 only updates manual sections 1, 2, and 3. If specific sec‐
105 tions are not listed, all sections in the man directory
106 specified by the environment variable MANPATH are pro‐
107 cessed.
108
111 TROFF The name of the formatter to use when the -t flag is given.
112 If not set, troff(1) is used.
113 MANPATH A colon-separated list of directories that are processed by
116 catman and man(1). Each directory can be followed by a
117 comma-separated list of sections. If set, its value over‐
118 rides /usr/share/man as the default directory search path,
119 and the man.cf file as the default section search path. The
120 -M and -s flags, in turn, override these values.
121
124 /usr/share/man default manual directory location
125 /usr/share/man/man*/*.* raw nroff input files
128 /usr/share/man/sman*/*.* raw SGML input files
131 /usr/share/man/cat*/*.* preformatted nroffed manual pages
134 /usr/share/man/fmt*/*.* preformatted troffed manual pages
137 /usr/share/man/windex table of contents and keyword database
140 /usr/lib/makewhatis command script to make windex database
143 /usr/share/lib/tmac/an default macro package
146
149 See attributes(5) for descriptions of the following attributes:
150 ┌─────────────────────────────┬─────────────────────────────┐
155 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
156 ├─────────────────────────────┼─────────────────────────────┤
157 │Availability │SUNWdoc │
158 ├─────────────────────────────┼─────────────────────────────┤
159 │CSI │Enabled │
160 └─────────────────────────────┴─────────────────────────────┘
161
163 apropos(1), man(1), nroff(1), rdist(1), rm(1), troff(1), whatis(1),
164 attributes(5), man(5), sgml(5)
165
167 man?/xxx.? (.so'ed from man?/yyy.?): No such file or directory
168 The file outside the parentheses is missing, and is referred to by
170 the file inside them.
171 target of .so in man?/xxx.? must be relative to /usr/man
174 catman only allows references to filenames that are relative to the
176 directory /usr/man.
177 opendir:man?: No such file or directory
180 A harmless warning message indicating that one of the directories
182 catman normally looks for is missing.
183 *.*: No such file or directory
186 A harmless warning message indicating catman came across an empty
188 directory.
189
192 If a user, who has previously run catman to install the cat* directo‐
193 ries, upgrades the operating system, the entire cat* directory struc‐
194 ture should be removed prior to running catman. See rm(1).
195 Do not re-run catman to re-build the whatis database unless the com‐
198 plete set of man* directories is present. catman builds this windex
199 file based on the man* directories.
200
202 To generate a valid windex index file, catman has certain requirements.
203 Within the individual man page file, catman requires two macro lines to
204 have a specific format. These are the .TH page heading line and the .SH
205 NAME line.
206 The .TH macro requires at least the first three arguments, that is, the
209 filename, section number, and the date. The .TH line starts off with
210 the .TH macro, followed by a space, the man page filename, a single
211 space, the section number, another single space, and the date. The date
212 should appear in double quotes and is specified as "day month year,"
213 with the month always abbreviated to the first three letters (Jan, Feb,
214 Mar, and so forth).
215 The .SH NAME macro, also known as the NAME line, must immediately fol‐
218 low the .TH line, with nothing in between those lines. No font changes
219 are permitted in the NAME line. The NAME line is immediately followed
220 by a line containing the man page filename; then shadow page names, if
221 applicable, separated by commas; a dash; and a brief summary statement.
222 These elements should all be on one line; no carriage returns are per‐
223 mitted.
224 An example of proper coding of these lines is:
227 .TH nismatch 1M "10 Apr 1998"
229 .SH NAME
230 nismatch, nisgrep \- utilities for searching NIS+ tables
231SunOS 5.11 27 Feb 1998 catman(1M)