contrib/mdocml/mdoc.7

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