man.7

   1 .\"     $Id: man.7,v 1.18 2009/07/04 09:00:41 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   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 above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: July 4 2009 $
  18 .Dt MAN 7
  19 .Os
  20 .\" SECTION
  21 .Sh NAME
  22 .Nm man
  23 .Nd man language reference
  24 .\" SECTION
  25 .Sh DESCRIPTION
  26 The
  27 .Nm man
  28 language was historically used to format
  29 .Ux
  30 manuals.  This reference document describes the syntax and structure of
  31 this language.
  32 .Pp
  33 .Em \&Do not
  34 use
  35 .Nm
  36 to write your manuals.  Use the
  37 .Xr mdoc 7
  38 language, instead.
  39 .\" PARAGRAPH
  40 .Pp
  41 An
  42 .Nm
  43 document follows simple rules:  lines beginning with the control
  44 character
  45 .Sq \&.
  46 are parsed for macros.  Other lines are interpreted within the scope of
  47 prior macros:
  48 .Bd -literal -offset indent
  49 \&.SH Macro lines change control state.
  50 Other lines are interpreted within the current state.
  51 .Ed
  52 .\" SECTION
  53 .Sh INPUT ENCODING
  54 .Nm
  55 documents may contain only graphable 7-bit ASCII characters, the
  56 space character
  57 .Sq \  ,
  58 and tabs
  59 .Sq \et .
  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 Comments
  76 Anything following a
  77 .Sq \e"
  78 delimiter is considered a comment (unless the
  79 .Sq \e
  80 itself has been escaped) and is ignored to the end of line.
  81 Furthermore, a macro line with only a control character
  82 .Sq \. ,
  83 optionally followed by whitespace, is ignored.
  84 .\" SUB-SECTION
  85 .Ss Special Characters
  86 Special character sequences begin with the escape character
  87 .Sq \e
  88 followed by either an open-parenthesis
  89 .Sq \&(
  90 for two-character sequences; an open-bracket
  91 .Sq \&[
  92 for n-character sequences (terminated at a close-bracket
  93 .Sq \&] ) ;
  94 or a single one-character sequence.
  95 .Pp
  96 Characters may alternatively be escaped by a slash-asterisk,
  97 .Sq \e* ,
  98 with the same combinations as described above.
  99 .Pp
 100 Terms may also be text-decorated using the
 101 .Sq \ef
 102 escape followed by a text-decoration letter: B (bold), I, (italic), or P
 103 and R (Roman, or reset).
 104 .\" SUB-SECTION
 105 .Ss Whitespace
 106 Unless specifically escaped, consecutive blocks of whitespace are pruned
 107 from input.  These are later re-added, if applicable, by a front-end
 108 utility such as
 109 .Xr mandoc 1 .
 110 .\" SECTION
 111 .Sh STRUCTURE
 112 Each
 113 .Nm
 114 document must contain contains at least the
 115 .Sq \&.TH
 116 macro describing the document's section and title.  It may occur
 117 anywhere in the document, although conventionally, it appears as the
 118 first macro.
 119 .Pp
 120 Beyond the
 121 .Sq \&.TH ,
 122 at least one macro or text node must appear in the document.
 123 .\" SECTION
 124 .Sh SYNTAX
 125 Macros are one to three three characters in length and begin with a
 126 control character ,
 127 .Sq \&. ,
 128 at the beginning of the line.  An arbitrary amount of whitespace may
 129 sit between the control character and the macro name.  Thus,
 130 .Sq \&.PP
 131 and
 132 .Sq \&.\ \ \ \&PP
 133 are equivalent.
 134 .Pp
 135 All
 136 .Nm
 137 macros follow the same structural rules:
 138 .Bd -literal -offset indent
 139 \&.YO \(lBbody...\(rB
 140 .Ed
 141 .Pp
 142 The
 143 .Dq body
 144 consists of zero or more arguments to the macro.
 145 .Pp
 146 .Nm
 147 has a primitive notion of multi-line scope for the following macros:
 148 .Sq \&.TM ,
 149 .Sq \&.SM ,
 150 .Sq \&.SB ,
 151 .Sq \&.BI ,
 152 .Sq \&.IB ,
 153 .Sq \&.BR ,
 154 .Sq \&.RB ,
 155 .Sq \&.R ,
 156 .Sq \&.B ,
 157 .Sq \&.I ,
 158 .Sq \&.IR
 159 and
 160 .Sq \&.RI .
 161 When these macros are invoked without arguments, the subsequent line is
 162 considered a continuation of the macro.  Thus:
 163 .Bd -literal -offset indent
 164 \&.RI
 165 foo
 166 .Ed
 167 .Pp
 168 is equivalent to
 169 .Sq \&.RI foo .
 170 If two consecutive lines exhibit the latter behaviour,
 171 an error is raised.  Thus, the following is not acceptable:
 172 .Bd -literal -offset indent
 173 \&.RI
 174 \&.I
 175 Hello, world.
 176 .Ed
 177 .Pp
 178 The
 179 .Sq \&.TP
 180 macro is similar, but does not need an empty argument line to trigger
 181 the behaviour.
 182 .\" SECTION
 183 .Sh MACROS
 184 This section contains a complete list of all
 185 .Nm
 186 macros and corresponding number of arguments.
 187 .Pp
 188 .Bl -column "MacroX" "Arguments" -compact -offset indent
 189 .It Em Macro Ta Em Arguments
 190 .It \&.TH    Ta    >1, <6
 191 .It \&.SH    Ta    >0
 192 .It \&.SS    Ta    >0
 193 .It \&.TP    Ta    n
 194 .It \&.LP    Ta    0
 195 .It \&.PP    Ta    0
 196 .It \&.P     Ta    0
 197 .It \&.IP    Ta    <3
 198 .It \&.HP    Ta    <2
 199 .It \&.SM    Ta    n
 200 .It \&.SB    Ta    n
 201 .It \&.BI    Ta    n
 202 .It \&.IB    Ta    n
 203 .It \&.BR    Ta    n
 204 .It \&.RB    Ta    n
 205 .It \&.R     Ta    n
 206 .It \&.B     Ta    n
 207 .It \&.I     Ta    n
 208 .It \&.IR    Ta    n
 209 .It \&.RI    Ta    n
 210 .El
 211 .Pp
 212 Although not historically part of the
 213 .Nm
 214 system, the following macros are also supported:
 215 .Pp
 216 .Bl -column "MacroX" "Arguments" -compact -offset indent
 217 .It Em Macro Ta Em Arguments
 218 .It \&.br    Ta    0
 219 .It \&.i     Ta    n
 220 .El
 221 .Pp
 222 These follow the same calling conventions as the above
 223 .Nm
 224 macros.
 225 .\" SECTION
 226 .Sh COMPATIBILITY
 227 See
 228 .Xr mdoc 7
 229 for groff compatibility notes.
 230 .\" SECTION
 231 .Sh SEE ALSO
 232 .Xr mandoc 1 ,
 233 .Xr mandoc_char 7
 234 .\" SECTION
 235 .Sh AUTHORS
 236 The
 237 .Nm
 238 utility was written by
 239 .An Kristaps Dzonsons Aq kristaps@kth.se .
 240 .\" SECTION
 241 .Sh CAVEATS
 242 Do not use this language.  Use
 243 .Xr mdoc 7 ,
 244 instead.