man.7

   1 .\"     $Id: man.7,v 1.97 2011/01/25 00:40:14 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: January 25 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 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 To include space characters in macro arguments, arguments may be quoted;
 374 see the
 375 .Sq MACRO SYNTAX
 376 section in the
 377 .Xr roff 7
 378 manual for details.
 379 .Pp
 380 The
 381 .Nm
 382 macros are classified by scope: line scope or block scope.
 383 Line macros are only scoped to the current line (and, in some
 384 situations, the subsequent line).
 385 Block macros are scoped to the current line and subsequent lines until
 386 closed by another block macro.
 387 .Ss Line Macros
 388 Line macros are generally scoped to the current line, with the body
 389 consisting of zero or more arguments.
 390 If a macro is scoped to the next line and the line arguments are empty,
 391 the next line, which must be text, is used instead.
 392 Thus:
 393 .Bd -literal -offset indent
 394 \&.I
 395 foo
 396 .Ed
 397 .Pp
 398 is equivalent to
 399 .Sq \&.I foo .
 400 If next-line macros are invoked consecutively, only the last is used.
 401 If a next-line macro is followed by a non-next-line macro, an error is
 402 raised, except for
 403 .Sx \&br ,
 404 .Sx \&sp ,
 405 and
 406 .Sx \&na .
 407 .Pp
 408 The syntax is as follows:
 409 .Bd -literal -offset indent
 410 \&.YO \(lBbody...\(rB
 411 \(lBbody...\(rB
 412 .Ed
 413 .Pp
 414 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
 415 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
 416 .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
 417 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
 418 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 419 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
 420 .It Sx \&DT  Ta    0         Ta    current   Ta    \&
 421 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 422 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 423 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
 424 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
 425 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 426 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
 427 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 428 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 429 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 430 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
 431 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 432 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 433 .It Sx \&ft  Ta    1         Ta    current   Ta    compat
 434 .It Sx \&in  Ta    1         Ta    current   Ta    compat
 435 .It Sx \&na  Ta    0         Ta    current   Ta    compat
 436 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
 437 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
 438 .El
 439 .Pp
 440 Macros marked as
 441 .Qq compat
 442 are included for compatibility with the significant corpus of existing
 443 manuals that mix dialects of roff.
 444 These macros should not be used for portable
 445 .Nm
 446 manuals.
 447 .Ss Block Macros
 448 Block macros comprise a head and body.
 449 As with in-line macros, the head is scoped to the current line and, in
 450 one circumstance, the next line (the next-line stipulations as in
 451 .Sx Line Macros
 452 apply here as well).
 453 .Pp
 454 The syntax is as follows:
 455 .Bd -literal -offset indent
 456 \&.YO \(lBhead...\(rB
 457 \(lBhead...\(rB
 458 \(lBbody...\(rB
 459 .Ed
 460 .Pp
 461 The closure of body scope may be to the section, where a macro is closed
 462 by
 463 .Sx \&SH ;
 464 sub-section, closed by a section or
 465 .Sx \&SS ;
 466 part, closed by a section, sub-section, or
 467 .Sx \&RE ;
 468 or paragraph, closed by a section, sub-section, part,
 469 .Sx \&HP ,
 470 .Sx \&IP ,
 471 .Sx \&LP ,
 472 .Sx \&P ,
 473 .Sx \&PP ,
 474 or
 475 .Sx \&TP .
 476 No closure refers to an explicit block closing macro.
 477 .Pp
 478 As a rule, block macros may not be nested; thus, calling a block macro
 479 while another block macro scope is open, and the open scope is not
 480 implicitly closed, is syntactically incorrect.
 481 .Pp
 482 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"
 483 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
 484 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
 485 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
 486 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 487 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
 488 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
 489 .It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
 490 .It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
 491 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
 492 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
 493 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
 494 .El
 495 .Pp
 496 Macros marked
 497 .Qq compat
 498 are as mentioned in
 499 .Sx Line Macros .
 500 .Pp
 501 If a block macro is next-line scoped, it may only be followed by in-line
 502 macros for decorating text.
 503 .Sh REFERENCE
 504 This section is a canonical reference to all macros, arranged
 505 alphabetically.
 506 For the scoping of individual macros, see
 507 .Sx MACRO SYNTAX .
 508 .Ss \&AT
 509 Sets the volume for the footer for compatibility with man pages from
 510 .Tn AT&T UNIX
 511 releases.
 512 The optional arguments specify which release it is from.
 513 .Ss \&B
 514 Text is rendered in bold face.
 515 .Pp
 516 See also
 517 .Sx \&I
 518 and
 519 .Sx \&R .
 520 .Ss \&BI
 521 Text is rendered alternately in bold face and italic.
 522 Thus,
 523 .Sq .BI this word and that
 524 causes
 525 .Sq this
 526 and
 527 .Sq and
 528 to render in bold face, while
 529 .Sq word
 530 and
 531 .Sq that
 532 render in italics.
 533 Whitespace between arguments is omitted in output.
 534 .Pp
 535 Examples:
 536 .Pp
 537 .Dl \&.BI bold italic bold italic
 538 .Pp
 539 The output of this example will be emboldened
 540 .Dq bold
 541 and italicised
 542 .Dq italic ,
 543 with spaces stripped between arguments.
 544 .Pp
 545 See also
 546 .Sx \&IB ,
 547 .Sx \&BR ,
 548 .Sx \&RB ,
 549 .Sx \&RI ,
 550 and
 551 .Sx \&IR .
 552 .Ss \&BR
 553 Text is rendered alternately in bold face and roman (the default font).
 554 Whitespace between arguments is omitted in output.
 555 .Pp
 556 See
 557 .Sx \&BI
 558 for an equivalent example.
 559 .Pp
 560 See also
 561 .Sx \&BI ,
 562 .Sx \&IB ,
 563 .Sx \&RB ,
 564 .Sx \&RI ,
 565 and
 566 .Sx \&IR .
 567 .Ss \&DT
 568 Has no effect.
 569 Included for compatibility.
 570 .Ss \&HP
 571 Begin a paragraph whose initial output line is left-justified, but
 572 subsequent output lines are indented, with the following syntax:
 573 .Bd -filled -offset indent
 574 .Pf \. Sx \&HP
 575 .Op Cm width
 576 .Ed
 577 .Pp
 578 The
 579 .Cm width
 580 argument must conform to
 581 .Sx Scaling Widths .
 582 If specified, it's saved for later paragraph left-margins; if unspecified, the
 583 saved or default width is used.
 584 .Pp
 585 See also
 586 .Sx \&IP ,
 587 .Sx \&LP ,
 588 .Sx \&P ,
 589 .Sx \&PP ,
 590 and
 591 .Sx \&TP .
 592 .Ss \&I
 593 Text is rendered in italics.
 594 .Pp
 595 See also
 596 .Sx \&B
 597 and
 598 .Sx \&R .
 599 .Ss \&IB
 600 Text is rendered alternately in italics and bold face.
 601 Whitespace between arguments is omitted in output.
 602 .Pp
 603 See
 604 .Sx \&BI
 605 for an equivalent example.
 606 .Pp
 607 See also
 608 .Sx \&BI ,
 609 .Sx \&BR ,
 610 .Sx \&RB ,
 611 .Sx \&RI ,
 612 and
 613 .Sx \&IR .
 614 .Ss \&IP
 615 Begin an indented paragraph with the following syntax:
 616 .Bd -filled -offset indent
 617 .Pf \. Sx \&IP
 618 .Op Cm head Op Cm width
 619 .Ed
 620 .Pp
 621 The
 622 .Cm width
 623 argument defines the width of the left margin and is defined by
 624 .Sx Scaling Widths .
 625 It's saved for later paragraph left-margins; if unspecified, the saved or
 626 default width is used.
 627 .Pp
 628 The
 629 .Cm head
 630 argument is used as a leading term, flushed to the left margin.
 631 This is useful for bulleted paragraphs and so on.
 632 .Pp
 633 See also
 634 .Sx \&HP ,
 635 .Sx \&LP ,
 636 .Sx \&P ,
 637 .Sx \&PP ,
 638 and
 639 .Sx \&TP .
 640 .Ss \&IR
 641 Text is rendered alternately in italics and roman (the default font).
 642 Whitespace between arguments is omitted in output.
 643 .Pp
 644 See
 645 .Sx \&BI
 646 for an equivalent example.
 647 .Pp
 648 See also
 649 .Sx \&BI ,
 650 .Sx \&IB ,
 651 .Sx \&BR ,
 652 .Sx \&RB ,
 653 and
 654 .Sx \&RI .
 655 .Ss \&LP
 656 Begin an undecorated paragraph.
 657 The scope of a paragraph is closed by a subsequent paragraph,
 658 sub-section, section, or end of file.
 659 The saved paragraph left-margin width is reset to the default.
 660 .Pp
 661 See also
 662 .Sx \&HP ,
 663 .Sx \&IP ,
 664 .Sx \&P ,
 665 .Sx \&PP ,
 666 and
 667 .Sx \&TP .
 668 .Ss \&P
 669 Synonym for
 670 .Sx \&LP .
 671 .Pp
 672 See also
 673 .Sx \&HP ,
 674 .Sx \&IP ,
 675 .Sx \&LP ,
 676 .Sx \&PP ,
 677 and
 678 .Sx \&TP .
 679 .Ss \&PP
 680 Synonym for
 681 .Sx \&LP .
 682 .Pp
 683 See also
 684 .Sx \&HP ,
 685 .Sx \&IP ,
 686 .Sx \&LP ,
 687 .Sx \&P ,
 688 and
 689 .Sx \&TP .
 690 .Ss \&R
 691 Text is rendered in roman (the default font).
 692 .Pp
 693 See also
 694 .Sx \&I
 695 and
 696 .Sx \&B .
 697 .Ss \&RB
 698 Text is rendered alternately in roman (the default font) and bold face.
 699 Whitespace between arguments is omitted in output.
 700 .Pp
 701 See
 702 .Sx \&BI
 703 for an equivalent example.
 704 .Pp
 705 See also
 706 .Sx \&BI ,
 707 .Sx \&IB ,
 708 .Sx \&BR ,
 709 .Sx \&RI ,
 710 and
 711 .Sx \&IR .
 712 .Ss \&RE
 713 Explicitly close out the scope of a prior
 714 .Sx \&RS .
 715 .Ss \&RI
 716 Text is rendered alternately in roman (the default font) and italics.
 717 Whitespace between arguments is omitted in output.
 718 .Pp
 719 See
 720 .Sx \&BI
 721 for an equivalent example.
 722 .Pp
 723 See also
 724 .Sx \&BI ,
 725 .Sx \&IB ,
 726 .Sx \&BR ,
 727 .Sx \&RB ,
 728 and
 729 .Sx \&IR .
 730 .Ss \&RS
 731 Begin a part setting the left margin.
 732 The left margin controls the offset, following an initial indentation,
 733 to un-indented text such as that of
 734 .Sx \&PP .
 735 This has the following syntax:
 736 .Bd -filled -offset indent
 737 .Pf \. Sx \&Rs
 738 .Op Cm width
 739 .Ed
 740 .Pp
 741 The
 742 .Cm width
 743 argument must conform to
 744 .Sx Scaling Widths .
 745 If not specified, the saved or default width is used.
 746 .Ss \&SB
 747 Text is rendered in small size (one point smaller than the default font)
 748 bold face.
 749 .Ss \&SH
 750 Begin a section.
 751 The scope of a section is only closed by another section or the end of
 752 file.
 753 The paragraph left-margin width is reset to the default.
 754 .Ss \&SM
 755 Text is rendered in small size (one point smaller than the default
 756 font).
 757 .Ss \&SS
 758 Begin a sub-section.
 759 The scope of a sub-section is closed by a subsequent sub-section,
 760 section, or end of file.
 761 The paragraph left-margin width is reset to the default.
 762 .Ss \&TH
 763 Sets the title of the manual page with the following syntax:
 764 .Bd -filled -offset indent
 765 .Pf \. Sx \&TH
 766 .Cm title section
 767 .Op Cm date Op Cm source Op Cm volume
 768 .Ed
 769 .Pp
 770 At least the upper-case document
 771 .Cm title
 772 and the manual
 773 .Cm section
 774 arguments must be provided.
 775 The
 776 .Cm date
 777 argument should be formatted as described in
 778 .Sx Dates ,
 779 but will be printed verbatim if it is not.
 780 If the date is not specified, the current date is used.
 781 The
 782 .Cm source
 783 string specifies the organisation providing the utility.
 784 The
 785 .Cm volume
 786 string replaces the default rendered volume, which is dictated by the
 787 manual section.
 788 .Pp
 789 Examples:
 790 .Pp
 791 .Dl \&.TH CVS 5 "1992-02-12" GNU
 792 .Ss \&TP
 793 Begin a paragraph where the head, if exceeding the indentation width, is
 794 followed by a newline; if not, the body follows on the same line after a
 795 buffer to the indentation width.
 796 Subsequent output lines are indented.
 797 The syntax is as follows:
 798 .Bd -filled -offset indent
 799 .Pf \. Sx \&TP
 800 .Op Cm width
 801 .Ed
 802 .Pp
 803 The
 804 .Cm width
 805 argument must conform to
 806 .Sx Scaling Widths .
 807 If specified, it's saved for later paragraph left-margins; if
 808 unspecified, the saved or default width is used.
 809 .Pp
 810 See also
 811 .Sx \&HP ,
 812 .Sx \&IP ,
 813 .Sx \&LP ,
 814 .Sx \&P ,
 815 and
 816 .Sx \&PP .
 817 .Ss \&UC
 818 Sets the volume for the footer for compatibility with man pages from
 819 BSD releases.
 820 The optional first argument specifies which release it is from.
 821 .Ss \&br
 822 Breaks the current line.
 823 Consecutive invocations have no further effect.
 824 .Pp
 825 See also
 826 .Sx \&sp .
 827 .Ss \&fi
 828 End literal mode begun by
 829 .Sx \&nf .
 830 .Ss \&ft
 831 Change the current font mode.
 832 See
 833 .Sx Text Decoration
 834 for a listing of available font modes.
 835 .Ss \&in
 836 Indent relative to the current indentation:
 837 .Pp
 838 .D1 Pf \. Sx \&in Op Cm width
 839 .Pp
 840 If
 841 .Cm width
 842 is signed, the new offset is relative.
 843 Otherwise, it is absolute.
 844 This value is reset upon the next paragraph, section, or sub-section.
 845 .Ss \&na
 846 Don't align to the right margin.
 847 .Ss \&nf
 848 Begin literal mode: all subsequent free-form lines have their end of
 849 line boundaries preserved.
 850 May be ended by
 851 .Sx \&fi .
 852 .Ss \&sp
 853 Insert vertical spaces into output with the following syntax:
 854 .Bd -filled -offset indent
 855 .Pf \. Sx \&sp
 856 .Op Cm height
 857 .Ed
 858 .Pp
 859 Insert
 860 .Cm height
 861 spaces, which must conform to
 862 .Sx Scaling Widths .
 863 If 0, this is equivalent to the
 864 .Sx \&br
 865 macro.
 866 Defaults to 1, if unspecified.
 867 .Pp
 868 See also
 869 .Sx \&br .
 870 .Sh COMPATIBILITY
 871 This section documents areas of questionable portability between
 872 implementations of the
 873 .Nm
 874 language.
 875 .Pp
 876 .Bl -dash -compact
 877 .It
 878 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 879 a standalone double-quote in formatted output.
 880 It is not known whether this behaviour is exhibited by other formatters.
 881 .It
 882 troff suppresses a newline before
 883 .Sq \(aq
 884 macro output; in mandoc, it is an alias for the standard
 885 .Sq \&.
 886 control character.
 887 .It
 888 The
 889 .Sq \eh
 890 .Pq horizontal position ,
 891 .Sq \ev
 892 .Pq vertical position ,
 893 .Sq \em
 894 .Pq text colour ,
 895 .Sq \eM
 896 .Pq text filling colour ,
 897 .Sq \ez
 898 .Pq zero-length character ,
 899 .Sq \ew
 900 .Pq string length ,
 901 .Sq \ek
 902 .Pq horizontal position marker ,
 903 .Sq \eo
 904 .Pq text overstrike ,
 905 and
 906 .Sq \es
 907 .Pq text size
 908 escape sequences are all discarded in mandoc.
 909 .It
 910 The
 911 .Sq \ef
 912 scaling unit is accepted by mandoc, but rendered as the default unit.
 913 .It
 914 The
 915 .Sx \&sp
 916 macro does not accept negative values in mandoc.
 917 In GNU troff, this would result in strange behaviour.
 918 .El
 919 .Sh SEE ALSO
 920 .Xr man 1 ,
 921 .Xr mandoc 1 ,
 922 .Xr mandoc_char 7 ,
 923 .Xr mdoc 7 ,
 924 .Xr roff 7 ,
 925 .Xr tbl 7
 926 .Sh HISTORY
 927 The
 928 .Nm
 929 language first appeared as a macro package for the roff typesetting
 930 system in
 931 .At v7 .
 932 It was later rewritten by James Clark as a macro package for groff.
 933 The stand-alone implementation that is part of the
 934 .Xr mandoc 1
 935 utility written by Kristaps Dzonsons appeared in
 936 .Ox 4.6 .
 937 .Sh AUTHORS
 938 This
 939 .Nm
 940 reference was written by
 941 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 942 .Sh CAVEATS
 943 Do not use this language.
 944 Use
 945 .Xr mdoc 7 ,
 946 instead.