contrib/mdocml/man.7

   1 .\"     $Id: man.7,v 1.132 2015/01/29 00:33:57 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: January 29 2015 $
  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 \&br Ta force output line break in text mode (no arguments)
 270 .It Sx \&sp Ta force vertical space: Op Ar height
 271 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
 272 .It Sx in Ta additional indent: Op Ar width
 273 .El
 274 .Ss Physical markup
 275 .Bl -column "PP, LP, P" description
 276 .It Sx B Ta boldface font
 277 .It Sx I Ta italic font
 278 .It Sx R Ta roman (default) font
 279 .It Sx SB Ta small boldface font
 280 .It Sx SM Ta small roman font
 281 .It Sx BI Ta alternate between boldface and italic fonts
 282 .It Sx BR Ta alternate between boldface and roman fonts
 283 .It Sx IB Ta alternate between italic and boldface fonts
 284 .It Sx IR Ta alternate between italic and roman fonts
 285 .It Sx RB Ta alternate between roman and boldface fonts
 286 .It Sx RI Ta alternate between roman and italic fonts
 287 .El
 288 .Sh MACRO REFERENCE
 289 This section is a canonical reference to all macros, arranged
 290 alphabetically.
 291 For the scoping of individual macros, see
 292 .Sx MACRO SYNTAX .
 293 .Ss \&AT
 294 Sets the volume for the footer for compatibility with man pages from
 295 .At
 296 releases.
 297 The optional arguments specify which release it is from.
 298 .Ss \&B
 299 Text is rendered in bold face.
 300 .Pp
 301 See also
 302 .Sx \&I
 303 and
 304 .Sx \&R .
 305 .Ss \&BI
 306 Text is rendered alternately in bold face and italic.
 307 Thus,
 308 .Sq .BI this word and that
 309 causes
 310 .Sq this
 311 and
 312 .Sq and
 313 to render in bold face, while
 314 .Sq word
 315 and
 316 .Sq that
 317 render in italics.
 318 Whitespace between arguments is omitted in output.
 319 .Pp
 320 Examples:
 321 .Pp
 322 .Dl \&.BI bold italic bold italic
 323 .Pp
 324 The output of this example will be emboldened
 325 .Dq bold
 326 and italicised
 327 .Dq italic ,
 328 with spaces stripped between arguments.
 329 .Pp
 330 See also
 331 .Sx \&IB ,
 332 .Sx \&BR ,
 333 .Sx \&RB ,
 334 .Sx \&RI ,
 335 and
 336 .Sx \&IR .
 337 .Ss \&BR
 338 Text is rendered alternately in bold face and roman (the default font).
 339 Whitespace between arguments is omitted in output.
 340 .Pp
 341 See
 342 .Sx \&BI
 343 for an equivalent example.
 344 .Pp
 345 See also
 346 .Sx \&BI ,
 347 .Sx \&IB ,
 348 .Sx \&RB ,
 349 .Sx \&RI ,
 350 and
 351 .Sx \&IR .
 352 .Ss \&DT
 353 Has no effect.
 354 Included for compatibility.
 355 .Ss \&EE
 356 This is a non-standard GNU extension, included only for compatibility.
 357 In
 358 .Xr mandoc 1 ,
 359 it does the same as
 360 .Sx \&fi .
 361 .Ss \&EX
 362 This is a non-standard GNU extension, included only for compatibility.
 363 In
 364 .Xr mandoc 1 ,
 365 it does the same as
 366 .Sx \&nf .
 367 .Ss \&HP
 368 Begin a paragraph whose initial output line is left-justified, but
 369 subsequent output lines are indented, with the following syntax:
 370 .Bd -filled -offset indent
 371 .Pf \. Sx \&HP
 372 .Op Ar width
 373 .Ed
 374 .Pp
 375 The
 376 .Ar width
 377 argument is a
 378 .Xr roff 7
 379 scaling width.
 380 If specified, it's saved for later paragraph left-margins; if unspecified, the
 381 saved or default width is used.
 382 .Pp
 383 See also
 384 .Sx \&IP ,
 385 .Sx \&LP ,
 386 .Sx \&P ,
 387 .Sx \&PP ,
 388 and
 389 .Sx \&TP .
 390 .Ss \&I
 391 Text is rendered in italics.
 392 .Pp
 393 See also
 394 .Sx \&B
 395 and
 396 .Sx \&R .
 397 .Ss \&IB
 398 Text is rendered alternately in italics and bold face.
 399 Whitespace between arguments is omitted in output.
 400 .Pp
 401 See
 402 .Sx \&BI
 403 for an equivalent example.
 404 .Pp
 405 See also
 406 .Sx \&BI ,
 407 .Sx \&BR ,
 408 .Sx \&RB ,
 409 .Sx \&RI ,
 410 and
 411 .Sx \&IR .
 412 .Ss \&IP
 413 Begin an indented paragraph with the following syntax:
 414 .Bd -filled -offset indent
 415 .Pf \. Sx \&IP
 416 .Op Ar head Op Ar width
 417 .Ed
 418 .Pp
 419 The
 420 .Ar width
 421 argument is a
 422 .Xr roff 7
 423 scaling width defining the left margin.
 424 It's saved for later paragraph left-margins; if unspecified, the saved or
 425 default width is used.
 426 .Pp
 427 The
 428 .Ar head
 429 argument is used as a leading term, flushed to the left margin.
 430 This is useful for bulleted paragraphs and so on.
 431 .Pp
 432 See also
 433 .Sx \&HP ,
 434 .Sx \&LP ,
 435 .Sx \&P ,
 436 .Sx \&PP ,
 437 and
 438 .Sx \&TP .
 439 .Ss \&IR
 440 Text is rendered alternately in italics and roman (the default font).
 441 Whitespace between arguments is omitted in output.
 442 .Pp
 443 See
 444 .Sx \&BI
 445 for an equivalent example.
 446 .Pp
 447 See also
 448 .Sx \&BI ,
 449 .Sx \&IB ,
 450 .Sx \&BR ,
 451 .Sx \&RB ,
 452 and
 453 .Sx \&RI .
 454 .Ss \&LP
 455 Begin an undecorated paragraph.
 456 The scope of a paragraph is closed by a subsequent paragraph,
 457 sub-section, section, or end of file.
 458 The saved paragraph left-margin width is reset to the default.
 459 .Pp
 460 See also
 461 .Sx \&HP ,
 462 .Sx \&IP ,
 463 .Sx \&P ,
 464 .Sx \&PP ,
 465 and
 466 .Sx \&TP .
 467 .Ss \&OP
 468 Optional command-line argument.
 469 This is a non-standard GNU extension, included only for compatibility.
 470 It has the following syntax:
 471 .Bd -filled -offset indent
 472 .Pf \. Sx \&OP
 473 .Ar key Op Ar value
 474 .Ed
 475 .Pp
 476 The
 477 .Ar key
 478 is usually a command-line flag and
 479 .Ar value
 480 its argument.
 481 .Ss \&P
 482 Synonym for
 483 .Sx \&LP .
 484 .Pp
 485 See also
 486 .Sx \&HP ,
 487 .Sx \&IP ,
 488 .Sx \&LP ,
 489 .Sx \&PP ,
 490 and
 491 .Sx \&TP .
 492 .Ss \&PD
 493 Specify the vertical space to be inserted before each new paragraph.
 494 .br
 495 The syntax is as follows:
 496 .Bd -filled -offset indent
 497 .Pf \. Sx \&PD
 498 .Op Ar height
 499 .Ed
 500 .Pp
 501 The
 502 .Ar height
 503 argument is a
 504 .Xr roff 7
 505 scaling width.
 506 It defaults to
 507 .Cm 1v .
 508 If the unit is omitted,
 509 .Cm v
 510 is assumed.
 511 .Pp
 512 This macro affects the spacing before any subsequent instances of
 513 .Sx \&HP ,
 514 .Sx \&IP ,
 515 .Sx \&LP ,
 516 .Sx \&P ,
 517 .Sx \&PP ,
 518 .Sx \&SH ,
 519 .Sx \&SS ,
 520 and
 521 .Sx \&TP .
 522 .Ss \&PP
 523 Synonym for
 524 .Sx \&LP .
 525 .Pp
 526 See also
 527 .Sx \&HP ,
 528 .Sx \&IP ,
 529 .Sx \&LP ,
 530 .Sx \&P ,
 531 and
 532 .Sx \&TP .
 533 .Ss \&R
 534 Text is rendered in roman (the default font).
 535 .Pp
 536 See also
 537 .Sx \&I
 538 and
 539 .Sx \&B .
 540 .Ss \&RB
 541 Text is rendered alternately in roman (the default font) and bold face.
 542 Whitespace between arguments is omitted in output.
 543 .Pp
 544 See
 545 .Sx \&BI
 546 for an equivalent example.
 547 .Pp
 548 See also
 549 .Sx \&BI ,
 550 .Sx \&IB ,
 551 .Sx \&BR ,
 552 .Sx \&RI ,
 553 and
 554 .Sx \&IR .
 555 .Ss \&RE
 556 Explicitly close out the scope of a prior
 557 .Sx \&RS .
 558 The default left margin is restored to the state before that
 559 .Sx \&RS
 560 invocation.
 561 .Pp
 562 The syntax is as follows:
 563 .Bd -filled -offset indent
 564 .Pf \. Sx \&RE
 565 .Op Ar level
 566 .Ed
 567 .Pp
 568 Without an argument, the most recent
 569 .Sx \&RS
 570 block is closed out.
 571 If
 572 .Ar level
 573 is 1, all open
 574 .Sx \&RS
 575 blocks are closed out.
 576 Otherwise,
 577 .Ar level No \(mi 1
 578 nested
 579 .Sx \&RS
 580 blocks remain open.
 581 .Ss \&RI
 582 Text is rendered alternately in roman (the default font) and italics.
 583 Whitespace between arguments is omitted in output.
 584 .Pp
 585 See
 586 .Sx \&BI
 587 for an equivalent example.
 588 .Pp
 589 See also
 590 .Sx \&BI ,
 591 .Sx \&IB ,
 592 .Sx \&BR ,
 593 .Sx \&RB ,
 594 and
 595 .Sx \&IR .
 596 .Ss \&RS
 597 Temporarily reset the default left margin.
 598 This has the following syntax:
 599 .Bd -filled -offset indent
 600 .Pf \. Sx \&RS
 601 .Op Ar width
 602 .Ed
 603 .Pp
 604 The
 605 .Ar width
 606 argument is a
 607 .Xr roff 7
 608 scaling width.
 609 If not specified, the saved or default width is used.
 610 .Pp
 611 See also
 612 .Sx \&RE .
 613 .Ss \&SB
 614 Text is rendered in small size (one point smaller than the default font)
 615 bold face.
 616 .Ss \&SH
 617 Begin a section.
 618 The scope of a section is only closed by another section or the end of
 619 file.
 620 The paragraph left-margin width is reset to the default.
 621 .Ss \&SM
 622 Text is rendered in small size (one point smaller than the default
 623 font).
 624 .Ss \&SS
 625 Begin a sub-section.
 626 The scope of a sub-section is closed by a subsequent sub-section,
 627 section, or end of file.
 628 The paragraph left-margin width is reset to the default.
 629 .Ss \&TH
 630 Sets the title of the manual page for use in the page header
 631 and footer with the following syntax:
 632 .Bd -filled -offset indent
 633 .Pf \. Sx \&TH
 634 .Ar title section date
 635 .Op Ar source Op Ar volume
 636 .Ed
 637 .Pp
 638 Conventionally, the document
 639 .Ar title
 640 is given in all caps.
 641 The recommended
 642 .Ar date
 643 format is
 644 .Sy YYYY-MM-DD
 645 as specified in the ISO-8601 standard;
 646 if the argument does not conform, it is printed verbatim.
 647 If the
 648 .Ar date
 649 is empty or not specified, the current date is used.
 650 The optional
 651 .Ar source
 652 string specifies the organisation providing the utility.
 653 When unspecified,
 654 .Xr mandoc 1
 655 uses its
 656 .Fl Ios
 657 argument.
 658 The
 659 .Ar volume
 660 string replaces the default rendered volume, which is dictated by the
 661 manual section.
 662 .Pp
 663 Examples:
 664 .Pp
 665 .Dl \&.TH CVS 5 "1992-02-12" GNU
 666 .Ss \&TP
 667 Begin a paragraph where the head, if exceeding the indentation width, is
 668 followed by a newline; if not, the body follows on the same line after a
 669 buffer to the indentation width.
 670 Subsequent output lines are indented.
 671 The syntax is as follows:
 672 .Bd -filled -offset indent
 673 .Pf \. Sx \&TP
 674 .Op Ar width
 675 .Ed
 676 .Pp
 677 The
 678 .Ar width
 679 argument is a
 680 .Xr roff 7
 681 scaling width.
 682 If specified, it's saved for later paragraph left-margins; if
 683 unspecified, the saved or default width is used.
 684 .Pp
 685 See also
 686 .Sx \&HP ,
 687 .Sx \&IP ,
 688 .Sx \&LP ,
 689 .Sx \&P ,
 690 and
 691 .Sx \&PP .
 692 .Ss \&UC
 693 Sets the volume for the footer for compatibility with man pages from
 694 .Bx
 695 releases.
 696 The optional first argument specifies which release it is from.
 697 .Ss \&UE
 698 End a uniform resource identifier block.
 699 This is a non-standard GNU extension, included only for compatibility.
 700 See
 701 .Sx \&UE .
 702 .Ss \&UR
 703 Begin a uniform resource identifier block.
 704 This is a non-standard GNU extension, included only for compatibility.
 705 It has the following syntax:
 706 .Bd -literal -offset indent
 707 .Pf \. Sx \&UR Ar uri
 708 link description to be shown
 709 .Pf \. Sx UE
 710 .Ed
 711 .Ss \&br
 712 Breaks the current line.
 713 Consecutive invocations have no further effect.
 714 .Pp
 715 See also
 716 .Sx \&sp .
 717 .Ss \&fi
 718 End literal mode begun by
 719 .Sx \&nf .
 720 .Ss \&in
 721 Indent relative to the current indentation:
 722 .Pp
 723 .D1 Pf \. Sx \&in Op Ar width
 724 .Pp
 725 If
 726 .Ar width
 727 is signed, the new offset is relative.
 728 Otherwise, it is absolute.
 729 This value is reset upon the next paragraph, section, or sub-section.
 730 .Ss \&nf
 731 Begin literal mode: all subsequent free-form lines have their end of
 732 line boundaries preserved.
 733 May be ended by
 734 .Sx \&fi .
 735 Literal mode is implicitly ended by
 736 .Sx \&SH
 737 or
 738 .Sx \&SS .
 739 .Ss \&sp
 740 Insert vertical spaces into output with the following syntax:
 741 .Bd -filled -offset indent
 742 .Pf \. Sx \&sp
 743 .Op Ar height
 744 .Ed
 745 .Pp
 746 The
 747 .Ar height
 748 argument is a scaling width as described in
 749 .Xr roff 7 .
 750 If 0, this is equivalent to the
 751 .Sx \&br
 752 macro.
 753 Defaults to 1, if unspecified.
 754 .Pp
 755 See also
 756 .Sx \&br .
 757 .Sh MACRO SYNTAX
 758 The
 759 .Nm
 760 macros are classified by scope: line scope or block scope.
 761 Line macros are only scoped to the current line (and, in some
 762 situations, the subsequent line).
 763 Block macros are scoped to the current line and subsequent lines until
 764 closed by another block macro.
 765 .Ss Line Macros
 766 Line macros are generally scoped to the current line, with the body
 767 consisting of zero or more arguments.
 768 If a macro is scoped to the next line and the line arguments are empty,
 769 the next line, which must be text, is used instead.
 770 Thus:
 771 .Bd -literal -offset indent
 772 \&.I
 773 foo
 774 .Ed
 775 .Pp
 776 is equivalent to
 777 .Sq \&.I foo .
 778 If next-line macros are invoked consecutively, only the last is used.
 779 If a next-line macro is followed by a non-next-line macro, an error is
 780 raised, except for
 781 .Sx \&br
 782 and
 783 .Sx \&sp .
 784 .Pp
 785 The syntax is as follows:
 786 .Bd -literal -offset indent
 787 \&.YO \(lBbody...\(rB
 788 \(lBbody...\(rB
 789 .Ed
 790 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
 791 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
 792 .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
 793 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
 794 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 795 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
 796 .It Sx \&DT  Ta    0         Ta    current   Ta    \&
 797 .It Sx \&EE  Ta    0         Ta    current   Ta    compat
 798 .It Sx \&EX  Ta    0         Ta    current   Ta    compat
 799 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 800 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 801 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
 802 .It Sx \&OP  Ta    0, 1      Ta    current   Ta    compat
 803 .It Sx \&PD  Ta    1         Ta    current   Ta    \&
 804 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
 805 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 806 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
 807 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 808 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 809 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 810 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
 811 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 812 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 813 .It Sx \&in  Ta    1         Ta    current   Ta    compat
 814 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
 815 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
 816 .El
 817 .Pp
 818 Macros marked as
 819 .Qq compat
 820 are included for compatibility with the significant corpus of existing
 821 manuals that mix dialects of roff.
 822 These macros should not be used for portable
 823 .Nm
 824 manuals.
 825 .Ss Block Macros
 826 Block macros comprise a head and body.
 827 As with in-line macros, the head is scoped to the current line and, in
 828 one circumstance, the next line (the next-line stipulations as in
 829 .Sx Line Macros
 830 apply here as well).
 831 .Pp
 832 The syntax is as follows:
 833 .Bd -literal -offset indent
 834 \&.YO \(lBhead...\(rB
 835 \(lBhead...\(rB
 836 \(lBbody...\(rB
 837 .Ed
 838 .Pp
 839 The closure of body scope may be to the section, where a macro is closed
 840 by
 841 .Sx \&SH ;
 842 sub-section, closed by a section or
 843 .Sx \&SS ;
 844 part, closed by a section, sub-section, or
 845 .Sx \&RE ;
 846 or paragraph, closed by a section, sub-section, part,
 847 .Sx \&HP ,
 848 .Sx \&IP ,
 849 .Sx \&LP ,
 850 .Sx \&P ,
 851 .Sx \&PP ,
 852 or
 853 .Sx \&TP .
 854 No closure refers to an explicit block closing macro.
 855 .Pp
 856 As a rule, block macros may not be nested; thus, calling a block macro
 857 while another block macro scope is open, and the open scope is not
 858 implicitly closed, is syntactically incorrect.
 859 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
 860 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
 861 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
 862 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
 863 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 864 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
 865 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 866 .It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
 867 .It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
 868 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
 869 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
 870 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
 871 .It Sx \&UE  Ta    0         Ta    current    Ta    none        Ta    compat
 872 .It Sx \&UR  Ta    1         Ta    current    Ta    part        Ta    compat
 873 .El
 874 .Pp
 875 Macros marked
 876 .Qq compat
 877 are as mentioned in
 878 .Sx Line Macros .
 879 .Pp
 880 If a block macro is next-line scoped, it may only be followed by in-line
 881 macros for decorating text.
 882 .Ss Font handling
 883 In
 884 .Nm
 885 documents, both
 886 .Sx Physical markup
 887 macros and
 888 .Xr roff 7
 889 .Ql \ef
 890 font escape sequences can be used to choose fonts.
 891 In text lines, the effect of manual font selection by escape sequences
 892 only lasts until the next macro invocation; in macro lines, it only lasts
 893 until the end of the macro scope.
 894 Note that macros like
 895 .Sx \&BR
 896 open and close a font scope for each argument.
 897 .Sh SEE ALSO
 898 .Xr man 1 ,
 899 .Xr mandoc 1 ,
 900 .Xr eqn 7 ,
 901 .Xr mandoc_char 7 ,
 902 .Xr mdoc 7 ,
 903 .Xr roff 7 ,
 904 .Xr tbl 7
 905 .Sh HISTORY
 906 The
 907 .Nm
 908 language first appeared as a macro package for the roff typesetting
 909 system in
 910 .At v7 .
 911 It was later rewritten by James Clark as a macro package for groff.
 912 Eric S. Raymond wrote the extended
 913 .Nm
 914 macros for groff in 2007.
 915 The stand-alone implementation that is part of the
 916 .Xr mandoc 1
 917 utility written by Kristaps Dzonsons appeared in
 918 .Ox 4.6 .
 919 .Sh AUTHORS
 920 This
 921 .Nm
 922 reference was written by
 923 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 924 .Sh CAVEATS
 925 Do not use this language.
 926 Use
 927 .Xr mdoc 7 ,
 928 instead.