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