contrib/mdocml/man.7

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