contrib/mdocml/man.7

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