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