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