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