Print this page
Latest round of fixes per RM and AL.  Fix bugs found in man.c.
feedback from Hans
mandoc import

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man1m/catman.1m
          +++ new/usr/src/man/man1m/catman.1m
   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
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX