5051 import mdocml-1.12.3
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Approved by: TBD

          --- old/usr/src/man/man1/man.1
          +++ new/usr/src/man/man1/man.1

   1    1  .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2    2  .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3    3  .\" Copyright (c) 1980 Regents of the University of California.
   4    4  .\" The Berkeley software License Agreement specifies the terms and conditions
   5    5  .\" for redistribution.
   6    6  .Dd Jul 18, 2014
   7    7  .Dt MAN 1
   8    8  .Os
   9    9  .Sh NAME
  10   10  .Nm man
  11   11  .Nd find and display reference manual pages
  12   12  .Sh SYNOPSIS
  13   13  .Nm
  14   14  .Op Fl
  15   15  .Op Fl adFlrt
  16   16  .Op Fl T Ar macro-package
  17   17  .Op Fl M Ar path
  18   18  .Op Fl s Ar section
  19   19  .Ar name ...
  20   20  .Nm
  21   21  .Op Fl M Ar path
  22   22  .Op Fl s Ar section
  23   23  .Fl k
  24   24  .Ar keyword
  25   25  .Ar ...
  26   26  .Nm
  27   27  .Op Fl M Ar path
  28   28  .Op Fl s Ar section
  29   29  .Fl f
  30   30  .Ar
  31   31  .Nm
  32   32  .Op Fl M Ar path
  33   33  .Fl w
  34   34  .Sh DESCRIPTION
  35   35  The
  36   36  .Nm
  37   37  command displays information from the reference manuals. It
  38   38  displays complete manual pages that you select by
  39   39  .Ar name ,
  40   40  or one-line summaries selected either by
  41   41  .Ar keyword
  42   42  .Pq Fl k ,
  43   43  or by the name of an associated file
  44   44  .Pq Fl f .
  45   45  If no manual page is located,
  46   46  .Nm
  47   47  prints an error message.
  48   48  .Ss "Source Format"
  49   49  Reference Manual pages are marked up with either
  50   50  .Xr man 5 ,
  51   51  or
  52   52  .Xr mdoc 5
  53   53  language tags. The
  54   54  .Nm
  55   55  command recognizes the type of markup and
  56   56  processes the file accordingly.
  57   57  .
  58   58  .Ss "Location of Manual Pages"
  59   59  .
  60   60  The online Reference Manual page directories are conventionally located in
  61   61  .Pa /usr/share/man .
  62   62  Each directory corresponds to a
  63   63  section of the manual. Since these directories are optionally installed, they
  64   64  might not reside on your host. You might have to mount
  65   65  .Pa /usr/share/man
  66   66  from a host on which they do reside.
  67   67  The
  68   68  .Nm
  69   69  command reformats a page whenever it is requested.
  70   70  .Pp
  71   71  If the standard output is not a terminal, or if the
  72   72  .Fl
  73   73  flag is given,
  74   74  .Nm
  75   75  pipes its output through
  76   76  .Xr cat 1 .
  77   77  Otherwise,
  78   78  .Nm
  79   79  pipes its output through a pager such as
  80   80  .Xr more 1
  81   81  to handle paging and underlining on the screen.
  82   82  .Sh OPTIONS
  83   83  The following options are supported:
  84   84  .Bl -tag -width indent
  85   85  .It Fl a
  86   86  Shows all manual pages matching
  87   87  .Ar name
  88   88  within the
  89   89  .Ev MANPATH
  90   90  search path. Manual pages are displayed in the order found.
  91   91  .It Fl d
  92   92  Debugs. Displays what a section-specifier evaluates to, method used for
  93   93  searching, and paths searched by
  94   94  .Nm .
  95   95  .It Fl f Ar file ...
  96   96  Attempts to locate manual pages related to any of the given
  97   97  .Ar file
  98   98  names. It strips the leading path name components from each
  99   99  .Ar file ,
 100  100  and then prints one-line summaries containing the resulting basename or names.
 101  101  This option also uses the
 102  102  .Pa whatis
 103  103  database.
 104  104  .It Fl F
 105  105  This option is present for backwards compatibility and is documented
 106  106  here for reference only.  It performs no function.
 107  107  .It Fl k Ar keyword ...
 108  108  Prints out one-line summaries from the
 109  109  .Pa whatis
 110  110  database (table of contents) that contain any of the given
 111  111  .Ar keyword .
 112  112  The
 113  113  .Pa whatis
 114  114  database is created using the
 115  115  .Fl w
 116  116  option.
 117  117  .It Fl l
 118  118  Lists all manual pages found matching
 119  119  .Ar name
 120  120  within the search path.
 121  121  .It Fl M Ar path
 122  122  Specifies an alternate search path for manual pages. The
 123  123  .Ar path
 124  124  is a colon-separated list of directories that contain manual page directory
 125  125  subtrees. For example, if
 126  126  .Ar path
 127  127  is
 128  128  .Pa /usr/share/man:/usr/local/man ,
 129  129  .Nm
 130  130  searches for
 131  131  .Ar name
 132  132  in the standard location, and then
 133  133  .Pa /usr/local/man .
 134  134  When used with the
 135  135  .Fl k ,
 136  136  .Fl f ,
 137  137  or
 138  138  .Fl w
 139  139  options, the
 140  140  .Fl M
 141  141  option must appear first. Each directory in the
 142  142  .Ar path
 143  143  is assumed to contain subdirectories of the form
 144  144  .Pa man* ,
 145  145  one for each section. This option overrides the
 146  146  .Ev MANPATH
 147  147  environment variable.
 148  148  .It Fl r
 149  149  Reformats the manual page, checking for formatting errors, but does not
 150  150  display it.
 151  151  .It Fl s Ar section
 152  152  Specifies sections of the manual for
 153  153  .Nm
 154  154  to search. The directories searched for
 155  155  .Ar name
 156  156  are limited to those specified by
 157  157  .Ar section .
 158  158  .Ar section
 159  159  can be a numerical digit, perhaps followed by one or more letters
 160  160  to match the desired section of the manual, for example,
 161  161  .Li "3libucb".
 162  162  Also,
 163  163  .Ar section
 164  164  can be a word, for example,
 165  165  .Li local ,
 166  166  .Li new ,
 167  167  .Li old ,
 168  168  .Li public .
 169  169  .Ar section
 170  170  can also be a letter. To specify multiple sections,
 171  171  separate each section with a comma. This option overrides the
 172  172  .Ev MANPATH
 173  173  environment variable and the
 174  174  .Pa man.cf
 175  175  file. See
 176  176  .Sx Search Path
 177  177  below for an explanation of how
 178  178  .Nm
 179  179  conducts its search.
 180  180  .It Fl t
 181  181  Arranges for the specified manual pages to be sent to the default
 182  182  printer as PostScript.
 183  183  .It Fl T Ar macro-package
 184  184  This option is present for backwards compatibility and is documented
 185  185  here for reference only.  It performs no function.
 186  186  .It Fl w
 187  187  Updates the
 188  188  .Nm whatis
 189  189  database.
 190  190  .El
 191  191  .Sh OPERANDS
 192  192  The following operand is supported:
 193  193  .Bl -tag -width indent
 194  194  .It Ar name
 195  195  The name of a standard utility or a keyword.
 196  196  .El
 197  197  .Sh USAGE
 198  198  The usage of
 199  199  .Nm
 200  200  is described below:
 201  201  .
 202  202  .Ss "Manual Page Sections"
 203  203  .
 204  204  Entries in the reference manuals are organized into
 205  205  .Em sections .
 206  206  A section
 207  207  name consists of a major section name, typically a single digit, optionally
 208  208  followed by a subsection name, typically one or more letters. An unadorned
 209  209  major section name, for example,
 210  210  .Qq 9 ,
 211  211  does not act as an abbreviation for
 212  212  the subsections of that name, such as
 213  213  .Qq 9e ,
 214  214  .Qq 9f ,
 215  215  or
 216  216  .Qq 9s .
 217  217  That is, each subsection must be searched separately by
 218  218  .Nm
 219  219  .Fl s .
 220  220  Each section contains descriptions apropos to a particular reference category,
 221  221  with subsections refining these distinctions. See the
 222  222  .Em intro
 223  223  manual pages for an explanation of the classification used in this release.
 224  224  .
 225  225  .Ss "Search Path"
 226  226  .
 227  227  Before searching for a given
 228  228  .Ar name ,
 229  229  .Nm
 230  230  constructs a list of candidate directories and sections.
 231  231  It searches for
 232  232  .Ar name
 233  233  in the directories specified by the
 234  234  .Ev MANPATH
 235  235  environment variable.
 236  236  .Lp
 237  237  In the absence of
 238  238  .Ev MANPATH ,
 239  239  .Nm
 240  240  constructs its search path based upon the
 241  241  .Ev PATH
 242  242  environment variable, primarily by substituting
 243  243  .Li man
 244  244  for the last component of the
 245  245  .Ev PATH
 246  246  element. Special provisions are added
 247  247  to account for unique characteristics of directories such as
 248  248  .Pa /sbin ,
 249  249  .Pa /usr/ucb ,
 250  250  .Pa /usr/xpg4/bin ,
 251  251  and others. If the file argument contains
 252  252  a
 253  253  .Qq /
 254  254  character, the
 255  255  .Em dirname
 256  256  portion of the argument is used in place of
 257  257  .Ev PATH
 258  258  elements to construct the search path.
 259  259  .Lp
 260  260  Within the manual page directories,
 261  261  .Nm
 262  262  confines its search to the
 263  263  sections specified in the following order:
 264  264  .Bl -bullet
 265  265  .It
 266  266  .Ar sections
 267  267  specified on the command line with the
 268  268  .Fl s
 269  269  option
 270  270  .It
 271  271  .Ar sections
 272  272  embedded in the
 273  273  .Ev MANPATH
 274  274  environment variable
 275  275  .It
 276  276  .Ar sections
 277  277  specified in the
 278  278  .Pa man.cf
 279  279  file for each directory specified in the
 280  280  .Ev MANPATH
 281  281  environment variable
 282  282  .El
 283  283  If none of the above exist,
 284  284  .Nm
 285  285  searches each directory in the manual
 286  286  page path, and displays the first matching manual page found.
 287  287  .Lp
 288  288  The
 289  289  .Pa man.cf
 290  290  file has the following format:
 291  291  .Lp
 292  292  .Dl Pf MANSECTS= Ar section , Ns Op Ar section...
 293  293  .Lp
 294  294  Lines beginning with
 295  295  .Sq Li #
 296  296  and blank lines are considered comments, and are
 297  297  ignored. Each directory specified in
 298  298  .Ev MANPATH
 299  299  can contain a manual page
 300  300  configuration file, specifying the default search order for that directory.
 301  301  .Sh "Referring to Other Manual Pages"
 302  302  If the first line of the manual page is a reference to another manual
 303  303  page entry fitting the pattern:
 304  304  .Lp
 305  305  .Dl \&.so man*/\fIsourcefile\fR
 306  306  .Lp
 307  307  .Nm
 308  308  processes the indicated file in place of the current one. The
 309  309  reference must be expressed as a path name relative to the root of the manual
 310  310  page directory subtree.
 311  311  .Lp
 312  312  When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
 313  313  ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
 314  314  manner.
 315  315  .Sh ENVIRONMENT VARIABLES
 316  316  See
 317  317  .Xr environ 5
 318  318  for descriptions of the following environment variables
 319  319  that affect the execution of
 320  320  .Nm man :
 321  321  .Ev LANG ,
 322  322  .Ev LC_ALL ,
 323  323  .Ev LC_CTYPE ,
 324  324  .Ev LC_MESSAGES ,
 325  325  and
 326  326  .Ev NLSPATH .
 327  327  .Bl -tag -width indent
 328  328  .It Ev MANPATH
 329  329  A colon-separated list of directories; each directory can be followed by a
 330  330  comma-separated list of sections. If set, its value overrides
 331  331  \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
 332  332  file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
 333  333  turn, override these values.)
 334  334  .It Ev PAGER
 335  335  A program to use for interactively delivering
 336  336  output to the screen. If not set,
 337  337  .Sq Nm more Fl s
 338  338  is used. See
 339  339  .Xr more 1 .
 340  340  .El
 341  341  .Sh FILES
 342  342  .Bl -tag -width indent
 343  343  .It Pa /usr/share/man
 344  344  Root of the standard manual page directory subtree
 345  345  .It Pa /usr/share/man/man?/*
 346  346  Unformatted manual entries
 347  347  .It Pa /usr/share/man/whatis
 348  348  Table of contents and keyword database
 349  349  .It Pa man.cf
 350  350  Default search order by section
 351  351  .El
 352  352  .Sh EXIT STATUS
 353  353  .Ex -std man
 354  354  .Sh EXAMPLES
 355  355  .
 356  356  .Ss Example 1: Creating a PostScript Version of a man page
 357  357  .
 358  358  The following example spools the
 359  359  .Xr pipe 2
 360  360  man page in PostScript to the default printer:
 361  361  .Pp
 362  362  .Dl % man -t -s 2 pipe
 363  363  .Pp
 364  364  Note that
 365  365  .Xr mandoc 1

 366  366  can be used to obtain the PostScript content directly.
 367  367  .Ss Example 2: Creating a Text Version of a man page
 368  368  The following example creates the
 369  369  .Xr pipe 2
 370  370  man page in ASCII text:
 371  371  .Pp
 372  372  .Dl % man pipe.2 | col -x -b > pipe.text
 373  373  .Sh CODE SET INDEPENDENCE
 374  374  Enabled.
 375  375  .Sh INTERFACE STABILITY
 376      -.Nm Committed .
      376 +.Sy Committed .
 377  377  .Sh SEE ALSO
 378  378  .Xr apropos 1 ,
 379  379  .Xr cat 1 ,
 380  380  .Xr col 1 ,
 381  381  .Xr mandoc 1 ,
 382  382  .Xr more 1 ,
 383  383  .Xr whatis 1 ,
 384  384  .Xr environ 5 ,
 385  385  .Xr man 5 ,
 386  386  .Xr mdoc 5

 387  387  .Sh NOTES
 388  388  The
 389  389  .Fl f
 390  390  and
 391  391  .Fl k
 392  392  options use the
 393  393  .Nm whatis
 394  394  database, which is
 395  395  created with the
 396  396  .Fl w
 397  397  option.
 398  398  .Sh BUGS
 399  399  The manual is supposed to be reproducible either on a phototypesetter or on an
 400  400  ASCII terminal. However, on a terminal some information (indicated by
 401  401  font changes, for instance) is lost.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX