mdoc.7

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