1.\" $Id: mdoc.7,v 1.299 2025/06/13 16:18:28 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: June 13 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 982A list must specify one of the following list types: 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. 997If the first line of the body of a 998.Fl column 999list is not an 1000.Ic \&It 1001macro line, 1002.Ic \&It 1003contexts spanning one input line each are implied until an 1004.Ic \&It 1005macro line is encountered, at which point items start being interpreted as 1006described in the 1007.Ic \&It 1008documentation. 1009.It Fl dash 1010Like 1011.Fl bullet , 1012except that dashes are used in place of bullets. 1013.It Fl diag 1014Like 1015.Fl inset , 1016except that item heads are not parsed for macro invocations. 1017Most often used in the 1018.Em DIAGNOSTICS 1019section with error constants in the item heads. 1020.It Fl enum 1021A numbered list. 1022No item heads can be specified. 1023Formatted like 1024.Fl bullet , 1025except that ordinal numbers are used in place of bullets, 1026starting at 1. 1027.It Fl hang 1028Like 1029.Fl tag , 1030except that the first lines of item bodies are not indented, but follow 1031the item heads like in 1032.Fl inset 1033lists. 1034.It Fl hyphen 1035Synonym for 1036.Fl dash . 1037.It Fl inset 1038Item bodies follow items heads on the same line, using normal inter-word 1039spacing. 1040Bodies are not indented, and the 1041.Fl width 1042argument is ignored. 1043.It Fl item 1044No item heads can be specified, and none are printed. 1045Bodies are not indented, and the 1046.Fl width 1047argument is ignored. 1048.It Fl ohang 1049Item bodies start on the line following item heads and are not indented. 1050The 1051.Fl width 1052argument is ignored. 1053.It Fl tag 1054Item bodies are indented according to the 1055.Fl width 1056argument. 1057When an item head fits inside the indentation, the item body follows 1058this head on the same output line. 1059Otherwise, the body starts on the output line following the head. 1060.El 1061.Pp 1062Lists may be nested within lists and displays. 1063Nesting of 1064.Fl column 1065and 1066.Fl enum 1067lists may not be portable. 1068.Pp 1069See also 1070.Ic \&El 1071and 1072.Ic \&It . 1073.It Ic \&Bo Ar block 1074Begin a block enclosed by square brackets. 1075Does not have any head arguments. 1076.Pp 1077Examples: 1078.Bd -literal -offset indent -compact 1079\&.Bo 1 , 1080\&.Dv BUFSIZ \&Bc 1081.Ed 1082.Pp 1083See also 1084.Ic \&Bq . 1085.Tg Bq 1086.It Ic \&Bq Ar line 1087Encloses its arguments in square brackets. 1088.Pp 1089Examples: 1090.Dl \&.Bq 1 , \&Dv BUFSIZ 1091.Pp 1092.Em Remarks : 1093this macro is sometimes abused to emulate optional arguments for 1094commands; the correct macros to use for this purpose are 1095.Ic \&Op , 1096.Ic \&Oo , 1097and 1098.Ic \&Oc . 1099.Pp 1100See also 1101.Ic \&Bo . 1102.It Ic \&Brc 1103Close a 1104.Ic \&Bro 1105block. 1106Does not have any tail arguments. 1107.It Ic \&Bro Ar block 1108Begin a block enclosed by curly braces. 1109Does not have any head arguments. 1110.Pp 1111Examples: 1112.Bd -literal -offset indent -compact 1113\&.Bro 1 , ... , 1114\&.Va n \&Brc 1115.Ed 1116.Pp 1117See also 1118.Ic \&Brq . 1119.Tg Brq 1120.It Ic \&Brq Ar line 1121Encloses its arguments in curly braces. 1122.Pp 1123Examples: 1124.Dl \&.Brq 1 , ... , \&Va n 1125.Pp 1126See also 1127.Ic \&Bro . 1128.Tg Bsx 1129.It Ic \&Bsx Op Ar version 1130Format the 1131.Bsx 1132version provided as an argument, or a default value if 1133no argument is provided. 1134.Pp 1135Examples: 1136.Dl \&.Bsx 1.0 1137.Dl \&.Bsx 1138.Pp 1139See also 1140.Ic \&At , 1141.Ic \&Bx , 1142.Ic \&Dx , 1143.Ic \&Fx , 1144.Ic \&Nx , 1145and 1146.Ic \&Ox . 1147.It Ic \&Bt 1148Supported only for compatibility, do not use this in new manuals. 1149Prints 1150.Dq is currently in beta test. 1151.Tg Bx 1152.It Ic \&Bx Op Ar version Op Ar variant 1153Format the 1154.Bx 1155version provided as an argument, or a default value if no 1156argument is provided. 1157.Pp 1158Examples: 1159.Dl \&.Bx 4.3 Tahoe 1160.Dl \&.Bx 4.4 1161.Dl \&.Bx 1162.Pp 1163See also 1164.Ic \&At , 1165.Ic \&Bsx , 1166.Ic \&Dx , 1167.Ic \&Fx , 1168.Ic \&Nx , 1169and 1170.Ic \&Ox . 1171.Tg Cd 1172.It Ic \&Cd Ar line 1173Kernel configuration declaration. 1174This denotes strings accepted by 1175.Xr config 8 . 1176It is most often used in section 4 manual pages. 1177.Pp 1178Examples: 1179.Dl \&.Cd device le0 at scode? 1180.Pp 1181.Em Remarks : 1182this macro is commonly abused by using quoted literals to retain 1183whitespace and align consecutive 1184.Ic \&Cd 1185declarations. 1186This practise is discouraged. 1187.Tg Cm 1188.It Ic \&Cm Ar keyword ... 1189Command modifiers. 1190Typically used for fixed strings passed as arguments to interactive 1191commands, to commands in interpreted scripts, or to configuration 1192file directives, unless 1193.Ic \&Fl 1194is more appropriate. 1195.Pp 1196Examples: 1197.Dl ".Nm mt Fl f Ar device Cm rewind" 1198.Dl ".Nm ps Fl o Cm pid , Ns Cm command" 1199.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" 1200.Dl ".Ic set Fl o Cm vi" 1201.Dl ".Ic lookup Cm file bind" 1202.Dl ".Ic permit Ar identity Op Cm as Ar target" 1203.Tg D1 1204.It Ic \&D1 Ar line 1205One-line indented display. 1206This is formatted by the default rules and is useful for simple indented 1207statements. 1208It is followed by a newline. 1209.Pp 1210Examples: 1211.Dl \&.D1 \&Fl abcdefgh 1212.Pp 1213See also 1214.Ic \&Bd 1215and 1216.Ic \&Dl . 1217.It Ic \&Db 1218This macro is obsolete. 1219No replacement is needed. 1220It is ignored by 1221.Xr mandoc 1 1222and groff including its arguments. 1223It was formerly used to toggle a debugging mode. 1224.It Ic \&Dc 1225Close a 1226.Ic \&Do 1227block. 1228Does not have any tail arguments. 1229.Tg Dd 1230.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year 1231Document date for display in the page footer, 1232by convention the date of the last change. 1233This is the mandatory first macro of any 1234.Nm 1235manual. 1236.Pp 1237The 1238.Ar month 1239is the full English month name, the 1240.Ar day 1241is an integer number, and the 1242.Ar year 1243is the full four-digit year. 1244.Pp 1245Other arguments are not portable; the 1246.Xr mandoc 1 1247utility handles them as follows: 1248.Bl -dash -offset 3n -compact 1249.It 1250To have the date automatically filled in by the 1251.Ox 1252version of 1253.Xr cvs 1 , 1254the special string 1255.Dq $\&Mdocdate$ 1256can be given as an argument. 1257.It 1258The traditional, purely numeric 1259.Xr man 7 1260format 1261.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day 1262is accepted, too. 1263.It 1264If a date string cannot be parsed, it is used verbatim. 1265.It 1266If no date string is given, the current date is used. 1267.El 1268.Pp 1269Examples: 1270.Dl \&.Dd $\&Mdocdate$ 1271.Dl \&.Dd $\&Mdocdate: July 2 2018$ 1272.Dl \&.Dd July 2, 2018 1273.Pp 1274See also 1275.Ic \&Dt 1276and 1277.Ic \&Os . 1278.Tg Dl 1279.It Ic \&Dl Ar line 1280One-line indented literal display. 1281This is formatted using a constant-width font 1282and is useful for commands and invocations. 1283It is followed by a newline. 1284.Pp 1285Examples: 1286.Dl \&.Dl % mandoc mdoc.7 \e(ba less 1287.Pp 1288See also 1289.Ic \&Ql , 1290.Ic \&Bd Fl literal , 1291and 1292.Ic \&D1 . 1293.It Ic \&Do Ar block 1294Begin a block enclosed by double quotes. 1295Does not have any head arguments. 1296.Pp 1297Examples: 1298.Bd -literal -offset indent -compact 1299\&.Do 1300April is the cruellest month 1301\&.Dc 1302\e(em T.S. Eliot 1303.Ed 1304.Pp 1305See also 1306.Ic \&Dq . 1307.Tg Dq 1308.It Ic \&Dq Ar line 1309Encloses its arguments in 1310.Dq typographic 1311double-quotes. 1312.Pp 1313Examples: 1314.Bd -literal -offset indent -compact 1315\&.Dq April is the cruellest month 1316\e(em T.S. Eliot 1317.Ed 1318.Pp 1319See also 1320.Ic \&Qq , 1321.Ic \&Sq , 1322and 1323.Ic \&Do . 1324.Tg Dt 1325.It Ic \&Dt Ar TITLE section Op Ar arch 1326Document title for display in the page header. 1327This is the mandatory second macro of any 1328.Nm 1329file. 1330.Pp 1331Its arguments are as follows: 1332.Bl -tag -width section -offset 2n 1333.It Ar TITLE 1334The document's title (name), defaulting to 1335.Dq UNTITLED 1336if unspecified. 1337To achieve a uniform appearance of page header lines, 1338it should by convention be all caps. 1339.It Ar section 1340The manual section. 1341This may be one of 1342.Cm 1 1343.Pq General Commands , 1344.Cm 2 1345.Pq System Calls , 1346.Cm 3 1347.Pq Library Functions , 1348.Cm 3p 1349.Pq Perl Library , 1350.Cm 4 1351.Pq Device Drivers , 1352.Cm 5 1353.Pq File Formats , 1354.Cm 6 1355.Pq Games , 1356.Cm 7 1357.Pq Miscellaneous Information , 1358.Cm 8 1359.Pq System Manager's Manual , 1360or 1361.Cm 9 1362.Pq Kernel Developer's Manual . 1363It should correspond to the manual's filename suffix and defaults to 1364the empty string if unspecified. 1365.It Ar arch 1366This specifies the machine architecture a manual page applies to, 1367where relevant, for example 1368.Cm alpha , 1369.Cm amd64 , 1370.Cm i386 , 1371or 1372.Cm sparc64 . 1373The list of valid architectures varies by operating system. 1374.El 1375.Pp 1376Examples: 1377.Dl \&.Dt FOO 1 1378.Dl \&.Dt FOO 9 i386 1379.Pp 1380See also 1381.Ic \&Dd 1382and 1383.Ic \&Os . 1384.Tg Dv 1385.It Ic \&Dv Ar identifier ... 1386Defined variables such as preprocessor constants, constant symbols, 1387enumeration values, and so on. 1388.Pp 1389Examples: 1390.Dl \&.Dv NULL 1391.Dl \&.Dv BUFSIZ 1392.Dl \&.Dv STDOUT_FILENO 1393.Pp 1394See also 1395.Ic \&Er 1396and 1397.Ic \&Ev 1398for special-purpose constants, 1399.Ic \&Va 1400for variable symbols, and 1401.Ic \&Fd 1402for listing preprocessor variable definitions in the 1403.Em SYNOPSIS . 1404.Tg Dx 1405.It Ic \&Dx Op Ar version 1406Format the 1407.Dx 1408version provided as an argument, or a default 1409value if no argument is provided. 1410.Pp 1411Examples: 1412.Dl \&.Dx 2.4.1 1413.Dl \&.Dx 1414.Pp 1415See also 1416.Ic \&At , 1417.Ic \&Bsx , 1418.Ic \&Bx , 1419.Ic \&Fx , 1420.Ic \&Nx , 1421and 1422.Ic \&Ox . 1423.It Ic \&Ec Op Ar closing_delimiter 1424Close a scope started by 1425.Ic \&Eo . 1426.Pp 1427The 1428.Ar closing_delimiter 1429argument is used as the enclosure tail, for example, specifying \e(rq 1430will emulate 1431.Ic \&Dc . 1432.It Ic \&Ed 1433End a display context started by 1434.Ic \&Bd . 1435.It Ic \&Ef 1436End a font mode context started by 1437.Ic \&Bf . 1438.It Ic \&Ek 1439End a keep context started by 1440.Ic \&Bk . 1441.It Ic \&El 1442End a list context started by 1443.Ic \&Bl . 1444See also 1445.Ic \&It . 1446.Tg Em 1447.It Ic \&Em Ar word ... 1448Request an italic font. 1449If the output device does not provide that, underline. 1450.Pp 1451This is most often used for stress emphasis (not to be confused with 1452importance, see 1453.Ic \&Sy ) . 1454In the rare cases where none of the semantic markup macros fit, 1455it can also be used for technical terms and placeholders, except 1456that for syntax elements, 1457.Ic \&Sy 1458and 1459.Ic \&Ar 1460are preferred, respectively. 1461.Pp 1462Examples: 1463.Bd -literal -compact -offset indent 1464Selected lines are those 1465\&.Em not 1466matching any of the specified patterns. 1467Some of the functions use a 1468\&.Em hold space 1469to save the pattern space for subsequent retrieval. 1470.Ed 1471.Pp 1472See also 1473.Ic \&No , 1474.Ic \&Ql , 1475and 1476.Ic \&Sy . 1477.It Ic \&En Ar word ... 1478This macro is obsolete. 1479Use 1480.Ic \&Eo 1481or any of the other enclosure macros. 1482.Pp 1483It encloses its argument in the delimiters specified by the last 1484.Ic \&Es 1485macro. 1486.Tg Eo 1487.It Ic \&Eo Op Ar opening_delimiter 1488An arbitrary enclosure. 1489The 1490.Ar opening_delimiter 1491argument is used as the enclosure head, for example, specifying \e(lq 1492will emulate 1493.Ic \&Do . 1494.Tg Er 1495.It Ic \&Er Ar identifier ... 1496Error constants for definitions of the 1497.Va errno 1498libc global variable. 1499This is most often used in section 2 and 3 manual pages. 1500.Pp 1501Examples: 1502.Dl \&.Er EPERM 1503.Dl \&.Er ENOENT 1504.Pp 1505See also 1506.Ic \&Dv 1507for general constants. 1508.It Ic \&Es Ar opening_delimiter closing_delimiter 1509This macro is obsolete. 1510Use 1511.Ic \&Eo 1512or any of the other enclosure macros. 1513.Pp 1514It takes two arguments, defining the delimiters to be used by subsequent 1515.Ic \&En 1516macros. 1517.Tg Ev 1518.It Ic \&Ev Ar identifier ... 1519Environmental variables such as those specified in 1520.Xr environ 7 . 1521.Pp 1522Examples: 1523.Dl \&.Ev DISPLAY 1524.Dl \&.Ev PATH 1525.Pp 1526See also 1527.Ic \&Dv 1528for general constants. 1529.Tg Ex 1530.It Ic \&Ex Fl std Op Ar utility ... 1531Insert a standard sentence regarding command exit values of 0 on success 1532and >0 on failure. 1533This is most often used in section 1, 6, and 8 manual pages. 1534.Pp 1535If 1536.Ar utility 1537is not specified, the document's name set by 1538.Ic \&Nm 1539is used. 1540Multiple 1541.Ar utility 1542arguments are treated as separate utilities. 1543.Pp 1544See also 1545.Ic \&Rv . 1546.Tg Fa 1547.It Ic \&Fa Ar argument ... 1548Function argument or parameter. 1549Each argument may be a name and a type (recommended for the 1550.Em SYNOPSIS 1551section), a name alone (for function invocations), 1552or a type alone (for function prototypes). 1553If both a type and a name are given or if the type consists of multiple 1554words, all words belonging to the same function argument have to be 1555given in a single argument to the 1556.Ic \&Fa 1557macro. 1558.Pp 1559This macro is also used to specify the field name of a structure. 1560.Pp 1561Most often, the 1562.Ic \&Fa 1563macro is used in the 1564.Em SYNOPSIS 1565within 1566.Ic \&Fo 1567blocks when documenting multi-line function prototypes. 1568If invoked with multiple arguments, the arguments are separated by a 1569comma. 1570Furthermore, if the following macro is another 1571.Ic \&Fa , 1572the last argument will also have a trailing comma. 1573.Pp 1574Examples: 1575.Dl \&.Fa \(dqconst char *p\(dq 1576.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1577.Dl \&.Fa \(dqchar *\(dq size_t 1578.Pp 1579See also 1580.Ic \&Fo . 1581.It Ic \&Fc 1582End a function context started by 1583.Ic \&Fo . 1584.Tg Fd 1585.It Ic \&Fd Pf # Ar directive Op Ar argument ... 1586Preprocessor directive, in particular for listing it in the 1587.Em SYNOPSIS . 1588Historically, it was also used to document include files. 1589The latter usage has been deprecated in favour of 1590.Ic \&In . 1591.Pp 1592Examples: 1593.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1594.Dl \&.Fd #define SIO_MAXNFDS 1595.Dl \&.Fd #ifdef FS_DEBUG 1596.Dl \&.Ft void 1597.Dl \&.Fn dbg_open \(dqconst char *\(dq 1598.Dl \&.Fd #endif 1599.Pp 1600See also 1601.Sx MANUAL STRUCTURE , 1602.Ic \&In , 1603and 1604.Ic \&Dv . 1605.Tg Fl 1606.It Ic \&Fl Op Ar word ... 1607Command-line flag or option. 1608Used when listing arguments to command-line utilities. 1609For each argument, prints an ASCII hyphen-minus character 1610.Sq \- , 1611immediately followed by the argument. 1612If no arguments are provided, a hyphen-minus is printed followed by a space. 1613If the argument is a macro, a hyphen-minus is prefixed 1614to the subsequent macro output. 1615.Pp 1616Examples: 1617.Dl ".Nm du Op Fl H | L | P" 1618.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1619.Dl ".Nm route Cm add Fl inet Ar destination gateway" 1620.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" 1621.Dl ".Nm aucat Fl o Fl" 1622.Dl ".Nm kill Fl Ar signal_number" 1623.Pp 1624For GNU-style long options, escaping the additional hyphen-minus is not 1625strictly required, but may be safer with future versions of GNU troff; see 1626.Xr mandoc_char 7 1627for details. 1628.Pp 1629See also 1630.Ic \&Cm . 1631.Tg Fn 1632.It Ic \&Fn Ar funcname Op Ar argument ... 1633A function name. 1634.Pp 1635Function arguments are surrounded in parenthesis and 1636are delimited by commas. 1637If no arguments are specified, blank parenthesis are output. 1638In the 1639.Em SYNOPSIS 1640section, this macro starts a new output line, 1641and a blank line is automatically inserted between function definitions. 1642.Pp 1643Examples: 1644.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1645.Dl \&.Fn funcname \(dqint arg0\(dq 1646.Dl \&.Fn funcname arg0 1647.Bd -literal -offset indent 1648\&.Ft functype 1649\&.Fn funcname 1650.Ed 1651.Pp 1652When referring to a function documented in another manual page, use 1653.Ic \&Xr 1654instead. 1655See also 1656.Sx MANUAL STRUCTURE , 1657.Ic \&Fo , 1658and 1659.Ic \&Ft . 1660.Tg Fo 1661.It Ic \&Fo Ar funcname 1662Begin a function block. 1663This is a multi-line version of 1664.Ic \&Fn . 1665.Pp 1666Invocations usually occur in the following context: 1667.Bd -ragged -offset indent 1668.Pf \. Ic \&Ft Ar functype 1669.br 1670.Pf \. Ic \&Fo Ar funcname 1671.br 1672.Pf \. Ic \&Fa Qq Ar argtype Ar argname 1673.br 1674\&.\.\. 1675.br 1676.Pf \. Ic \&Fc 1677.Ed 1678.Pp 1679A 1680.Ic \&Fo 1681scope is closed by 1682.Ic \&Fc . 1683.Pp 1684See also 1685.Sx MANUAL STRUCTURE , 1686.Ic \&Fa , 1687.Ic \&Fc , 1688and 1689.Ic \&Ft . 1690.It Ic \&Fr Ar number 1691This macro is obsolete. 1692No replacement markup is needed. 1693.Pp 1694It was used to show numerical function return values in an italic font. 1695.Tg Ft 1696.It Ic \&Ft Ar functype 1697A function type. 1698.Pp 1699In the 1700.Em SYNOPSIS 1701section, a new output line is started after this macro. 1702.Pp 1703Examples: 1704.Dl \&.Ft int 1705.Bd -literal -offset indent -compact 1706\&.Ft functype 1707\&.Fn funcname 1708.Ed 1709.Pp 1710See also 1711.Sx MANUAL STRUCTURE , 1712.Ic \&Fn , 1713and 1714.Ic \&Fo . 1715.Tg Fx 1716.It Ic \&Fx Op Ar version 1717Format the 1718.Fx 1719version provided as an argument, or a default value 1720if no argument is provided. 1721.Pp 1722Examples: 1723.Dl \&.Fx 7.1 1724.Dl \&.Fx 1725.Pp 1726See also 1727.Ic \&At , 1728.Ic \&Bsx , 1729.Ic \&Bx , 1730.Ic \&Dx , 1731.Ic \&Nx , 1732and 1733.Ic \&Ox . 1734.It Ic \&Hf Ar filename 1735This macro is not implemented in 1736.Xr mandoc 1 . 1737It was used to include the contents of a (header) file literally. 1738.Tg Ic 1739.It Ic \&Ic Ar keyword ... 1740Internal or interactive command, or configuration instruction 1741in a configuration file. 1742See also 1743.Ic \&Cm . 1744.Pp 1745Examples: 1746.Dl \&.Ic :wq 1747.Dl \&.Ic hash 1748.Dl \&.Ic alias 1749.Pp 1750Note that using 1751.Ic \&Ql , 1752.Ic \&Dl , 1753or 1754.Ic \&Bd Fl literal 1755is preferred for displaying code samples; the 1756.Ic \&Ic 1757macro is used when referring to an individual command name. 1758.Tg In 1759.It Ic \&In Ar filename 1760The name of an include file. 1761This macro is most often used in section 2, 3, and 9 manual pages. 1762.Pp 1763When invoked as the first macro on an input line in the 1764.Em SYNOPSIS 1765section, the argument is displayed in angle brackets 1766and preceded by 1767.Qq #include , 1768and a blank line is inserted in front if there is a preceding 1769function declaration. 1770In other sections, it only encloses its argument in angle brackets 1771and causes no line break. 1772.Pp 1773Examples: 1774.Dl \&.In sys/types.h 1775.Pp 1776See also 1777.Sx MANUAL STRUCTURE . 1778.Tg It 1779.It Ic \&It Op Ar head 1780A list item. 1781The syntax of this macro depends on the list type. 1782.Pp 1783Lists 1784of type 1785.Fl hang , 1786.Fl ohang , 1787.Fl inset , 1788and 1789.Fl diag 1790have the following syntax: 1791.Pp 1792.D1 Pf \. Ic \&It Ar args 1793.Pp 1794Lists of type 1795.Fl bullet , 1796.Fl dash , 1797.Fl enum , 1798.Fl hyphen 1799and 1800.Fl item 1801have the following syntax: 1802.Pp 1803.D1 Pf \. Ic \&It 1804.Pp 1805with subsequent lines interpreted within the scope of the 1806.Ic \&It 1807until either a closing 1808.Ic \&El 1809or another 1810.Ic \&It . 1811.Pp 1812The 1813.Fl tag 1814list has the following syntax: 1815.Pp 1816.D1 Pf \. Ic \&It Op Cm args 1817.Pp 1818Subsequent lines are interpreted as with 1819.Fl bullet 1820and family. 1821The line arguments correspond to the list's left-hand side; body 1822arguments correspond to the list's contents. 1823.Pp 1824The 1825.Fl column 1826list is the most complicated. 1827Its syntax is as follows: 1828.Pp 1829.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... 1830.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... 1831.Pp 1832The arguments consist of one or more lines of text and macros 1833representing a complete table line. 1834Cells within the line are delimited by the special 1835.Ic \&Ta 1836block macro or by literal tab characters. 1837.Pp 1838Using literal tabs is strongly discouraged because they are very 1839hard to use correctly and 1840.Nm 1841code using them is very hard to read. 1842In particular, a blank character is syntactically significant 1843before and after the literal tab character. 1844If a word precedes or follows the tab without an intervening blank, 1845that word is never interpreted as a macro call, but always output 1846literally. 1847.Pp 1848The tab cell delimiter may only be used within the 1849.Ic \&It 1850line itself; on following lines, only the 1851.Ic \&Ta 1852macro can be used to delimit cells, and portability requires that 1853.Ic \&Ta 1854is called by other macros: some parsers do not recognize it when 1855it appears as the first macro on a line. 1856.Pp 1857Note that quoted strings may span tab-delimited cells on an 1858.Ic \&It 1859line. 1860For example, 1861.Pp 1862.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1863.Pp 1864will preserve the whitespace before both commas, 1865but not the whitespace before the semicolon. 1866.Pp 1867See also 1868.Ic \&Bl . 1869.Tg Lb 1870.It Ic \&Lb Cm lib Ns Ar name Op Cm lib Ns Ar name ... 1871Specify one or more libraries to link against. 1872Putting this macro at the beginning of the 1873.Em SYNOPSIS 1874section is recommended, in which case it prints this comment: 1875.D1 /* Fl l Ns Ar name Oo Fl l Ns Ar name ... Oc */ 1876.Pp 1877If used outside the 1878.Em SYNOPSIS , 1879this macro prints 1880.D1 library Dq Cm lib Ns Ar name 1881instead. 1882For system libraries, some operating systems 1883print a short library description. 1884.Pp 1885Example: 1886.Bd -literal -offset indent -compact 1887\&.Sh SYNOPSIS 1888\&.Lb libtls libssl libcrypto 1889\&.In tls.h 1890\&.Ft int 1891\&.Fn tls_init void 1892.Ed 1893.Tg Li 1894.It Ic \&Li Ar word ... 1895Unquoted in-line literal display, always set in a constant-width font. 1896In most cases, use 1897.Ic \&Ql 1898instead because on terminal output devices, 1899.Ic \&Li 1900is usually indistinguishable from normal text. 1901This macro is only useful when enclosing the argument in quotes 1902is explicitly not desired, for example because it already stands out 1903due to being wrapped in another macro, e.g. in an 1904.Ic \&It 1905head. 1906.Pp 1907For longer literal displays, use 1908.Ic \&Dl Pq single line 1909or 1910.Ic \&Bd Fl literal Pq multi-line 1911instead. 1912.Tg Lk 1913.It Ic \&Lk Ar uri Op Ar display_name 1914Format a hyperlink. 1915.Pp 1916Examples: 1917.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq 1918.Dl \&.Lk https://bsd.lv 1919.Pp 1920See also 1921.Ic \&Mt . 1922.It Ic \&Lp 1923Deprecated synonym for 1924.Ic \&Pp . 1925.Tg Ms 1926.It Ic \&Ms Ar name 1927Display a mathematical symbol. 1928.Pp 1929Examples: 1930.Dl \&.Ms sigma 1931.Dl \&.Ms aleph 1932.Tg Mt 1933.It Ic \&Mt Ar localpart Ns @ Ns Ar domain 1934Format a 1935.Dq mailto: 1936hyperlink. 1937.Pp 1938Examples: 1939.Dl \&.Mt discuss@manpages.bsd.lv 1940.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 1941.Tg Nd 1942.It Ic \&Nd Ar line 1943A one line description of the manual's content. 1944This is the mandatory last macro of the 1945.Em NAME 1946section and not appropriate for other sections. 1947.Pp 1948Examples: 1949.Dl Pf . Ic \&Nd mdoc language reference 1950.Dl Pf . Ic \&Nd format and display UNIX manuals 1951.Pp 1952The 1953.Ic \&Nd 1954macro technically accepts child macros and terminates with a subsequent 1955.Ic \&Sh 1956invocation. 1957Do not assume this behaviour: some 1958.Xr whatis 1 1959database generators are not smart enough to parse more than the line 1960arguments and will display macros verbatim. 1961.Pp 1962See also 1963.Ic \&Nm . 1964.Tg Nm 1965.It Ic \&Nm Op Ar name 1966The name of the manual page, or \(em in particular in section 1, 6, 1967and 8 pages \(em of an additional command or feature documented in 1968the manual page. 1969When first invoked, the 1970.Ic \&Nm 1971macro expects a single argument, the name of the manual page. 1972Usually, the first invocation happens in the 1973.Em NAME 1974section of the page. 1975The specified name will be remembered and used whenever the macro is 1976called again without arguments later in the page. 1977The 1978.Ic \&Nm 1979macro uses 1980.Sx Block full-implicit 1981semantics when invoked as the first macro on an input line in the 1982.Em SYNOPSIS 1983section; otherwise, it uses ordinary 1984.Sx In-line 1985semantics. 1986.Pp 1987Examples: 1988.Bd -literal -offset indent 1989\&.Sh SYNOPSIS 1990\&.Nm cat 1991\&.Op Fl benstuv 1992\&.Op Ar 1993.Ed 1994.Pp 1995In the 1996.Em SYNOPSIS 1997of section 2, 3 and 9 manual pages, use the 1998.Ic \&Fn 1999macro rather than 2000.Ic \&Nm 2001to mark up the name of the manual page. 2002.Tg No 2003.It Ic \&No Ar word ... 2004Normal text. 2005Closes the scope of any preceding in-line macro. 2006When used after physical formatting macros like 2007.Ic \&Em 2008or 2009.Ic \&Sy , 2010switches back to the standard font face and weight. 2011Can also be used to embed plain text strings in macro lines 2012using semantic annotation macros. 2013.Pp 2014Examples: 2015.Dl ".Em italic , Sy bold , No and roman" 2016.Bd -literal -offset indent 2017\&.Sm off 2018\&.Cm :C No / Ar pattern No / Ar replacement No / 2019\&.Sm on 2020.Ed 2021.Pp 2022See also 2023.Ic \&Em , 2024.Ic \&Ql , 2025and 2026.Ic \&Sy . 2027.Tg Ns 2028.It Ic \&Ns 2029Suppress a space between the output of the preceding macro 2030and the following text or macro. 2031Following invocation, input is interpreted as normal text 2032just like after an 2033.Ic \&No 2034macro. 2035.Pp 2036This has no effect when invoked at the start of a macro line. 2037.Pp 2038Examples: 2039.Dl ".Ar name Ns = Ns Ar value" 2040.Dl ".Cm :M Ns Ar pattern" 2041.Dl ".Fl o Ns Ar output" 2042.Pp 2043See also 2044.Ic \&No 2045and 2046.Ic \&Sm . 2047.Tg Nx 2048.It Ic \&Nx Op Ar version 2049Format the 2050.Nx 2051version provided as an argument, or a default value if 2052no argument is provided. 2053.Pp 2054Examples: 2055.Dl \&.Nx 5.01 2056.Dl \&.Nx 2057.Pp 2058See also 2059.Ic \&At , 2060.Ic \&Bsx , 2061.Ic \&Bx , 2062.Ic \&Dx , 2063.Ic \&Fx , 2064and 2065.Ic \&Ox . 2066.It Ic \&Oc 2067Close multi-line 2068.Ic \&Oo 2069context. 2070.It Ic \&Oo Ar block 2071Multi-line version of 2072.Ic \&Op . 2073.Pp 2074Examples: 2075.Bd -literal -offset indent -compact 2076\&.Oo 2077\&.Op Fl flag Ns Ar value 2078\&.Oc 2079.Ed 2080.Tg Op 2081.It Ic \&Op Ar line 2082Optional part of a command line. 2083Prints the argument(s) in brackets. 2084This is most often used in the 2085.Em SYNOPSIS 2086section of section 1 and 8 manual pages. 2087.Pp 2088Examples: 2089.Dl \&.Op \&Fl a \&Ar b 2090.Dl \&.Op \&Ar a | b 2091.Pp 2092See also 2093.Ic \&Oo . 2094.Tg Os 2095.It Ic \&Os Op Ar footer text 2096The mandatory third macro of every 2097.Nm 2098file. 2099Usually, do not specify any arguments, 2100in particular not the operating system name and/or version. 2101.Pp 2102If no argument is given, 2103.Xr mandoc 1 2104prints its 2105.Fl Ios 2106argument in the page footer, or 2107.Fa sysname 2108and 2109.Fa release 2110as returned by 2111.Xr uname 3 2112by default. 2113.Pp 2114Manual pages that are part of a portable software project can override 2115the default by giving the project name and version number as arguments, 2116but leaving it blank is never a bad choice. 2117.Pp 2118See also 2119.Ic \&Dd 2120and 2121.Ic \&Dt . 2122.It Ic \&Ot Ar functype 2123This macro is obsolete. 2124Use 2125.Ic \&Ft 2126instead; with 2127.Xr mandoc 1 , 2128both have the same effect. 2129.Pp 2130Historical 2131.Nm 2132packages described it as 2133.Dq "old function type (FORTRAN)" . 2134.Tg Ox 2135.It Ic \&Ox Op Ar version 2136Format the 2137.Ox 2138version provided as an argument, or a default value 2139if no argument is provided. 2140.Pp 2141Examples: 2142.Dl \&.Ox 4.5 2143.Dl \&.Ox 2144.Pp 2145See also 2146.Ic \&At , 2147.Ic \&Bsx , 2148.Ic \&Bx , 2149.Ic \&Dx , 2150.Ic \&Fx , 2151and 2152.Ic \&Nx . 2153.Tg Pa 2154.It Ic \&Pa Ar name ... 2155An absolute or relative file system path, or a file or directory name. 2156If an argument is not provided, the character 2157.Sq \(ti 2158is used as a default. 2159.Pp 2160Examples: 2161.Dl \&.Pa /usr/bin/mandoc 2162.Dl \&.Pa /usr/share/man/man7/mdoc.7 2163.Pp 2164See also 2165.Ic \&Lk . 2166.It Ic \&Pc 2167Close parenthesised context opened by 2168.Ic \&Po . 2169.Tg Pf 2170.It Ic \&Pf Ar prefix macro Op Ar argument ... 2171Removes the space between its argument and the following macro. 2172It is equivalent to: 2173.Pp 2174.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... 2175.Pp 2176The 2177.Ar prefix 2178argument is not parsed for macro names or delimiters, 2179but used verbatim as if it were escaped. 2180.Pp 2181Examples: 2182.Dl ".Pf $ Ar variable_name" 2183.Dl ".Pf . Ar macro_name" 2184.Dl ".Pf 0x Ar hex_digits" 2185.Pp 2186See also 2187.Ic \&Ns 2188and 2189.Ic \&Sm . 2190.It Ic \&Po Ar block 2191Multi-line version of 2192.Ic \&Pq . 2193.Tg Pp 2194.It Ic \&Pp 2195Break a paragraph. 2196This will assert vertical space between prior and subsequent macros 2197and/or text. 2198.Pp 2199Paragraph breaks are not needed before or after 2200.Ic \&Sh 2201or 2202.Ic \&Ss 2203macros or before displays 2204.Pq Ic \&Bd Ar line 2205or lists 2206.Pq Ic \&Bl 2207unless the 2208.Fl compact 2209flag is given. 2210.Tg Pq 2211.It Ic \&Pq Ar line 2212Parenthesised enclosure. 2213.Pp 2214See also 2215.Ic \&Po . 2216.It Ic \&Qc 2217Close quoted context opened by 2218.Ic \&Qo . 2219.Tg Ql 2220.It Ic \&Ql Ar line 2221Normal in-line literal display, always set in constant-width font and 2222additionally enclosed in quotes by many formatters in many cases. 2223This can be used for complete command invocations and for multi-word 2224code examples when an indented display is not desired. 2225.Pp 2226See also 2227.Ic \&Dl , 2228.Ic \&Bd 2229.Fl literal , 2230and 2231.Ic \&Li . 2232.It Ic \&Qo Ar block 2233Multi-line version of 2234.Ic \&Qq . 2235.Tg Qq 2236.It Ic \&Qq Ar line 2237Encloses its arguments in 2238.Qq typewriter 2239double-quotes. 2240Consider using 2241.Ic \&Dq . 2242.Pp 2243See also 2244.Ic \&Dq , 2245.Ic \&Sq , 2246and 2247.Ic \&Qo . 2248.It Ic \&Re 2249Close an 2250.Ic \&Rs 2251block. 2252Does not have any tail arguments. 2253.Tg Rs 2254.It Ic \&Rs 2255Begin a bibliographic 2256.Pq Dq reference 2257block. 2258Does not have any head arguments. 2259The block macro may only contain 2260.Ic \&%A , 2261.Ic \&%B , 2262.Ic \&%C , 2263.Ic \&%D , 2264.Ic \&%I , 2265.Ic \&%J , 2266.Ic \&%N , 2267.Ic \&%O , 2268.Ic \&%P , 2269.Ic \&%Q , 2270.Ic \&%R , 2271.Ic \&%T , 2272.Ic \&%U , 2273and 2274.Ic \&%V 2275child macros (at least one must be specified). 2276.Pp 2277Examples: 2278.Bd -literal -offset indent -compact 2279\&.Rs 2280\&.%A J. E. Hopcroft 2281\&.%A J. D. Ullman 2282\&.%B Introduction to Automata Theory, Languages, and Computation 2283\&.%I Addison-Wesley 2284\&.%C Reading, Massachusetts 2285\&.%D 1979 2286\&.Re 2287.Ed 2288.Pp 2289If an 2290.Ic \&Rs 2291block is used within a SEE ALSO section, a vertical space is asserted 2292before the rendered output, else the block continues on the current 2293line. 2294.Tg Rv 2295.It Ic \&Rv Fl std Op Ar function ... 2296Insert a standard sentence regarding a function call's return value of 0 2297on success and \-1 on error, with the 2298.Va errno 2299libc global variable set on error. 2300.Pp 2301If 2302.Ar function 2303is not specified, the document's name set by 2304.Ic \&Nm 2305is used. 2306Multiple 2307.Ar function 2308arguments are treated as separate functions. 2309.Pp 2310See also 2311.Ic \&Ex . 2312.It Ic \&Sc 2313Close single-quoted context opened by 2314.Ic \&So . 2315.Tg Sh 2316.It Ic \&Sh Ar TITLE LINE 2317Begin a new section. 2318For a list of conventional manual sections, see 2319.Sx MANUAL STRUCTURE . 2320Use the conventional sections where applicable. 2321For unusually long and complicated manual pages, 2322adding custom sections is occasionally useful. 2323.Pp 2324Avoid using macros inside the 2325.Ar TITLE LINE 2326and keep that line unique within the manual page, 2327such that it can be pointed to with 2328.Ic \&Sx . 2329.Pp 2330See also 2331.Ic \&Pp , 2332.Ic \&Ss , 2333and 2334.Ic \&Sx . 2335.Tg Sm 2336.It Ic \&Sm Op Cm on | off 2337Switches the spacing mode for output generated from macros. 2338.Pp 2339By default, spacing is 2340.Cm on . 2341When switched 2342.Cm off , 2343no white space is inserted between macro arguments and between the 2344output generated from adjacent macros, but text lines 2345still get normal spacing between words and sentences. 2346.Pp 2347When called without an argument, the 2348.Ic \&Sm 2349macro toggles the spacing mode. 2350Using this is not recommended because it makes the code harder to read. 2351.It Ic \&So Ar block 2352Multi-line version of 2353.Ic \&Sq . 2354.Tg Sq 2355.It Ic \&Sq Ar line 2356Encloses its arguments in 2357.Sq typewriter 2358single-quotes. 2359.Pp 2360See also 2361.Ic \&Dq , 2362.Ic \&Qq , 2363and 2364.Ic \&So . 2365.Tg Ss 2366.It Ic \&Ss Ar Title line 2367Begin a new subsection. 2368Unlike with 2369.Ic \&Sh , 2370there is no convention for the naming of subsections. 2371Except 2372.Em DESCRIPTION , 2373the conventional sections described in 2374.Sx MANUAL STRUCTURE 2375rarely have subsections. 2376.Pp 2377Avoid using macros inside the 2378.Ar Title line 2379and keep that line unique within the manual page, 2380such that it can be pointed to with 2381.Ic \&Sx . 2382.Pp 2383See also 2384.Ic \&Pp , 2385.Ic \&Sh , 2386and 2387.Ic \&Sx . 2388.Tg St 2389.It Ic \&St Fl Ns Ar abbreviation 2390Replace an abbreviation for a standard with the full form. 2391The following standards are recognised. 2392Where multiple lines are given without a blank line in between, 2393they all refer to the same standard, and using the first form 2394is recommended. 2395.Bl -tag -width 1n 2396.It C language standards 2397.Pp 2398.Bl -tag -width "-p1003.1g-2000" -compact 2399.It \-ansiC 2400.St -ansiC 2401.It \-ansiC-89 2402.St -ansiC-89 2403.It \-isoC 2404.St -isoC 2405.It \-isoC-90 2406.St -isoC-90 2407.br 2408The original C standard. 2409.Pp 2410.It \-isoC-amd1 2411.St -isoC-amd1 2412.Pp 2413.It \-isoC-tcor1 2414.St -isoC-tcor1 2415.Pp 2416.It \-isoC-tcor2 2417.St -isoC-tcor2 2418.Pp 2419.It \-isoC-99 2420.St -isoC-99 2421.br 2422Edition 2 of the C language standard. 2423.Pp 2424.It \-isoC-2011 2425.St -isoC-2011 2426.br 2427Edition 3 of the C language standard. 2428.Pp 2429.It \-isoC-2023 2430.St -isoC-2023 2431.br 2432Edition 5 of the C language standard. 2433.El 2434.It POSIX.1 before XPG4.2 2435.Pp 2436.Bl -tag -width "-p1003.1g-2000" -compact 2437.It \-p1003.1-88 2438.St -p1003.1-88 2439.It \-p1003.1 2440.St -p1003.1 2441.br 2442The original POSIX standard, based on ANSI C. 2443.Pp 2444.It \-p1003.1-90 2445.St -p1003.1-90 2446.It \-iso9945-1-90 2447.St -iso9945-1-90 2448.br 2449The first update of POSIX.1. 2450.Pp 2451.It \-p1003.1b-93 2452.St -p1003.1b-93 2453.It \-p1003.1b 2454.St -p1003.1b 2455.br 2456Real-time extensions. 2457.Pp 2458.It \-p1003.1c-95 2459.St -p1003.1c-95 2460.br 2461POSIX thread interfaces. 2462.Pp 2463.It \-p1003.1i-95 2464.St -p1003.1i-95 2465.br 2466Technical Corrigendum. 2467.Pp 2468.It \-p1003.1-96 2469.St -p1003.1-96 2470.It \-iso9945-1-96 2471.St -iso9945-1-96 2472.br 2473Includes POSIX.1-1990, 1b, 1c, and 1i. 2474.El 2475.It X/Open Portability Guide before XPG4.2 2476.Pp 2477.Bl -tag -width "-p1003.1g-2000" -compact 2478.It \-xpg3 2479.St -xpg3 2480.br 2481An XPG4 precursor, published in 1989. 2482.Pp 2483.It \-p1003.2 2484.St -p1003.2 2485.It \-p1003.2-92 2486.St -p1003.2-92 2487.It \-iso9945-2-93 2488.St -iso9945-2-93 2489.br 2490An XCU4 precursor. 2491.Pp 2492.It \-p1003.2a-92 2493.St -p1003.2a-92 2494.br 2495Updates to POSIX.2. 2496.Pp 2497.It \-xpg4 2498.St -xpg4 2499.br 2500Based on POSIX.1 and POSIX.2, published in 1992. 2501.El 2502.It X/Open Portability Guide Issue 4 Version 2 and related standards 2503.Pp 2504.Bl -tag -width "-p1003.1g-2000" -compact 2505.It \-susv1 2506.St -susv1 2507.It \-xpg4.2 2508.St -xpg4.2 2509.br 2510This standard was published in 1994. 2511It was used as the basis for UNIX 95 certification. 2512The following two refer to parts of it. 2513.Pp 2514.It \-xcurses4.2 2515.St -xcurses4.2 2516.Pp 2517.It \-p1003.1g-2000 2518.St -p1003.1g-2000 2519.br 2520Networking APIs, including sockets. 2521.Pp 2522.It \-svid4 2523.St -svid4 , 2524.br 2525Published in 1995. 2526.El 2527.It X/Open Portability Guide Issue 5 and related standards 2528.Pp 2529.Bl -tag -width "-p1003.1g-2000" -compact 2530.It \-susv2 2531.St -susv2 2532.br 2533This Standard was published in 1997 2534and is also called X/Open Portability Guide Issue 5. 2535It was used as the basis for UNIX 98 certification. 2536The following refer to parts of it. 2537.Pp 2538.It \-xbd5 2539.St -xbd5 2540.Pp 2541.It \-xsh5 2542.St -xsh5 2543.Pp 2544.It \-xcu5 2545.St -xcu5 2546.Pp 2547.It \-xns5 2548.St -xns5 2549.It \-xns5.2 2550.St -xns5.2 2551.El 2552.It POSIX Issue 6 2553.Pp 2554.Bl -tag -width "-p1003.1-2001" -compact 2555.It \-p1003.1-2001 2556.St -p1003.1-2001 2557.It \-susv3 2558.St -susv3 2559.br 2560This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2561It is also called X/Open Portability Guide Issue 6. 2562It is used as the basis for UNIX 03 certification. 2563.Pp 2564.It \-p1003.1-2004 2565.St -p1003.1-2004 2566.br 2567The second and last Technical Corrigendum. 2568.El 2569.It POSIX Issues 7 and 8 2570.Pp 2571.Bl -tag -width "-p1003.1g-2000" -compact 2572.It \-p1003.1-2008 2573.St -p1003.1-2008 2574.It \-susv4 2575.St -susv4 2576.br 2577This standard is based on C99. 2578It is also called the 2579Open Group Standard Base Specifications, Issue 7. 2580.El 2581.Pp 2582.Bl -tag -width "-p1003.1g-2000" -compact 2583.It \-p1003.1-2024 2584.St -p1003.1-2024 2585.br 2586This standard is based on C17. 2587It is also called the 2588Open Group Standard Base Specifications, Issue 8. 2589.El 2590.It Other standards 2591.Pp 2592.Bl -tag -width "-p1003.1g-2000" -compact 2593.It \-ieee754 2594.St -ieee754 2595.br 2596Floating-point arithmetic. 2597.Pp 2598.It \-iso8601 2599.St -iso8601 2600.br 2601Representation of dates and times, published in 1988. 2602.Pp 2603.It \-iso8802-3 2604.St -iso8802-3 2605.br 2606Ethernet local area networks. 2607.Pp 2608.It \-ieee1275-94 2609.St -ieee1275-94 2610.El 2611.El 2612.Tg Sx 2613.It Ic \&Sx Ar Title line 2614Reference a section or subsection in the same manual page. 2615The referenced section or subsection name must be identical to the 2616enclosed argument, including whitespace. 2617.Pp 2618Examples: 2619.Dl \&.Sx MANUAL STRUCTURE 2620.Pp 2621See also 2622.Ic \&Sh 2623and 2624.Ic \&Ss . 2625.Tg Sy 2626.It Ic \&Sy Ar word ... 2627Request a boldface font. 2628.Pp 2629This is most often used to indicate importance or seriousness (not to be 2630confused with stress emphasis, see 2631.Ic \&Em ) . 2632When none of the semantic macros fit, it is also adequate for syntax 2633elements that have to be given or that appear verbatim. 2634.Pp 2635Examples: 2636.Bd -literal -compact -offset indent 2637\&.Sy Warning : 2638If 2639\&.Sy s 2640appears in the owner permissions, set-user-ID mode is set. 2641This utility replaces the former 2642\&.Sy dumpdir 2643program. 2644.Ed 2645.Pp 2646See also 2647.Ic \&Em , 2648.Ic \&No , 2649and 2650.Ic \&Ql . 2651.Tg Ta 2652.It Ic \&Ta 2653Table cell separator in 2654.Ic \&Bl Fl column 2655lists; can only be used below 2656.Ic \&It . 2657.Tg Tg 2658.It Ic \&Tg Op Ar term 2659Announce that the next input line starts a definition of the 2660.Ar term . 2661This macro must appear alone on its own input line. 2662The argument defaults to the first argument of the first macro 2663on the next line. 2664The argument may not contain whitespace characters, not even when it is quoted. 2665This macro is a 2666.Xr mandoc 1 2667extension and is typically ignored by other formatters. 2668.Pp 2669When viewing terminal output with 2670.Xr less 1 , 2671the interactive 2672.Ic :t 2673command can be used to go to the definition of the 2674.Ar term 2675as described for the 2676.Ev MANPAGER 2677variable in 2678.Xr man 1 ; 2679when producing HTML output, a fragment identifier 2680.Pq Ic id No attribute 2681is generated, to be used for deep linking to this place of the document. 2682.Pp 2683In most cases, adding a 2684.Ic \&Tg 2685macro would be redundant because 2686.Xr mandoc 1 2687is able to automatically tag most definitions. 2688This macro is intended for cases where automatic tagging of a 2689.Ar term 2690is unsatisfactory, for example if a definition is not tagged 2691automatically (false negative) or if places are tagged that do 2692not define the 2693.Ar term 2694(false positives). 2695When there is at least one 2696.Ic \&Tg 2697macro for a 2698.Ar term , 2699no other places are automatically marked as definitions of that 2700.Ar term . 2701.It Ic \&Tn Ar word ... 2702Supported only for compatibility, do not use this in new manuals. 2703Even though the macro name 2704.Pq Dq tradename 2705suggests a semantic function, historic usage is inconsistent, mostly 2706using it as a presentation-level macro to request a small caps font. 2707.It Ic \&Ud 2708Supported only for compatibility, do not use this in new manuals. 2709Prints out 2710.Dq currently under development. 2711.It Ic \&Ux 2712Supported only for compatibility, do not use this in new manuals. 2713Prints out 2714.Dq Ux . 2715.Tg Va 2716.It Ic \&Va Oo Ar type Oc Ar identifier ... 2717A variable name. 2718.Pp 2719Examples: 2720.Dl \&.Va foo 2721.Dl \&.Va const char *bar ; 2722.Pp 2723For function arguments and parameters, use 2724.Ic \&Fa 2725instead. 2726For declarations of global variables in the 2727.Em SYNOPSIS 2728section, use 2729.Ic \&Vt . 2730.Tg Vt 2731.It Ic \&Vt Ar type Op Ar identifier 2732A variable type. 2733.Pp 2734This is also used for indicating global variables in the 2735.Em SYNOPSIS 2736section, in which case a variable name is also specified. 2737Note that it accepts 2738.Sx Block partial-implicit 2739syntax when invoked as the first macro on an input line in the 2740.Em SYNOPSIS 2741section, else it accepts ordinary 2742.Sx In-line 2743syntax. 2744In the former case, this macro starts a new output line, 2745and a blank line is inserted in front if there is a preceding 2746function definition or include directive. 2747.Pp 2748Examples: 2749.Dl \&.Vt unsigned char 2750.Dl \&.Vt extern const char * const sys_signame[] \&; 2751.Pp 2752For parameters in function prototypes, use 2753.Ic \&Fa 2754instead, for function return types 2755.Ic \&Ft , 2756and for variable names outside the 2757.Em SYNOPSIS 2758section 2759.Ic \&Va , 2760even when including a type with the name. 2761See also 2762.Sx MANUAL STRUCTURE . 2763.It Ic \&Xc 2764Close a scope opened by 2765.Ic \&Xo . 2766.It Ic \&Xo Ar block 2767Extend the header of an 2768.Ic \&It 2769macro or the body of a partial-implicit block macro 2770beyond the end of the input line. 2771This macro originally existed to work around the 9-argument limit 2772of historic 2773.Xr roff 7 . 2774.Tg Xr 2775.It Ic \&Xr Ar name section 2776Link to another manual 2777.Pq Qq cross-reference . 2778.Pp 2779Cross reference the 2780.Ar name 2781and 2782.Ar section 2783number of another man page. 2784.Pp 2785Examples: 2786.Dl \&.Xr mandoc 1 2787.Dl \&.Xr mandoc 1 \&; 2788.Dl \&.Xr mandoc 1 \&Ns s behaviour 2789.El 2790.Sh MACRO SYNTAX 2791The syntax of a macro depends on its classification. 2792In this section, 2793.Sq \-arg 2794refers to macro arguments, which may be followed by zero or more 2795.Sq parm 2796parameters; 2797.Sq \&Yo 2798opens the scope of a macro; and if specified, 2799.Sq \&Yc 2800closes it out. 2801.Pp 2802The 2803.Em Callable 2804column indicates that the macro may also be called by passing its name 2805as an argument to another macro. 2806For example, 2807.Sq \&.Op \&Fl O \&Ar file 2808produces 2809.Sq Op Fl O Ar file . 2810To prevent a macro call and render the macro name literally, 2811escape it by prepending a zero-width space, 2812.Sq \e& . 2813For example, 2814.Sq \&Op \e&Fl O 2815produces 2816.Sq Op \&Fl O . 2817If a macro is not callable but its name appears as an argument 2818to another macro, it is interpreted as opaque text. 2819For example, 2820.Sq \&.Fl \&Sh 2821produces 2822.Sq Fl \&Sh . 2823.Pp 2824The 2825.Em Parsed 2826column indicates whether the macro may call other macros by receiving 2827their names as arguments. 2828If a macro is not parsed but the name of another macro appears 2829as an argument, it is interpreted as opaque text. 2830.Pp 2831The 2832.Em Scope 2833column, if applicable, describes closure rules. 2834.Ss Block full-explicit 2835Multi-line scope closed by an explicit closing macro. 2836All macros contains bodies; only 2837.Ic \&Bf 2838and 2839.Pq optionally 2840.Ic \&Bl 2841contain a head. 2842.Bd -literal -offset indent 2843\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2844\(lBbody...\(rB 2845\&.Yc 2846.Ed 2847.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2848.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2849.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed 2850.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef 2851.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek 2852.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El 2853.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd 2854.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf 2855.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk 2856.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl 2857.El 2858.Ss Block full-implicit 2859Multi-line scope closed by end-of-file or implicitly by another macro. 2860All macros have bodies; some 2861.Po 2862.Ic \&It Fl bullet , 2863.Fl hyphen , 2864.Fl dash , 2865.Fl enum , 2866.Fl item 2867.Pc 2868don't have heads; only one 2869.Po 2870.Ic \&It 2871in 2872.Ic \&Bl Fl column 2873.Pc 2874has multiple heads. 2875.Bd -literal -offset indent 2876\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2877\(lBbody...\(rB 2878.Ed 2879.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2880.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2881.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El 2882.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh 2883.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss 2884.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh 2885.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss 2886.El 2887.Pp 2888Note that the 2889.Ic \&Nm 2890macro is a 2891.Sx Block full-implicit 2892macro only when invoked as the first macro 2893in a 2894.Em SYNOPSIS 2895section line, else it is 2896.Sx In-line . 2897.Ss Block partial-explicit 2898Like block full-explicit, but also with single-line scope. 2899Each has at least a body and, in limited circumstances, a head 2900.Po 2901.Ic \&Fo , 2902.Ic \&Eo 2903.Pc 2904and/or tail 2905.Pq Ic \&Ec . 2906.Bd -literal -offset indent 2907\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2908\(lBbody...\(rB 2909\&.Yc \(lBtail...\(rB 2910 2911\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2912\(lBbody...\(rB \&Yc \(lBtail...\(rB 2913.Ed 2914.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2915.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2916.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao 2917.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac 2918.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo 2919.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc 2920.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro 2921.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc 2922.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do 2923.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc 2924.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo 2925.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec 2926.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo 2927.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc 2928.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo 2929.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc 2930.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po 2931.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc 2932.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo 2933.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc 2934.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs 2935.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re 2936.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So 2937.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc 2938.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo 2939.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc 2940.El 2941.Ss Block partial-implicit 2942Like block full-implicit, but with single-line scope closed by the 2943end of the line. 2944.Bd -literal -offset indent 2945\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 2946.Ed 2947.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 2948.It Em Macro Ta Em Callable Ta Em Parsed 2949.It Ic \&Aq Ta Yes Ta Yes 2950.It Ic \&Bq Ta Yes Ta Yes 2951.It Ic \&Brq Ta Yes Ta Yes 2952.It Ic \&D1 Ta \&No Ta \&Yes 2953.It Ic \&Dl Ta \&No Ta Yes 2954.It Ic \&Dq Ta Yes Ta Yes 2955.It Ic \&En Ta Yes Ta Yes 2956.It Ic \&Op Ta Yes Ta Yes 2957.It Ic \&Pq Ta Yes Ta Yes 2958.It Ic \&Ql Ta Yes Ta Yes 2959.It Ic \&Qq Ta Yes Ta Yes 2960.It Ic \&Sq Ta Yes Ta Yes 2961.It Ic \&Vt Ta Yes Ta Yes 2962.El 2963.Pp 2964Note that the 2965.Ic \&Vt 2966macro is a 2967.Sx Block partial-implicit 2968only when invoked as the first macro 2969in a 2970.Em SYNOPSIS 2971section line, else it is 2972.Sx In-line . 2973.Ss Special block macro 2974The 2975.Ic \&Ta 2976macro can only be used below 2977.Ic \&It 2978in 2979.Ic \&Bl Fl column 2980lists. 2981It delimits blocks representing table cells; 2982these blocks have bodies, but no heads. 2983.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2984.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2985.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It 2986.El 2987.Ss In-line 2988Closed by the end of the line, fixed argument lengths, 2989and/or subsequent macros. 2990In-line macros have only text children. 2991If a number (or inequality) of arguments is 2992.Pq n , 2993then the macro accepts an arbitrary number of arguments. 2994.Bd -literal -offset indent 2995\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 2996 2997\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 2998 2999\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 3000.Ed 3001.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 3002.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 3003.It Ic \&%A Ta \&No Ta \&No Ta >0 3004.It Ic \&%B Ta \&No Ta \&No Ta >0 3005.It Ic \&%C Ta \&No Ta \&No Ta >0 3006.It Ic \&%D Ta \&No Ta \&No Ta >0 3007.It Ic \&%I Ta \&No Ta \&No Ta >0 3008.It Ic \&%J Ta \&No Ta \&No Ta >0 3009.It Ic \&%N Ta \&No Ta \&No Ta >0 3010.It Ic \&%O Ta \&No Ta \&No Ta >0 3011.It Ic \&%P Ta \&No Ta \&No Ta >0 3012.It Ic \&%Q Ta \&No Ta \&No Ta >0 3013.It Ic \&%R Ta \&No Ta \&No Ta >0 3014.It Ic \&%T Ta \&No Ta \&No Ta >0 3015.It Ic \&%U Ta \&No Ta \&No Ta >0 3016.It Ic \&%V Ta \&No Ta \&No Ta >0 3017.It Ic \&Ad Ta Yes Ta Yes Ta >0 3018.It Ic \&An Ta Yes Ta Yes Ta >0 3019.It Ic \&Ap Ta Yes Ta Yes Ta 0 3020.It Ic \&Ar Ta Yes Ta Yes Ta n 3021.It Ic \&At Ta Yes Ta Yes Ta 1 3022.It Ic \&Bsx Ta Yes Ta Yes Ta n 3023.It Ic \&Bt Ta \&No Ta \&No Ta 0 3024.It Ic \&Bx Ta Yes Ta Yes Ta n 3025.It Ic \&Cd Ta Yes Ta Yes Ta >0 3026.It Ic \&Cm Ta Yes Ta Yes Ta >0 3027.It Ic \&Db Ta \&No Ta \&No Ta 1 3028.It Ic \&Dd Ta \&No Ta \&No Ta n 3029.It Ic \&Dt Ta \&No Ta \&No Ta n 3030.It Ic \&Dv Ta Yes Ta Yes Ta >0 3031.It Ic \&Dx Ta Yes Ta Yes Ta n 3032.It Ic \&Em Ta Yes Ta Yes Ta >0 3033.It Ic \&Er Ta Yes Ta Yes Ta >0 3034.It Ic \&Es Ta Yes Ta Yes Ta 2 3035.It Ic \&Ev Ta Yes Ta Yes Ta >0 3036.It Ic \&Ex Ta \&No Ta \&No Ta n 3037.It Ic \&Fa Ta Yes Ta Yes Ta >0 3038.It Ic \&Fd Ta \&No Ta \&No Ta >0 3039.It Ic \&Fl Ta Yes Ta Yes Ta n 3040.It Ic \&Fn Ta Yes Ta Yes Ta >0 3041.It Ic \&Fr Ta Yes Ta Yes Ta >0 3042.It Ic \&Ft Ta Yes Ta Yes Ta >0 3043.It Ic \&Fx Ta Yes Ta Yes Ta n 3044.It Ic \&Hf Ta \&No Ta \&No Ta n 3045.It Ic \&Ic Ta Yes Ta Yes Ta >0 3046.It Ic \&In Ta Yes Ta Yes Ta 1 3047.It Ic \&Lb Ta \&No Ta \&No Ta >0 3048.It Ic \&Li Ta Yes Ta Yes Ta >0 3049.It Ic \&Lk Ta Yes Ta Yes Ta >0 3050.It Ic \&Lp Ta \&No Ta \&No Ta 0 3051.It Ic \&Ms Ta Yes Ta Yes Ta >0 3052.It Ic \&Mt Ta Yes Ta Yes Ta >0 3053.It Ic \&Nm Ta Yes Ta Yes Ta n 3054.It Ic \&No Ta Yes Ta Yes Ta >0 3055.It Ic \&Ns Ta Yes Ta Yes Ta 0 3056.It Ic \&Nx Ta Yes Ta Yes Ta n 3057.It Ic \&Os Ta \&No Ta \&No Ta n 3058.It Ic \&Ot Ta Yes Ta Yes Ta >0 3059.It Ic \&Ox Ta Yes Ta Yes Ta n 3060.It Ic \&Pa Ta Yes Ta Yes Ta n 3061.It Ic \&Pf Ta Yes Ta Yes Ta 1 3062.It Ic \&Pp Ta \&No Ta \&No Ta 0 3063.It Ic \&Rv Ta \&No Ta \&No Ta n 3064.It Ic \&Sm Ta \&No Ta \&No Ta <2 3065.It Ic \&St Ta \&No Ta Yes Ta 1 3066.It Ic \&Sx Ta Yes Ta Yes Ta >0 3067.It Ic \&Sy Ta Yes Ta Yes Ta >0 3068.It Ic \&Tg Ta \&No Ta \&No Ta <2 3069.It Ic \&Tn Ta Yes Ta Yes Ta >0 3070.It Ic \&Ud Ta \&No Ta \&No Ta 0 3071.It Ic \&Ux Ta Yes Ta Yes Ta n 3072.It Ic \&Va Ta Yes Ta Yes Ta n 3073.It Ic \&Vt Ta Yes Ta Yes Ta >0 3074.It Ic \&Xr Ta Yes Ta Yes Ta 2 3075.El 3076.Ss Delimiters 3077When a macro argument consists of one single input character 3078considered as a delimiter, the argument gets special handling. 3079This does not apply when delimiters appear in arguments containing 3080more than one character. 3081Consequently, to prevent special handling and just handle it 3082like any other argument, a delimiter can be escaped by prepending 3083a zero-width space 3084.Pq Sq \e& . 3085In text lines, delimiters never need escaping, but may be used 3086as normal punctuation. 3087.Pp 3088For many macros, when the leading arguments are opening delimiters, 3089these delimiters are put before the macro scope, 3090and when the trailing arguments are closing delimiters, 3091these delimiters are put after the macro scope. 3092Spacing is suppressed after opening delimiters 3093and before closing delimiters. 3094For example, 3095.Pp 3096.D1 Pf \. \&Aq "( [ word ] ) ." 3097.Pp 3098renders as: 3099.Pp 3100.D1 Aq ( [ word ] ) . 3101.Pp 3102Opening delimiters are: 3103.Pp 3104.Bl -tag -width Ds -offset indent -compact 3105.It \&( 3106left parenthesis 3107.It \&[ 3108left bracket 3109.El 3110.Pp 3111Closing delimiters are: 3112.Pp 3113.Bl -tag -width Ds -offset indent -compact 3114.It \&. 3115period 3116.It \&, 3117comma 3118.It \&: 3119colon 3120.It \&; 3121semicolon 3122.It \&) 3123right parenthesis 3124.It \&] 3125right bracket 3126.It \&? 3127question mark 3128.It \&! 3129exclamation mark 3130.El 3131.Pp 3132Note that even a period preceded by a backslash 3133.Pq Sq \e.\& 3134gets this special handling; use 3135.Sq \e&.\& 3136to prevent that. 3137.Pp 3138Many in-line macros interrupt their scope when they encounter 3139delimiters, and resume their scope when more arguments follow that 3140are not delimiters. 3141For example, 3142.Pp 3143.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 3144.Pp 3145renders as: 3146.Pp 3147.D1 Fl a ( b | c \*(Ba d ) e 3148.Pp 3149This applies to both opening and closing delimiters, 3150and also to the middle delimiter, which does not suppress spacing: 3151.Pp 3152.Bl -tag -width Ds -offset indent -compact 3153.It \&| 3154vertical bar 3155.El 3156.Pp 3157As a special case, the predefined string \e*(Ba is handled and rendered 3158in the same way as a plain 3159.Sq \&| 3160character. 3161Using this predefined string is not recommended in new manuals. 3162.Pp 3163Appending a zero-width space 3164.Pq Sq \e& 3165to the end of an input line is also useful to prevent the interpretation 3166of a trailing period, exclamation or question mark as the end of a 3167sentence, for example when an abbreviation happens to occur 3168at the end of a text or macro input line. 3169.Ss Font handling 3170In 3171.Nm 3172documents, usage of semantic markup is recommended in order to have 3173proper fonts automatically selected; only when no fitting semantic markup 3174is available, consider falling back to 3175.Sx Physical markup 3176macros. 3177Whenever any 3178.Nm 3179macro switches the 3180.Xr roff 7 3181font mode, it will automatically restore the previous font when exiting 3182its scope. 3183Manually switching the font using the 3184.Xr roff 7 3185.Ql \ef 3186font escape sequences is never required. 3187.Sh COMPATIBILITY 3188This section provides an incomplete list of compatibility issues 3189between mandoc and GNU troff 3190.Pq Qq groff . 3191.Pp 3192The following problematic behaviour is found in groff: 3193.Pp 3194.Bl -dash -compact 3195.It 3196.Ic \&Pa 3197does not format its arguments when used in the FILES section under 3198certain list types. 3199.It 3200.Ic \&Ta 3201can only be called by other macros, but not at the beginning of a line. 3202.It 3203.Sq \ef 3204.Pq font face 3205and 3206.Sq \eF 3207.Pq font family face 3208.Sx Text Decoration 3209escapes behave irregularly when specified within line-macro scopes. 3210.It 3211Negative scaling units return to prior lines. 3212Instead, mandoc truncates them to zero. 3213.El 3214.Pp 3215The following features are unimplemented in mandoc: 3216.Pp 3217.Bl -dash -compact 3218.It 3219.Ic \&Bd Fl file Ar file 3220is unsupported for security reasons. 3221.It 3222.Ic \&Bd 3223.Fl filled 3224does not adjust the right margin, but is an alias for 3225.Ic \&Bd 3226.Fl ragged . 3227.It 3228.Ic \&Bd 3229.Fl literal 3230does not use a literal font, but is an alias for 3231.Ic \&Bd 3232.Fl unfilled . 3233.It 3234.Ic \&Bd 3235.Fl offset Cm center 3236and 3237.Fl offset Cm right 3238don't work. 3239Groff does not implement centered and flush-right rendering either, 3240but produces large indentations. 3241.El 3242.Sh SEE ALSO 3243.Xr man 1 , 3244.Xr mandoc 1 , 3245.Xr eqn 7 , 3246.Xr man 7 , 3247.Xr mandoc_char 7 , 3248.Xr roff 7 , 3249.Xr tbl 7 3250.Pp 3251The web page 3252.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3253provides a few tutorial-style pages for beginners, an extensive style 3254guide for advanced authors, and an alphabetic index helping to choose 3255the best macros for various kinds of content. 3256.Pp 3257The manual page 3258.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)" 3259contained in the 3260.Dq groff 3261package documents exactly the same language in a somewhat different style. 3262.Sh HISTORY 3263The 3264.Nm 3265language first appeared as a troff macro package in 3266.Bx 4.4 . 3267It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3268in groff-1.17. 3269The standalone implementation that is part of the 3270.Xr mandoc 1 3271utility written by Kristaps Dzonsons appeared in 3272.Ox 4.6 . 3273.Sh AUTHORS 3274The 3275.Nm 3276reference was written by 3277.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3278