mdoc.7

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