man.7

   1 .\"     $Id: man.7,v 1.31 2009/08/20 11:51:07 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 20 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
 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 generally scoped to the current line, with the body
 181 consisting of zero or more arguments.  If a macro is scoped to the next
 182 line and the line arguments are empty, the next line is used instead,
 183 else the general syntax is used.  Thus:
 184 .  Bd -literal -offset indent
 185 \&.I
 186 foo
 187 .  Ed
 188 .  Pp
 189 is equivalent to
 190 .  Sq \&.I foo .
 191 .\" PARAGRAPH
 192 Consecutive next-line scope invocations are disallowed.
 193 .  Bd -literal -offset indent
 194 \&.YO \(lBbody...\(rB
 195 \(lBbody...\(rB
 196 .  Ed
 197 .  Pp
 198 It is considered an error when next-line scope is open at the end of
 199 file.
 200 .  Pp
 201 .  Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
 202 .   It Em Macro Ta Em Arguments Ta Em Scope
 203 .   It    B     Ta    n         Ta    next-line
 204 .   It    BI    Ta    n         Ta    current
 205 .   It    BR    Ta    n         Ta    current
 206 .   It    DT    Ta    0         Ta    current
 207 .   It    I     Ta    n         Ta    next-line
 208 .   It    IB    Ta    n         Ta    current
 209 .   It    IR    Ta    n         Ta    current
 210 .   It    R     Ta    n         Ta    next-line
 211 .   It    RB    Ta    n         Ta    current
 212 .   It    RI    Ta    n         Ta    current
 213 .   It    SB    Ta    n         Ta    next-line
 214 .   It    SM    Ta    n         Ta    next-line
 215 .   It    TH    Ta    >1, <6    Ta    current
 216 .   It    br    Ta    0         Ta    current
 217 .   It    fi    Ta    0         Ta    current
 218 .   It    i     Ta    n         Ta    current
 219 .   It    na    Ta    0         Ta    current
 220 .   It    nf    Ta    0         Ta    current
 221 .   It    r     Ta    0         Ta    current
 222 .   It    sp    Ta    1         Ta    current
 223 .  El
 224 .  Pp
 225 The
 226 .  Sq RS ,
 227 .  Sq RE ,
 228 .  Sq br ,
 229 .  Sq fi ,
 230 .  Sq i ,
 231 .  Sq na ,
 232 .  Sq nf ,
 233 .  Sq r ,
 234 and
 235 .  Sq sp
 236 macros aren't historically part of
 237 .  Nm
 238 and should not be used.  They're included for compatibility.
 239 .
 240 .
 241 . Ss Block Macros
 242 Block macros are comprised of a head and body.  Like for in-line macros,
 243 the head is scoped to the current line and, in one circumstance, the
 244 next line; the body is scoped to subsequent lines and is closed out by a
 245 subsequent block macro invocation.
 246 .  Bd -literal -offset indent
 247 \&.YO \(lBhead...\(rB
 248 \(lBhead...\(rB
 249 \(lBbody...\(rB
 250 .  Ed
 251 .  Pp
 252 The closure of body scope may be to the section, where a macro is closed
 253 by
 254 .  Sq SH ;
 255 sub-section, closed by a section or
 256 .  Sq SS ;
 257 part, closed by a section, sub-section, or
 258 .  Sq RE ;
 259 or paragraph, closed by a section, sub-section, part,
 260 .  Sq HP ,
 261 .  Sq IP ,
 262 .  Sq LP ,
 263 .  Sq P ,
 264 .  Sq PP ,
 265 or
 266 .  Sq TP .
 267 No closure refers to an explicit block closing macro.
 268 .  Pp
 269 It is considered an error when part or next-line scope is open at the
 270 end of file.
 271 .  Pp
 272 .  Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
 273 .   It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
 274 .   It   HP     Ta    <2        Ta    current    Ta    paragraph
 275 .   It   IP     Ta    <3        Ta    current    Ta    paragraph
 276 .   It   LP     Ta    0         Ta    current    Ta    paragraph
 277 .   It   P      Ta    0         Ta    current    Ta    paragraph
 278 .   It   PP     Ta    0         Ta    current    Ta    paragraph
 279 .   It   RE     Ta    0         Ta    current    Ta    none
 280 .   It   RS     Ta    1         Ta    current    Ta    part
 281 .   It   SH     Ta    >0        Ta    current    Ta    section
 282 .   It   SS     Ta    >0        Ta    current    Ta    sub-section
 283 .   It   TP     Ta    n         Ta    next-line  Ta    paragraph
 284 .  El
 285 .  Pp
 286 If a block macro is next-line scoped, it may only be followed by in-line
 287 macros (excluding
 288 .  Sq DT ,
 289 .  Sq TH ,
 290 .  Sq br ,
 291 .  Sq na ,
 292 .  Sq sp ,
 293 .  Sq nf ,
 294 and
 295 .  Sq fi ) .
 296 .
 297 .
 298 .Sh REFERENCE
 299 This section is a canonical reference to all macros, arranged
 300 alphabetically.  For the scoping of individual macros, see
 301 . Sx MACRO SYNTAX .
 302 .
 303 .
 304 . Ss Definitions
 305 In this reference, a numerical width may be either a standalone natural
 306 number (such as 3, 4, 10, etc.) or a natural number followed by a width
 307 multiplier
 308 .  Qq n ,
 309 corresponding to the width of the formatted letter n, or
 310 .  Qq m ,
 311 corresponding to the width of the formatted letter m.  The latter is the
 312 default, if unspecified.  Thus,
 313 .  Bd -literal -offset indent
 314 \&.HP 12n
 315 .  Ed
 316 .  Pp
 317 indicates an offset of 12
 318 .  Qq n
 319 .  Ns -sized
 320 letters.
 321 .
 322 .
 323 . Ss Macro Reference
 324 .  Bl -tag -width Ds
 325 .   It B
 326 Text is rendered in bold face.
 327 .   It BI
 328 Text is rendered alternately in bold face and italic.  Thus,
 329 .    Sq .BI this word and that
 330 causes
 331 .    Sq this
 332 and
 333 .    Sq and
 334 to render in bold face, while
 335 .    Sq word
 336 and
 337 .    Sq that
 338 render in italics.  Whitespace between arguments is omitted in output.
 339 .   It BR
 340 Text is rendered alternately in bold face and roman (the default font).
 341 Whitespace between arguments is omitted in output.
 342 .   It DT
 343 Re-set the tab spacing to 0.5 inches.
 344 .   It HP
 345 Begin a paragraph whose initial output line is left-justified, but
 346 subsequent output lines are indented, with the following syntax:
 347 .    Bd -literal -offset indent
 348 \&.HP [width]
 349 .    Ed
 350 .    Pp
 351 If
 352 .    Va width
 353 is specified, it's saved for later paragraph left-margins; if
 354 unspecified, the saved or default width is used.
 355 .   It I
 356 Text is rendered in italics.
 357 .   It IB
 358 Text is rendered alternately in italics and bold face.  Whitespace
 359 between arguments is omitted in output.
 360 .   It IP
 361 Begin a paragraph with the following syntax:
 362 .    Bd -literal -offset indent
 363 \&.IP [head [width]]
 364 .    Ed
 365 .    Pp
 366 This follows the behaviour of the
 367 .    Sq TP
 368 except for the macro syntax (all arguments on the line, instead of
 369 having next-line scope).  If
 370 .    Va width
 371 is specified, it's saved for later paragraph left-margins; if
 372 unspecified, the saved or default width is used.
 373 .   It IR
 374 Text is rendered alternately in italics and roman (the default font).
 375 Whitespace between arguments is omitted in output.
 376 .   It LP, P, PP
 377 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 378 subsequent paragraph, sub-section, section, or end of file.  The saved
 379 paragraph left-margin width is re-set to the default.
 380 .   It R
 381 Text is rendered in roman (the default font).
 382 .   It RB
 383 Text is rendered alternately in roman (the default font) and bold face.
 384 Whitespace between arguments is omitted in output.
 385 .   It RE
 386 Explicitly close out the scope of a prior
 387 .    Sq RS .
 388 .   It RI
 389 Text is rendered alternately in roman (the default font) and italics.
 390 Whitespace between arguments is omitted in output.
 391 .   It RS
 392 Begin a part setting the left margin.  The left margin controls the
 393 offset, following an initial indentation, to un-indented text such as
 394 that of
 395 .    Sq PP .
 396 The width may be specified as following:
 397 .    Bd -literal -offset indent
 398 \&.RS [width]
 399 .    Ed
 400 .    Pp
 401 If
 402 .    Va width
 403 is not specified, the saved or default width is used.
 404 .   It SB
 405 Text is rendered in small size (one point smaller than the default font)
 406 bold face.
 407 .   It SH
 408 Begin a section.  The scope of a section is only closed by another
 409 section or the end of file.  The paragraph left-margin width is re-set
 410 to the default.
 411 .   It SM
 412 Text is rendered in small size (one point smaller than the default
 413 font).
 414 .   It SS
 415 Begin a sub-section.  The scope of a sub-section is closed by a
 416 subsequent sub-section, section, or end of file.  The paragraph
 417 left-margin width is re-set to the default.
 418 .   It TH
 419 Sets the title of the manual page with the following syntax:
 420 .    Bd -literal -offset indent
 421 \&.TH title section [date [source [volume]]]
 422 .    Ed
 423 .    Pp
 424 At least the
 425 .    Va title
 426 and
 427 .    Va section
 428 arguments must be provided.  The
 429 .    Va date
 430 argument should be formatted as
 431 .    Qq %b [%d] %Y
 432 format, described in
 433 .    Xr strptime 3 .
 434 The
 435 .    Va source
 436 string specifies the organisation providing the utility.  The
 437 .    Va volume
 438 replaces the default rendered volume as dictated by the manual section.
 439 .   It TP
 440 Begin a paragraph where the head, if exceeding the indentation width, is
 441 followed by a newline; if not, the body follows on the same line after a
 442 buffer to the indentation width.  Subsequent output lines are indented.
 443 .    Pp
 444 The indentation width may be set as follows:
 445 .    Bd -literal -offset indent
 446 \&.TP [width]
 447 .    Ed
 448 .    Pp
 449 Where
 450 .    Va width
 451 must be a properly-formed numeric width.  If
 452 .    Va width
 453 is specified, it's saved for later paragraph left-margins; if
 454 unspecified, the saved or default width is used.
 455 .   It br
 456 Breaks the current line.  Consecutive invocations have no further effect.
 457 .   It fi
 458 End literal mode begun by
 459 .    Sq nf .
 460 .   It i
 461 Italicise arguments.  If no arguments are specified, all subsequent text
 462 is italicised.
 463 .   It na
 464 Don't alignment the right margin.
 465 .   It nf
 466 Begin literal mode: all subsequent free-form lines have their end of
 467 line boundaries preserved.  May be ended by
 468 .    Sq fi .
 469 .   It r
 470 Fonts and styles (bold face, italics) reset to roman (default font).
 471 .   It sp
 472 Insert n spaces, where n is the macro's positive numeric argument.  If
 473 0, this is equivalent to the
 474 .    Sq br
 475 macro.
 476 .  El
 477 .
 478 .
 479 .Sh COMPATIBILITY
 480 This section documents compatibility with other roff implementations, at
 481 this time limited to
 482 . Xr groff 1 .
 483 . Bl -hyphen
 484 .  It
 485 In quoted literals, groff allowed pair-wise double-quotes to produce a
 486 standalone double-quote in formatted output.  This idiosyncratic
 487 behaviour is no longer applicable.
 488 .  It
 489 The
 490 .   Sq sp
 491 macro does not accept negative numbers.
 492 .  It
 493 Blocks of whitespace are stripped from both macro and free-form text
 494 lines (except when in literal mode), while groff would retain whitespace
 495 in free-form text lines.
 496 . El
 497 .
 498 .
 499 .Sh SEE ALSO
 500 . Xr mandoc 1 ,
 501 . Xr mandoc_char 7
 502 .
 503 .
 504 .Sh AUTHORS
 505 The
 506 . Nm
 507 reference was written by
 508 . An Kristaps Dzonsons Aq kristaps@kth.se .
 509 .
 510 .
 511 .Sh CAVEATS
 512 Do not use this language.  Use
 513 . Xr mdoc 7 ,
 514 instead.
 515 .