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