contrib/mdocml/man.7

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