mdoc.7

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