contrib/mdocml/mdoc.7

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