contrib/mdocml/mdoc.7

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