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