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