contrib/mdocml/mdoc.7

   1 .\"     $Id: mdoc.7,v 1.223 2013/12/25 14:09:32 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: December 25 2013 $
  19 .Dt MDOC 7
  20 .Os
  21 .Sh NAME
  22 .Nm mdoc
  23 .Nd semantic markup language for formatting manual pages
  24 .Sh DESCRIPTION
  25 The
  26 .Nm mdoc
  27 language supports authoring of manual pages for the
  28 .Xr man 1
  29 utility by allowing semantic annotations of words, phrases,
  30 page sections and complete manual pages.
  31 Such annotations are used by formatting tools to achieve a uniform
  32 presentation across all manuals written in
  33 .Nm ,
  34 and to support hyperlinking if supported by the output medium.
  35 .Pp
  36 This reference document describes the structure of manual pages
  37 and the syntax and usage of the
  38 .Nm
  39 language.
  40 The reference implementation of a parsing and formatting tool is
  41 .Xr mandoc 1 ;
  42 the
  43 .Sx COMPATIBILITY
  44 section describes compatibility with other implementations.
  45 .Pp
  46 In an
  47 .Nm
  48 document, lines beginning with the control character
  49 .Sq \&.
  50 are called
  51 .Dq macro lines .
  52 The first word is the macro name.
  53 It consists of two or three letters.
  54 Most macro names begin with a capital letter.
  55 For a list of available macros, see
  56 .Sx MACRO OVERVIEW .
  57 The words following the macro name are arguments to the macro, optionally
  58 including the names of other, callable macros; see
  59 .Sx MACRO SYNTAX
  60 for details.
  61 .Pp
  62 Lines not beginning with the control character are called
  63 .Dq text lines .
  64 They provide free-form text to be printed; the formatting of the text
  65 depends on the respective processing context:
  66 .Bd -literal -offset indent
  67 \&.Sh Macro lines change control state.
  68 Text lines are interpreted within the current state.
  69 .Ed
  70 .Pp
  71 Many aspects of the basic syntax of the
  72 .Nm
  73 language are based on the
  74 .Xr roff 7
  75 language; see the
  76 .Em LANGUAGE SYNTAX
  77 and
  78 .Em MACRO SYNTAX
  79 sections in the
  80 .Xr roff 7
  81 manual for details, in particular regarding
  82 comments, escape sequences, whitespace, and quoting.
  83 However, using
  84 .Xr roff 7
  85 requests in
  86 .Nm
  87 documents is discouraged;
  88 .Xr mandoc 1
  89 supports some of them merely for backward compatibility.
  90 .Sh MANUAL STRUCTURE
  91 A well-formed
  92 .Nm
  93 document consists of a document prologue followed by one or more
  94 sections.
  95 .Pp
  96 The prologue, which consists of the
  97 .Sx \&Dd ,
  98 .Sx \&Dt ,
  99 and
 100 .Sx \&Os
 101 macros in that order, is required for every document.
 102 .Pp
 103 The first section (sections are denoted by
 104 .Sx \&Sh )
 105 must be the NAME section, consisting of at least one
 106 .Sx \&Nm
 107 followed by
 108 .Sx \&Nd .
 109 .Pp
 110 Following that, convention dictates specifying at least the
 111 .Em SYNOPSIS
 112 and
 113 .Em DESCRIPTION
 114 sections, although this varies between manual sections.
 115 .Pp
 116 The following is a well-formed skeleton
 117 .Nm
 118 file for a utility
 119 .Qq progname :
 120 .Bd -literal -offset indent
 121 \&.Dd $\&Mdocdate$
 122 \&.Dt PROGNAME section
 123 \&.Os
 124 \&.Sh NAME
 125 \&.Nm progname
 126 \&.Nd one line about what it does
 127 \&.\e\(dq .Sh LIBRARY
 128 \&.\e\(dq For sections 2, 3, & 9 only.
 129 \&.\e\(dq Not used in OpenBSD.
 130 \&.Sh SYNOPSIS
 131 \&.Nm progname
 132 \&.Op Fl options
 133 \&.Ar
 134 \&.Sh DESCRIPTION
 135 The
 136 \&.Nm
 137 utility processes files ...
 138 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 139 \&.\e\(dq Not used in OpenBSD.
 140 \&.\e\(dq .Sh RETURN VALUES
 141 \&.\e\(dq For sections 2, 3, & 9 only.
 142 \&.\e\(dq .Sh ENVIRONMENT
 143 \&.\e\(dq For sections 1, 6, 7, & 8 only.
 144 \&.\e\(dq .Sh FILES
 145 \&.\e\(dq .Sh EXIT STATUS
 146 \&.\e\(dq For sections 1, 6, & 8 only.
 147 \&.\e\(dq .Sh EXAMPLES
 148 \&.\e\(dq .Sh DIAGNOSTICS
 149 \&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
 150 \&.\e\(dq .Sh ERRORS
 151 \&.\e\(dq For sections 2, 3, & 9 only.
 152 \&.\e\(dq .Sh SEE ALSO
 153 \&.\e\(dq .Xr foobar 1
 154 \&.\e\(dq .Sh STANDARDS
 155 \&.\e\(dq .Sh HISTORY
 156 \&.\e\(dq .Sh AUTHORS
 157 \&.\e\(dq .Sh CAVEATS
 158 \&.\e\(dq .Sh BUGS
 159 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
 160 \&.\e\(dq Not used in OpenBSD.
 161 .Ed
 162 .Pp
 163 The sections in an
 164 .Nm
 165 document are conventionally ordered as they appear above.
 166 Sections should be composed as follows:
 167 .Bl -ohang -offset Ds
 168 .It Em NAME
 169 The name(s) and a one line description of the documented material.
 170 The syntax for this as follows:
 171 .Bd -literal -offset indent
 172 \&.Nm name0 ,
 173 \&.Nm name1 ,
 174 \&.Nm name2
 175 \&.Nd a one line description
 176 .Ed
 177 .Pp
 178 Multiple
 179 .Sq \&Nm
 180 names should be separated by commas.
 181 .Pp
 182 The
 183 .Sx \&Nm
 184 macro(s) must precede the
 185 .Sx \&Nd
 186 macro.
 187 .Pp
 188 See
 189 .Sx \&Nm
 190 and
 191 .Sx \&Nd .
 192 .It Em LIBRARY
 193 The name of the library containing the documented material, which is
 194 assumed to be a function in a section 2, 3, or 9 manual.
 195 The syntax for this is as follows:
 196 .Bd -literal -offset indent
 197 \&.Lb libarm
 198 .Ed
 199 .Pp
 200 See
 201 .Sx \&Lb .
 202 .It Em SYNOPSIS
 203 Documents the utility invocation syntax, function call syntax, or device
 204 configuration.
 205 .Pp
 206 For the first, utilities (sections 1, 6, and 8), this is
 207 generally structured as follows:
 208 .Bd -literal -offset indent
 209 \&.Nm bar
 210 \&.Op Fl v
 211 \&.Op Fl o Ar file
 212 \&.Op Ar
 213 \&.Nm foo
 214 \&.Op Fl v
 215 \&.Op Fl o Ar file
 216 \&.Op Ar
 217 .Ed
 218 .Pp
 219 Commands should be ordered alphabetically.
 220 .Pp
 221 For the second, function calls (sections 2, 3, 9):
 222 .Bd -literal -offset indent
 223 \&.In header.h
 224 \&.Vt extern const char *global;
 225 \&.Ft "char *"
 226 \&.Fn foo "const char *src"
 227 \&.Ft "char *"
 228 \&.Fn bar "const char *src"
 229 .Ed
 230 .Pp
 231 Ordering of
 232 .Sx \&In ,
 233 .Sx \&Vt ,
 234 .Sx \&Fn ,
 235 and
 236 .Sx \&Fo
 237 macros should follow C header-file conventions.
 238 .Pp
 239 And for the third, configurations (section 4):
 240 .Bd -literal -offset indent
 241 \&.Cd \(dqit* at isa? port 0x2e\(dq
 242 \&.Cd \(dqit* at isa? port 0x4e\(dq
 243 .Ed
 244 .Pp
 245 Manuals not in these sections generally don't need a
 246 .Em SYNOPSIS .
 247 .Pp
 248 Some macros are displayed differently in the
 249 .Em SYNOPSIS
 250 section, particularly
 251 .Sx \&Nm ,
 252 .Sx \&Cd ,
 253 .Sx \&Fd ,
 254 .Sx \&Fn ,
 255 .Sx \&Fo ,
 256 .Sx \&In ,
 257 .Sx \&Vt ,
 258 and
 259 .Sx \&Ft .
 260 All of these macros are output on their own line.
 261 If two such dissimilar macros are pairwise invoked (except for
 262 .Sx \&Ft
 263 before
 264 .Sx \&Fo
 265 or
 266 .Sx \&Fn ) ,
 267 they are separated by a vertical space, unless in the case of
 268 .Sx \&Fo ,
 269 .Sx \&Fn ,
 270 and
 271 .Sx \&Ft ,
 272 which are always separated by vertical space.
 273 .Pp
 274 When text and macros following an
 275 .Sx \&Nm
 276 macro starting an input line span multiple output lines,
 277 all output lines but the first will be indented to align
 278 with the text immediately following the
 279 .Sx \&Nm
 280 macro, up to the next
 281 .Sx \&Nm ,
 282 .Sx \&Sh ,
 283 or
 284 .Sx \&Ss
 285 macro or the end of an enclosing block, whichever comes first.
 286 .It Em DESCRIPTION
 287 This begins with an expansion of the brief, one line description in
 288 .Em NAME :
 289 .Bd -literal -offset indent
 290 The
 291 \&.Nm
 292 utility does this, that, and the other.
 293 .Ed
 294 .Pp
 295 It usually follows with a breakdown of the options (if documenting a
 296 command), such as:
 297 .Bd -literal -offset indent
 298 The arguments are as follows:
 299 \&.Bl \-tag \-width Ds
 300 \&.It Fl v
 301 Print verbose information.
 302 \&.El
 303 .Ed
 304 .Pp
 305 Manuals not documenting a command won't include the above fragment.
 306 .Pp
 307 Since the
 308 .Em DESCRIPTION
 309 section usually contains most of the text of a manual, longer manuals
 310 often use the
 311 .Sx \&Ss
 312 macro to form subsections.
 313 In very long manuals, the
 314 .Em DESCRIPTION
 315 may be split into multiple sections, each started by an
 316 .Sx \&Sh
 317 macro followed by a non-standard section name, and each having
 318 several subsections, like in the present
 319 .Nm
 320 manual.
 321 .It Em IMPLEMENTATION NOTES
 322 Implementation-specific notes should be kept here.
 323 This is useful when implementing standard functions that may have side
 324 effects or notable algorithmic implications.
 325 .It Em RETURN VALUES
 326 This section documents the
 327 return values of functions in sections 2, 3, and 9.
 328 .Pp
 329 See
 330 .Sx \&Rv .
 331 .It Em ENVIRONMENT
 332 Lists the environment variables used by the utility,
 333 and explains the syntax and semantics of their values.
 334 The
 335 .Xr environ 7
 336 manual provides examples of typical content and formatting.
 337 .Pp
 338 See
 339 .Sx \&Ev .
 340 .It Em FILES
 341 Documents files used.
 342 It's helpful to document both the file name and a short description of how
 343 the file is used (created, modified, etc.).
 344 .Pp
 345 See
 346 .Sx \&Pa .
 347 .It Em EXIT STATUS
 348 This section documents the
 349 command exit status for section 1, 6, and 8 utilities.
 350 Historically, this information was described in
 351 .Em DIAGNOSTICS ,
 352 a practise that is now discouraged.
 353 .Pp
 354 See
 355 .Sx \&Ex .
 356 .It Em EXAMPLES
 357 Example usages.
 358 This often contains snippets of well-formed, well-tested invocations.
 359 Make sure that examples work properly!
 360 .It Em DIAGNOSTICS
 361 Documents error conditions.
 362 This is most useful in section 4 manuals.
 363 Historically, this section was used in place of
 364 .Em EXIT STATUS
 365 for manuals in sections 1, 6, and 8; however, this practise is
 366 discouraged.
 367 .Pp
 368 See
 369 .Sx \&Bl
 370 .Fl diag .
 371 .It Em ERRORS
 372 Documents error handling in sections 2, 3, and 9.
 373 .Pp
 374 See
 375 .Sx \&Er .
 376 .It Em SEE ALSO
 377 References other manuals with related topics.
 378 This section should exist for most manuals.
 379 Cross-references should conventionally be ordered first by section, then
 380 alphabetically.
 381 .Pp
 382 References to other documentation concerning the topic of the manual page,
 383 for example authoritative books or journal articles, may also be
 384 provided in this section.
 385 .Pp
 386 See
 387 .Sx \&Rs
 388 and
 389 .Sx \&Xr .
 390 .It Em STANDARDS
 391 References any standards implemented or used.
 392 If not adhering to any standards, the
 393 .Em HISTORY
 394 section should be used instead.
 395 .Pp
 396 See
 397 .Sx \&St .
 398 .It Em HISTORY
 399 A brief history of the subject, including where it was first implemented,
 400 and when it was ported to or reimplemented for the operating system at hand.
 401 .It Em AUTHORS
 402 Credits to the person or persons who wrote the code and/or documentation.
 403 Authors should generally be noted by both name and email address.
 404 .Pp
 405 See
 406 .Sx \&An .
 407 .It Em CAVEATS
 408 Common misuses and misunderstandings should be explained
 409 in this section.
 410 .It Em BUGS
 411 Known bugs, limitations, and work-arounds should be described
 412 in this section.
 413 .It Em SECURITY CONSIDERATIONS
 414 Documents any security precautions that operators should consider.
 415 .El
 416 .Sh MACRO OVERVIEW
 417 This overview is sorted such that macros of similar purpose are listed
 418 together, to help find the best macro for any given purpose.
 419 Deprecated macros are not included in the overview, but can be found below
 420 in the alphabetical
 421 .Sx MACRO REFERENCE .
 422 .Ss Document preamble and NAME section macros
 423 .Bl -column "Brq, Bro, Brc" description
 424 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
 425 .It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
 426 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
 427 .It Sx \&Nm Ta document name (one argument)
 428 .It Sx \&Nd Ta document description (one line)
 429 .El
 430 .Ss Sections and cross references
 431 .Bl -column "Brq, Bro, Brc" description
 432 .It Sx \&Sh Ta section header (one line)
 433 .It Sx \&Ss Ta subsection header (one line)
 434 .It Sx \&Sx Ta internal cross reference to a section or subsection
 435 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
 436 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
 437 .El
 438 .Ss Displays and lists
 439 .Bl -column "Brq, Bro, Brc" description
 440 .It Sx \&Bd , \&Ed Ta display block:
 441 .Fl Ar type
 442 .Op Fl offset Ar width
 443 .Op Fl compact
 444 .It Sx \&D1 Ta indented display (one line)
 445 .It Sx \&Dl Ta indented literal display (one line)
 446 .It Sx \&Bl , \&El Ta list block:
 447 .Fl Ar type
 448 .Op Fl width Ar val
 449 .Op Fl offset Ar val
 450 .Op Fl compact
 451 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
 452 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
 453 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
 454 .El
 455 .Ss Spacing control
 456 .Bl -column "Brq, Bro, Brc" description
 457 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
 458 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
 459 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
 460 .It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
 461 .It Sx \&Bk , \&Ek Ta keep block: Fl words
 462 .It Sx \&br Ta force output line break in text mode (no arguments)
 463 .It Sx \&sp Ta force vertical space: Op Ar height
 464 .El
 465 .Ss Semantic markup for command line utilities:
 466 .Bl -column "Brq, Bro, Brc" description
 467 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
 468 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
 469 .It Sx \&Cm Ta command modifier (>0 arguments)
 470 .It Sx \&Ar Ta command arguments (>=0 arguments)
 471 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
 472 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
 473 .It Sx \&Ev Ta environmental variable (>0 arguments)
 474 .It Sx \&Pa Ta file system path (>=0 arguments)
 475 .El
 476 .Ss Semantic markup for function libraries:
 477 .Bl -column "Brq, Bro, Brc" description
 478 .It Sx \&Lb Ta function library (one argument)
 479 .It Sx \&In Ta include file (one argument)
 480 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
 481 .It Sx \&Ft Ta function type (>0 arguments)
 482 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
 483 .It Sx \&Fn Ta function name:
 484 .Op Ar functype
 485 .Ar funcname
 486 .Oo
 487 .Op Ar argtype
 488 .Ar argname
 489 .Oc
 490 .It Sx \&Fa Ta function argument (>0 arguments)
 491 .It Sx \&Vt Ta variable type (>0 arguments)
 492 .It Sx \&Va Ta variable name (>0 arguments)
 493 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
 494 .It Sx \&Er Ta error constant (>0 arguments)
 495 .It Sx \&Ev Ta environmental variable (>0 arguments)
 496 .El
 497 .Ss Various semantic markup:
 498 .Bl -column "Brq, Bro, Brc" description
 499 .It Sx \&An Ta author name (>0 arguments)
 500 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
 501 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
 502 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
 503 .It Sx \&Ad Ta memory address (>0 arguments)
 504 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
 505 .It Sx \&Tn Ta tradename (>0 arguments)
 506 .El
 507 .Ss Physical markup
 508 .Bl -column "Brq, Bro, Brc" description
 509 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
 510 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
 511 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
 512 .It Sx \&No Ta return to roman font (normal) (no arguments)
 513 .It Sx \&Bf , \&Ef Ta font block:
 514 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
 515 .El
 516 .Ss Physical enclosures
 517 .Bl -column "Brq, Bro, Brc" description
 518 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
 519 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
 520 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
 521 .It Sx \&Ql Ta single-quoted literal text: Ql text
 522 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
 523 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
 524 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
 525 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
 526 .It Sx \&Eo , \&Ec Ta generic enclosure
 527 .El
 528 .Ss Text production
 529 .Bl -column "Brq, Bro, Brc" description
 530 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
 531 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
 532 .It Sx \&St Ta reference to a standards document (one argument)
 533 .It Sx \&Ux Ta Ux
 534 .It Sx \&At Ta At
 535 .It Sx \&Bx Ta Bx
 536 .It Sx \&Bsx Ta Bsx
 537 .It Sx \&Nx Ta Nx
 538 .It Sx \&Fx Ta Fx
 539 .It Sx \&Ox Ta Ox
 540 .It Sx \&Dx Ta Dx
 541 .El
 542 .Sh MACRO REFERENCE
 543 This section is a canonical reference of all macros, arranged
 544 alphabetically.
 545 For the scoping of individual macros, see
 546 .Sx MACRO SYNTAX .
 547 .Ss \&%A
 548 Author name of an
 549 .Sx \&Rs
 550 block.
 551 Multiple authors should each be accorded their own
 552 .Sx \%%A
 553 line.
 554 Author names should be ordered with full or abbreviated forename(s)
 555 first, then full surname.
 556 .Ss \&%B
 557 Book title of an
 558 .Sx \&Rs
 559 block.
 560 This macro may also be used in a non-bibliographic context when
 561 referring to book titles.
 562 .Ss \&%C
 563 Publication city or location of an
 564 .Sx \&Rs
 565 block.
 566 .Ss \&%D
 567 Publication date of an
 568 .Sx \&Rs
 569 block.
 570 Recommended formats of arguments are
 571 .Ar month day , year
 572 or just
 573 .Ar year .
 574 .Ss \&%I
 575 Publisher or issuer name of an
 576 .Sx \&Rs
 577 block.
 578 .Ss \&%J
 579 Journal name of an
 580 .Sx \&Rs
 581 block.
 582 .Ss \&%N
 583 Issue number (usually for journals) of an
 584 .Sx \&Rs
 585 block.
 586 .Ss \&%O
 587 Optional information of an
 588 .Sx \&Rs
 589 block.
 590 .Ss \&%P
 591 Book or journal page number of an
 592 .Sx \&Rs
 593 block.
 594 .Ss \&%Q
 595 Institutional author (school, government, etc.) of an
 596 .Sx \&Rs
 597 block.
 598 Multiple institutional authors should each be accorded their own
 599 .Sx \&%Q
 600 line.
 601 .Ss \&%R
 602 Technical report name of an
 603 .Sx \&Rs
 604 block.
 605 .Ss \&%T
 606 Article title of an
 607 .Sx \&Rs
 608 block.
 609 This macro may also be used in a non-bibliographical context when
 610 referring to article titles.
 611 .Ss \&%U
 612 URI of reference document.
 613 .Ss \&%V
 614 Volume number of an
 615 .Sx \&Rs
 616 block.
 617 .Ss \&Ac
 618 Close an
 619 .Sx \&Ao
 620 block.
 621 Does not have any tail arguments.
 622 .Ss \&Ad
 623 Memory address.
 624 Do not use this for postal addresses.
 625 .Pp
 626 Examples:
 627 .Dl \&.Ad [0,$]
 628 .Dl \&.Ad 0x00000000
 629 .Ss \&An
 630 Author name.
 631 Can be used both for the authors of the program, function, or driver
 632 documented in the manual, or for the authors of the manual itself.
 633 Requires either the name of an author or one of the following arguments:
 634 .Pp
 635 .Bl -tag -width "-nosplitX" -offset indent -compact
 636 .It Fl split
 637 Start a new output line before each subsequent invocation of
 638 .Sx \&An .
 639 .It Fl nosplit
 640 The opposite of
 641 .Fl split .
 642 .El
 643 .Pp
 644 The default is
 645 .Fl nosplit .
 646 The effect of selecting either of the
 647 .Fl split
 648 modes ends at the beginning of the
 649 .Em AUTHORS
 650 section.
 651 In the
 652 .Em AUTHORS
 653 section, the default is
 654 .Fl nosplit
 655 for the first author listing and
 656 .Fl split
 657 for all other author listings.
 658 .Pp
 659 Examples:
 660 .Dl \&.An -nosplit
 661 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 662 .Ss \&Ao
 663 Begin a block enclosed by angle brackets.
 664 Does not have any head arguments.
 665 .Pp
 666 Examples:
 667 .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 668 .Pp
 669 See also
 670 .Sx \&Aq .
 671 .Ss \&Ap
 672 Inserts an apostrophe without any surrounding whitespace.
 673 This is generally used as a grammatical device when referring to the verb
 674 form of a function.
 675 .Pp
 676 Examples:
 677 .Dl \&.Fn execve \&Ap d
 678 .Ss \&Aq
 679 Encloses its arguments in angle brackets.
 680 .Pp
 681 Examples:
 682 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
 683 .Pp
 684 .Em Remarks :
 685 this macro is often abused for rendering URIs, which should instead use
 686 .Sx \&Lk
 687 or
 688 .Sx \&Mt ,
 689 or to note pre-processor
 690 .Dq Li #include
 691 statements, which should use
 692 .Sx \&In .
 693 .Pp
 694 See also
 695 .Sx \&Ao .
 696 .Ss \&Ar
 697 Command arguments.
 698 If an argument is not provided, the string
 699 .Dq file ...\&
 700 is used as a default.
 701 .Pp
 702 Examples:
 703 .Dl ".Fl o Ar file"
 704 .Dl ".Ar"
 705 .Dl ".Ar arg1 , arg2 ."
 706 .Pp
 707 The arguments to the
 708 .Sx \&Ar
 709 macro are names and placeholders for command arguments;
 710 for fixed strings to be passed verbatim as arguments, use
 711 .Sx \&Fl
 712 or
 713 .Sx \&Cm .
 714 .Ss \&At
 715 Formats an
 716 .At
 717 version.
 718 Accepts one optional argument:
 719 .Pp
 720 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
 721 .It Cm v[1-7] | 32v
 722 A version of
 723 .At .
 724 .It Cm III
 725 .At III .
 726 .It Cm V[.[1-4]]?
 727 A version of
 728 .At V .
 729 .El
 730 .Pp
 731 Note that these arguments do not begin with a hyphen.
 732 .Pp
 733 Examples:
 734 .Dl \&.At
 735 .Dl \&.At III
 736 .Dl \&.At V.1
 737 .Pp
 738 See also
 739 .Sx \&Bsx ,
 740 .Sx \&Bx ,
 741 .Sx \&Dx ,
 742 .Sx \&Fx ,
 743 .Sx \&Nx ,
 744 .Sx \&Ox ,
 745 and
 746 .Sx \&Ux .
 747 .Ss \&Bc
 748 Close a
 749 .Sx \&Bo
 750 block.
 751 Does not have any tail arguments.
 752 .Ss \&Bd
 753 Begin a display block.
 754 Its syntax is as follows:
 755 .Bd -ragged -offset indent
 756 .Pf \. Sx \&Bd
 757 .Fl Ns Ar type
 758 .Op Fl offset Ar width
 759 .Op Fl compact
 760 .Ed
 761 .Pp
 762 Display blocks are used to select a different indentation and
 763 justification than the one used by the surrounding text.
 764 They may contain both macro lines and text lines.
 765 By default, a display block is preceded by a vertical space.
 766 .Pp
 767 The
 768 .Ar type
 769 must be one of the following:
 770 .Bl -tag -width 13n -offset indent
 771 .It Fl centered
 772 Produce one output line from each input line, and centre-justify each line.
 773 Using this display type is not recommended; many
 774 .Nm
 775 implementations render it poorly.
 776 .It Fl filled
 777 Change the positions of line breaks to fill each line, and left- and
 778 right-justify the resulting block.
 779 .It Fl literal
 780 Produce one output line from each input line,
 781 and do not justify the block at all.
 782 Preserve white space as it appears in the input.
 783 Always use a constant-width font.
 784 Use this for displaying source code.
 785 .It Fl ragged
 786 Change the positions of line breaks to fill each line, and left-justify
 787 the resulting block.
 788 .It Fl unfilled
 789 The same as
 790 .Fl literal ,
 791 but using the same font as for normal text, which is a variable width font
 792 if supported by the output device.
 793 .El
 794 .Pp
 795 The
 796 .Ar type
 797 must be provided first.
 798 Additional arguments may follow:
 799 .Bl -tag -width 13n -offset indent
 800 .It Fl offset Ar width
 801 Indent the display by the
 802 .Ar width ,
 803 which may be one of the following:
 804 .Bl -item
 805 .It
 806 One of the pre-defined strings
 807 .Cm indent ,
 808 the width of a standard indentation (six constant width characters);
 809 .Cm indent-two ,
 810 twice
 811 .Cm indent ;
 812 .Cm left ,
 813 which has no effect;
 814 .Cm right ,
 815 which justifies to the right margin; or
 816 .Cm center ,
 817 which aligns around an imagined centre axis.
 818 .It
 819 A macro invocation, which selects a predefined width
 820 associated with that macro.
 821 The most popular is the imaginary macro
 822 .Ar \&Ds ,
 823 which resolves to
 824 .Sy 6n .
 825 .It
 826 A scaling width as described in
 827 .Xr roff 7 .
 828 .It
 829 An arbitrary string, which indents by the length of this string.
 830 .El
 831 .Pp
 832 When the argument is missing,
 833 .Fl offset
 834 is ignored.
 835 .It Fl compact
 836 Do not assert vertical space before the display.
 837 .El
 838 .Pp
 839 Examples:
 840 .Bd -literal -offset indent
 841 \&.Bd \-literal \-offset indent \-compact
 842    Hello       world.
 843 \&.Ed
 844 .Ed
 845 .Pp
 846 See also
 847 .Sx \&D1
 848 and
 849 .Sx \&Dl .
 850 .Ss \&Bf
 851 Change the font mode for a scoped block of text.
 852 Its syntax is as follows:
 853 .Bd -ragged -offset indent
 854 .Pf \. Sx \&Bf
 855 .Oo
 856 .Fl emphasis | literal | symbolic |
 857 .Cm \&Em | \&Li | \&Sy
 858 .Oc
 859 .Ed
 860 .Pp
 861 The
 862 .Fl emphasis
 863 and
 864 .Cm \&Em
 865 argument are equivalent, as are
 866 .Fl symbolic
 867 and
 868 .Cm \&Sy ,
 869 and
 870 .Fl literal
 871 and
 872 .Cm \&Li .
 873 Without an argument, this macro does nothing.
 874 The font mode continues until broken by a new font mode in a nested
 875 scope or
 876 .Sx \&Ef
 877 is encountered.
 878 .Pp
 879 See also
 880 .Sx \&Li ,
 881 .Sx \&Ef ,
 882 .Sx \&Em ,
 883 and
 884 .Sx \&Sy .
 885 .Ss \&Bk
 886 For each macro, keep its output together on the same output line,
 887 until the end of the macro or the end of the input line is reached,
 888 whichever comes first.
 889 Line breaks in text lines are unaffected.
 890 The syntax is as follows:
 891 .Pp
 892 .D1 Pf \. Sx \&Bk Fl words
 893 .Pp
 894 The
 895 .Fl words
 896 argument is required; additional arguments are ignored.
 897 .Pp
 898 The following example will not break within each
 899 .Sx \&Op
 900 macro line:
 901 .Bd -literal -offset indent
 902 \&.Bk \-words
 903 \&.Op Fl f Ar flags
 904 \&.Op Fl o Ar output
 905 \&.Ek
 906 .Ed
 907 .Pp
 908 Be careful in using over-long lines within a keep block!
 909 Doing so will clobber the right margin.
 910 .Ss \&Bl
 911 Begin a list.
 912 Lists consist of items specified using the
 913 .Sx \&It
 914 macro, containing a head or a body or both.
 915 The list syntax is as follows:
 916 .Bd -ragged -offset indent
 917 .Pf \. Sx \&Bl
 918 .Fl Ns Ar type
 919 .Op Fl width Ar val
 920 .Op Fl offset Ar val
 921 .Op Fl compact
 922 .Op HEAD ...
 923 .Ed
 924 .Pp
 925 The list
 926 .Ar type
 927 is mandatory and must be specified first.
 928 The
 929 .Fl width
 930 and
 931 .Fl offset
 932 arguments accept scaling widths as described in
 933 .Xr roff 7
 934 or use the length of the given string.
 935 The
 936 .Fl offset
 937 is a global indentation for the whole list, affecting both item heads
 938 and bodies.
 939 For those list types supporting it, the
 940 .Fl width
 941 argument requests an additional indentation of item bodies,
 942 to be added to the
 943 .Fl offset .
 944 Unless the
 945 .Fl compact
 946 argument is specified, list entries are separated by vertical space.
 947 .Pp
 948 A list must specify one of the following list types:
 949 .Bl -tag -width 12n -offset indent
 950 .It Fl bullet
 951 No item heads can be specified, but a bullet will be printed at the head
 952 of each item.
 953 Item bodies start on the same output line as the bullet
 954 and are indented according to the
 955 .Fl width
 956 argument.
 957 .It Fl column
 958 A columnated list.
 959 The
 960 .Fl width
 961 argument has no effect; instead, each argument specifies the width
 962 of one column, using either the scaling width syntax described in
 963 .Xr roff 7
 964 or the string length of the argument.
 965 If the first line of the body of a
 966 .Fl column
 967 list is not an
 968 .Sx \&It
 969 macro line,
 970 .Sx \&It
 971 contexts spanning one input line each are implied until an
 972 .Sx \&It
 973 macro line is encountered, at which point items start being interpreted as
 974 described in the
 975 .Sx \&It
 976 documentation.
 977 .It Fl dash
 978 Like
 979 .Fl bullet ,
 980 except that dashes are used in place of bullets.
 981 .It Fl diag
 982 Like
 983 .Fl inset ,
 984 except that item heads are not parsed for macro invocations.
 985 Most often used in the
 986 .Em DIAGNOSTICS
 987 section with error constants in the item heads.
 988 .It Fl enum
 989 A numbered list.
 990 No item heads can be specified.
 991 Formatted like
 992 .Fl bullet ,
 993 except that cardinal numbers are used in place of bullets,
 994 starting at 1.
 995 .It Fl hang
 996 Like
 997 .Fl tag ,
 998 except that the first lines of item bodies are not indented, but follow
 999 the item heads like in
1000 .Fl inset
1001 lists.
1002 .It Fl hyphen
1003 Synonym for
1004 .Fl dash .
1005 .It Fl inset
1006 Item bodies follow items heads on the same line, using normal inter-word
1007 spacing.
1008 Bodies are not indented, and the
1009 .Fl width
1010 argument is ignored.
1011 .It Fl item
1012 No item heads can be specified, and none are printed.
1013 Bodies are not indented, and the
1014 .Fl width
1015 argument is ignored.
1016 .It Fl ohang
1017 Item bodies start on the line following item heads and are not indented.
1018 The
1019 .Fl width
1020 argument is ignored.
1021 .It Fl tag
1022 Item bodies are indented according to the
1023 .Fl width
1024 argument.
1025 When an item head fits inside the indentation, the item body follows
1026 this head on the same output line.
1027 Otherwise, the body starts on the output line following the head.
1028 .El
1029 .Pp
1030 Lists may be nested within lists and displays.
1031 Nesting of
1032 .Fl column
1033 and
1034 .Fl enum
1035 lists may not be portable.
1036 .Pp
1037 See also
1038 .Sx \&El
1039 and
1040 .Sx \&It .
1041 .Ss \&Bo
1042 Begin a block enclosed by square brackets.
1043 Does not have any head arguments.
1044 .Pp
1045 Examples:
1046 .Bd -literal -offset indent -compact
1047 \&.Bo 1 ,
1048 \&.Dv BUFSIZ \&Bc
1049 .Ed
1050 .Pp
1051 See also
1052 .Sx \&Bq .
1053 .Ss \&Bq
1054 Encloses its arguments in square brackets.
1055 .Pp
1056 Examples:
1057 .Dl \&.Bq 1 , \&Dv BUFSIZ
1058 .Pp
1059 .Em Remarks :
1060 this macro is sometimes abused to emulate optional arguments for
1061 commands; the correct macros to use for this purpose are
1062 .Sx \&Op ,
1063 .Sx \&Oo ,
1064 and
1065 .Sx \&Oc .
1066 .Pp
1067 See also
1068 .Sx \&Bo .
1069 .Ss \&Brc
1070 Close a
1071 .Sx \&Bro
1072 block.
1073 Does not have any tail arguments.
1074 .Ss \&Bro
1075 Begin a block enclosed by curly braces.
1076 Does not have any head arguments.
1077 .Pp
1078 Examples:
1079 .Bd -literal -offset indent -compact
1080 \&.Bro 1 , ... ,
1081 \&.Va n \&Brc
1082 .Ed
1083 .Pp
1084 See also
1085 .Sx \&Brq .
1086 .Ss \&Brq
1087 Encloses its arguments in curly braces.
1088 .Pp
1089 Examples:
1090 .Dl \&.Brq 1 , ... , \&Va n
1091 .Pp
1092 See also
1093 .Sx \&Bro .
1094 .Ss \&Bsx
1095 Format the
1096 .Bsx
1097 version provided as an argument, or a default value if
1098 no argument is provided.
1099 .Pp
1100 Examples:
1101 .Dl \&.Bsx 1.0
1102 .Dl \&.Bsx
1103 .Pp
1104 See also
1105 .Sx \&At ,
1106 .Sx \&Bx ,
1107 .Sx \&Dx ,
1108 .Sx \&Fx ,
1109 .Sx \&Nx ,
1110 .Sx \&Ox ,
1111 and
1112 .Sx \&Ux .
1113 .Ss \&Bt
1114 Prints
1115 .Dq is currently in beta test.
1116 .Ss \&Bx
1117 Format the
1118 .Bx
1119 version provided as an argument, or a default value if no
1120 argument is provided.
1121 .Pp
1122 Examples:
1123 .Dl \&.Bx 4.3 Tahoe
1124 .Dl \&.Bx 4.4
1125 .Dl \&.Bx
1126 .Pp
1127 See also
1128 .Sx \&At ,
1129 .Sx \&Bsx ,
1130 .Sx \&Dx ,
1131 .Sx \&Fx ,
1132 .Sx \&Nx ,
1133 .Sx \&Ox ,
1134 and
1135 .Sx \&Ux .
1136 .Ss \&Cd
1137 Kernel configuration declaration.
1138 This denotes strings accepted by
1139 .Xr config 8 .
1140 It is most often used in section 4 manual pages.
1141 .Pp
1142 Examples:
1143 .Dl \&.Cd device le0 at scode?
1144 .Pp
1145 .Em Remarks :
1146 this macro is commonly abused by using quoted literals to retain
1147 whitespace and align consecutive
1148 .Sx \&Cd
1149 declarations.
1150 This practise is discouraged.
1151 .Ss \&Cm
1152 Command modifiers.
1153 Typically used for fixed strings passed as arguments, unless
1154 .Sx \&Fl
1155 is more appropriate.
1156 Also useful when specifying configuration options or keys.
1157 .Pp
1158 Examples:
1159 .Dl ".Nm mt Fl f Ar device Cm rewind"
1160 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1161 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1162 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1163 .Dl ".Cm LogLevel Dv DEBUG"
1164 .Ss \&D1
1165 One-line indented display.
1166 This is formatted by the default rules and is useful for simple indented
1167 statements.
1168 It is followed by a newline.
1169 .Pp
1170 Examples:
1171 .Dl \&.D1 \&Fl abcdefgh
1172 .Pp
1173 See also
1174 .Sx \&Bd
1175 and
1176 .Sx \&Dl .
1177 .Ss \&Db
1178 Switch debugging mode.
1179 Its syntax is as follows:
1180 .Pp
1181 .D1 Pf \. Sx \&Db Cm on | off
1182 .Pp
1183 This macro is ignored by
1184 .Xr mandoc 1 .
1185 .Ss \&Dc
1186 Close a
1187 .Sx \&Do
1188 block.
1189 Does not have any tail arguments.
1190 .Ss \&Dd
1191 Document date.
1192 This is the mandatory first macro of any
1193 .Nm
1194 manual.
1195 Its syntax is as follows:
1196 .Pp
1197 .D1 Pf \. Sx \&Dd Ar month day , year
1198 .Pp
1199 The
1200 .Ar month
1201 is the full English month name, the
1202 .Ar day
1203 is an optionally zero-padded numeral, and the
1204 .Ar year
1205 is the full four-digit year.
1206 .Pp
1207 Other arguments are not portable; the
1208 .Xr mandoc 1
1209 utility handles them as follows:
1210 .Bl -dash -offset 3n -compact
1211 .It
1212 To have the date automatically filled in by the
1213 .Ox
1214 version of
1215 .Xr cvs 1 ,
1216 the special string
1217 .Dq $\&Mdocdate$
1218 can be given as an argument.
1219 .It
1220 A few alternative date formats are accepted as well
1221 and converted to the standard form.
1222 .It
1223 If a date string cannot be parsed, it is used verbatim.
1224 .It
1225 If no date string is given, the current date is used.
1226 .El
1227 .Pp
1228 Examples:
1229 .Dl \&.Dd $\&Mdocdate$
1230 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1231 .Dl \&.Dd July 21, 2007
1232 .Pp
1233 See also
1234 .Sx \&Dt
1235 and
1236 .Sx \&Os .
1237 .Ss \&Dl
1238 One-line intended display.
1239 This is formatted as literal text and is useful for commands and
1240 invocations.
1241 It is followed by a newline.
1242 .Pp
1243 Examples:
1244 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1245 .Pp
1246 See also
1247 .Sx \&Bd
1248 and
1249 .Sx \&D1 .
1250 .Ss \&Do
1251 Begin a block enclosed by double quotes.
1252 Does not have any head arguments.
1253 .Pp
1254 Examples:
1255 .Bd -literal -offset indent -compact
1256 \&.Do
1257 April is the cruellest month
1258 \&.Dc
1259 \e(em T.S. Eliot
1260 .Ed
1261 .Pp
1262 See also
1263 .Sx \&Dq .
1264 .Ss \&Dq
1265 Encloses its arguments in
1266 .Dq typographic
1267 double-quotes.
1268 .Pp
1269 Examples:
1270 .Bd -literal -offset indent -compact
1271 \&.Dq April is the cruellest month
1272 \e(em T.S. Eliot
1273 .Ed
1274 .Pp
1275 See also
1276 .Sx \&Qq ,
1277 .Sx \&Sq ,
1278 and
1279 .Sx \&Do .
1280 .Ss \&Dt
1281 Document title.
1282 This is the mandatory second macro of any
1283 .Nm
1284 file.
1285 Its syntax is as follows:
1286 .Bd -ragged -offset indent
1287 .Pf \. Sx \&Dt
1288 .Oo
1289 .Ar title
1290 .Oo
1291 .Ar section
1292 .Op Ar volume
1293 .Op Ar arch
1294 .Oc
1295 .Oc
1296 .Ed
1297 .Pp
1298 Its arguments are as follows:
1299 .Bl -tag -width Ds -offset Ds
1300 .It Ar title
1301 The document's title (name), defaulting to
1302 .Dq UNKNOWN
1303 if unspecified.
1304 It should be capitalised.
1305 .It Ar section
1306 The manual section.
1307 This may be one of
1308 .Ar 1
1309 .Pq utilities ,
1310 .Ar 2
1311 .Pq system calls ,
1312 .Ar 3
1313 .Pq libraries ,
1314 .Ar 3p
1315 .Pq Perl libraries ,
1316 .Ar 4
1317 .Pq devices ,
1318 .Ar 5
1319 .Pq file formats ,
1320 .Ar 6
1321 .Pq games ,
1322 .Ar 7
1323 .Pq miscellaneous ,
1324 .Ar 8
1325 .Pq system utilities ,
1326 .Ar 9
1327 .Pq kernel functions ,
1328 .Ar X11
1329 .Pq X Window System ,
1330 .Ar X11R6
1331 .Pq X Window System ,
1332 .Ar unass
1333 .Pq unassociated ,
1334 .Ar local
1335 .Pq local system ,
1336 .Ar draft
1337 .Pq draft manual ,
1338 or
1339 .Ar paper
1340 .Pq paper .
1341 It should correspond to the manual's filename suffix and defaults to
1342 .Dq 1
1343 if unspecified.
1344 .It Ar volume
1345 This overrides the volume inferred from
1346 .Ar section .
1347 This field is optional, and if specified, must be one of
1348 .Ar USD
1349 .Pq users' supplementary documents ,
1350 .Ar PS1
1351 .Pq programmers' supplementary documents ,
1352 .Ar AMD
1353 .Pq administrators' supplementary documents ,
1354 .Ar SMM
1355 .Pq system managers' manuals ,
1356 .Ar URM
1357 .Pq users' reference manuals ,
1358 .Ar PRM
1359 .Pq programmers' reference manuals ,
1360 .Ar KM
1361 .Pq kernel manuals ,
1362 .Ar IND
1363 .Pq master index ,
1364 .Ar MMI
1365 .Pq master index ,
1366 .Ar LOCAL
1367 .Pq local manuals ,
1368 .Ar LOC
1369 .Pq local manuals ,
1370 or
1371 .Ar CON
1372 .Pq contributed manuals .
1373 .It Ar arch
1374 This specifies the machine architecture a manual page applies to,
1375 where relevant, for example
1376 .Cm alpha ,
1377 .Cm amd64 ,
1378 .Cm i386 ,
1379 or
1380 .Cm sparc64 .
1381 The list of supported architectures varies by operating system.
1382 For the full list of all architectures recognized by
1383 .Xr mandoc 1 ,
1384 see the file
1385 .Pa arch.in
1386 in the source distribution.
1387 .El
1388 .Pp
1389 Examples:
1390 .Dl \&.Dt FOO 1
1391 .Dl \&.Dt FOO 4 KM
1392 .Dl \&.Dt FOO 9 i386
1393 .Pp
1394 See also
1395 .Sx \&Dd
1396 and
1397 .Sx \&Os .
1398 .Ss \&Dv
1399 Defined variables such as preprocessor constants, constant symbols,
1400 enumeration values, and so on.
1401 .Pp
1402 Examples:
1403 .Dl \&.Dv NULL
1404 .Dl \&.Dv BUFSIZ
1405 .Dl \&.Dv STDOUT_FILENO
1406 .Pp
1407 See also
1408 .Sx \&Er
1409 and
1410 .Sx \&Ev
1411 for special-purpose constants,
1412 .Sx \&Va
1413 for variable symbols, and
1414 .Sx \&Fd
1415 for listing preprocessor variable definitions in the
1416 .Em SYNOPSIS .
1417 .Ss \&Dx
1418 Format the
1419 .Dx
1420 version provided as an argument, or a default
1421 value if no argument is provided.
1422 .Pp
1423 Examples:
1424 .Dl \&.Dx 2.4.1
1425 .Dl \&.Dx
1426 .Pp
1427 See also
1428 .Sx \&At ,
1429 .Sx \&Bsx ,
1430 .Sx \&Bx ,
1431 .Sx \&Fx ,
1432 .Sx \&Nx ,
1433 .Sx \&Ox ,
1434 and
1435 .Sx \&Ux .
1436 .Ss \&Ec
1437 Close a scope started by
1438 .Sx \&Eo .
1439 Its syntax is as follows:
1440 .Pp
1441 .D1 Pf \. Sx \&Ec Op Ar TERM
1442 .Pp
1443 The
1444 .Ar TERM
1445 argument is used as the enclosure tail, for example, specifying \e(rq
1446 will emulate
1447 .Sx \&Dc .
1448 .Ss \&Ed
1449 End a display context started by
1450 .Sx \&Bd .
1451 .Ss \&Ef
1452 End a font mode context started by
1453 .Sx \&Bf .
1454 .Ss \&Ek
1455 End a keep context started by
1456 .Sx \&Bk .
1457 .Ss \&El
1458 End a list context started by
1459 .Sx \&Bl .
1460 .Pp
1461 See also
1462 .Sx \&Bl
1463 and
1464 .Sx \&It .
1465 .Ss \&Em
1466 Denotes text that should be
1467 .Em emphasised .
1468 Note that this is a presentation term and should not be used for
1469 stylistically decorating technical terms.
1470 Depending on the output device, this is usually represented
1471 using an italic font or underlined characters.
1472 .Pp
1473 Examples:
1474 .Dl \&.Em Warnings!
1475 .Dl \&.Em Remarks :
1476 .Pp
1477 See also
1478 .Sx \&Bf ,
1479 .Sx \&Li ,
1480 .Sx \&No ,
1481 and
1482 .Sx \&Sy .
1483 .Ss \&En
1484 This macro is obsolete and not implemented in
1485 .Xr mandoc 1 .
1486 .Ss \&Eo
1487 An arbitrary enclosure.
1488 Its syntax is as follows:
1489 .Pp
1490 .D1 Pf \. Sx \&Eo Op Ar TERM
1491 .Pp
1492 The
1493 .Ar TERM
1494 argument is used as the enclosure head, for example, specifying \e(lq
1495 will emulate
1496 .Sx \&Do .
1497 .Ss \&Er
1498 Error constants for definitions of the
1499 .Va errno
1500 libc global variable.
1501 This is most often used in section 2 and 3 manual pages.
1502 .Pp
1503 Examples:
1504 .Dl \&.Er EPERM
1505 .Dl \&.Er ENOENT
1506 .Pp
1507 See also
1508 .Sx \&Dv
1509 for general constants.
1510 .Ss \&Es
1511 This macro is obsolete and not implemented.
1512 .Ss \&Ev
1513 Environmental variables such as those specified in
1514 .Xr environ 7 .
1515 .Pp
1516 Examples:
1517 .Dl \&.Ev DISPLAY
1518 .Dl \&.Ev PATH
1519 .Pp
1520 See also
1521 .Sx \&Dv
1522 for general constants.
1523 .Ss \&Ex
1524 Insert a standard sentence regarding command exit values of 0 on success
1525 and >0 on failure.
1526 This is most often used in section 1, 6, and 8 manual pages.
1527 Its syntax is as follows:
1528 .Pp
1529 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1530 .Pp
1531 If
1532 .Ar utility
1533 is not specified, the document's name set by
1534 .Sx \&Nm
1535 is used.
1536 Multiple
1537 .Ar utility
1538 arguments are treated as separate utilities.
1539 .Pp
1540 See also
1541 .Sx \&Rv .
1542 .Ss \&Fa
1543 Function argument.
1544 Its syntax is as follows:
1545 .Bd -ragged -offset indent
1546 .Pf \. Sx \&Fa
1547 .Op Cm argtype
1548 .Cm argname
1549 .Ed
1550 .Pp
1551 This may be invoked for names with or without the corresponding type.
1552 It is also used to specify the field name of a structure.
1553 Most often, the
1554 .Sx \&Fa
1555 macro is used in the
1556 .Em SYNOPSIS
1557 within
1558 .Sx \&Fo
1559 section when documenting multi-line function prototypes.
1560 If invoked with multiple arguments, the arguments are separated by a
1561 comma.
1562 Furthermore, if the following macro is another
1563 .Sx \&Fa ,
1564 the last argument will also have a trailing comma.
1565 .Pp
1566 Examples:
1567 .Dl \&.Fa \(dqconst char *p\(dq
1568 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1569 .Dl \&.Fa foo
1570 .Pp
1571 See also
1572 .Sx \&Fo .
1573 .Ss \&Fc
1574 End a function context started by
1575 .Sx \&Fo .
1576 .Ss \&Fd
1577 Preprocessor directive, in particular for listing it in the
1578 .Em SYNOPSIS .
1579 Historically, it was also used to document include files.
1580 The latter usage has been deprecated in favour of
1581 .Sx \&In .
1582 .Pp
1583 Its syntax is as follows:
1584 .Bd -ragged -offset indent
1585 .Pf \. Sx \&Fd
1586 .Li # Ns Ar directive
1587 .Op Ar argument ...
1588 .Ed
1589 .Pp
1590 Examples:
1591 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1592 .Dl \&.Fd #define SIO_MAXNFDS
1593 .Dl \&.Fd #ifdef FS_DEBUG
1594 .Dl \&.Ft void
1595 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1596 .Dl \&.Fd #endif
1597 .Pp
1598 See also
1599 .Sx MANUAL STRUCTURE ,
1600 .Sx \&In ,
1601 and
1602 .Sx \&Dv .
1603 .Ss \&Fl
1604 Command-line flag or option.
1605 Used when listing arguments to command-line utilities.
1606 Prints a fixed-width hyphen
1607 .Sq \-
1608 directly followed by each argument.
1609 If no arguments are provided, a hyphen is printed followed by a space.
1610 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1611 output.
1612 .Pp
1613 Examples:
1614 .Dl ".Fl R Op Fl H | L | P"
1615 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1616 .Dl ".Fl type Cm d Fl name Pa CVS"
1617 .Dl ".Fl Ar signal_number"
1618 .Dl ".Fl o Fl"
1619 .Pp
1620 See also
1621 .Sx \&Cm .
1622 .Ss \&Fn
1623 A function name.
1624 Its syntax is as follows:
1625 .Bd -ragged -offset indent
1626 .Pf \. Ns Sx \&Fn
1627 .Op Ar functype
1628 .Ar funcname
1629 .Op Oo Ar argtype Oc Ar argname
1630 .Ed
1631 .Pp
1632 Function arguments are surrounded in parenthesis and
1633 are delimited by commas.
1634 If no arguments are specified, blank parenthesis are output.
1635 In the
1636 .Em SYNOPSIS
1637 section, this macro starts a new output line,
1638 and a blank line is automatically inserted between function definitions.
1639 .Pp
1640 Examples:
1641 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1642 .Dl \&.Fn funcname \(dqint arg0\(dq
1643 .Dl \&.Fn funcname arg0
1644 .Pp
1645 .Bd -literal -offset indent -compact
1646 \&.Ft functype
1647 \&.Fn funcname
1648 .Ed
1649 .Pp
1650 When referring to a function documented in another manual page, use
1651 .Sx \&Xr
1652 instead.
1653 See also
1654 .Sx MANUAL STRUCTURE ,
1655 .Sx \&Fo ,
1656 and
1657 .Sx \&Ft .
1658 .Ss \&Fo
1659 Begin a function block.
1660 This is a multi-line version of
1661 .Sx \&Fn .
1662 Its syntax is as follows:
1663 .Pp
1664 .D1 Pf \. Sx \&Fo Ar funcname
1665 .Pp
1666 Invocations usually occur in the following context:
1667 .Bd -ragged -offset indent
1668 .Pf \. Sx \&Ft Ar functype
1669 .br
1670 .Pf \. Sx \&Fo Ar funcname
1671 .br
1672 .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
1673 .br
1674 \&.\.\.
1675 .br
1676 .Pf \. Sx \&Fc
1677 .Ed
1678 .Pp
1679 A
1680 .Sx \&Fo
1681 scope is closed by
1682 .Sx \&Fc .
1683 .Pp
1684 See also
1685 .Sx MANUAL STRUCTURE ,
1686 .Sx \&Fa ,
1687 .Sx \&Fc ,
1688 and
1689 .Sx \&Ft .
1690 .Ss \&Fr
1691 This macro is obsolete and not implemented in
1692 .Xr mandoc 1 .
1693 .Pp
1694 It was used to show function return values.
1695 The syntax was:
1696 .Pp
1697 .Dl Pf . Sx \&Fr Ar value
1698 .Ss \&Ft
1699 A function type.
1700 Its syntax is as follows:
1701 .Pp
1702 .D1 Pf \. Sx \&Ft Ar functype
1703 .Pp
1704 In the
1705 .Em SYNOPSIS
1706 section, a new output line is started after this macro.
1707 .Pp
1708 Examples:
1709 .Dl \&.Ft int
1710 .Bd -literal -offset indent -compact
1711 \&.Ft functype
1712 \&.Fn funcname
1713 .Ed
1714 .Pp
1715 See also
1716 .Sx MANUAL STRUCTURE ,
1717 .Sx \&Fn ,
1718 and
1719 .Sx \&Fo .
1720 .Ss \&Fx
1721 Format the
1722 .Fx
1723 version provided as an argument, or a default value
1724 if no argument is provided.
1725 .Pp
1726 Examples:
1727 .Dl \&.Fx 7.1
1728 .Dl \&.Fx
1729 .Pp
1730 See also
1731 .Sx \&At ,
1732 .Sx \&Bsx ,
1733 .Sx \&Bx ,
1734 .Sx \&Dx ,
1735 .Sx \&Nx ,
1736 .Sx \&Ox ,
1737 and
1738 .Sx \&Ux .
1739 .Ss \&Hf
1740 This macro is not implemented in
1741 .Xr mandoc 1 .
1742 .Pp
1743 It was used to include the contents of a (header) file literally.
1744 The syntax was:
1745 .Pp
1746 .Dl Pf . Sx \&Hf Ar filename
1747 .Ss \&Ic
1748 Designate an internal or interactive command.
1749 This is similar to
1750 .Sx \&Cm
1751 but used for instructions rather than values.
1752 .Pp
1753 Examples:
1754 .Dl \&.Ic :wq
1755 .Dl \&.Ic hash
1756 .Dl \&.Ic alias
1757 .Pp
1758 Note that using
1759 .Sx \&Bd Fl literal
1760 or
1761 .Sx \&D1
1762 is preferred for displaying code; the
1763 .Sx \&Ic
1764 macro is used when referring to specific instructions.
1765 .Ss \&In
1766 An
1767 .Dq include
1768 file.
1769 When invoked as the first macro on an input line in the
1770 .Em SYNOPSIS
1771 section, the argument is displayed in angle brackets
1772 and preceded by
1773 .Dq #include ,
1774 and a blank line is inserted in front if there is a preceding
1775 function declaration.
1776 This is most often used in section 2, 3, and 9 manual pages.
1777 .Pp
1778 Examples:
1779 .Dl \&.In sys/types.h
1780 .Pp
1781 See also
1782 .Sx MANUAL STRUCTURE .
1783 .Ss \&It
1784 A list item.
1785 The syntax of this macro depends on the list type.
1786 .Pp
1787 Lists
1788 of type
1789 .Fl hang ,
1790 .Fl ohang ,
1791 .Fl inset ,
1792 and
1793 .Fl diag
1794 have the following syntax:
1795 .Pp
1796 .D1 Pf \. Sx \&It Ar args
1797 .Pp
1798 Lists of type
1799 .Fl bullet ,
1800 .Fl dash ,
1801 .Fl enum ,
1802 .Fl hyphen
1803 and
1804 .Fl item
1805 have the following syntax:
1806 .Pp
1807 .D1 Pf \. Sx \&It
1808 .Pp
1809 with subsequent lines interpreted within the scope of the
1810 .Sx \&It
1811 until either a closing
1812 .Sx \&El
1813 or another
1814 .Sx \&It .
1815 .Pp
1816 The
1817 .Fl tag
1818 list has the following syntax:
1819 .Pp
1820 .D1 Pf \. Sx \&It Op Cm args
1821 .Pp
1822 Subsequent lines are interpreted as with
1823 .Fl bullet
1824 and family.
1825 The line arguments correspond to the list's left-hand side; body
1826 arguments correspond to the list's contents.
1827 .Pp
1828 The
1829 .Fl column
1830 list is the most complicated.
1831 Its syntax is as follows:
1832 .Pp
1833 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1834 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1835 .Pp
1836 The arguments consist of one or more lines of text and macros
1837 representing a complete table line.
1838 Cells within the line are delimited by tabs or by the special
1839 .Sx \&Ta
1840 block macro.
1841 The tab cell delimiter may only be used within the
1842 .Sx \&It
1843 line itself; on following lines, only the
1844 .Sx \&Ta
1845 macro can be used to delimit cells, and
1846 .Sx \&Ta
1847 is only recognised as a macro when called by other macros,
1848 not as the first macro on a line.
1849 .Pp
1850 Note that quoted strings may span tab-delimited cells on an
1851 .Sx \&It
1852 line.
1853 For example,
1854 .Pp
1855 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
1856 .Pp
1857 will preserve the semicolon whitespace except for the last.
1858 .Pp
1859 See also
1860 .Sx \&Bl .
1861 .Ss \&Lb
1862 Specify a library.
1863 The syntax is as follows:
1864 .Pp
1865 .D1 Pf \. Sx \&Lb Ar library
1866 .Pp
1867 The
1868 .Ar library
1869 parameter may be a system library, such as
1870 .Cm libz
1871 or
1872 .Cm libpam ,
1873 in which case a small library description is printed next to the linker
1874 invocation; or a custom library, in which case the library name is
1875 printed in quotes.
1876 This is most commonly used in the
1877 .Em SYNOPSIS
1878 section as described in
1879 .Sx MANUAL STRUCTURE .
1880 .Pp
1881 Examples:
1882 .Dl \&.Lb libz
1883 .Dl \&.Lb libmandoc
1884 .Ss \&Li
1885 Denotes text that should be in a
1886 .Li literal
1887 font mode.
1888 Note that this is a presentation term and should not be used for
1889 stylistically decorating technical terms.
1890 .Pp
1891 On terminal output devices, this is often indistinguishable from
1892 normal text.
1893 .Pp
1894 See also
1895 .Sx \&Bf ,
1896 .Sx \&Em ,
1897 .Sx \&No ,
1898 and
1899 .Sx \&Sy .
1900 .Ss \&Lk
1901 Format a hyperlink.
1902 Its syntax is as follows:
1903 .Pp
1904 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1905 .Pp
1906 Examples:
1907 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
1908 .Dl \&.Lk http://bsd.lv
1909 .Pp
1910 See also
1911 .Sx \&Mt .
1912 .Ss \&Lp
1913 Synonym for
1914 .Sx \&Pp .
1915 .Ss \&Ms
1916 Display a mathematical symbol.
1917 Its syntax is as follows:
1918 .Pp
1919 .D1 Pf \. Sx \&Ms Ar symbol
1920 .Pp
1921 Examples:
1922 .Dl \&.Ms sigma
1923 .Dl \&.Ms aleph
1924 .Ss \&Mt
1925 Format a
1926 .Dq mailto:
1927 hyperlink.
1928 Its syntax is as follows:
1929 .Pp
1930 .D1 Pf \. Sx \&Mt Ar address
1931 .Pp
1932 Examples:
1933 .Dl \&.Mt discuss@manpages.bsd.lv
1934 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
1935 .Ss \&Nd
1936 A one line description of the manual's content.
1937 This may only be invoked in the
1938 .Em SYNOPSIS
1939 section subsequent the
1940 .Sx \&Nm
1941 macro.
1942 .Pp
1943 Examples:
1944 .Dl Pf . Sx \&Nd mdoc language reference
1945 .Dl Pf . Sx \&Nd format and display UNIX manuals
1946 .Pp
1947 The
1948 .Sx \&Nd
1949 macro technically accepts child macros and terminates with a subsequent
1950 .Sx \&Sh
1951 invocation.
1952 Do not assume this behaviour: some
1953 .Xr whatis 1
1954 database generators are not smart enough to parse more than the line
1955 arguments and will display macros verbatim.
1956 .Pp
1957 See also
1958 .Sx \&Nm .
1959 .Ss \&Nm
1960 The name of the manual page, or \(em in particular in section 1, 6,
1961 and 8 pages \(em of an additional command or feature documented in
1962 the manual page.
1963 When first invoked, the
1964 .Sx \&Nm
1965 macro expects a single argument, the name of the manual page.
1966 Usually, the first invocation happens in the
1967 .Em NAME
1968 section of the page.
1969 The specified name will be remembered and used whenever the macro is
1970 called again without arguments later in the page.
1971 The
1972 .Sx \&Nm
1973 macro uses
1974 .Sx Block full-implicit
1975 semantics when invoked as the first macro on an input line in the
1976 .Em SYNOPSIS
1977 section; otherwise, it uses ordinary
1978 .Sx In-line
1979 semantics.
1980 .Pp
1981 Examples:
1982 .Bd -literal -offset indent
1983 \&.Sh SYNOPSIS
1984 \&.Nm cat
1985 \&.Op Fl benstuv
1986 \&.Op Ar
1987 .Ed
1988 .Pp
1989 In the
1990 .Em SYNOPSIS
1991 of section 2, 3 and 9 manual pages, use the
1992 .Sx \&Fn
1993 macro rather than
1994 .Sx \&Nm
1995 to mark up the name of the manual page.
1996 .Ss \&No
1997 Normal text.
1998 Closes the scope of any preceding in-line macro.
1999 When used after physical formatting macros like
2000 .Sx \&Em
2001 or
2002 .Sx \&Sy ,
2003 switches back to the standard font face and weight.
2004 Can also be used to embed plain text strings in macro lines
2005 using semantic annotation macros.
2006 .Pp
2007 Examples:
2008 .Dl ".Em italic , Sy bold , No and roman"
2009 .Pp
2010 .Bd -literal -offset indent -compact
2011 \&.Sm off
2012 \&.Cm :C No / Ar pattern No / Ar replacement No /
2013 \&.Sm on
2014 .Ed
2015 .Pp
2016 See also
2017 .Sx \&Em ,
2018 .Sx \&Li ,
2019 and
2020 .Sx \&Sy .
2021 .Ss \&Ns
2022 Suppress a space between the output of the preceding macro
2023 and the following text or macro.
2024 Following invocation, input is interpreted as normal text
2025 just like after an
2026 .Sx \&No
2027 macro.
2028 .Pp
2029 This has no effect when invoked at the start of a macro line.
2030 .Pp
2031 Examples:
2032 .Dl ".Ar name Ns = Ns Ar value"
2033 .Dl ".Cm :M Ns Ar pattern"
2034 .Dl ".Fl o Ns Ar output"
2035 .Pp
2036 See also
2037 .Sx \&No
2038 and
2039 .Sx \&Sm .
2040 .Ss \&Nx
2041 Format the
2042 .Nx
2043 version provided as an argument, or a default value if
2044 no argument is provided.
2045 .Pp
2046 Examples:
2047 .Dl \&.Nx 5.01
2048 .Dl \&.Nx
2049 .Pp
2050 See also
2051 .Sx \&At ,
2052 .Sx \&Bsx ,
2053 .Sx \&Bx ,
2054 .Sx \&Dx ,
2055 .Sx \&Fx ,
2056 .Sx \&Ox ,
2057 and
2058 .Sx \&Ux .
2059 .Ss \&Oc
2060 Close multi-line
2061 .Sx \&Oo
2062 context.
2063 .Ss \&Oo
2064 Multi-line version of
2065 .Sx \&Op .
2066 .Pp
2067 Examples:
2068 .Bd -literal -offset indent -compact
2069 \&.Oo
2070 \&.Op Fl flag Ns Ar value
2071 \&.Oc
2072 .Ed
2073 .Ss \&Op
2074 Optional part of a command line.
2075 Prints the argument(s) in brackets.
2076 This is most often used in the
2077 .Em SYNOPSIS
2078 section of section 1 and 8 manual pages.
2079 .Pp
2080 Examples:
2081 .Dl \&.Op \&Fl a \&Ar b
2082 .Dl \&.Op \&Ar a | b
2083 .Pp
2084 See also
2085 .Sx \&Oo .
2086 .Ss \&Os
2087 Document operating system version.
2088 This is the mandatory third macro of
2089 any
2090 .Nm
2091 file.
2092 Its syntax is as follows:
2093 .Pp
2094 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2095 .Pp
2096 The optional
2097 .Ar system
2098 parameter specifies the relevant operating system or environment.
2099 Left unspecified, it defaults to the local operating system version.
2100 This is the suggested form.
2101 .Pp
2102 Examples:
2103 .Dl \&.Os
2104 .Dl \&.Os KTH/CSC/TCS
2105 .Dl \&.Os BSD 4.3
2106 .Pp
2107 See also
2108 .Sx \&Dd
2109 and
2110 .Sx \&Dt .
2111 .Ss \&Ot
2112 This macro is obsolete and not implemented in
2113 .Xr mandoc 1 .
2114 .Pp
2115 Historical
2116 .Nm
2117 packages described it as
2118 .Dq "old function type (FORTRAN)" .
2119 .Ss \&Ox
2120 Format the
2121 .Ox
2122 version provided as an argument, or a default value
2123 if no argument is provided.
2124 .Pp
2125 Examples:
2126 .Dl \&.Ox 4.5
2127 .Dl \&.Ox
2128 .Pp
2129 See also
2130 .Sx \&At ,
2131 .Sx \&Bsx ,
2132 .Sx \&Bx ,
2133 .Sx \&Dx ,
2134 .Sx \&Fx ,
2135 .Sx \&Nx ,
2136 and
2137 .Sx \&Ux .
2138 .Ss \&Pa
2139 An absolute or relative file system path, or a file or directory name.
2140 If an argument is not provided, the character
2141 .Sq \(ti
2142 is used as a default.
2143 .Pp
2144 Examples:
2145 .Dl \&.Pa /usr/bin/mandoc
2146 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2147 .Pp
2148 See also
2149 .Sx \&Lk .
2150 .Ss \&Pc
2151 Close parenthesised context opened by
2152 .Sx \&Po .
2153 .Ss \&Pf
2154 Removes the space between its argument
2155 .Pq Dq prefix
2156 and the following macro.
2157 Its syntax is as follows:
2158 .Pp
2159 .D1 .Pf Ar prefix macro arguments ...
2160 .Pp
2161 This is equivalent to:
2162 .Pp
2163 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2164 .Pp
2165 Examples:
2166 .Dl ".Pf $ Ar variable_name"
2167 .Dl ".Pf 0x Ar hex_digits"
2168 .Pp
2169 See also
2170 .Sx \&Ns
2171 and
2172 .Sx \&Sm .
2173 .Ss \&Po
2174 Multi-line version of
2175 .Sx \&Pq .
2176 .Ss \&Pp
2177 Break a paragraph.
2178 This will assert vertical space between prior and subsequent macros
2179 and/or text.
2180 .Pp
2181 Paragraph breaks are not needed before or after
2182 .Sx \&Sh
2183 or
2184 .Sx \&Ss
2185 macros or before displays
2186 .Pq Sx \&Bd
2187 or lists
2188 .Pq Sx \&Bl
2189 unless the
2190 .Fl compact
2191 flag is given.
2192 .Ss \&Pq
2193 Parenthesised enclosure.
2194 .Pp
2195 See also
2196 .Sx \&Po .
2197 .Ss \&Qc
2198 Close quoted context opened by
2199 .Sx \&Qo .
2200 .Ss \&Ql
2201 Format a single-quoted literal.
2202 See also
2203 .Sx \&Qq
2204 and
2205 .Sx \&Sq .
2206 .Ss \&Qo
2207 Multi-line version of
2208 .Sx \&Qq .
2209 .Ss \&Qq
2210 Encloses its arguments in
2211 .Qq typewriter
2212 double-quotes.
2213 Consider using
2214 .Sx \&Dq .
2215 .Pp
2216 See also
2217 .Sx \&Dq ,
2218 .Sx \&Sq ,
2219 and
2220 .Sx \&Qo .
2221 .Ss \&Re
2222 Close an
2223 .Sx \&Rs
2224 block.
2225 Does not have any tail arguments.
2226 .Ss \&Rs
2227 Begin a bibliographic
2228 .Pq Dq reference
2229 block.
2230 Does not have any head arguments.
2231 The block macro may only contain
2232 .Sx \&%A ,
2233 .Sx \&%B ,
2234 .Sx \&%C ,
2235 .Sx \&%D ,
2236 .Sx \&%I ,
2237 .Sx \&%J ,
2238 .Sx \&%N ,
2239 .Sx \&%O ,
2240 .Sx \&%P ,
2241 .Sx \&%Q ,
2242 .Sx \&%R ,
2243 .Sx \&%T ,
2244 .Sx \&%U ,
2245 and
2246 .Sx \&%V
2247 child macros (at least one must be specified).
2248 .Pp
2249 Examples:
2250 .Bd -literal -offset indent -compact
2251 \&.Rs
2252 \&.%A J. E. Hopcroft
2253 \&.%A J. D. Ullman
2254 \&.%B Introduction to Automata Theory, Languages, and Computation
2255 \&.%I Addison-Wesley
2256 \&.%C Reading, Massachusettes
2257 \&.%D 1979
2258 \&.Re
2259 .Ed
2260 .Pp
2261 If an
2262 .Sx \&Rs
2263 block is used within a SEE ALSO section, a vertical space is asserted
2264 before the rendered output, else the block continues on the current
2265 line.
2266 .Ss \&Rv
2267 Insert a standard sentence regarding a function call's return value of 0
2268 on success and \-1 on error, with the
2269 .Va errno
2270 libc global variable set on error.
2271 Its syntax is as follows:
2272 .Pp
2273 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2274 .Pp
2275 If
2276 .Ar function
2277 is not specified, the document's name set by
2278 .Sx \&Nm
2279 is used.
2280 Multiple
2281 .Ar function
2282 arguments are treated as separate functions.
2283 .Pp
2284 See also
2285 .Sx \&Ex .
2286 .Ss \&Sc
2287 Close single-quoted context opened by
2288 .Sx \&So .
2289 .Ss \&Sh
2290 Begin a new section.
2291 For a list of conventional manual sections, see
2292 .Sx MANUAL STRUCTURE .
2293 These sections should be used unless it's absolutely necessary that
2294 custom sections be used.
2295 .Pp
2296 Section names should be unique so that they may be keyed by
2297 .Sx \&Sx .
2298 Although this macro is parsed, it should not consist of child node or it
2299 may not be linked with
2300 .Sx \&Sx .
2301 .Pp
2302 See also
2303 .Sx \&Pp ,
2304 .Sx \&Ss ,
2305 and
2306 .Sx \&Sx .
2307 .Ss \&Sm
2308 Switches the spacing mode for output generated from macros.
2309 Its syntax is as follows:
2310 .Pp
2311 .D1 Pf \. Sx \&Sm Cm on | off
2312 .Pp
2313 By default, spacing is
2314 .Cm on .
2315 When switched
2316 .Cm off ,
2317 no white space is inserted between macro arguments and between the
2318 output generated from adjacent macros, but text lines
2319 still get normal spacing between words and sentences.
2320 .Ss \&So
2321 Multi-line version of
2322 .Sx \&Sq .
2323 .Ss \&Sq
2324 Encloses its arguments in
2325 .Sq typewriter
2326 single-quotes.
2327 .Pp
2328 See also
2329 .Sx \&Dq ,
2330 .Sx \&Qq ,
2331 and
2332 .Sx \&So .
2333 .Ss \&Ss
2334 Begin a new subsection.
2335 Unlike with
2336 .Sx \&Sh ,
2337 there is no convention for the naming of subsections.
2338 Except
2339 .Em DESCRIPTION ,
2340 the conventional sections described in
2341 .Sx MANUAL STRUCTURE
2342 rarely have subsections.
2343 .Pp
2344 Sub-section names should be unique so that they may be keyed by
2345 .Sx \&Sx .
2346 Although this macro is parsed, it should not consist of child node or it
2347 may not be linked with
2348 .Sx \&Sx .
2349 .Pp
2350 See also
2351 .Sx \&Pp ,
2352 .Sx \&Sh ,
2353 and
2354 .Sx \&Sx .
2355 .Ss \&St
2356 Replace an abbreviation for a standard with the full form.
2357 The following standards are recognised:
2358 .Pp
2359 .Bl -tag -width "-p1003.1g-2000X" -compact
2360 .It \-p1003.1-88
2361 .St -p1003.1-88
2362 .It \-p1003.1-90
2363 .St -p1003.1-90
2364 .It \-p1003.1-96
2365 .St -p1003.1-96
2366 .It \-p1003.1-2001
2367 .St -p1003.1-2001
2368 .It \-p1003.1-2004
2369 .St -p1003.1-2004
2370 .It \-p1003.1-2008
2371 .St -p1003.1-2008
2372 .It \-p1003.1
2373 .St -p1003.1
2374 .It \-p1003.1b
2375 .St -p1003.1b
2376 .It \-p1003.1b-93
2377 .St -p1003.1b-93
2378 .It \-p1003.1c-95
2379 .St -p1003.1c-95
2380 .It \-p1003.1d-99
2381 .St -p1003.1d-99
2382 .It \-p1003.1g-2000
2383 .St -p1003.1g-2000
2384 .It \-p1003.1i-95
2385 .St -p1003.1i-95
2386 .It \-p1003.1j-2000
2387 .St -p1003.1j-2000
2388 .It \-p1003.1q-2000
2389 .St -p1003.1q-2000
2390 .It \-p1003.2
2391 .St -p1003.2
2392 .It \-p1003.2-92
2393 .St -p1003.2-92
2394 .It \-p1003.2a-92
2395 .St -p1003.2a-92
2396 .It \-p1387.2
2397 .St -p1387.2
2398 .It \-p1387.2-95
2399 .St -p1387.2-95
2400 .It \-isoC
2401 .St -isoC
2402 .It \-isoC-90
2403 .St -isoC-90
2404 .It \-isoC-amd1
2405 .St -isoC-amd1
2406 .It \-isoC-tcor1
2407 .St -isoC-tcor1
2408 .It \-isoC-tcor2
2409 .St -isoC-tcor2
2410 .It \-isoC-99
2411 .St -isoC-99
2412 .It \-isoC-2011
2413 .St -isoC-2011
2414 .It \-iso9945-1-90
2415 .St -iso9945-1-90
2416 .It \-iso9945-1-96
2417 .St -iso9945-1-96
2418 .It \-iso9945-2-93
2419 .St -iso9945-2-93
2420 .It \-ansiC
2421 .St -ansiC
2422 .It \-ansiC-89
2423 .St -ansiC-89
2424 .It \-ansiC-99
2425 .St -ansiC-99
2426 .It \-ieee754
2427 .St -ieee754
2428 .It \-iso8802-3
2429 .St -iso8802-3
2430 .It \-iso8601
2431 .St -iso8601
2432 .It \-ieee1275-94
2433 .St -ieee1275-94
2434 .It \-xpg3
2435 .St -xpg3
2436 .It \-xpg4
2437 .St -xpg4
2438 .It \-xpg4.2
2439 .St -xpg4.2
2440 .It \-xpg4.3
2441 .St -xpg4.3
2442 .It \-xbd5
2443 .St -xbd5
2444 .It \-xcu5
2445 .St -xcu5
2446 .It \-xsh4.2
2447 .St -xsh4.2
2448 .It \-xsh5
2449 .St -xsh5
2450 .It \-xns5
2451 .St -xns5
2452 .It \-xns5.2
2453 .St -xns5.2
2454 .It \-xns5.2d2.0
2455 .St -xns5.2d2.0
2456 .It \-xcurses4.2
2457 .St -xcurses4.2
2458 .It \-susv2
2459 .St -susv2
2460 .It \-susv3
2461 .St -susv3
2462 .It \-svid4
2463 .St -svid4
2464 .El
2465 .Ss \&Sx
2466 Reference a section or subsection in the same manual page.
2467 The referenced section or subsection name must be identical to the
2468 enclosed argument, including whitespace.
2469 .Pp
2470 Examples:
2471 .Dl \&.Sx MANUAL STRUCTURE
2472 .Pp
2473 See also
2474 .Sx \&Sh
2475 and
2476 .Sx \&Ss .
2477 .Ss \&Sy
2478 Format enclosed arguments in symbolic
2479 .Pq Dq boldface .
2480 Note that this is a presentation term and should not be used for
2481 stylistically decorating technical terms.
2482 .Pp
2483 See also
2484 .Sx \&Bf ,
2485 .Sx \&Em ,
2486 .Sx \&Li ,
2487 and
2488 .Sx \&No .
2489 .Ss \&Ta
2490 Table cell separator in
2491 .Sx \&Bl Fl column
2492 lists; can only be used below
2493 .Sx \&It .
2494 .Ss \&Tn
2495 Format a tradename.
2496 .Pp
2497 Since this macro is often implemented to use a small caps font,
2498 it has historically been used for acronyms (like ASCII) as well.
2499 Such usage is not recommended because it would use the same macro
2500 sometimes for semantical annotation, sometimes for physical formatting.
2501 .Pp
2502 Examples:
2503 .Dl \&.Tn IBM
2504 .Ss \&Ud
2505 Prints out
2506 .Dq currently under development.
2507 .Ss \&Ux
2508 Format the
2509 .Ux
2510 name.
2511 Accepts no argument.
2512 .Pp
2513 Examples:
2514 .Dl \&.Ux
2515 .Pp
2516 See also
2517 .Sx \&At ,
2518 .Sx \&Bsx ,
2519 .Sx \&Bx ,
2520 .Sx \&Dx ,
2521 .Sx \&Fx ,
2522 .Sx \&Nx ,
2523 and
2524 .Sx \&Ox .
2525 .Ss \&Va
2526 A variable name.
2527 .Pp
2528 Examples:
2529 .Dl \&.Va foo
2530 .Dl \&.Va const char *bar ;
2531 .Ss \&Vt
2532 A variable type.
2533 This is also used for indicating global variables in the
2534 .Em SYNOPSIS
2535 section, in which case a variable name is also specified.
2536 Note that it accepts
2537 .Sx Block partial-implicit
2538 syntax when invoked as the first macro on an input line in the
2539 .Em SYNOPSIS
2540 section, else it accepts ordinary
2541 .Sx In-line
2542 syntax.
2543 In the former case, this macro starts a new output line,
2544 and a blank line is inserted in front if there is a preceding
2545 function definition or include directive.
2546 .Pp
2547 Note that this should not be confused with
2548 .Sx \&Ft ,
2549 which is used for function return types.
2550 .Pp
2551 Examples:
2552 .Dl \&.Vt unsigned char
2553 .Dl \&.Vt extern const char * const sys_signame[] \&;
2554 .Pp
2555 See also
2556 .Sx MANUAL STRUCTURE
2557 and
2558 .Sx \&Va .
2559 .Ss \&Xc
2560 Close a scope opened by
2561 .Sx \&Xo .
2562 .Ss \&Xo
2563 Extend the header of an
2564 .Sx \&It
2565 macro or the body of a partial-implicit block macro
2566 beyond the end of the input line.
2567 This macro originally existed to work around the 9-argument limit
2568 of historic
2569 .Xr roff 7 .
2570 .Ss \&Xr
2571 Link to another manual
2572 .Pq Qq cross-reference .
2573 Its syntax is as follows:
2574 .Pp
2575 .D1 Pf \. Sx \&Xr Ar name Op section
2576 .Pp
2577 Cross reference the
2578 .Ar name
2579 and
2580 .Ar section
2581 number of another man page;
2582 omitting the section number is rarely useful.
2583 .Pp
2584 Examples:
2585 .Dl \&.Xr mandoc 1
2586 .Dl \&.Xr mandoc 1 \&;
2587 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2588 .Ss \&br
2589 Emits a line-break.
2590 This macro should not be used; it is implemented for compatibility with
2591 historical manuals.
2592 .Pp
2593 Consider using
2594 .Sx \&Pp
2595 in the event of natural paragraph breaks.
2596 .Ss \&sp
2597 Emits vertical space.
2598 This macro should not be used; it is implemented for compatibility with
2599 historical manuals.
2600 Its syntax is as follows:
2601 .Pp
2602 .D1 Pf \. Sx \&sp Op Ar height
2603 .Pp
2604 The
2605 .Ar height
2606 argument is a scaling width as described in
2607 .Xr roff 7 .
2608 If unspecified,
2609 .Sx \&sp
2610 asserts a single vertical space.
2611 .Sh MACRO SYNTAX
2612 The syntax of a macro depends on its classification.
2613 In this section,
2614 .Sq \-arg
2615 refers to macro arguments, which may be followed by zero or more
2616 .Sq parm
2617 parameters;
2618 .Sq \&Yo
2619 opens the scope of a macro; and if specified,
2620 .Sq \&Yc
2621 closes it out.
2622 .Pp
2623 The
2624 .Em Callable
2625 column indicates that the macro may also be called by passing its name
2626 as an argument to another macro.
2627 For example,
2628 .Sq \&.Op \&Fl O \&Ar file
2629 produces
2630 .Sq Op Fl O Ar file .
2631 To prevent a macro call and render the macro name literally,
2632 escape it by prepending a zero-width space,
2633 .Sq \e& .
2634 For example,
2635 .Sq \&Op \e&Fl O
2636 produces
2637 .Sq Op \&Fl O .
2638 If a macro is not callable but its name appears as an argument
2639 to another macro, it is interpreted as opaque text.
2640 For example,
2641 .Sq \&.Fl \&Sh
2642 produces
2643 .Sq Fl \&Sh .
2644 .Pp
2645 The
2646 .Em Parsed
2647 column indicates whether the macro may call other macros by receiving
2648 their names as arguments.
2649 If a macro is not parsed but the name of another macro appears
2650 as an argument, it is interpreted as opaque text.
2651 .Pp
2652 The
2653 .Em Scope
2654 column, if applicable, describes closure rules.
2655 .Ss Block full-explicit
2656 Multi-line scope closed by an explicit closing macro.
2657 All macros contains bodies; only
2658 .Sx \&Bf
2659 and
2660 .Pq optionally
2661 .Sx \&Bl
2662 contain a head.
2663 .Bd -literal -offset indent
2664 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2665 \(lBbody...\(rB
2666 \&.Yc
2667 .Ed
2668 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2669 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2670 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
2671 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
2672 .It Sx \&Bk  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ek
2673 .It Sx \&Bl  Ta    \&No     Ta    \&No     Ta    closed by Sx \&El
2674 .It Sx \&Ed  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bd
2675 .It Sx \&Ef  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bf
2676 .It Sx \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bk
2677 .It Sx \&El  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bl
2678 .El
2679 .Ss Block full-implicit
2680 Multi-line scope closed by end-of-file or implicitly by another macro.
2681 All macros have bodies; some
2682 .Po
2683 .Sx \&It Fl bullet ,
2684 .Fl hyphen ,
2685 .Fl dash ,
2686 .Fl enum ,
2687 .Fl item
2688 .Pc
2689 don't have heads; only one
2690 .Po
2691 .Sx \&It
2692 in
2693 .Sx \&Bl Fl column
2694 .Pc
2695 has multiple heads.
2696 .Bd -literal -offset indent
2697 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2698 \(lBbody...\(rB
2699 .Ed
2700 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2701 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2702 .It Sx \&It Ta \&No Ta Yes  Ta closed by Sx \&It , Sx \&El
2703 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2704 .It Sx \&Nm Ta \&No Ta Yes  Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2705 .It Sx \&Sh Ta \&No Ta Yes  Ta closed by Sx \&Sh
2706 .It Sx \&Ss Ta \&No Ta Yes  Ta closed by Sx \&Sh , Sx \&Ss
2707 .El
2708 .Pp
2709 Note that the
2710 .Sx \&Nm
2711 macro is a
2712 .Sx Block full-implicit
2713 macro only when invoked as the first macro
2714 in a
2715 .Em SYNOPSIS
2716 section line, else it is
2717 .Sx In-line .
2718 .Ss Block partial-explicit
2719 Like block full-explicit, but also with single-line scope.
2720 Each has at least a body and, in limited circumstances, a head
2721 .Po
2722 .Sx \&Fo ,
2723 .Sx \&Eo
2724 .Pc
2725 and/or tail
2726 .Pq Sx \&Ec .
2727 .Bd -literal -offset indent
2728 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2729 \(lBbody...\(rB
2730 \&.Yc \(lBtail...\(rB
2731
2732 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2733 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2734 .Ed
2735 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2736 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2737 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
2738 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
2739 .It Sx \&Bc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Bo
2740 .It Sx \&Bo  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Bc
2741 .It Sx \&Brc Ta    Yes      Ta    Yes      Ta    opened by Sx \&Bro
2742 .It Sx \&Bro Ta    Yes      Ta    Yes      Ta    closed by Sx \&Brc
2743 .It Sx \&Dc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Do
2744 .It Sx \&Do  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Dc
2745 .It Sx \&Ec  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Eo
2746 .It Sx \&Eo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ec
2747 .It Sx \&Fc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Fo
2748 .It Sx \&Fo  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Fc
2749 .It Sx \&Oc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Oo
2750 .It Sx \&Oo  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Oc
2751 .It Sx \&Pc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Po
2752 .It Sx \&Po  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Pc
2753 .It Sx \&Qc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Oo
2754 .It Sx \&Qo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Oc
2755 .It Sx \&Re  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Rs
2756 .It Sx \&Rs  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Re
2757 .It Sx \&Sc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&So
2758 .It Sx \&So  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Sc
2759 .It Sx \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Xo
2760 .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc
2761 .El
2762 .Ss Block partial-implicit
2763 Like block full-implicit, but with single-line scope closed by the
2764 end of the line.
2765 .Bd -literal -offset indent
2766 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2767 .Ed
2768 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2769 .It Em Macro Ta Em Callable Ta Em Parsed
2770 .It Sx \&Aq  Ta    Yes      Ta    Yes
2771 .It Sx \&Bq  Ta    Yes      Ta    Yes
2772 .It Sx \&Brq Ta    Yes      Ta    Yes
2773 .It Sx \&D1  Ta    \&No     Ta    \&Yes
2774 .It Sx \&Dl  Ta    \&No     Ta    Yes
2775 .It Sx \&Dq  Ta    Yes      Ta    Yes
2776 .It Sx \&Op  Ta    Yes      Ta    Yes
2777 .It Sx \&Pq  Ta    Yes      Ta    Yes
2778 .It Sx \&Ql  Ta    Yes      Ta    Yes
2779 .It Sx \&Qq  Ta    Yes      Ta    Yes
2780 .It Sx \&Sq  Ta    Yes      Ta    Yes
2781 .It Sx \&Vt  Ta    Yes      Ta    Yes
2782 .El
2783 .Pp
2784 Note that the
2785 .Sx \&Vt
2786 macro is a
2787 .Sx Block partial-implicit
2788 only when invoked as the first macro
2789 in a
2790 .Em SYNOPSIS
2791 section line, else it is
2792 .Sx In-line .
2793 .Ss Special block macro
2794 The
2795 .Sx \&Ta
2796 macro can only be used below
2797 .Sx \&It
2798 in
2799 .Sx \&Bl Fl column
2800 lists.
2801 It delimits blocks representing table cells;
2802 these blocks have bodies, but no heads.
2803 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2804 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2805 .It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
2806 .El
2807 .Ss In-line
2808 Closed by the end of the line, fixed argument lengths,
2809 and/or subsequent macros.
2810 In-line macros have only text children.
2811 If a number (or inequality) of arguments is
2812 .Pq n ,
2813 then the macro accepts an arbitrary number of arguments.
2814 .Bd -literal -offset indent
2815 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
2816
2817 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
2818
2819 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
2820 .Ed
2821 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
2822 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
2823 .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
2824 .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
2825 .It Sx \&%C  Ta    \&No     Ta    \&No     Ta    >0
2826 .It Sx \&%D  Ta    \&No     Ta    \&No     Ta    >0
2827 .It Sx \&%I  Ta    \&No     Ta    \&No     Ta    >0
2828 .It Sx \&%J  Ta    \&No     Ta    \&No     Ta    >0
2829 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
2830 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
2831 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
2832 .It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
2833 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
2834 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
2835 .It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
2836 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
2837 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    >0
2838 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    >0
2839 .It Sx \&Ap  Ta    Yes      Ta    Yes      Ta    0
2840 .It Sx \&Ar  Ta    Yes      Ta    Yes      Ta    n
2841 .It Sx \&At  Ta    Yes      Ta    Yes      Ta    1
2842 .It Sx \&Bsx Ta    Yes      Ta    Yes      Ta    n
2843 .It Sx \&Bt  Ta    \&No     Ta    \&No     Ta    0
2844 .It Sx \&Bx  Ta    Yes      Ta    Yes      Ta    n
2845 .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0
2846 .It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    >0
2847 .It Sx \&Db  Ta    \&No     Ta    \&No     Ta    1
2848 .It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    n
2849 .It Sx \&Dt  Ta    \&No     Ta    \&No     Ta    n
2850 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    >0
2851 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
2852 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0
2853 .It Sx \&En  Ta    \&No     Ta    \&No     Ta    0
2854 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0
2855 .It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0
2856 .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    >0
2857 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
2858 .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    >0
2859 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
2860 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
2861 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0
2862 .It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n
2863 .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    >0
2864 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
2865 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n
2866 .It Sx \&Ic  Ta    Yes      Ta    Yes      Ta    >0
2867 .It Sx \&In  Ta    \&No     Ta    \&No     Ta    1
2868 .It Sx \&Lb  Ta    \&No     Ta    \&No     Ta    1
2869 .It Sx \&Li  Ta    Yes      Ta    Yes      Ta    >0
2870 .It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    >0
2871 .It Sx \&Lp  Ta    \&No     Ta    \&No     Ta    0
2872 .It Sx \&Ms  Ta    Yes      Ta    Yes      Ta    >0
2873 .It Sx \&Mt  Ta    Yes      Ta    Yes      Ta    >0
2874 .It Sx \&Nm  Ta    Yes      Ta    Yes      Ta    n
2875 .It Sx \&No  Ta    Yes      Ta    Yes      Ta    0
2876 .It Sx \&Ns  Ta    Yes      Ta    Yes      Ta    0
2877 .It Sx \&Nx  Ta    Yes      Ta    Yes      Ta    n
2878 .It Sx \&Os  Ta    \&No     Ta    \&No     Ta    n
2879 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
2880 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
2881 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
2882 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
2883 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
2884 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
2885 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
2886 .It Sx \&St  Ta    \&No     Ta    Yes      Ta    1
2887 .It Sx \&Sx  Ta    Yes      Ta    Yes      Ta    >0
2888 .It Sx \&Sy  Ta    Yes      Ta    Yes      Ta    >0
2889 .It Sx \&Tn  Ta    Yes      Ta    Yes      Ta    >0
2890 .It Sx \&Ud  Ta    \&No     Ta    \&No     Ta    0
2891 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
2892 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
2893 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
2894 .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0
2895 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
2896 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
2897 .El
2898 .Ss Delimiters
2899 When a macro argument consists of one single input character
2900 considered as a delimiter, the argument gets special handling.
2901 This does not apply when delimiters appear in arguments containing
2902 more than one character.
2903 Consequently, to prevent special handling and just handle it
2904 like any other argument, a delimiter can be escaped by prepending
2905 a zero-width space
2906 .Pq Sq \e& .
2907 In text lines, delimiters never need escaping, but may be used
2908 as normal punctuation.
2909 .Pp
2910 For many macros, when the leading arguments are opening delimiters,
2911 these delimiters are put before the macro scope,
2912 and when the trailing arguments are closing delimiters,
2913 these delimiters are put after the macro scope.
2914 For example,
2915 .Pp
2916 .D1 Pf \. \&Aq "( [ word ] ) ."
2917 .Pp
2918 renders as:
2919 .Pp
2920 .D1 Aq ( [ word ] ) .
2921 .Pp
2922 Opening delimiters are:
2923 .Pp
2924 .Bl -tag -width Ds -offset indent -compact
2925 .It \&(
2926 left parenthesis
2927 .It \&[
2928 left bracket
2929 .El
2930 .Pp
2931 Closing delimiters are:
2932 .Pp
2933 .Bl -tag -width Ds -offset indent -compact
2934 .It \&.
2935 period
2936 .It \&,
2937 comma
2938 .It \&:
2939 colon
2940 .It \&;
2941 semicolon
2942 .It \&)
2943 right parenthesis
2944 .It \&]
2945 right bracket
2946 .It \&?
2947 question mark
2948 .It \&!
2949 exclamation mark
2950 .El
2951 .Pp
2952 Note that even a period preceded by a backslash
2953 .Pq Sq \e.\&
2954 gets this special handling; use
2955 .Sq \e&.
2956 to prevent that.
2957 .Pp
2958 Many in-line macros interrupt their scope when they encounter
2959 delimiters, and resume their scope when more arguments follow that
2960 are not delimiters.
2961 For example,
2962 .Pp
2963 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
2964 .Pp
2965 renders as:
2966 .Pp
2967 .D1 Fl a ( b | c \*(Ba d ) e
2968 .Pp
2969 This applies to both opening and closing delimiters,
2970 and also to the middle delimiter:
2971 .Pp
2972 .Bl -tag -width Ds -offset indent -compact
2973 .It \&|
2974 vertical bar
2975 .El
2976 .Pp
2977 As a special case, the predefined string \e*(Ba is handled and rendered
2978 in the same way as a plain
2979 .Sq \&|
2980 character.
2981 Using this predefined string is not recommended in new manuals.
2982 .Ss Font handling
2983 In
2984 .Nm
2985 documents, usage of semantic markup is recommended in order to have
2986 proper fonts automatically selected; only when no fitting semantic markup
2987 is available, consider falling back to
2988 .Sx Physical markup
2989 macros.
2990 Whenever any
2991 .Nm
2992 macro switches the
2993 .Xr roff 7
2994 font mode, it will automatically restore the previous font when exiting
2995 its scope.
2996 Manually switching the font using the
2997 .Xr roff 7
2998 .Ql \ef
2999 font escape sequences is never required.
3000 .Sh COMPATIBILITY
3001 This section documents compatibility between mandoc and other
3002 troff implementations, at this time limited to GNU troff
3003 .Pq Qq groff .
3004 The term
3005 .Qq historic groff
3006 refers to groff versions before 1.17,
3007 which featured a significant update of the
3008 .Pa doc.tmac
3009 file.
3010 .Pp
3011 Heirloom troff, the other significant troff implementation accepting
3012 \-mdoc, is similar to historic groff.
3013 .Pp
3014 The following problematic behaviour is found in groff:
3015 .ds hist (Historic groff only.)
3016 .Pp
3017 .Bl -dash -compact
3018 .It
3019 Display macros
3020 .Po
3021 .Sx \&Bd ,
3022 .Sx \&Dl ,
3023 and
3024 .Sx \&D1
3025 .Pc
3026 may not be nested.
3027 \*[hist]
3028 .It
3029 .Sx \&At
3030 with unknown arguments produces no output at all.
3031 \*[hist]
3032 Newer groff and mandoc print
3033 .Qq AT&T UNIX
3034 and the arguments.
3035 .It
3036 .Sx \&Bl Fl column
3037 does not recognise trailing punctuation characters when they immediately
3038 precede tabulator characters, but treats them as normal text and
3039 outputs a space before them.
3040 .It
3041 .Sx \&Bd Fl ragged compact
3042 does not start a new line.
3043 \*[hist]
3044 .It
3045 .Sx \&Dd
3046 with non-standard arguments behaves very strangely.
3047 When there are three arguments, they are printed verbatim.
3048 Any other number of arguments is replaced by the current date,
3049 but without any arguments the string
3050 .Dq Epoch
3051 is printed.
3052 .It
3053 .Sx \&Fl
3054 does not print a dash for an empty argument.
3055 \*[hist]
3056 .It
3057 .Sx \&Fn
3058 does not start a new line unless invoked as the line macro in the
3059 .Em SYNOPSIS
3060 section.
3061 \*[hist]
3062 .It
3063 .Sx \&Fo
3064 with
3065 .Pf non- Sx \&Fa
3066 children causes inconsistent spacing between arguments.
3067 In mandoc, a single space is always inserted between arguments.
3068 .It
3069 .Sx \&Ft
3070 in the
3071 .Em SYNOPSIS
3072 causes inconsistent vertical spacing, depending on whether a prior
3073 .Sx \&Fn
3074 has been invoked.
3075 See
3076 .Sx \&Ft
3077 and
3078 .Sx \&Fn
3079 for the normalised behaviour in mandoc.
3080 .It
3081 .Sx \&In
3082 ignores additional arguments and is not treated specially in the
3083 .Em SYNOPSIS .
3084 \*[hist]
3085 .It
3086 .Sx \&It
3087 sometimes requires a
3088 .Fl nested
3089 flag.
3090 \*[hist]
3091 In new groff and mandoc, any list may be nested by default and
3092 .Fl enum
3093 lists will restart the sequence only for the sub-list.
3094 .It
3095 .Sx \&Li
3096 followed by a delimiter is incorrectly used in some manuals
3097 instead of properly quoting that character, which sometimes works with
3098 historic groff.
3099 .It
3100 .Sx \&Lk
3101 only accepts a single link-name argument; the remainder is misformatted.
3102 .It
3103 .Sx \&Pa
3104 does not format its arguments when used in the FILES section under
3105 certain list types.
3106 .It
3107 .Sx \&Ta
3108 can only be called by other macros, but not at the beginning of a line.
3109 .It
3110 .Sx \&%C
3111 is not implemented.
3112 .It
3113 Historic groff only allows up to eight or nine arguments per macro input
3114 line, depending on the exact situation.
3115 Providing more arguments causes garbled output.
3116 The number of arguments on one input line is not limited with mandoc.
3117 .It
3118 Historic groff has many un-callable macros.
3119 Most of these (excluding some block-level macros) are callable
3120 in new groff and mandoc.
3121 .It
3122 .Sq \(ba
3123 (vertical bar) is not fully supported as a delimiter.
3124 \*[hist]
3125 .It
3126 .Sq \ef
3127 .Pq font face
3128 and
3129 .Sq \ef
3130 .Pq font family face
3131 .Sx Text Decoration
3132 escapes behave irregularly when specified within line-macro scopes.
3133 .It
3134 Negative scaling units return to prior lines.
3135 Instead, mandoc truncates them to zero.
3136 .El
3137 .Pp
3138 The following features are unimplemented in mandoc:
3139 .Pp
3140 .Bl -dash -compact
3141 .It
3142 .Sx \&Bd
3143 .Fl file Ar file .
3144 .It
3145 .Sx \&Bd
3146 .Fl offset Ar center
3147 and
3148 .Fl offset Ar right .
3149 Groff does not implement centred and flush-right rendering either,
3150 but produces large indentations.
3151 .It
3152 The
3153 .Sq \eh
3154 .Pq horizontal position ,
3155 .Sq \ev
3156 .Pq vertical position ,
3157 .Sq \em
3158 .Pq text colour ,
3159 .Sq \eM
3160 .Pq text filling colour ,
3161 .Sq \ez
3162 .Pq zero-length character ,
3163 .Sq \ew
3164 .Pq string length ,
3165 .Sq \ek
3166 .Pq horizontal position marker ,
3167 .Sq \eo
3168 .Pq text overstrike ,
3169 and
3170 .Sq \es
3171 .Pq text size
3172 escape sequences are all discarded in mandoc.
3173 .It
3174 The
3175 .Sq \ef
3176 scaling unit is accepted by mandoc, but rendered as the default unit.
3177 .It
3178 In quoted literals, groff allows pairwise double-quotes to produce a
3179 standalone double-quote in formatted output.
3180 This is not supported by mandoc.
3181 .El
3182 .Sh SEE ALSO
3183 .Xr man 1 ,
3184 .Xr mandoc 1 ,
3185 .Xr eqn 7 ,
3186 .Xr man 7 ,
3187 .Xr mandoc_char 7 ,
3188 .Xr roff 7 ,
3189 .Xr tbl 7
3190 .Sh HISTORY
3191 The
3192 .Nm
3193 language first appeared as a troff macro package in
3194 .Bx 4.4 .
3195 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3196 in groff-1.17.
3197 The standalone implementation that is part of the
3198 .Xr mandoc 1
3199 utility written by Kristaps Dzonsons appeared in
3200 .Ox 4.6 .
3201 .Sh AUTHORS
3202 The
3203 .Nm
3204 reference was written by
3205 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .