man.7

   1 .\"     $Id: man.7,v 1.29 2009/08/19 11:30:40 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: August 19 2009 $
  18 .Dt MAN 7
  19 .Os
  20 .
  21 .
  22 .Sh NAME
  23 . Nm man
  24 . Nd man language reference
  25 .
  26 .
  27 .Sh DESCRIPTION
  28 The
  29 . Nm man
  30 language was historically used to format
  31 . Ux
  32 manuals.  This reference document describes its syntax, structure, and
  33 usage.
  34 . Pp
  35 . Bf -emphasis
  36 Do not use
  37 .  Nm
  38 to write your manuals.
  39 . Ef
  40 Use the
  41 . Xr mdoc 7
  42 language, instead.
  43 . Pp
  44 An
  45 . Nm
  46 document follows simple rules:  lines beginning with the control
  47 character
  48 . Sq \&.
  49 are parsed for macros.  Other lines are interpreted within the scope of
  50 prior macros:
  51 . Bd -literal -offset indent
  52 \&.SH Macro lines change control state.
  53 Other lines are interpreted within the current state.
  54 . Ed
  55 .
  56 .
  57 .Sh INPUT ENCODING
  58 . Nm
  59 documents may contain only graphable 7-bit ASCII characters, the
  60 space character, and the tabs character.  All manuals must have
  61 . Ux
  62 line termination.
  63 . Pp
  64 Blank lines are acceptable; where found, the output will assert a
  65 vertical space.
  66 . Pp
  67 The
  68 . Sq \ec
  69 escape is common in historical
  70 . Nm
  71 documents; if encountered at the end of a word, it ensures that the
  72 subsequent word isn't off-set by whitespace.
  73 .
  74 .
  75 . Ss Comments
  76 Text following a
  77 .  Sq \e\*" ,
  78 whether in a macro or free-form text line, is ignored to the end of
  79 line.  A macro line with only a control character and comment escape,
  80 .  Sq \&.\e" ,
  81 is also ignored.  Macro lines with only a control charater and
  82 optionally whitespace are stripped from input.
  83 .
  84 .
  85 . Ss Special Characters
  86 Special characters may occur in both macro and free-form lines.
  87 Sequences begin with the escape character
  88 .  Sq \e
  89 followed by either an open-parenthesis
  90 .  Sq \&(
  91 for two-character sequences; an open-bracket
  92 .  Sq \&[
  93 for n-character sequences (terminated at a close-bracket
  94 .  Sq \&] ) ;
  95 or a single one-character sequence.  See
  96 .  Xr mandoc_char 7
  97 for a complete list.  Examples include
  98 .  Sq \e(em
  99 .  Pq em-dash
 100 and
 101 .  Sq \ee
 102 .  Pq back-slash .
 103 .
 104 .
 105 . Ss Text Decoration
 106 Terms may be text-decorated using the
 107 .  Sq \ef
 108 escape followed by an indicator: B (bold), I, (italic), or P and R
 109 (Roman, or reset).
 110 .
 111 .
 112 . Ss Whitespace
 113 Unless specifically escaped, consecutive blocks of whitespace are pruned
 114 from input.  These are later re-added, if applicable, by a front-end
 115 utility such as
 116 .  Xr mandoc 1 .
 117 .
 118 .
 119 .Sh MANUAL STRUCTURE
 120 Each
 121 . Nm
 122 document must contain contains at least the
 123 . Sq \&TH
 124 macro describing the document's section and title.  It may occur
 125 anywhere in the document, although conventionally, it appears as the
 126 first macro.
 127 . Pp
 128 Beyond
 129 . Sq \&TH ,
 130 at least one macro or text node must appear in the document.  Documents
 131 are generally structured as follows:
 132 . Bd -literal -offset indent
 133 \&.TH FOO 1 "13 Aug 2009"
 134 \&.
 135 \&.SH NAME
 136 \efBfoo\efR \e(en a description goes here
 137 \&.
 138 \&.SH SYNOPSIS
 139 \efBfoo\efR [\efB\e-options\efR] arguments...
 140 \&.
 141 \&.SH DESCRIPTION
 142 The \efBfoo\efR utility does...
 143 \&.
 144 \&.\e\*q .SH RETURN VALUES
 145 \&.\e\*q .SH ENVIRONMENT
 146 \&.\e\*q .SH FILES
 147 \&.\e\*q .SH EXAMPLES
 148 \&.\e\*q .SH DIAGNOSTICS
 149 \&.\e\*q .SH ERRORS
 150 \&.\e\*q .SH SEE ALSO
 151 \&.\e\*q \efBbar\efR(1)
 152 \&.\e\*q .SH STANDARDS
 153 \&.\e\*q .SH HISTORY
 154 \&.\e\*q .SH AUTHORS
 155 \&.\e\*q .SH CAVEATS
 156 \&.\e\*q .SH BUGS
 157 . Ed
 158 .
 159 .
 160 .Sh MACRO SYNTAX
 161 Macros are one to three three characters in length and begin with a
 162 control character ,
 163 . Sq \&. ,
 164 at the beginning of the line.  An arbitrary amount of whitespace may
 165 sit between the control character and the macro name.  Thus,
 166 . Sq \&.PP
 167 and
 168 . Sq \&.\ \ \ \&PP
 169 are equivalent.
 170 . Pp
 171 The
 172 . Nm
 173 macros are classified by scope: line scope or block scope.  Line-scoped
 174 macros are only scoped to the current line (and, in some situations,
 175 the subsequent line).  Block macros are scoped to the current line and
 176 subsequent lines until closed by another block macro.
 177 .
 178 .
 179 . Ss Line Macros
 180 Line-macros are scoped to the current line, with the body consisting of
 181 zero or more arguments.  If a macro is next-line scoped and the line
 182 arguments are empty, the next line is used instead.  Thus:
 183 .  Bd -literal -offset indent
 184 \&.RI
 185 foo
 186 .  Ed
 187 .  Pp
 188 is equivalent to
 189 .  Sq \&.RI foo .
 190 .\" PARAGRAPH
 191 Consecutive next-line invocations are disallowed.
 192 .  Bd -literal -offset indent
 193 \&.YO \(lBbody...\(rB
 194 \(lBbody...\(rB
 195 .  Ed
 196 .  Pp
 197 .  Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
 198 .   It Em Macro Ta Em Arguments Ta Em Scope
 199 .   It  \&B     Ta    n         Ta    next-line
 200 .   It  \&BI    Ta    n         Ta    current
 201 .   It  \&BR    Ta    n         Ta    current
 202 .   It  \&I     Ta    n         Ta    next-line
 203 .   It  \&IB    Ta    n         Ta    current
 204 .   It  \&IR    Ta    n         Ta    current
 205 .   It  \&R     Ta    n         Ta    next-line
 206 .   It  \&RB    Ta    n         Ta    current
 207 .   It  \&RI    Ta    n         Ta    current
 208 .   It  \&SB    Ta    n         Ta    next-line
 209 .   It  \&SM    Ta    n         Ta    next-line
 210 .   It  \&TH    Ta    >1, <6    Ta    current
 211 .   It  \&br    Ta    0         Ta    current
 212 .   It  \&fi    Ta    0         Ta    current
 213 .   It  \&i     Ta    n         Ta    current
 214 .   It  \&na    Ta    0         Ta    current
 215 .   It  \&nf    Ta    0         Ta    current
 216 .   It  \&r     Ta    0         Ta    current
 217 .   It  \&sp    Ta    1         Ta    current
 218 .  El
 219 .  Pp
 220 The lower-case
 221 .  Sq \&br ,
 222 .  Sq \&fi ,
 223 .  Sq \&i ,
 224 .  Sq \&na ,
 225 .  Sq \&nf ,
 226 .  Sq \&r ,
 227 and
 228 .  Sq \&sp
 229 macros aren't historically part of
 230 .  Nm
 231 and should not be used.  They're included for compatibility.
 232 .
 233 .
 234 . Ss Block Macros
 235 Block macros are comprised of a head and body.  The head is scoped to
 236 the current line and, in one circumstance, the next line; the body is
 237 scoped to subsequent lines and is closed out by a subsequent block macro
 238 invocation.
 239 .  Bd -literal -offset indent
 240 \&.YO \(lBhead...\(rB
 241 \(lBhead...\(rB
 242 \(lBbody...\(rB
 243 .  Ed
 244 .  Pp
 245 If a block macro is next-line scoped, it may only be followed by in-line
 246 macros (excluding
 247 .  Sq br ,
 248 .  Sq na ,
 249 .  Sq sp ,
 250 .  Sq nf ,
 251 .  Sq fi ,
 252 and
 253 .  Sq TH ) .
 254 .  Pp
 255 .  Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
 256 .   It Em Macro Ta Em Arguments Ta Em Scope
 257 .   It \&HP     Ta    <2        Ta    current
 258 .   It \&IP     Ta    <3        Ta    current
 259 .   It \&LP     Ta    0         Ta    current
 260 .   It \&P      Ta    0         Ta    current
 261 .   It \&PP     Ta    0         Ta    current
 262 .   It \&SH     Ta    >0        Ta    current
 263 .   It \&SS     Ta    >0        Ta    current
 264 .   It \&TP     Ta    n         Ta    next-line
 265 .  El
 266 .
 267 .
 268 .Sh REFERENCE
 269 This section is a canonical reference to all macros, arranged
 270 alphabetically.  For the scoping of individual macros, see
 271 . Sx MACRO SYNTAX .
 272 .
 273 .
 274 . Ss Terms
 275 In this reference, a numerical width may be either a standalone natural
 276 number (such as 3, 4, 10, etc.) or a natural number followed by a width
 277 multiplier
 278 .  Qq n ,
 279 corresponding to the width of the formatted letter n, or
 280 .  Qq m ,
 281 corresponding to the width of the formatted letter m.  The latter is the
 282 default, if unspecified.  Thus,
 283 .  Bd -literal -offset indent
 284 \&.HP 12n
 285 .  Ed
 286 .  Pp
 287 indicates an offset of 12
 288 .  Qq n
 289 .  Ns -sized
 290 letters.
 291 .
 292 .
 293 . Ss Macro Reference
 294 .  Bl -tag -width Ds
 295 .   It \&B
 296 Text is rendered in bold face.
 297 .   It \&BI
 298 Text is rendered alternately in bold face and italic.  Thus,
 299 .    Sq \&.BI this word and that
 300 causes
 301 .    Sq this
 302 and
 303 .    Sq and
 304 to render in bold face, while
 305 .    Sq word
 306 and
 307 .    Sq that
 308 render in italics.  Whitespace between arguments is omitted in output.
 309 .   It \&BR
 310 Text is rendered alternately in bold face and roman (the default font).
 311 Whitespace between arguments is omitted in output.
 312 .   It \&HP
 313 Begin a paragraph whose initial output line is left-justified, but
 314 subsequent output lines are indented, with the following syntax:
 315 .    Bd -literal -offset indent
 316 \&.HP [width]
 317 .    Ed
 318 .    Pp
 319 If
 320 .    Va width
 321 is specified, it's saved for later paragraph left-margins; if
 322 unspecified, the saved or default width is used.
 323 .   It \&I
 324 Text is rendered in italics.
 325 .   It \&IB
 326 Text is rendered alternately in italics and bold face.  Whitespace
 327 between arguments is omitted in output.
 328 .   It \&IP
 329 Begin a paragraph with the following syntax:
 330 .    Bd -literal -offset indent
 331 \&.IP [head [width]]
 332 .    Ed
 333 .    Pp
 334 This follows the behaviour of the
 335 .    Sq \&TP
 336 except for the macro syntax (all arguments on the line, instead of
 337 having next-line scope).  If
 338 .    Va width
 339 is specified, it's saved for later paragraph left-margins; if
 340 unspecified, the saved or default width is used.
 341 .   It \&IR
 342 Text is rendered alternately in italics and roman (the default font).
 343 Whitespace between arguments is omitted in output.
 344 .   It \&LP, \&P, \&PP
 345 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 346 subsequent paragraph, sub-section, section, or end of file.  The saved
 347 paragraph left-margin width is re-set to the default.
 348 .   It \&R
 349 Text is rendered in roman (the default font).
 350 .   It \&RB
 351 Text is rendered alternately in roman (the default font) and bold face.
 352 Whitespace between arguments is omitted in output.
 353 .   It \&RI
 354 Text is rendered alternately in roman (the default font) and italics.
 355 Whitespace between arguments is omitted in output.
 356 .   It \&SB
 357 Text is rendered in small size (one point smaller than the default font)
 358 bold face.
 359 .   It \&SH
 360 Begin a section.  The scope of a section is only closed by another
 361 section or the end of file.  The paragraph left-margin width is re-set
 362 to the default.
 363 .   It \&SM
 364 Text is rendered in small size (one point smaller than the default
 365 font).
 366 .   It \&SS
 367 Begin a sub-section.  The scope of a sub-section is closed by a
 368 subsequent sub-section, section, or end of file.  The paragraph
 369 left-margin width is re-set to the default.
 370 .   It \&TH
 371 Sets the title of the manual page with the following syntax:
 372 .    Bd -literal -offset indent
 373 \&.TH title section date source volume
 374 .    Ed
 375 .    Pp
 376 At least the
 377 .    Va title
 378 and
 379 .    Va section
 380 arguments must be provided.  The
 381 .    Va date
 382 argument should be formatted as
 383 .    Qq %b [%d] %Y
 384 format, described in
 385 .    Xr strptime 3 .
 386 The
 387 .    Va source
 388 string specifies the organisation providing the utility.  The
 389 .    Va volume
 390 replaces the default rendered volume as dictated by the manual section.
 391 .   It \&TP
 392 Begin a paragraph where the head, if exceeding the indentation width, is
 393 followed by a newline; if not, the body follows on the same line after a
 394 buffer to the indentation width.  Subsequent output lines are indented.
 395 .    Pp
 396 The indentation width may be set as follows:
 397 .    Bd -literal -offset indent
 398 \&.TP [width]
 399 .    Ed
 400 .    Pp
 401 Where
 402 .    Va width
 403 must be a properly-formed numeric width.  If
 404 .    Va width
 405 is specified, it's saved for later paragraph left-margins; if
 406 unspecified, the saved or default width is used.
 407 .   It \&br
 408 Breaks the current line.  Consecutive invocations have no further effect.
 409 .   It \&fi
 410 End literal mode begun by
 411 .    Sq \&nf .
 412 .   It \&i
 413 Italicise arguments.  If no arguments are specified, all subsequent text
 414 is italicised.
 415 .   It \&na
 416 No alignment to the right margin.
 417 .   It \&nf
 418 Begin literal mode: all subsequent free-form lines have their end of
 419 line boundaries preserved.  May be ended by
 420 .    Sq \&fi .
 421 .   It \&r
 422 Fonts and styles (bold face, italics) reset to roman (default font).
 423 .   It \&sp
 424 Insert n spaces, where n is the macro's positive numeric argument.  If
 425 0, this is equivalent to the
 426 .    Sq br
 427 macro.
 428 .  El
 429 .
 430 .
 431 .Sh COMPATIBILITY
 432 This section documents compatibility with other roff implementations, at
 433 this time limited to
 434 . Xr groff 1 .
 435 . Bl -hyphen
 436 .  It
 437 In quoted literals, groff allowed pair-wise double-quotes to produce a
 438 standalone double-quote in formatted output.  This idiosyncratic
 439 behaviour is no longer applicable.
 440 .  It
 441 The
 442 .   Sq \&sp
 443 macro does not accept negative numbers.
 444 .  It
 445 Blocks of whitespace are stripped from both macro and free-form text
 446 lines (except when in literal mode), while groff would retain whitespace
 447 in free-form text lines.
 448 . El
 449 .
 450 .
 451 .Sh SEE ALSO
 452 . Xr mandoc 1 ,
 453 . Xr mandoc_char 7
 454 .
 455 .
 456 .Sh AUTHORS
 457 The
 458 . Nm
 459 reference was written by
 460 . An Kristaps Dzonsons Aq kristaps@kth.se .
 461 .
 462 .
 463 .Sh CAVEATS
 464 Do not use this language.  Use
 465 . Xr mdoc 7 ,
 466 instead.
 467 .