man.7

   1 .\" $Id: man.7,v 1.9 2009/04/12 19:19:57 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: April 12 2009 $
  20 .Dt MAN 7
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm man
  25 .Nd man language reference
  26 .\" SECTION
  27 .Sh DESCRIPTION
  28 The
  29 .Nm man
  30 language was historically used to format
  31 .Ux
  32 manuals.  This reference document describes the syntax and structure of
  33 this language.
  34 .Pp
  35 .Em \&Do not
  36 use
  37 .Nm
  38 to write your manuals.  Use the
  39 .Xr mdoc 7
  40 language, instead.
  41 .\" PARAGRAPH
  42 .Pp
  43 An
  44 .Nm
  45 document follows simple rules:  lines beginning with the control
  46 character
  47 .Sq \&.
  48 are parsed for macros.  Other lines are interpreted within the scope of
  49 prior macros:
  50 .Bd -literal -offset indent
  51 \&.SH Macro lines change control state.
  52 Other lines are interpreted within the current state.
  53 .Ed
  54 .\" SECTION
  55 .Sh INPUT ENCODING
  56 .Nm
  57 documents may contain only graphable 7-bit ASCII characters and the
  58 space character
  59 .Sq \  .
  60 All manuals must have
  61 .Ux
  62 .Sq \en
  63 line termination.
  64 .Pp
  65 Blank lines are acceptable; where found, the output will assert a
  66 vertical space.
  67 .Pp
  68 The
  69 .Sq \ec
  70 escape is common in historical
  71 .Nm
  72 documents; if encountered at the end of a word, it ensures that the
  73 subsequent word isn't off-set by whitespace.
  74 .\" SUB-SECTION
  75 .Ss Special Characters
  76 Special character sequences begin with the escape character
  77 .Sq \e
  78 followed by either an open-parenthesis
  79 .Sq \&(
  80 for two-character sequences; an open-bracket
  81 .Sq \&[
  82 for n-character sequences (terminated at a close-bracket
  83 .Sq \&] ) ;
  84 or a single one-character sequence.
  85 .Pp
  86 Characters may alternatively be escaped by a slash-asterisk,
  87 .Sq \e* ,
  88 with the same combinations as described above.  This form is deprecated.
  89 .\" SECTION
  90 .Sh STRUCTURE
  91 Macros are one to three three characters in length and begin with a
  92 control character ,
  93 .Sq \&. ,
  94 at the beginning of the line.  An arbitrary amount of whitespace may
  95 sit between the control character and the macro name.  Thus,
  96 .Sq \&.PP
  97 and
  98 .Sq \&.\ \ \ \&PP
  99 are equivalent.
 100 .Pp
 101 All
 102 .Nm
 103 macros follow the same structural rules:
 104 .Bd -literal -offset indent
 105 \&.YO \(lBbody...\(rB
 106 .Ed
 107 .Pp
 108 The
 109 .Dq body
 110 consists of zero or more arguments to the macro.
 111 .Pp
 112 .Nm
 113 has a primitive notion of multi-line scope for the following macros:
 114 .Sq \&.TM ,
 115 .Sq \&.SM ,
 116 .Sq \&.SB ,
 117 .Sq \&.BI ,
 118 .Sq \&.IB ,
 119 .Sq \&.BR ,
 120 .Sq \&.RB ,
 121 .Sq \&.R ,
 122 .Sq \&.B ,
 123 .Sq \&.I ,
 124 .Sq \&.IR
 125 and
 126 .Sq \&.RI .
 127 When these macros are invoked without arguments, the subsequent line is
 128 considered a continuation of the macro.  Thus:
 129 .Bd -literal -offset indent
 130 \&.RI
 131 foo
 132 .Ed
 133 .Pp
 134 is equivalent to
 135 .Sq \&.RI foo .
 136 If two consecutive lines exhibit the latter behaviour,
 137 an error is raised.  Thus, the following is not acceptable:
 138 .Bd -literal -offset indent
 139 \&.RI
 140 \&.I
 141 Hello, world.
 142 .Ed
 143 .Pp
 144 The
 145 .Sq \&.TP
 146 macro is similar, but does not need an empty argument line to trigger
 147 the behaviour.
 148 .\" PARAGRAPH
 149 .Sh MACROS
 150 This section contains a complete list of all
 151 .Nm
 152 macros and corresponding number of arguments.
 153 .Pp
 154 .Bl -column "MacroX" "Arguments" -compact -offset indent
 155 .It Em Macro Ta Em Arguments
 156 .It \&.TH    Ta    >1, <6
 157 .It \&.SH    Ta    >0
 158 .It \&.SS    Ta    >0
 159 .It \&.TP    Ta    n
 160 .It \&.LP    Ta    0
 161 .It \&.PP    Ta    0
 162 .It \&.P     Ta    0
 163 .It \&.IP    Ta    <3
 164 .It \&.HP    Ta    <2
 165 .It \&.SM    Ta    n
 166 .It \&.SB    Ta    n
 167 .It \&.BI    Ta    n
 168 .It \&.IB    Ta    n
 169 .It \&.BR    Ta    n
 170 .It \&.RB    Ta    n
 171 .It \&.R     Ta    n
 172 .It \&.B     Ta    n
 173 .It \&.I     Ta    n
 174 .It \&.IR    Ta    n
 175 .It \&.RI    Ta    n
 176 .El
 177 .Pp
 178 Although not historically part of the
 179 .Nm
 180 system, the following macros are also supported:
 181 .Pp
 182 .Bl -column "MacroX" "Arguments" -compact -offset indent
 183 .It Em Macro Ta Em Arguments
 184 .It \&.br    Ta    0
 185 .It \&.i     Ta    n
 186 .El
 187 .Pp
 188 These follow the same calling conventions as the above
 189 .Nm
 190 macros.
 191 .\" SECTION
 192 .Sh SEE ALSO
 193 .Xr mandoc 1 ,
 194 .Xr mandoc_char 7
 195 .\" SECTION
 196 .Sh AUTHORS
 197 The
 198 .Nm
 199 utility was written by
 200 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 201 .\" SECTION
 202 .Sh CAVEATS
 203 Do not use this language.  Use
 204 .Xr mdoc 7 ,
 205 instead.