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