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