1 .\"
   2 .\" Permission to use, copy, modify, and distribute this software for any
   3 .\" purpose with or without fee is hereby granted, provided that the above
   4 .\" copyright notice and this permission notice appear in all copies.
   5 .\"
   6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13 .\"
  14 .\"
  15 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16 .\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
  17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
  18 .\"
  19 .Dd Jan 3, 2012
  20 .Dt MAN 5
  21 .Os
  22 .Sh NAME
  23 .Nm man
  24 .Nd legacy formatting language for manual pages
  25 .Sh DESCRIPTION
  26 Traditionally, the
  27 .Nm man
  28 language has been used to write
  29 .Ux
  30 manuals for the
  31 .Xr man 1
  32 utility.
  33 It supports limited control of presentational details like fonts,
  34 indentation and spacing.
  35 This reference document describes the structure of manual pages
  36 and the syntax and usage of the man language.
  37 .Pp
  38 .Bf -emphasis
  39 Do not use
  40 .Nm
  41 to write your manuals:
  42 .Ef
  43 It lacks support for semantic markup.
  44 Use the
  45 .Xr mdoc 5
  46 language, instead.
  47 .Pp
  48 In a
  49 .Nm
  50 document, lines beginning with the control character
  51 .Sq \&.
  52 are called
  53 .Dq macro lines .
  54 The first word is the macro name.
  55 It usually consists of two capital letters.
  56 For a list of available macros, see
  57 .Sx MACRO OVERVIEW .
  58 The words following the macro name are arguments to the macro.
  59 .Pp
  60 Lines not beginning with the control character are called
  61 .Dq text lines .
  62 They provide free-form text to be printed; the formatting of the text
  63 depends on the respective processing context:
  64 .Bd -literal -offset indent
  65 \&.SH Macro lines change control state.
  66 Text lines are interpreted within the current state.
  67 .Ed
  68 .Pp
  69 Many aspects of the basic syntax of the
  70 .Nm
  71 language are based on the
  72 .Xr roff 5
  73 language; see the
  74 .Em LANGUAGE SYNTAX
  75 and
  76 .Em MACRO SYNTAX
  77 sections in the
  78 .Xr roff 5
  79 manual for details, in particular regarding
  80 comments, escape sequences, whitespace, and quoting.
  81 .Sh MANUAL STRUCTURE
  82 Each
  83 .Nm
  84 document must contain the
  85 .Sx \&TH
  86 macro describing the document's section and title.
  87 It may occur anywhere in the document, although conventionally it
  88 appears as the first macro.
  89 .Pp
  90 Beyond
  91 .Sx \&TH ,
  92 at least one macro or text line must appear in the document.
  93 .Pp
  94 The following is a well-formed skeleton
  95 .Nm
  96 file for a utility
  97 .Qq progname :
  98 .Bd -literal -offset indent
  99 \&.TH PROGNAME 1 "Oct 10, 2009"
 100 \&.SH NAME
 101 \efBprogname\efR \e(en a description goes here
 102 \&.\e\(dq .SH LIBRARY
 103 \&.\e\(dq For sections 2 & 3 only.
 104 \&.SH SYNOPSIS
 105 \efBprogname\efR [\efB\e-options\efR] arguments...
 106 \&.SH DESCRIPTION
 107 The \efBfoo\efR utility processes files...
 108 \&.\e\(dq .SH IMPLEMENTATION NOTES
 109 \&.\e\(dq .SH RETURN VALUES
 110 \&.\e\(dq For sections 2, 3, & 9 only.
 111 \&.\e\(dq .SH ENVIRONMENT
 112 \&.\e\(dq For sections 1, 1M, 5, & 6 only.
 113 \&.\e\(dq .SH FILES
 114 \&.\e\(dq .SH EXIT STATUS
 115 \&.\e\(dq For sections 1, 1M, & 6 only.
 116 \&.\e\(dq .SH EXAMPLES
 117 \&.\e\(dq .SH DIAGNOSTICS
 118 \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
 119 \&.\e\(dq .SH ERRORS
 120 \&.\e\(dq For sections 2, 3, & 9 only.
 121 \&.\e\(dq .SH SEE ALSO
 122 \&.\e\(dq .BR foo ( 1 )
 123 \&.\e\(dq .SH STANDARDS
 124 \&.\e\(dq .SH HISTORY
 125 \&.\e\(dq .SH AUTHORS
 126 \&.\e\(dq .SH CAVEATS
 127 \&.\e\(dq .SH BUGS
 128 \&.\e\(dq .SH SECURITY CONSIDERATIONS
 129 .Ed
 130 .Pp
 131 The sections in a
 132 .Nm
 133 document are conventionally ordered as they appear above.
 134 Sections should be composed as follows:
 135 .Bl -ohang -offset indent
 136 .It Em NAME
 137 The name(s) and a short description of the documented material.
 138 The syntax for this is generally as follows:
 139 .Pp
 140 .D1 \efBname\efR \e(en description
 141 .It Em LIBRARY
 142 The name of the library containing the documented material, which is
 143 assumed to be a function in a section 2 or 3 manual.
 144 For functions in the C library, this may be as follows:
 145 .Pp
 146 .D1 Standard C Library (libc, -lc)
 147 .It Em SYNOPSIS
 148 Documents the utility invocation syntax, function call syntax, or device
 149 configuration.
 150 .Pp
 151 For the first, utilities (sections 1, 1M, and 6), this is
 152 generally structured as follows:
 153 .Pp
 154 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
 155 .Pp
 156 For the second, function calls (sections 2, 3, 9):
 157 .Pp
 158 .D1 \&.B char *name(char *\efIarg\efR);
 159 .Pp
 160 And for the third, configurations (section 7):
 161 .Pp
 162 .D1 \&.B name* at cardbus ? function ?
 163 .Pp
 164 Manuals not in these sections generally don't need a
 165 .Em SYNOPSIS .
 166 .It Em DESCRIPTION
 167 This expands upon the brief, one-line description in
 168 .Em NAME .
 169 It usually contains a break-down of the options (if documenting a
 170 command).
 171 .It Em IMPLEMENTATION NOTES
 172 Implementation-specific notes should be kept here.
 173 This is useful when implementing standard functions that may have side
 174 effects or notable algorithmic implications.
 175 .It Em RETURN VALUES
 176 This section documents the return values of functions in sections 2, 3, and 9.
 177 .It Em ENVIRONMENT
 178 Documents any usages of environment variables, e.g.,
 179 .Xr environ 5 .
 180 .It Em FILES
 181 Documents files used.
 182 It's helpful to document both the file name and a short description of how
 183 the file is used (created, modified, etc.).
 184 .It Em EXIT STATUS
 185 This section documents the command exit status for
 186 section 1, 6, and 8 utilities.
 187 Historically, this information was described in
 188 .Em DIAGNOSTICS ,
 189 a practise that is now discouraged.
 190 .It Em EXAMPLES
 191 Example usages.
 192 This often contains snippets of well-formed,
 193 well-tested invocations.
 194 Make sure that examples work properly!
 195 .It Em DIAGNOSTICS
 196 Documents error conditions.
 197 This is most useful in section 4 manuals.
 198 Historically, this section was used in place of
 199 .Em EXIT STATUS
 200 for manuals in sections 1, 6, and 8; however, this practise is
 201 discouraged.
 202 .It Em ERRORS
 203 Documents error handling in sections 2, 3, and 9.
 204 .It Em SEE ALSO
 205 References other manuals with related topics.
 206 This section should exist for most manuals.
 207 .Pp
 208 .D1 \&.BR bar \&( 1 \&),
 209 .Pp
 210 Cross-references should conventionally be ordered
 211 first by section, then alphabetically.
 212 .It Em STANDARDS
 213 References any standards implemented or used, such as
 214 .Pp
 215 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
 216 .Pp
 217 If not adhering to any standards, the
 218 .Em HISTORY
 219 section should be used.
 220 .It Em HISTORY
 221 A brief history of the subject, including where support first appeared.
 222 .It Em AUTHORS
 223 Credits to the person or persons who wrote the code and/or documentation.
 224 Authors should generally be noted by both name and email address.
 225 .It Em CAVEATS
 226 Common misuses and misunderstandings should be explained
 227 in this section.
 228 .It Em BUGS
 229 Known bugs, limitations, and work-arounds should be described
 230 in this section.
 231 .It Em SECURITY CONSIDERATIONS
 232 Documents any security precautions that operators should consider.
 233 .El
 234 .Sh MACRO OVERVIEW
 235 This overview is sorted such that macros of similar purpose are listed
 236 together, to help find the best macro for any given purpose.
 237 Deprecated macros are not included in the overview, but can be found
 238 in the alphabetical reference below.
 239 .Ss Page header and footer meta-data
 240 .Bl -column "PP, LP, P" description
 241 .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
 242 .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
 243 .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
 244 .El
 245 .Ss Sections and paragraphs
 246 .Bl -column "PP, LP, P" description
 247 .It Sx SH Ta section header (one line)
 248 .It Sx SS Ta subsection header (one line)
 249 .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
 250 .It Sx RS , RE Ta reset the left margin: Op Ar width
 251 .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
 252 .It Sx TP Ta tagged paragraph: Op Ar width
 253 .It Sx HP Ta hanged paragraph: Op Ar width
 254 .It Sx \&br Ta force output line break in text mode (no arguments)
 255 .It Sx \&sp Ta force vertical space: Op Ar height
 256 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
 257 .It Sx in Ta additional indent: Op Ar width
 258 .El
 259 .Ss Physical markup
 260 .Bl -column "PP, LP, P" description
 261 .It Sx B Ta boldface font
 262 .It Sx I Ta italic font
 263 .It Sx R Ta roman (default) font
 264 .It Sx SB Ta small boldface font
 265 .It Sx SM Ta small roman font
 266 .It Sx BI Ta alternate between boldface and italic fonts
 267 .It Sx BR Ta alternate between boldface and roman fonts
 268 .It Sx IB Ta alternate between italic and boldface fonts
 269 .It Sx IR Ta alternate between italic and roman fonts
 270 .It Sx RB Ta alternate between roman and boldface fonts
 271 .It Sx RI Ta alternate between roman and italic fonts
 272 .El
 273 .Ss Semantic markup
 274 .Bl -column "PP, LP, P" description
 275 .It Sx OP Ta optional arguments
 276 .El
 277 .Sh MACRO REFERENCE
 278 This section is a canonical reference to all macros, arranged
 279 alphabetically.
 280 For the scoping of individual macros, see
 281 .Sx MACRO SYNTAX .
 282 .Ss \&AT
 283 Sets the volume for the footer for compatibility with man pages from
 284 .Tn AT&T UNIX
 285 releases.
 286 The optional arguments specify which release it is from.
 287 .Ss \&B
 288 Text is rendered in bold face.
 289 .Pp
 290 See also
 291 .Sx \&I
 292 and
 293 .Sx \&R .
 294 .Ss \&BI
 295 Text is rendered alternately in bold face and italic.
 296 Thus,
 297 .Sq .BI this word and that
 298 causes
 299 .Sq this
 300 and
 301 .Sq and
 302 to render in bold face, while
 303 .Sq word
 304 and
 305 .Sq that
 306 render in italics.
 307 Whitespace between arguments is omitted in output.
 308 .Pp
 309 Examples:
 310 .Pp
 311 .Dl \&.BI bold italic bold italic
 312 .Pp
 313 The output of this example will be emboldened
 314 .Dq bold
 315 and italicised
 316 .Dq italic ,
 317 with spaces stripped between arguments.
 318 .Pp
 319 See also
 320 .Sx \&IB ,
 321 .Sx \&BR ,
 322 .Sx \&RB ,
 323 .Sx \&RI ,
 324 and
 325 .Sx \&IR .
 326 .Ss \&BR
 327 Text is rendered alternately in bold face and roman (the default font).
 328 Whitespace between arguments is omitted in output.
 329 .Pp
 330 See
 331 .Sx \&BI
 332 for an equivalent example.
 333 .Pp
 334 See also
 335 .Sx \&BI ,
 336 .Sx \&IB ,
 337 .Sx \&RB ,
 338 .Sx \&RI ,
 339 and
 340 .Sx \&IR .
 341 .Ss \&DT
 342 Has no effect.
 343 Included for compatibility.
 344 .Ss \&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 -filled -offset indent
 348 .Pf \. Sx \&HP
 349 .Op Cm width
 350 .Ed
 351 .Pp
 352 The
 353 .Cm width
 354 argument must conform to
 355 .Sx Scaling Widths .
 356 If specified, it's saved for later paragraph left-margins; if unspecified, the
 357 saved or default width is used.
 358 .Pp
 359 See also
 360 .Sx \&IP ,
 361 .Sx \&LP ,
 362 .Sx \&P ,
 363 .Sx \&PP ,
 364 and
 365 .Sx \&TP .
 366 .Ss \&I
 367 Text is rendered in italics.
 368 .Pp
 369 See also
 370 .Sx \&B
 371 and
 372 .Sx \&R .
 373 .Ss \&IB
 374 Text is rendered alternately in italics and bold face.
 375 Whitespace between arguments is omitted in output.
 376 .Pp
 377 See
 378 .Sx \&BI
 379 for an equivalent example.
 380 .Pp
 381 See also
 382 .Sx \&BI ,
 383 .Sx \&BR ,
 384 .Sx \&RB ,
 385 .Sx \&RI ,
 386 and
 387 .Sx \&IR .
 388 .Ss \&IP
 389 Begin an indented paragraph with the following syntax:
 390 .Bd -filled -offset indent
 391 .Pf \. Sx \&IP
 392 .Op Cm head Op Cm width
 393 .Ed
 394 .Pp
 395 The
 396 .Cm width
 397 argument defines the width of the left margin and is defined by
 398 .Sx Scaling Widths .
 399 It's saved for later paragraph left-margins; if unspecified, the saved or
 400 default width is used.
 401 .Pp
 402 The
 403 .Cm head
 404 argument is used as a leading term, flushed to the left margin.
 405 This is useful for bulleted paragraphs and so on.
 406 .Pp
 407 See also
 408 .Sx \&HP ,
 409 .Sx \&LP ,
 410 .Sx \&P ,
 411 .Sx \&PP ,
 412 and
 413 .Sx \&TP .
 414 .Ss \&IR
 415 Text is rendered alternately in italics and roman (the default font).
 416 Whitespace between arguments is omitted in output.
 417 .Pp
 418 See
 419 .Sx \&BI
 420 for an equivalent example.
 421 .Pp
 422 See also
 423 .Sx \&BI ,
 424 .Sx \&IB ,
 425 .Sx \&BR ,
 426 .Sx \&RB ,
 427 and
 428 .Sx \&RI .
 429 .Ss \&LP
 430 Begin an undecorated paragraph.
 431 The scope of a paragraph is closed by a subsequent paragraph,
 432 sub-section, section, or end of file.
 433 The saved paragraph left-margin width is reset to the default.
 434 .Pp
 435 See also
 436 .Sx \&HP ,
 437 .Sx \&IP ,
 438 .Sx \&P ,
 439 .Sx \&PP ,
 440 and
 441 .Sx \&TP .
 442 .Ss \&OP
 443 Optional command-line argument.
 444 This has the following syntax:
 445 .Bd -filled -offset indent
 446 .Pf \. Sx \&OP
 447 .Cm key Op Cm value
 448 .Ed
 449 .Pp
 450 The
 451 .Cm key
 452 is usually a command-line flag and
 453 .Cm value
 454 its argument.
 455 .Ss \&P
 456 Synonym for
 457 .Sx \&LP .
 458 .Pp
 459 See also
 460 .Sx \&HP ,
 461 .Sx \&IP ,
 462 .Sx \&LP ,
 463 .Sx \&PP ,
 464 and
 465 .Sx \&TP .
 466 .Ss \&PP
 467 Synonym for
 468 .Sx \&LP .
 469 .Pp
 470 See also
 471 .Sx \&HP ,
 472 .Sx \&IP ,
 473 .Sx \&LP ,
 474 .Sx \&P ,
 475 and
 476 .Sx \&TP .
 477 .Ss \&R
 478 Text is rendered in roman (the default font).
 479 .Pp
 480 See also
 481 .Sx \&I
 482 and
 483 .Sx \&B .
 484 .Ss \&RB
 485 Text is rendered alternately in roman (the default font) and bold face.
 486 Whitespace between arguments is omitted in output.
 487 .Pp
 488 See
 489 .Sx \&BI
 490 for an equivalent example.
 491 .Pp
 492 See also
 493 .Sx \&BI ,
 494 .Sx \&IB ,
 495 .Sx \&BR ,
 496 .Sx \&RI ,
 497 and
 498 .Sx \&IR .
 499 .Ss \&RE
 500 Explicitly close out the scope of a prior
 501 .Sx \&RS .
 502 The default left margin is restored to the state of the original
 503 .Sx \&RS
 504 invocation.
 505 .Ss \&RI
 506 Text is rendered alternately in roman (the default font) and italics.
 507 Whitespace between arguments is omitted in output.
 508 .Pp
 509 See
 510 .Sx \&BI
 511 for an equivalent example.
 512 .Pp
 513 See also
 514 .Sx \&BI ,
 515 .Sx \&IB ,
 516 .Sx \&BR ,
 517 .Sx \&RB ,
 518 and
 519 .Sx \&IR .
 520 .Ss \&RS
 521 Temporarily reset the default left margin.
 522 This has the following syntax:
 523 .Bd -filled -offset indent
 524 .Pf \. Sx \&RS
 525 .Op Cm width
 526 .Ed
 527 .Pp
 528 The
 529 .Cm width
 530 argument must conform to
 531 .Sx Scaling Widths .
 532 If not specified, the saved or default width is used.
 533 .Pp
 534 See also
 535 .Sx \&RE .
 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.
 541 The scope of a section is only closed by another section or the end of
 542 file.
 543 The paragraph left-margin width is reset to the default.
 544 .Ss \&SM
 545 Text is rendered in small size (one point smaller than the default
 546 font).
 547 .Ss \&SS
 548 Begin a sub-section.
 549 The scope of a sub-section is closed by a subsequent sub-section,
 550 section, or end of file.
 551 The paragraph left-margin width is reset to the default.
 552 .Ss \&TH
 553 Sets the title of the manual page with the following syntax:
 554 .Bd -filled -offset indent
 555 .Pf \. Sx \&TH
 556 .Ar title section date
 557 .Op Ar source Op Ar volume
 558 .Ed
 559 .Pp
 560 Conventionally, the document
 561 .Ar title
 562 is given in all caps.
 563 The recommended
 564 .Ar date
 565 format is
 566 .Sy YYYY-MM-DD
 567 as specified in the ISO-8601 standard;
 568 if the argument does not conform, it is printed verbatim.
 569 If the
 570 .Ar date
 571 is empty or not specified, the current date is used.
 572 The optional
 573 .Ar source
 574 string specifies the organisation providing the utility.
 575 The
 576 .Ar volume
 577 string replaces the default rendered volume, which is dictated by the
 578 manual section.
 579 .Pp
 580 Examples:
 581 .Pp
 582 .Dl \&.TH CVS 5 "1992-02-12" GNU
 583 .Ss \&TP
 584 Begin a paragraph where the head, if exceeding the indentation width, is
 585 followed by a newline; if not, the body follows on the same line after a
 586 buffer to the indentation width.
 587 Subsequent output lines are indented.
 588 The syntax is as follows:
 589 .Bd -filled -offset indent
 590 .Pf \. Sx \&TP
 591 .Op Cm width
 592 .Ed
 593 .Pp
 594 The
 595 .Cm width
 596 argument must conform to
 597 .Sx Scaling Widths .
 598 If specified, it's saved for later paragraph left-margins; if
 599 unspecified, the saved or default width is used.
 600 .Pp
 601 See also
 602 .Sx \&HP ,
 603 .Sx \&IP ,
 604 .Sx \&LP ,
 605 .Sx \&P ,
 606 and
 607 .Sx \&PP .
 608 .Ss \&UC
 609 Sets the volume for the footer for compatibility with man pages from
 610 BSD releases.
 611 The optional first argument specifies which release it is from.
 612 .Ss \&br
 613 Breaks the current line.
 614 Consecutive invocations have no further effect.
 615 .Pp
 616 See also
 617 .Sx \&sp .
 618 .Ss \&fi
 619 End literal mode begun by
 620 .Sx \&nf .
 621 .Ss \&ft
 622 Change the current font mode.
 623 See
 624 .Sx Text Decoration
 625 for a listing of available font modes.
 626 .Ss \&in
 627 Indent relative to the current indentation:
 628 .Pp
 629 .D1 Pf \. Sx \&in Op Cm width
 630 .Pp
 631 If
 632 .Cm width
 633 is signed, the new offset is relative.
 634 Otherwise, it is absolute.
 635 This value is reset upon the next paragraph, section, or sub-section.
 636 .Ss \&na
 637 Don't align to the right margin.
 638 .Ss \&nf
 639 Begin literal mode: all subsequent free-form lines have their end of
 640 line boundaries preserved.
 641 May be ended by
 642 .Sx \&fi .
 643 Literal mode is implicitly ended by
 644 .Sx \&SH
 645 or
 646 .Sx \&SS .
 647 .Ss \&sp
 648 Insert vertical spaces into output with the following syntax:
 649 .Bd -filled -offset indent
 650 .Pf \. Sx \&sp
 651 .Op Cm height
 652 .Ed
 653 .Pp
 654 Insert
 655 .Cm height
 656 spaces, which must conform to
 657 .Sx Scaling Widths .
 658 If 0, this is equivalent to the
 659 .Sx \&br
 660 macro.
 661 Defaults to 1, if unspecified.
 662 .Pp
 663 See also
 664 .Sx \&br .
 665 .Sh MACRO SYNTAX
 666 The
 667 .Nm
 668 macros are classified by scope: line scope or block scope.
 669 Line macros are only scoped to the current line (and, in some
 670 situations, the subsequent line).
 671 Block macros are scoped to the current line and subsequent lines until
 672 closed by another block macro.
 673 .Ss Line Macros
 674 Line macros are generally scoped to the current line, with the body
 675 consisting of zero or more arguments.
 676 If a macro is scoped to the next line and the line arguments are empty,
 677 the next line, which must be text, is used instead.
 678 Thus:
 679 .Bd -literal -offset indent
 680 \&.I
 681 foo
 682 .Ed
 683 .Pp
 684 is equivalent to
 685 .Sq \&.I foo .
 686 If next-line macros are invoked consecutively, only the last is used.
 687 If a next-line macro is followed by a non-next-line macro, an error is
 688 raised, except for
 689 .Sx \&br ,
 690 .Sx \&sp ,
 691 and
 692 .Sx \&na .
 693 .Pp
 694 The syntax is as follows:
 695 .Bd -literal -offset indent
 696 \&.YO \(lBbody...\(rB
 697 \(lBbody...\(rB
 698 .Ed
 699 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
 700 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
 701 .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
 702 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
 703 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 704 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
 705 .It Sx \&DT  Ta    0         Ta    current   Ta    \&
 706 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 707 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 708 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
 709 .It Sx \&OP  Ta    0, 1      Ta    current   Ta    compat
 710 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
 711 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 712 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
 713 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 714 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 715 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 716 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
 717 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 718 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 719 .It Sx \&ft  Ta    1         Ta    current   Ta    compat
 720 .It Sx \&in  Ta    1         Ta    current   Ta    compat
 721 .It Sx \&na  Ta    0         Ta    current   Ta    compat
 722 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
 723 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
 724 .El
 725 .Pp
 726 Macros marked as
 727 .Qq compat
 728 are included for compatibility with the significant corpus of existing
 729 manuals that mix dialects of roff.
 730 These macros should not be used for portable
 731 .Nm
 732 manuals.
 733 .Ss Block Macros
 734 Block macros comprise a head and body.
 735 As with in-line macros, the head is scoped to the current line and, in
 736 one circumstance, the next line (the next-line stipulations as in
 737 .Sx Line Macros
 738 apply here as well).
 739 .Pp
 740 The syntax is as follows:
 741 .Bd -literal -offset indent
 742 \&.YO \(lBhead...\(rB
 743 \(lBhead...\(rB
 744 \(lBbody...\(rB
 745 .Ed
 746 .Pp
 747 The closure of body scope may be to the section, where a macro is closed
 748 by
 749 .Sx \&SH ;
 750 sub-section, closed by a section or
 751 .Sx \&SS ;
 752 part, closed by a section, sub-section, or
 753 .Sx \&RE ;
 754 or paragraph, closed by a section, sub-section, part,
 755 .Sx \&HP ,
 756 .Sx \&IP ,
 757 .Sx \&LP ,
 758 .Sx \&P ,
 759 .Sx \&PP ,
 760 or
 761 .Sx \&TP .
 762 No closure refers to an explicit block closing macro.
 763 .Pp
 764 As a rule, block macros may not be nested; thus, calling a block macro
 765 while another block macro scope is open, and the open scope is not
 766 implicitly closed, is syntactically incorrect.
 767 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
 768 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
 769 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
 770 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
 771 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 772 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
 773 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 774 .It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
 775 .It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
 776 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
 777 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
 778 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
 779 .El
 780 .Pp
 781 Macros marked
 782 .Qq compat
 783 are as mentioned in
 784 .Sx Line Macros .
 785 .Pp
 786 If a block macro is next-line scoped, it may only be followed by in-line
 787 macros for decorating text.
 788 .Ss Font handling
 789 In
 790 .Nm
 791 documents, both
 792 .Sx Physical markup
 793 macros and
 794 .Xr roff 5
 795 .Ql \ef
 796 font escape sequences can be used to choose fonts.
 797 In text lines, the effect of manual font selection by escape sequences
 798 only lasts until the next macro invocation; in macro lines, it only lasts
 799 until the end of the macro scope.
 800 Note that macros like
 801 .Sx \&BR
 802 open and close a font scope for each argument.
 803 .Sh COMPATIBILITY
 804 This section documents areas of questionable portability between
 805 implementations of the
 806 .Nm
 807 language.
 808 .Pp
 809 .Bl -dash -compact
 810 .It
 811 Do not depend on
 812 .Sx \&SH
 813 or
 814 .Sx \&SS
 815 to close out a literal context opened with
 816 .Sx \&nf .
 817 This behaviour may not be portable.
 818 .It
 819 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 820 a standalone double-quote in formatted output.
 821 It is not known whether this behaviour is exhibited by other formatters.
 822 .It
 823 troff suppresses a newline before
 824 .Sq \(aq
 825 macro output; in mandoc, it is an alias for the standard
 826 .Sq \&.
 827 control character.
 828 .It
 829 The
 830 .Sq \eh
 831 .Pq horizontal position ,
 832 .Sq \ev
 833 .Pq vertical position ,
 834 .Sq \em
 835 .Pq text colour ,
 836 .Sq \eM
 837 .Pq text filling colour ,
 838 .Sq \ez
 839 .Pq zero-length character ,
 840 .Sq \ew
 841 .Pq string length ,
 842 .Sq \ek
 843 .Pq horizontal position marker ,
 844 .Sq \eo
 845 .Pq text overstrike ,
 846 and
 847 .Sq \es
 848 .Pq text size
 849 escape sequences are all discarded in mandoc.
 850 .It
 851 The
 852 .Sq \ef
 853 scaling unit is accepted by mandoc, but rendered as the default unit.
 854 .It
 855 The
 856 .Sx \&sp
 857 macro does not accept negative values in mandoc.
 858 In GNU troff, this would result in strange behaviour.
 859 .It
 860 In page header lines, GNU troff versions up to and including 1.21
 861 only print
 862 .Ar volume
 863 names explicitly specified in the
 864 .Sx \&TH
 865 macro; mandoc and newer groff print the default volume name
 866 corresponding to the
 867 .Ar section
 868 number when no
 869 .Ar volume
 870 is given, like in
 871 .Xr mdoc 5 .
 872 .El
 873 .Pp
 874 The
 875 .Sx OP
 876 macro is part of the extended
 877 .Nm
 878 macro set, and may not be portable to non-GNU troff implementations.
 879 .Sh SEE ALSO
 880 .Xr man 1 ,
 881 .Xr mandoc 1 ,
 882 .Xr eqn 5 ,
 883 .Xr mandoc_char 5 ,
 884 .Xr mdoc 5 ,
 885 .Xr roff 5 ,
 886 .Xr tbl 5
 887 .Sh HISTORY
 888 The
 889 .Nm
 890 language first appeared as a macro package for the roff typesetting
 891 system in
 892 .At v7 .
 893 It was later rewritten by James Clark as a macro package for groff.
 894 Eric S. Raymond wrote the extended
 895 .Nm
 896 macros for groff in 2007.
 897 The stand-alone implementation that is part of the
 898 .Xr mandoc 1
 899 utility written by Kristaps Dzonsons appeared in
 900 .Ox 4.6 .
 901 .Sh AUTHORS
 902 This
 903 .Nm
 904 reference was written by
 905 .An Kristaps Dzonsons ,
 906 .Mt kristaps@bsd.lv .
 907 .Sh CAVEATS
 908 Do not use this language.
 909 Use
 910 .Xr mdoc 5 ,
 911 instead.