contrib/mdocml/man.7

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