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

          --- old/usr/src/man/man5/man.5
          +++ new/usr/src/man/man5/man.5
   1    1  .\" Copryight 2014 Garrett D'Amore <garrett@damore.org>
   2    2  .\" Copyright (c) 1995, Sun Microsystems, Inc.
   3    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    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    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      -.Dd "Jul 19, 2014"
        6 +.Dd "Jul 30, 2014"
   7    7  .Dt MAN 5
   8    8  .Os
   9    9  .Sh NAME
  10   10  .Nm man
  11   11  .Nd macros to format Reference Manual pages
  12   12  .Sh SYNOPSIS
  13   13  .Nm mandoc
  14   14  .Fl T Ar man
  15   15  .Ar
  16   16  .Nm nroff

  17   17  .Fl man
  18   18  .Ar
  19   19  .Nm troff
  20   20  .Fl man
  21   21  .Ar
  22   22  .Sh DESCRIPTION
  23   23  These macros are used to lay out the reference pages in this manual. Note: if
  24   24  .Ar file
  25   25  contains format input for a preprocessor, the commands shown
  26   26  above must be piped through the appropriate preprocessor. This is handled
  27   27  automatically by the
  28   28  .Xr man 1
  29   29  command. See the
  30   30  .Sx Conventions
  31   31  section.
  32   32  .Lp
  33   33  Any text argument
  34   34  .Ar t
  35   35  may be zero to six words. Quotes may be used to
  36   36  include SPACE characters in a
  37   37  .Qq word .
  38   38  If
  39   39  .Ar text
  40   40  is empty, the special
  41   41  treatment is applied to the next input line with text to be printed. In this
  42   42  way
  43   43  .Nm \&.I
  44   44  may be used to italicize a whole line, or
  45   45  .Nm \&.SB
  46   46  may be used to make small bold letters.
  47   47  .Lp
  48   48  A prevailing indent distance is remembered between successive indented
  49   49  paragraphs, and is reset to default value upon reaching a non-indented
  50   50  paragraph.  Default units for indents
  51   51  .Nm i
  52   52  are ens.
  53   53  .Lp
  54   54  Type font and size are reset to default values before each paragraph, and after
  55   55  processing font and size setting macros.
  56   56  .Pp
  57   57  These strings are predefined by
  58   58  .Nm -man :
  59   59  .Bl -tag -width Ds
  60   60  .It Nm \e*R
  61   61  .Sq \(rg ,
  62   62  .Sq (Reg)
  63   63  in
  64   64  .Nm nroff .
  65   65  .It Nm \e*S
  66   66  Change to default type size.
  67   67  .El
  68   68  .Sh "Requests"
  69   69  * n.t.l. = next text line; p.i. = prevailing indent
  70   70  .Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds
  71   71  .It Sy Request  Sy Cause        Sy "If No"      Sy Explanation
  72   72  .It ""  Sy Break        Sy "Argument"   ""
  73   73  .It Nm \&.B Ar "t"      no      Ar t Ns =n.t.l.*        Text is in bold font.
  74   74  .It Nm \&.BI Ar t       no      Ar t Ns =n.t.l. Join words, alternating bold and italic.
  75   75  .It Nm \&.BR Ar t       no      Ar t Ns =n.t.l. Join words, alternating bold and roman.
  76   76  .It Nm \&.DT    no      Li \&.5i 1i...  Restore default tabs.
  77   77  .It Nm \&.HP Ar i       yes     Ar i Ns =p.i.*  "Begin paragraph with hanging indent. Set prevailing indent to" Ar i .
  78   78  .It Nm \&.I Ar t        no      Ar t Ns =n.t.l. Text is italic.
  79   79  .It Nm \&.IB Ar t       no      Ar t Ns =n.t.l. Join words, altenrating italic and bold.
  80   80  .It Nm \&.IP Ar x Ar i  yes     Ar x Ns =""     Same as
  81   81  .Nm \&.TP
  82   82  with tag
  83   83  .Ar x .
  84   84  .It Nm \&.IR Ar t       no      Ar t Ns =n.t.l. Join words, alternating italic and roman.
  85   85  .It Nm \&.IX Ar t       no      -       Index macro, not used (obsolete).
  86   86  .It Nm \&.LP    yes     -       Begin left-aligned paragraph. Set prevailing indent to .5i.
  87   87  .It Nm \&.P     yes     -       Same as
  88   88  .Nm \&.LP .
  89   89  .It Nm \&.PD Ar d       no      Ar d Ns =.4v    Set vertical distance between paragraphs.
  90   90  .It Nm \&.PP    yes     -       Same as
  91   91  .Nm \&.LP .
  92   92  .It Nm \&.RE    yes     -       End of relative indent. Restores prevailing indent.
  93   93  .It Nm \&.RB Ar t       no      Ar t Ns =n.t.l. Join words, alternating roman and bold.
  94   94  .It Nm \&.RI Ar t       no      Ar t Ns =n.t.l. Join words, alternating roman and italic.
  95   95  .It Nm \&.RS Ar i       yes     Ar i Ns =p.i.   Start relative indent, increase indent by Ar i .
  96   96  Sets prevailing indent to .5i for nested indents.
  97   97  .It Nm \&.SB Ar t       no      -       Reduce size of text by 1 point, make text bold.
  98   98  .It Nm \&.SH Ar t       yes     -       Section Heading.
  99   99  .It Nm \&.SM Ar t       no      Ar t Ns =n.t.l. Reduce size of text by 1 point.
 100  100  .It Nm \&.SS Ar t       yes     Ar t Ns =n.t.l. Section Subheading.
 101  101  .It Nm \&.TH Ar n s d f m       yes     -       Begin reference page Ar n , No of section Ar s ; Ar d No is the date of the most recent change.  If present, Ar f No is the left page footer; Ar m No is the main page (center) header.  Sets prevailing indent and tabs to .5i.
 102  102  .It Nm \&.TP Ar i       yes     Ar i Ns =p.i.   Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to
 103  103  .Ar i .
 104  104  .It Nm \&.TX Ar t p     no      -       Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p .
 105  105  .El
 106  106  .Ss "Conventions"
 107  107  When formatting a manual page,
 108  108  .Nm
 109  109  examines the first line to determine
 110  110  whether it requires special processing. For example a first line consisting of:
 111  111  .Lp
 112  112  .Dl \&'\e" t
 113  113  .Lp
 114  114  indicates that the manual page must be run through the
 115  115  .Xr tbl 1
 116  116  preprocessor.
 117  117  .Lp
 118  118  A typical manual page for a command or function is laid out as follows:
 119  119  .Bl -tag -width ".SH RETURN VALUES"
 120  120  .
 121  121  .It Nm \&.TH Ar title Op "1-9"
 122  122  .
 123  123  The name of the command or function, which serves as the title of the manual
 124  124  page. This is followed by the number of the section in which it appears.
 125  125  .
 126  126  .It Nm SH NAME
 127  127  .
 128  128  The name, or list of names, by which the command is called, followed by a dash
 129  129  and then a one-line summary of the action performed. All in roman font, this
 130  130  section contains no
 131  131  .Xr troff 1
 132  132  commands or escapes, and no macro requests.
 133  133  It is used to generate the database used by the
 134  134  .Xr whatis 1
 135  135  command.
 136  136  .
 137  137  .It Nm SH SYNOPSIS
 138  138  .Bl -tag -width "Functions:"
 139  139  .It Sy Commands:
 140  140  The syntax of the command and its arguments, as typed on the command line.
 141  141  When in boldface, a word must be typed exactly as printed.  When in italics, a
 142  142  word can be replaced with an argument that you supply. References to bold or
 143  143  italicized items are not capitalized in other sections, even when they begin a
 144  144  sentence.
 145  145  .Lp
 146  146  Syntactic symbols appear in roman face:
 147  147  .Bl -tag -width "   "
 148  148  .It Op " "
 149  149  An argument, when surrounded by brackets is optional.
 150  150  .It |
 151  151  Arguments separated by a vertical bar are exclusive. You can supply only one
 152  152  item from such a list.
 153  153  .It \&.\|.\|.
 154  154  Arguments followed by an ellipsis can be repeated. When an ellipsis follows a
 155  155  bracketed set, the expression within the brackets can be repeated.
 156  156  .El
 157  157  .It Sy Functions:
 158  158  If required, the data declaration, or
 159  159  .Li #include
 160  160  directive, is shown first,
 161  161  followed by the  function declaration. Otherwise, the function declaration is
 162  162  shown.
 163  163  .El
 164  164  .
 165  165  .It Nm \&.SH DESCRIPTION
 166  166  .
 167  167  A narrative overview of the command or function's external behavior. This
 168  168  includes how it interacts with files or data, and how it handles the standard
 169  169  input, standard output and standard error. Internals and implementation details
 170  170  are normally omitted. This section attempts to provide a succinct overview in
 171  171  answer to the question, "what does it do?"
 172  172  .Lp
 173  173  Literal text from the synopsis appears in constant width, as do literal
 174  174  filenames and references to items that appear elsewhere in the  reference
 175  175  manuals. Arguments are italicized.
 176  176  .Lp
 177  177  If a command interprets either subcommands or an input grammar, its command
 178  178  interface or input grammar is normally described in a
 179  179  .Nm USAGE
 180  180  section, which follows the
 181  181  .Nm OPTIONS
 182  182  section.  The
 183  183  .Nm DESCRIPTION
 184  184  section only
 185  185  describes the behavior of the command itself, not that of subcommands.
 186  186  .
 187  187  .It Nm \&.SH OPTIONS
 188  188  .
 189  189  The list of options along with a description of how each affects the command's
 190  190  operation.
 191  191  .
 192  192  .It Nm \&.SH RETURN VALUES
 193  193  .
 194  194  A list of the values the library routine will return to the calling  program
 195  195  and the conditions that cause these values to be returned.
 196  196  .
 197  197  .It Nm \&.SH EXIT STATUS
 198  198  .
 199  199  A list of the values the utility will return to the calling  program or shell,
 200  200  and the conditions that cause these values to be  returned.
 201  201  .
 202  202  .It Nm \&.SH FILES
 203  203  .
 204  204  A list of files associated with the command or function.
 205  205  .
 206  206  .It Nm \&.SH SEE ALSO
 207  207  .
 208  208  A comma-separated list of related manual pages, followed by references to other
 209  209  published materials.
 210  210  .
 211  211  .It Nm \&.SH DIAGNOSTICS
 212  212  .
 213  213  A list of diagnostic messages and an explanation of each.
 214  214  .
 215  215  .It Nm \&.SH BUGS
 216  216  .
 217  217  A description of limitations, known defects, and possible problems associated
 218  218  with the command or function.
 219  219  .El
 220  220  .Sh FILES
 221  221  .Pa /usr/share/man/whatis
 222  222  .Sh NOTES
 223  223  The
 224  224  .Nm
 225  225  package should not be used for new documentation.  The
 226  226  .Xr mdoc 5 ,
 227  227  package is preferred, as it uses semantic markup rather than physical markup.

 228  228  .Sh CODE SET INDEPENDENCE
 229  229  When processed with
 230  230  .Xr mandoc 1 ,
 231  231  this package is Code Set Independent. However, when processed with
 232  232  legacy tools such as
 233  233  .Xr nroff 1
 234  234  and
 235  235  .Xr troff 1 ,
 236  236  the use of multi-byte characters may not be supported.
 237  237  .Sh INTERFACE STABILITY
 238      -.Nm Obsolete Committed .
      238 +.Sy Obsolete Committed .
 239  239  The
 240  240  .Xr mdoc 5
 241  241  package should be used instead.
 242  242  .Sh SEE ALSO
 243  243  .Xr eqn 1 ,
 244  244  .Xr man 1 ,
 245  245  .Xr mandoc 1 ,
 246  246  .Xr nroff 1 ,
 247  247  .Xr troff 1 ,
 248  248  .Xr tbl 1 ,
 249  249  .Xr whatis 1 ,
 250  250  .Xr mdoc 5 ,
 251  251  .Rs
 252  252  .%A Dale Dougherty and Tim O'Reilly
 253  253  .%B Unix Text Processing
 254  254  .Re
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX