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