usr.bin/mandoc/man.7

   1 .\"     $Id: man.7,v 1.13 2009/10/27 21:40:07 schwarze 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 October 29, 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 .
  35 .Pp
  36 .Bf -emphasis
  37 Do not use
  38 .Nm
  39 to write your manuals.
  40 .Ef
  41 Use the
  42 .Xr mdoc 7
  43 language, instead.
  44 .
  45 .Pp
  46 An
  47 .Nm
  48 document follows simple rules:  lines beginning with the control
  49 character
  50 .Sq \&.
  51 are parsed for macros.  Other lines are interpreted within the scope of
  52 prior macros:
  53 .Bd -literal -offset indent
  54 \&.SH Macro lines change control state.
  55 Other lines are interpreted within the current state.
  56 .Ed
  57 .
  58 .
  59 .Sh INPUT ENCODING
  60 .Nm
  61 documents may contain only graphable 7-bit ASCII characters, the
  62 space character, and the tabs character.  All manuals must have
  63 .Ux
  64 line termination.
  65 .
  66 .Pp
  67 Blank lines are acceptable; where found, the output will assert a
  68 vertical space.
  69 .
  70 .Pp
  71 The
  72 .Sq \ec
  73 escape is common in historical
  74 .Nm
  75 documents; if encountered at the end of a word, it ensures that the
  76 subsequent word isn't off-set by whitespace.
  77 .
  78 .
  79 .Ss Comments
  80 Text following a
  81 .Sq \e\*" ,
  82 whether in a macro or free-form text line, is ignored to the end of
  83 line.  A macro line with only a control character and comment escape,
  84 .Sq \&.\e" ,
  85 is also ignored.  Macro lines with only a control charater and
  86 optionally whitespace are stripped from input.
  87 .
  88 .
  89 .Ss Special Characters
  90 Special characters may occur in both macro and free-form lines.
  91 Sequences begin with the escape character
  92 .Sq \e
  93 followed by either an open-parenthesis
  94 .Sq \&(
  95 for two-character sequences; an open-bracket
  96 .Sq \&[
  97 for n-character sequences (terminated at a close-bracket
  98 .Sq \&] ) ;
  99 or a single one-character sequence.  See
 100 .Xr mandoc_char 7
 101 for a complete list.  Examples include
 102 .Sq \e(em
 103 .Pq em-dash
 104 and
 105 .Sq \ee
 106 .Pq back-slash .
 107 .
 108 .
 109 .Ss Text Decoration
 110 Terms may be text-decorated using the
 111 .Sq \ef
 112 escape followed by an indicator: B (bold), I, (italic), or P and R
 113 (Roman, or reset).
 114 .
 115 .
 116 .Ss Whitespace
 117 Unless specifically escaped, consecutive blocks of whitespace are pruned
 118 from input.  These are later re-added, if applicable, by a front-end
 119 utility such as
 120 .Xr mandoc 1 .
 121 .
 122 .Ss Scaling Widths
 123 Many macros support scaled widths for their arguments, such as
 124 stipulating a two-inch paragraph indentation with the following:
 125 .Bd -literal -offset indent
 126 \&.HP 2i
 127 .Ed
 128 .
 129 .Pp
 130 The syntax for scaled widths is
 131 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
 132 where a decimal must be preceded or proceeded by at least one digit.
 133 Negative numbers, while accepted, are truncated to zero.  The following
 134 scaling units are accepted:
 135 .
 136 .Pp
 137 .Bl -tag -width Ds -offset indent -compact
 138 .It c
 139 centimetre
 140 .It i
 141 inch
 142 .It P
 143 pica (~1/6 inch)
 144 .It p
 145 point (~1/72 inch)
 146 .It f
 147 synonym for
 148 .Sq u
 149 .It v
 150 default vertical span
 151 .It m
 152 width of rendered
 153 .Sq m
 154 .Pq em
 155 character
 156 .It n
 157 width of rendered
 158 .Sq n
 159 .Pq en
 160 character
 161 .It u
 162 default horizontal span
 163 .It M
 164 mini-em (~1/100 em)
 165 .El
 166 .Pp
 167 Using anything other than
 168 .Sq m ,
 169 .Sq n ,
 170 .Sq u ,
 171 or
 172 .Sq v
 173 is necessarily non-portable across output media.  See
 174 .Sx COMPATIBILITY .
 175 .
 176 .Pp
 177 If a scaling unit is not provided, the numerical value is interpreted
 178 under the default rules of
 179 .Sq v
 180 for vertical spaces and
 181 .Sq u
 182 for horizontal ones.
 183 .Em Note :
 184 this differs from
 185 .Xr mdoc 7 ,
 186 which, if a unit is not provided, will instead interpret the string as
 187 literal text.
 188 .
 189 .
 190 .Sh MANUAL STRUCTURE
 191 Each
 192 .Nm
 193 document must contain contains at least the
 194 .Sx \&TH
 195 macro describing the document's section and title.  It may occur
 196 anywhere in the document, although conventionally, it appears as the
 197 first macro.
 198 .
 199 .Pp
 200 Beyond
 201 .Sx \&TH ,
 202 at least one macro or text node must appear in the document.  Documents
 203 are generally structured as follows:
 204 .Bd -literal -offset indent
 205 \&.TH FOO 1 "13 Aug 2009"
 206 \&.
 207 \&.SH NAME
 208 \efBfoo\efR \e(en a description goes here
 209 \&.\e\*q The next is for sections 2 & 3 only.
 210 \&.\e\*q .SH LIBRARY
 211 \&.
 212 \&.SH SYNOPSIS
 213 \efBfoo\efR [\efB\e-options\efR] arguments...
 214 \&.
 215 \&.SH DESCRIPTION
 216 The \efBfoo\efR utility processes files...
 217 \&.
 218 \&.\e\*q .SH IMPLEMENTATION NOTES
 219 \&.\e\*q The next is for sections 1 & 8 only.
 220 \&.\e\*q .SH EXIT STATUS
 221 \&.\e\*q The next is for sections 2, 3, & 9 only.
 222 \&.\e\*q .SH RETURN VALUES
 223 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
 224 \&.\e\*q .SH ENVIRONMENT
 225 \&.\e\*q .SH FILES
 226 \&.\e\*q .SH EXAMPLES
 227 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 228 \&.\e\*q .SH DIAGNOSTICS
 229 \&.\e\*q The next is for sections 2, 3, & 9 only.
 230 \&.\e\*q .SH ERRORS
 231 \&.\e\*q .SH SEE ALSO
 232 \&.\e\*q \efBbar\efR(1)
 233 \&.\e\*q .SH STANDARDS
 234 \&.\e\*q .SH HISTORY
 235 \&.\e\*q .SH AUTHORS
 236 \&.\e\*q .SH CAVEATS
 237 \&.\e\*q .SH BUGS
 238 \&.\e\*q .SH SECURITY CONSIDERATIONS
 239 .Ed
 240 .Pp
 241 The sections in a
 242 .Nm
 243 document are conventionally ordered as they appear above.  Sections
 244 should be composed as follows:
 245 .Bl -tag -width Ds -offset Ds
 246 .It NAME
 247 The name(s) and a short description of the documented material.  The
 248 syntax for this is generally as follows:
 249 .Pp
 250 .D1 \efBname\efR \e(en description
 251 .It LIBRARY
 252 The name of the library containing the documented material, which is
 253 assumed to be a function in a section 2 or 3 manual.  For functions in
 254 the C library, this may be as follows:
 255 .Pp
 256 .D1 Standard C Library (libc, -lc)
 257 .It SYNOPSIS
 258 Documents the utility invocation syntax, function call syntax, or device
 259 configuration.
 260 .Pp
 261 For the first, utilities (sections 1, 6, and 8), this is
 262 generally structured as follows:
 263 .Pp
 264 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
 265 .Pp
 266 For the second, function calls (sections 2, 3, 9):
 267 .Pp
 268 .D1 \. Ns Sx \&B No char *name(char *\efIarg\efR);
 269 .Pp
 270 And for the third, configurations (section 4):
 271 .Pp
 272 .D1 \. Ns Sx \&B No name* at cardbus ? function ?
 273 .Pp
 274 Manuals not in these sections generally don't need a SYNOPSIS.
 275 .It DESCRIPTION
 276 This expands upon the brief, one-line description in NAME.  It usually
 277 contains a break-down of the options (if documenting a command).
 278 .It IMPLEMENTATION NOTES
 279 Implementation-specific notes should be kept here.  This is useful when
 280 implementing standard functions that may have side effects or notable
 281 algorithmic implications.
 282 .It EXIT STATUS
 283 .It RETURN VALUES
 284 .It ENVIRONMENT
 285 .It FILES
 286 .It EXAMPLES
 287 .It DIAGNOSTICS
 288 .It ERRORS
 289 .It SEE ALSO
 290 .It STANDARDS
 291 .It HISTORY
 292 .It AUTHORS
 293 .It CAVEATS
 294 .It BUGS
 295 .It SECURITY CONSIDERATIONS
 296 .El
 297 .
 298 .
 299 .Sh MACRO SYNTAX
 300 Macros are one to three three characters in length and begin with a
 301 control character ,
 302 .Sq \&. ,
 303 at the beginning of the line.  An arbitrary amount of whitespace may
 304 sit between the control character and the macro name.  Thus, the
 305 following are equivalent:
 306 .Bd -literal -offset indent
 307 \&.PP
 308 \&.\ \ \ PP
 309 .Ed
 310 .
 311 .Pp
 312 The
 313 .Nm
 314 macros are classified by scope: line scope or block scope.  Line
 315 macros are only scoped to the current line (and, in some situations,
 316 the subsequent line).  Block macros are scoped to the current line and
 317 subsequent lines until closed by another block macro.
 318 .
 319 .
 320 .Ss Line Macros
 321 Line macros are generally scoped to the current line, with the body
 322 consisting of zero or more arguments.  If a macro is scoped to the next
 323 line and the line arguments are empty, the next line is used instead,
 324 else the general syntax is used.  Thus:
 325 .Bd -literal -offset indent
 326 \&.I
 327 foo
 328 .Ed
 329 .
 330 .Pp
 331 is equivalent to
 332 .Sq \&.I foo .
 333 If next-line macros are invoked consecutively, only the last is used.
 334 If a next-line macro is proceded by a block macro, it is ignored.
 335 .Bd -literal -offset indent
 336 \&.YO \(lBbody...\(rB
 337 \(lBbody...\(rB
 338 .Ed
 339 .
 340 .Pp
 341 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
 342 .It Em Macro Ta Em Arguments Ta Em Scope
 343 .It Sx \&B   Ta    n         Ta    next-line
 344 .It Sx \&BI  Ta    n         Ta    current
 345 .It Sx \&BR  Ta    n         Ta    current
 346 .It Sx \&DT  Ta    0         Ta    current
 347 .It Sx \&I   Ta    n         Ta    next-line
 348 .It Sx \&IB  Ta    n         Ta    current
 349 .It Sx \&IR  Ta    n         Ta    current
 350 .It Sx \&PD  Ta    n         Ta    current
 351 .It Sx \&R   Ta    n         Ta    next-line
 352 .It Sx \&RB  Ta    n         Ta    current
 353 .It Sx \&RI  Ta    n         Ta    current
 354 .It Sx \&SB  Ta    n         Ta    next-line
 355 .It Sx \&SM  Ta    n         Ta    next-line
 356 .It Sx \&TH  Ta    >1, <6    Ta    current
 357 .It Sx \&UC  Ta    n         Ta    current
 358 .It Sx \&br  Ta    0         Ta    current
 359 .It Sx \&fi  Ta    0         Ta    current
 360 .It Sx \&i   Ta    n         Ta    current
 361 .It Sx \&na  Ta    0         Ta    current
 362 .It Sx \&nf  Ta    0         Ta    current
 363 .It Sx \&r   Ta    0         Ta    current
 364 .It Sx \&sp  Ta    1         Ta    current
 365 .El
 366 .
 367 .Pp
 368 The
 369 .Sx \&PD ,
 370 .Sx \&RS ,
 371 .Sx \&RE ,
 372 .Sx \&UC ,
 373 .Sx \&br ,
 374 .Sx \&fi ,
 375 .Sx \&i ,
 376 .Sx \&na ,
 377 .Sx \&nf ,
 378 .Sx \&r ,
 379 and
 380 .Sx \&sp
 381 macros should not be used.  They're included for compatibility.
 382 .
 383 .
 384 .Ss Block Macros
 385 Block macros are comprised of a head and body.  Like for in-line macros,
 386 the head is scoped to the current line and, in one circumstance, the
 387 next line; the body is scoped to subsequent lines and is closed out by a
 388 subsequent block macro invocation.
 389 .Bd -literal -offset indent
 390 \&.YO \(lBhead...\(rB
 391 \(lBhead...\(rB
 392 \(lBbody...\(rB
 393 .Ed
 394 .
 395 .Pp
 396 The closure of body scope may be to the section, where a macro is closed
 397 by
 398 .Sx \&SH ;
 399 sub-section, closed by a section or
 400 .Sx \&SS ;
 401 part, closed by a section, sub-section, or
 402 .Sx \&RE ;
 403 or paragraph, closed by a section, sub-section, part,
 404 .Sx \&HP ,
 405 .Sx \&IP ,
 406 .Sx \&LP ,
 407 .Sx \&P ,
 408 .Sx \&PP ,
 409 or
 410 .Sx \&TP .
 411 No closure refers to an explicit block closing macro.
 412 .
 413 .Pp
 414 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
 415 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
 416 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph
 417 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph
 418 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph
 419 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph
 420 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph
 421 .It Sx \&RE  Ta    0         Ta    current    Ta    none
 422 .It Sx \&RS  Ta    1         Ta    current    Ta    part
 423 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section
 424 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section
 425 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph
 426 .El
 427 .
 428 .Pp
 429 If a block macro is next-line scoped, it may only be followed by in-line
 430 macros (excluding
 431 .Sx \&DT ,
 432 .Sx \&PD ,
 433 .Sx \&TH ,
 434 .Sx \&UC ,
 435 .Sx \&br ,
 436 .Sx \&na ,
 437 .Sx \&sp ,
 438 .Sx \&nf ,
 439 and
 440 .Sx \&fi ) .
 441 .
 442 .
 443 .Sh REFERENCE
 444 This section is a canonical reference to all macros, arranged
 445 alphabetically.  For the scoping of individual macros, see
 446 .Sx MACRO SYNTAX .
 447 .
 448 .Ss \&B
 449 Text is rendered in bold face.
 450 .Ss \&BI
 451 Text is rendered alternately in bold face and italic.  Thus,
 452 .Sq .BI this word and that
 453 causes
 454 .Sq this
 455 and
 456 .Sq and
 457 to render in bold face, while
 458 .Sq word
 459 and
 460 .Sq that
 461 render in italics.  Whitespace between arguments is omitted in output.
 462 .Ss \&BR
 463 Text is rendered alternately in bold face and roman (the default font).
 464 Whitespace between arguments is omitted in output.
 465 .Ss \&DT
 466 Has no effect.  Included for compatibility.
 467 .Ss \&HP
 468 Begin a paragraph whose initial output line is left-justified, but
 469 subsequent output lines are indented, with the following syntax:
 470 .Bd -literal -offset indent
 471 \&.HP [width]
 472 .Ed
 473 .
 474 .Pp
 475 If scaling width
 476 .Va width
 477 is specified, it's saved for later paragraph left-margins; if
 478 unspecified, the saved or default width is used.
 479 .Ss \&I
 480 Text is rendered in italics.
 481 .Ss \&IB
 482 Text is rendered alternately in italics and bold face.  Whitespace
 483 between arguments is omitted in output.
 484 .Ss \&IP
 485 Begin a paragraph with the following syntax:
 486 .Bd -literal -offset indent
 487 \&.IP [head [width]]
 488 .Ed
 489 .
 490 .Pp
 491 This follows the behaviour of the
 492 .Sx \&TP
 493 except for the macro syntax (all arguments on the line, instead of
 494 having next-line scope).  If
 495 .Va width
 496 is specified, it's saved for later paragraph left-margins; if
 497 unspecified, the saved or default width is used.
 498 .Ss \&IR
 499 Text is rendered alternately in italics and roman (the default font).
 500 Whitespace between arguments is omitted in output.
 501 .Ss \&LP
 502 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 503 subsequent paragraph, sub-section, section, or end of file.  The saved
 504 paragraph left-margin width is re-set to the default.
 505 .Ss \&P
 506 Synonym for
 507 .Sx \&LP .
 508 .Ss \&PP
 509 Synonym for
 510 .Sx \&LP .
 511 .Ss \&R
 512 Text is rendered in roman (the default font).
 513 .Ss \&RB
 514 Text is rendered alternately in roman (the default font) and bold face.
 515 Whitespace between arguments is omitted in output.
 516 .Ss \&RE
 517 Explicitly close out the scope of a prior
 518 .Sx \&RS .
 519 .Ss \&RI
 520 Text is rendered alternately in roman (the default font) and italics.
 521 Whitespace between arguments is omitted in output.
 522 .Ss \&RS
 523 Begin a part setting the left margin.  The left margin controls the
 524 offset, following an initial indentation, to un-indented text such as
 525 that of
 526 .Sx \&PP .
 527 A scaling width may be specified as following:
 528 .Bd -literal -offset indent
 529 \&.RS [width]
 530 .Ed
 531 .
 532 .Pp
 533 If
 534 .Va width
 535 is not specified, the saved or default width is used.
 536 .Ss \&SB
 537 Text is rendered in small size (one point smaller than the default font)
 538 bold face.
 539 .Ss \&SH
 540 Begin a section.  The scope of a section is only closed by another
 541 section or the end of file.  The paragraph left-margin width is re-set
 542 to the default.
 543 .Ss \&SM
 544 Text is rendered in small size (one point smaller than the default
 545 font).
 546 .Ss \&SS
 547 Begin a sub-section.  The scope of a sub-section is closed by a
 548 subsequent sub-section, section, or end of file.  The paragraph
 549 left-margin width is re-set to the default.
 550 .Ss \&TH
 551 Sets the title of the manual page with the following syntax:
 552 .Bd -literal -offset indent
 553 \&.TH title section [date [source [volume]]]
 554 .Ed
 555 .
 556 .Pp
 557 At least the
 558 .Va title
 559 and
 560 .Va section
 561 arguments must be provided.  The
 562 .Va date
 563 argument should be formatted as
 564 .Qq %b [%d] %Y
 565 format, described in
 566 .Xr strptime 3 .
 567 The
 568 .Va source
 569 string specifies the organisation providing the utility.  The
 570 .Va volume
 571 replaces the default rendered volume as dictated by the manual section.
 572 .Ss \&TP
 573 Begin a paragraph where the head, if exceeding the indentation width, is
 574 followed by a newline; if not, the body follows on the same line after a
 575 buffer to the indentation width.  Subsequent output lines are indented.
 576 .
 577 .Pp
 578 The indentation scaling width may be set as follows:
 579 .Bd -literal -offset indent
 580 \&.TP [width]
 581 .Ed
 582 .
 583 .Pp
 584 If
 585 .Va width
 586 is specified, it's saved for later paragraph left-margins; if
 587 unspecified, the saved or default width is used.
 588 .Ss \&PD
 589 Has no effect.  Included for compatibility.
 590 .Ss \&UC
 591 Has no effect.  Included for compatibility.
 592 .Ss \&br
 593 Breaks the current line.  Consecutive invocations have no further effect.
 594 .Ss \&fi
 595 End literal mode begun by
 596 .Sx \&nf .
 597 .Ss \&i
 598 Italicise arguments.  If no arguments are specified, all subsequent text
 599 is italicised.
 600 .Ss \&na
 601 Don't align to the right margin.
 602 .Ss \&nf
 603 Begin literal mode: all subsequent free-form lines have their end of
 604 line boundaries preserved.  May be ended by
 605 .Sx \&fi .
 606 .Ss \&r
 607 Fonts and styles (bold face, italics) reset to roman (default font).
 608 .Ss \&sp
 609 Insert n spaces, where n is the macro's positive numeric argument.  If
 610 0, this is equivalent to the
 611 .Sx \&br
 612 macro.
 613 .
 614 .
 615 .Sh COMPATIBILITY
 616 This section documents compatibility with other roff implementations, at
 617 this time limited to
 618 .Xr groff 1 .
 619 .Bl -hyphen
 620 .It
 621 In quoted literals, groff allowed pair-wise double-quotes to produce a
 622 standalone double-quote in formatted output.  This idiosyncratic
 623 behaviour is no longer applicable.
 624 .It
 625 The
 626 .Sq sp
 627 macro does not accept negative numbers.
 628 .It
 629 Blocks of whitespace are stripped from both macro and free-form text
 630 lines (except when in literal mode), while groff would retain whitespace
 631 in free-form text lines.
 632 .El
 633 .
 634 .
 635 .Sh SEE ALSO
 636 .Xr mandoc 1 ,
 637 .Xr mandoc_char 7
 638 .
 639 .
 640 .Sh AUTHORS
 641 The
 642 .Nm
 643 reference was written by
 644 .An Kristaps Dzonsons Aq kristaps@kth.se .
 645 .
 646 .
 647 .Sh CAVEATS
 648 Do not use this language.  Use
 649 .Xr mdoc 7 ,
 650 instead.
 651 .