1 '\" te
2 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH CATMAN 1M "Feb 27, 1998"
7 .SH NAME
8 catman \- create the formatted files for the reference manual
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/bin/catman\fR [\fB-c\fR] [\fB-n\fR] [\fB-p\fR] [\fB-t\fR] [\fB-w\fR] [\fB-M\fR \fIdirectory\fR]
13 [\fB-T\fR \fImacro-package\fR] [\fIsections\fR]
14 .fi
15
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The \fBcatman\fR utility creates the preformatted versions of the on-line
20 manual from the \fBnroff\fR(1) or \fBsgml\fR(5) input files. This feature
21 allows easy distribution of the preformatted manual pages among a group of
22 associated machines (for example, with \fBrdist\fR(1)), since it makes the
23 directories of preformatted manual pages self-contained and independent of the
24 unformatted entries.
25 .sp
26 .LP
27 \fBcatman\fR also creates the \fBwindex\fR database file in the directories
28 specified by the \fBMANPATH\fR or the \fB-M\fR option. The \fBwindex\fR
29 database file is a three column list consisting of a keyword, the reference
30 page that the keyword points to, and a line of text that describes the purpose
31 of the utility or interface documented on the reference page. Each keyword is
32 taken from the comma separated list of words on the \fBNAME\fR line before the
33 `\(mi' (dash). The reference page that the keyword points to is the first word
34 on the \fBNAME\fR line. The text after the \(mi on the \fBNAME\fR line is the
35 descriptive text in the third column. The \fBNAME\fR line must be immediately
36 preceded by the page heading line created by the \fB\&.TH\fR macro (see
37 \fBNOTES\fR for required format).
38 .sp
39 .LP
40 Each manual page is examined and those whose preformatted versions are missing
41 or out of date are recreated. If any changes are made, \fBcatman\fR recreates
42 the \fBwindex\fR database.
43 .sp
44 .LP
45 If a manual page is a \fIshadow\fR page, that is, it sources another manual
46 page for its contents, a symbolic link is made in the \fBcat\fR\fIx\fR or
47 \fBfmt\fR\fIx\fR directory to the appropriate preformatted manual page.
48 .sp
49 .LP
50 Shadow files in an unformatted nroff source file are identified by the first
51 line being of the form \fB\&.so man\fR\fIx\fR\fB/yyy.\fR\fIx\fR\fB\&.\fR
52 .sp
53 .LP
54 Shadow files in the \fBSGML\fR sources are identified by the string
55 \fBSHADOW_PAGE\fR. The file entity declared in the shadow file identifies the
56 file to be sourced.
57 .SH OPTIONS
58 .sp
59 .LP
60 The following options are supported:
61 .sp
62 .ne 2
63 .na
64 \fB\fB-c\fR\fR
65 .ad
66 .RS 20n
67 Create unformatted nroff source files in the appropriate \fBman\fR
68 subdirectories from the \fBSGML\fR sources. This option will overwrite any
69 existing file in the \fBman\fR directory of the same name as the \fBSGML\fR
70 file.
71 .RE
72
73 .sp
74 .ne 2
75 .na
76 \fB\fB-n\fR\fR
77 .ad
78 .RS 20n
79 Do not create (or recreate) the \fBwindex\fR database. If the \fB-n\fR option
80 is specified, the \fBwindex\fR database is not created and the \fBapropos\fR,
81 \fBwhatis\fR, \fBman\fR \fB-f\fR, and \fBman\fR \fB-k\fR commands will fail.
82 .RE
83
84 .sp
85 .ne 2
86 .na
87 \fB\fB-p\fR\fR
88 .ad
89 .RS 20n
90 Print what would be done instead of doing it.
91 .RE
92
93 .sp
94 .ne 2
95 .na
96 \fB\fB-t\fR\fR
97 .ad
98 .RS 20n
99 Create \fBtroff\fRed entries in the appropriate \fBfmt\fR subdirectories
100 instead of \fBnroff\fRing into the \fBcat\fR subdirectories.
101 .RE
102
103 .sp
104 .ne 2
105 .na
106 \fB\fB-w\fR\fR
107 .ad
108 .RS 20n
109 Only create the \fBwindex\fR database that is used by \fBwhatis\fR(1) and the
110 \fBman\fR(1) \fB-f\fR and \fB-k\fR options. No manual reformatting is done.
111 .RE
112
113 .sp
114 .ne 2
115 .na
116 \fB\fB-M\fR\fI directory\fR\fR
117 .ad
118 .RS 20n
119 Update manual pages located in the specified \fIdirectory\fR,
120 (\fB/usr/share/man\fR by default). If the \fB-M\fR option is specified, the
121 directory argument must not contain a `,' (comma), since a comma is used to
122 delineate section numbers. See \fBman\fR(1).
123 .RE
124
125 .sp
126 .ne 2
127 .na
128 \fB\fB-T\fR\fI macro-package\fR\fR
129 .ad
130 .RS 20n
131 Use \fImacro-package\fR in place of the standard manual page macros, (
132 \fBman\fR(5) by default).
133 .RE
134
135 .SH OPERANDS
136 .sp
137 .LP
138 The following operand is supported:
139 .sp
140 .ne 2
141 .na
142 \fB\fIsections\fR\fR
143 .ad
144 .RS 12n
145 If there is one parameter not starting with a `\fB\(mi\fR\&', it is taken to be
146 a space separated list of manual sections to be processed by \fBcatman\fR. If
147 this operand is specified, only the manual sections in the list will be
148 processed. For example,
149 .sp
150 .in +2
151 .nf
152 \fBcatman 1 2 3\fR
153 .fi
154 .in -2
155 .sp
156
157 only updates manual sections \fB1\fR, \fB2\fR, and \fB3\fR. If specific
158 sections are not listed, all sections in the \fBman\fR directory specified by
159 the environment variable \fBMANPATH\fR are processed.
160 .RE
161
162 .SH ENVIRONMENT VARIABLES
163 .sp
164 .ne 2
165 .na
166 \fB\fBTROFF\fR\fR
167 .ad
168 .RS 11n
169 The name of the formatter to use when the \fB-t\fR flag is given. If not set,
170 \fBtroff\fR(1) is used.
171 .RE
172
173 .sp
174 .ne 2
175 .na
176 \fB\fBMANPATH\fR\fR
177 .ad
178 .RS 11n
179 A colon-separated list of directories that are processed by \fBcatman\fR and
180 \fBman\fR(1). Each directory can be followed by a comma-separated list of
181 sections. If set, its value overrides \fB/usr/share/man\fR as the default
182 directory search path, and the \fBman.cf\fR file as the default section search
183 path. The \fB-M\fR and \fB-s\fR flags, in turn, override these values.
184 .RE
185
186 .SH FILES
187 .sp
188 .ne 2
189 .na
190 \fB\fB/usr/share/man\fR\fR
191 .ad
192 .RS 28n
193 default manual directory location
194 .RE
195
196 .sp
197 .ne 2
198 .na
199 \fB\fB/usr/share/man/man*/*.*\fR\fR
200 .ad
201 .RS 28n
202 raw nroff input files
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB\fB/usr/share/man/sman*/*.*\fR\fR
209 .ad
210 .RS 28n
211 raw \fBSGML\fR input files
212 .RE
213
214 .sp
215 .ne 2
216 .na
217 \fB\fB/usr/share/man/cat*/*.*\fR\fR
218 .ad
219 .RS 28n
220 preformatted \fBnroff\fRed manual pages
221 .RE
222
223 .sp
224 .ne 2
225 .na
226 \fB\fB/usr/share/man/fmt*/*.*\fR\fR
227 .ad
228 .RS 28n
229 preformatted \fBtroff\fRed manual pages
230 .RE
231
232 .sp
233 .ne 2
234 .na
235 \fB\fB/usr/share/man/windex\fR\fR
236 .ad
237 .RS 28n
238 table of contents and keyword database
239 .RE
240
241 .sp
242 .ne 2
243 .na
244 \fB\fB/usr/lib/makewhatis\fR\fR
245 .ad
246 .RS 28n
247 command script to make \fBwindex\fR database
248 .RE
249
250 .sp
251 .ne 2
252 .na
253 \fB\fB/usr/share/lib/tmac/an\fR\fR
254 .ad
255 .RS 28n
256 default macro package
257 .RE
258
259 .SH ATTRIBUTES
260 .sp
261 .LP
262 See \fBattributes\fR(5) for descriptions of the following attributes:
263 .sp
264
265 .sp
266 .TS
267 box;
268 c | c
269 l | l .
270 ATTRIBUTE TYPE ATTRIBUTE VALUE
271 _
272 CSI Enabled
273 .TE
274
275 .SH SEE ALSO
276 .sp
277 .LP
278 \fBapropos\fR(1), \fBman\fR(1), \fBnroff\fR(1), \fBrdist\fR(1), \fBrm\fR(1),
279 \fBtroff\fR(1), \fBwhatis\fR(1), \fBattributes\fR(5), \fBman\fR(5),
280 \fBsgml\fR(5)
281 .SH DIAGNOSTICS
282 .sp
283 .ne 2
284 .na
285 \fB\fBman?/xxx.? (.so'ed from man?/yyy.?): No such file or directory\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 The file outside the parentheses is missing, and is referred to by the file
290 inside them.
291 .RE
292
293 .sp
294 .ne 2
295 .na
296 \fB\fBtarget of .so in man?/xxx.? must be relative to /usr/man\fR\fR
297 .ad
298 .sp .6
299 .RS 4n
300 \fBcatman\fR only allows references to filenames that are relative to the
301 directory \fB/usr/man\fR.
302 .RE
303
304 .sp
305 .ne 2
306 .na
307 \fB\fBopendir:man?:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR
308 \fBdirectory\fR\fR
309 .ad
310 .sp .6
311 .RS 4n
312 A harmless warning message indicating that one of the directories \fBcatman\fR
313 normally looks for is missing.
314 .RE
315
316 .sp
317 .ne 2
318 .na
319 \fB\fB*.*:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR \fBdirectory\fR\fR
320 .ad
321 .sp .6
322 .RS 4n
323 A harmless warning message indicating \fBcatman\fR came across an empty
324 directory.
325 .RE
326
327 .SH WARNINGS
328 .sp
329 .LP
330 If a user, who has previously run \fBcatman\fR to install the \fBcat*\fR
331 directories, upgrades the operating system, the entire \fBcat*\fR directory
332 structure should be removed prior to running \fBcatman\fR. See \fBrm\fR(1).
333 .sp
334 .LP
335 Do not re-run \fBcatman\fR to re-build the \fBwhatis\fR database unless the
336 complete set of \fBman*\fR directories is present. \fBcatman\fR builds this
337 \fBwindex\fR file based on the \fBman*\fR directories.
338 .SH NOTES
339 .sp
340 .LP
341 To generate a valid windex index file, \fBcatman\fR has certain requirements.
342 Within the individual man page file, \fBcatman\fR requires two macro lines to
343 have a specific format. These are the \fB\&.TH \fRpage heading line and the
344 \fB\&.SH NAME \fRline.
345 .sp
346 .LP
347 The \fB\&.TH \fRmacro requires at least the first three arguments, that is, the
348 filename, section number, and the date. The \fB\&.TH \fRline starts off with
349 the \fB\&.TH \fRmacro, followed by a space, the man page filename, a single
350 space, the section number, another single space, and the date. The date should
351 appear in double quotes and is specified as "day month year," with the month
352 always abbreviated to the first three letters (Jan, Feb, Mar, and so forth).
353 .sp
354 .LP
355 The \fB\&.SH NAME \fRmacro, also known as the \fBNAME \fRline, must immediately
356 follow the \fB\&.TH \fRline, with nothing in between those lines. No font
357 changes are permitted in the \fBNAME \fRline. The \fBNAME \fRline is
358 immediately followed by a line containing the man page filename; then shadow
359 page names, if applicable, separated by commas; a dash; and a brief summary
360 statement. These elements should all be on one line; no carriage returns are
361 permitted.
362 .sp
363 .LP
364 An example of proper coding of these lines is:
365 .sp
366 .in +2
367 .nf
368 \&.TH NISMATCH 1M "Apr "10, 1998""
369 \&.SH NAME
370 nismatch, nisgrep \e- utilities for searching NIS+ tables
371 .fi
372 .in -2
373
|
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
13 .\"
14 .Dd Jul 19, 2014
15 .Dt CATMAN 1M
16 .Os
17 .Sh NAME
18 .Nm catman
19 .Nd generate
20 .Nm whatis
21 database files
22 .Sh SYNOPSIS
23 .Nm
24 .Op Fl M Ar path
25 .Op Fl w
26 .Sh DESCRIPTION
27 The
28 .Nm
29 utility generates a set of
30 .Nm whatis
31 database files suitable for use with
32 .Xr apropos 1
33 and
34 .Xr whatis 1 .
35 It is supplied for compatibility reasons. The same databases can
36 be generated using the
37 .Fl w
38 option with
39 .Xr man 1 ,
40 and that command should be used instead.
41 .Sh OPTIONS
42 .Bl -tag -width ".Fl d"
43 .It Fl M Ar path
44 Generate the
45 .Nm whatis
46 database files within the specified colon separated manual paths.
47 Overrides the
48 .Ev MANPATH
49 environment variable.
50 .It Fl w
51 This option is present for backwards compatibility, and is ignored.
52 .El
53 .Sh ENVIRONMENT
54 The following environment variables affect the execution of
55 .Nm :
56 .Bl -tag -width ".Ev MANPATH"
57 .It Ev MANPATH
58 Used to specify a colon seperated list of manual paths within
59 which to generate
60 .Nm whatis
61 database files.
62 .El
63 .Sh EXIT STATUS
64 .Ex -std
65 .Sh INTERFACE STABILITY
66 .Nm "Obsolete Committed" .
67 .Sh CODE SET INDEPENDENCE
68 Enabled.
69 .Sh SEE ALSO
70 .Xr apropos 1 ,
71 .Xr man 1 ,
72 .Xr whatis 1
|