man.7

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