contrib/mdocml/man.7

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