contrib/mdocml/mdoc.7

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