1.\" $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: July 28 2018 $ 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 integer number, 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 2 2018$ 1268.Dl \&.Dd July 2, 2018 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, for example 1369.Cm alpha , 1370.Cm amd64 , 1371.Cm i386 , 1372or 1373.Cm sparc64 . 1374The list of valid architectures varies by operating system. 1375.El 1376.Pp 1377Examples: 1378.Dl \&.Dt FOO 1 1379.Dl \&.Dt FOO 9 i386 1380.Pp 1381See also 1382.Sx \&Dd 1383and 1384.Sx \&Os . 1385.Ss \&Dv 1386Defined variables such as preprocessor constants, constant symbols, 1387enumeration values, and so on. 1388.Pp 1389Examples: 1390.Dl \&.Dv NULL 1391.Dl \&.Dv BUFSIZ 1392.Dl \&.Dv STDOUT_FILENO 1393.Pp 1394See also 1395.Sx \&Er 1396and 1397.Sx \&Ev 1398for special-purpose constants, 1399.Sx \&Va 1400for variable symbols, and 1401.Sx \&Fd 1402for listing preprocessor variable definitions in the 1403.Em SYNOPSIS . 1404.Ss \&Dx 1405Format the 1406.Dx 1407version provided as an argument, or a default 1408value if no argument is provided. 1409.Pp 1410Examples: 1411.Dl \&.Dx 2.4.1 1412.Dl \&.Dx 1413.Pp 1414See also 1415.Sx \&At , 1416.Sx \&Bsx , 1417.Sx \&Bx , 1418.Sx \&Fx , 1419.Sx \&Nx , 1420and 1421.Sx \&Ox . 1422.Ss \&Ec 1423Close a scope started by 1424.Sx \&Eo . 1425Its syntax is as follows: 1426.Pp 1427.D1 Pf \. Sx \&Ec Op Ar TERM 1428.Pp 1429The 1430.Ar TERM 1431argument is used as the enclosure tail, for example, specifying \e(rq 1432will emulate 1433.Sx \&Dc . 1434.Ss \&Ed 1435End a display context started by 1436.Sx \&Bd . 1437.Ss \&Ef 1438End a font mode context started by 1439.Sx \&Bf . 1440.Ss \&Ek 1441End a keep context started by 1442.Sx \&Bk . 1443.Ss \&El 1444End a list context started by 1445.Sx \&Bl . 1446.Pp 1447See also 1448.Sx \&Bl 1449and 1450.Sx \&It . 1451.Ss \&Em 1452Request an italic font. 1453If the output device does not provide that, underline. 1454.Pp 1455This is most often used for stress emphasis (not to be confused with 1456importance, see 1457.Sx \&Sy ) . 1458In the rare cases where none of the semantic markup macros fit, 1459it can also be used for technical terms and placeholders, except 1460that for syntax elements, 1461.Sx \&Sy 1462and 1463.Sx \&Ar 1464are preferred, respectively. 1465.Pp 1466Examples: 1467.Bd -literal -compact -offset indent 1468Selected lines are those 1469\&.Em not 1470matching any of the specified patterns. 1471Some of the functions use a 1472\&.Em hold space 1473to save the pattern space for subsequent retrieval. 1474.Ed 1475.Pp 1476See also 1477.Sx \&Bf , 1478.Sx \&Li , 1479.Sx \&No , 1480and 1481.Sx \&Sy . 1482.Ss \&En 1483This macro is obsolete. 1484Use 1485.Sx \&Eo 1486or any of the other enclosure macros. 1487.Pp 1488It encloses its argument in the delimiters specified by the last 1489.Sx \&Es 1490macro. 1491.Ss \&Eo 1492An arbitrary enclosure. 1493Its syntax is as follows: 1494.Pp 1495.D1 Pf \. Sx \&Eo Op Ar TERM 1496.Pp 1497The 1498.Ar TERM 1499argument is used as the enclosure head, for example, specifying \e(lq 1500will emulate 1501.Sx \&Do . 1502.Ss \&Er 1503Error constants for definitions of the 1504.Va errno 1505libc global variable. 1506This is most often used in section 2 and 3 manual pages. 1507.Pp 1508Examples: 1509.Dl \&.Er EPERM 1510.Dl \&.Er ENOENT 1511.Pp 1512See also 1513.Sx \&Dv 1514for general constants. 1515.Ss \&Es 1516This macro is obsolete. 1517Use 1518.Sx \&Eo 1519or any of the other enclosure macros. 1520.Pp 1521It takes two arguments, defining the delimiters to be used by subsequent 1522.Sx \&En 1523macros. 1524.Ss \&Ev 1525Environmental variables such as those specified in 1526.Xr environ 7 . 1527.Pp 1528Examples: 1529.Dl \&.Ev DISPLAY 1530.Dl \&.Ev PATH 1531.Pp 1532See also 1533.Sx \&Dv 1534for general constants. 1535.Ss \&Ex 1536Insert a standard sentence regarding command exit values of 0 on success 1537and >0 on failure. 1538This is most often used in section 1, 6, and 8 manual pages. 1539Its syntax is as follows: 1540.Pp 1541.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... 1542.Pp 1543If 1544.Ar utility 1545is not specified, the document's name set by 1546.Sx \&Nm 1547is used. 1548Multiple 1549.Ar utility 1550arguments are treated as separate utilities. 1551.Pp 1552See also 1553.Sx \&Rv . 1554.Ss \&Fa 1555Function argument or parameter. 1556Its syntax is as follows: 1557.Bd -ragged -offset indent 1558.Pf \. Sx \&Fa 1559.Qo 1560.Op Ar argtype 1561.Op Ar argname 1562.Qc Ar \&... 1563.Ed 1564.Pp 1565Each argument may be a name and a type (recommended for the 1566.Em SYNOPSIS 1567section), a name alone (for function invocations), 1568or a type alone (for function prototypes). 1569If both a type and a name are given or if the type consists of multiple 1570words, all words belonging to the same function argument have to be 1571given in a single argument to the 1572.Sx \&Fa 1573macro. 1574.Pp 1575This macro is also used to specify the field name of a structure. 1576.Pp 1577Most often, the 1578.Sx \&Fa 1579macro is used in the 1580.Em SYNOPSIS 1581within 1582.Sx \&Fo 1583blocks when documenting multi-line function prototypes. 1584If invoked with multiple arguments, the arguments are separated by a 1585comma. 1586Furthermore, if the following macro is another 1587.Sx \&Fa , 1588the last argument will also have a trailing comma. 1589.Pp 1590Examples: 1591.Dl \&.Fa \(dqconst char *p\(dq 1592.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1593.Dl \&.Fa \(dqchar *\(dq size_t 1594.Pp 1595See also 1596.Sx \&Fo . 1597.Ss \&Fc 1598End a function context started by 1599.Sx \&Fo . 1600.Ss \&Fd 1601Preprocessor directive, in particular for listing it in the 1602.Em SYNOPSIS . 1603Historically, it was also used to document include files. 1604The latter usage has been deprecated in favour of 1605.Sx \&In . 1606.Pp 1607Its syntax is as follows: 1608.Bd -ragged -offset indent 1609.Pf \. Sx \&Fd 1610.Li # Ns Ar directive 1611.Op Ar argument ... 1612.Ed 1613.Pp 1614Examples: 1615.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1616.Dl \&.Fd #define SIO_MAXNFDS 1617.Dl \&.Fd #ifdef FS_DEBUG 1618.Dl \&.Ft void 1619.Dl \&.Fn dbg_open \(dqconst char *\(dq 1620.Dl \&.Fd #endif 1621.Pp 1622See also 1623.Sx MANUAL STRUCTURE , 1624.Sx \&In , 1625and 1626.Sx \&Dv . 1627.Ss \&Fl 1628Command-line flag or option. 1629Used when listing arguments to command-line utilities. 1630Prints a fixed-width hyphen 1631.Sq \- 1632directly followed by each argument. 1633If no arguments are provided, a hyphen is printed followed by a space. 1634If the argument is a macro, a hyphen is prefixed to the subsequent macro 1635output. 1636.Pp 1637Examples: 1638.Dl ".Fl R Op Fl H | L | P" 1639.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1640.Dl ".Fl type Cm d Fl name Pa CVS" 1641.Dl ".Fl Ar signal_number" 1642.Dl ".Fl o Fl" 1643.Pp 1644See also 1645.Sx \&Cm . 1646.Ss \&Fn 1647A function name. 1648Its syntax is as follows: 1649.Bd -ragged -offset indent 1650.Pf . Sx \&Fn 1651.Op Ar functype 1652.Ar funcname 1653.Op Oo Ar argtype Oc Ar argname 1654.Ed 1655.Pp 1656Function arguments are surrounded in parenthesis and 1657are delimited by commas. 1658If no arguments are specified, blank parenthesis are output. 1659In the 1660.Em SYNOPSIS 1661section, this macro starts a new output line, 1662and a blank line is automatically inserted between function definitions. 1663.Pp 1664Examples: 1665.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1666.Dl \&.Fn funcname \(dqint arg0\(dq 1667.Dl \&.Fn funcname arg0 1668.Pp 1669.Bd -literal -offset indent -compact 1670\&.Ft functype 1671\&.Fn funcname 1672.Ed 1673.Pp 1674When referring to a function documented in another manual page, use 1675.Sx \&Xr 1676instead. 1677See also 1678.Sx MANUAL STRUCTURE , 1679.Sx \&Fo , 1680and 1681.Sx \&Ft . 1682.Ss \&Fo 1683Begin a function block. 1684This is a multi-line version of 1685.Sx \&Fn . 1686Its syntax is as follows: 1687.Pp 1688.D1 Pf \. Sx \&Fo Ar funcname 1689.Pp 1690Invocations usually occur in the following context: 1691.Bd -ragged -offset indent 1692.Pf \. Sx \&Ft Ar functype 1693.br 1694.Pf \. Sx \&Fo Ar funcname 1695.br 1696.Pf \. Sx \&Fa Qq Ar argtype Ar argname 1697.br 1698\&.\.\. 1699.br 1700.Pf \. Sx \&Fc 1701.Ed 1702.Pp 1703A 1704.Sx \&Fo 1705scope is closed by 1706.Sx \&Fc . 1707.Pp 1708See also 1709.Sx MANUAL STRUCTURE , 1710.Sx \&Fa , 1711.Sx \&Fc , 1712and 1713.Sx \&Ft . 1714.Ss \&Fr 1715This macro is obsolete. 1716No replacement markup is needed. 1717.Pp 1718It was used to show numerical function return values in an italic font. 1719.Ss \&Ft 1720A function type. 1721Its syntax is as follows: 1722.Pp 1723.D1 Pf \. Sx \&Ft Ar functype 1724.Pp 1725In the 1726.Em SYNOPSIS 1727section, a new output line is started after this macro. 1728.Pp 1729Examples: 1730.Dl \&.Ft int 1731.Bd -literal -offset indent -compact 1732\&.Ft functype 1733\&.Fn funcname 1734.Ed 1735.Pp 1736See also 1737.Sx MANUAL STRUCTURE , 1738.Sx \&Fn , 1739and 1740.Sx \&Fo . 1741.Ss \&Fx 1742Format the 1743.Fx 1744version provided as an argument, or a default value 1745if no argument is provided. 1746.Pp 1747Examples: 1748.Dl \&.Fx 7.1 1749.Dl \&.Fx 1750.Pp 1751See also 1752.Sx \&At , 1753.Sx \&Bsx , 1754.Sx \&Bx , 1755.Sx \&Dx , 1756.Sx \&Nx , 1757and 1758.Sx \&Ox . 1759.Ss \&Hf 1760This macro is not implemented in 1761.Xr mandoc 1 . 1762.Pp 1763It was used to include the contents of a (header) file literally. 1764The syntax was: 1765.Pp 1766.Dl Pf . Sx \&Hf Ar filename 1767.Ss \&Ic 1768Designate an internal or interactive command. 1769This is similar to 1770.Sx \&Cm 1771but used for instructions rather than values. 1772.Pp 1773Examples: 1774.Dl \&.Ic :wq 1775.Dl \&.Ic hash 1776.Dl \&.Ic alias 1777.Pp 1778Note that using 1779.Sx \&Bd Fl literal 1780or 1781.Sx \&D1 1782is preferred for displaying code; the 1783.Sx \&Ic 1784macro is used when referring to specific instructions. 1785.Ss \&In 1786The name of an include file. 1787This macro is most often used in section 2, 3, and 9 manual pages. 1788.Pp 1789When invoked as the first macro on an input line in the 1790.Em SYNOPSIS 1791section, the argument is displayed in angle brackets 1792and preceded by 1793.Qq #include , 1794and a blank line is inserted in front if there is a preceding 1795function declaration. 1796In other sections, it only encloses its argument in angle brackets 1797and causes no line break. 1798.Pp 1799Examples: 1800.Dl \&.In sys/types.h 1801.Pp 1802See also 1803.Sx MANUAL STRUCTURE . 1804.Ss \&It 1805A list item. 1806The syntax of this macro depends on the list type. 1807.Pp 1808Lists 1809of type 1810.Fl hang , 1811.Fl ohang , 1812.Fl inset , 1813and 1814.Fl diag 1815have the following syntax: 1816.Pp 1817.D1 Pf \. Sx \&It Ar args 1818.Pp 1819Lists of type 1820.Fl bullet , 1821.Fl dash , 1822.Fl enum , 1823.Fl hyphen 1824and 1825.Fl item 1826have the following syntax: 1827.Pp 1828.D1 Pf \. Sx \&It 1829.Pp 1830with subsequent lines interpreted within the scope of the 1831.Sx \&It 1832until either a closing 1833.Sx \&El 1834or another 1835.Sx \&It . 1836.Pp 1837The 1838.Fl tag 1839list has the following syntax: 1840.Pp 1841.D1 Pf \. Sx \&It Op Cm args 1842.Pp 1843Subsequent lines are interpreted as with 1844.Fl bullet 1845and family. 1846The line arguments correspond to the list's left-hand side; body 1847arguments correspond to the list's contents. 1848.Pp 1849The 1850.Fl column 1851list is the most complicated. 1852Its syntax is as follows: 1853.Pp 1854.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... 1855.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... 1856.Pp 1857The arguments consist of one or more lines of text and macros 1858representing a complete table line. 1859Cells within the line are delimited by the special 1860.Sx \&Ta 1861block macro or by literal tab characters. 1862.Pp 1863Using literal tabs is strongly discouraged because they are very 1864hard to use correctly and 1865.Nm 1866code using them is very hard to read. 1867In particular, a blank character is syntactically significant 1868before and after the literal tab character. 1869If a word precedes or follows the tab without an intervening blank, 1870that word is never interpreted as a macro call, but always output 1871literally. 1872.Pp 1873The tab cell delimiter may only be used within the 1874.Sx \&It 1875line itself; on following lines, only the 1876.Sx \&Ta 1877macro can be used to delimit cells, and portability requires that 1878.Sx \&Ta 1879is called by other macros: some parsers do not recognize it when 1880it appears as the first macro on a line. 1881.Pp 1882Note that quoted strings may span tab-delimited cells on an 1883.Sx \&It 1884line. 1885For example, 1886.Pp 1887.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1888.Pp 1889will preserve the whitespace before both commas, 1890but not the whitespace before the semicolon. 1891.Pp 1892See also 1893.Sx \&Bl . 1894.Ss \&Lb 1895Specify a library. 1896The syntax is as follows: 1897.Pp 1898.D1 Pf \. Sx \&Lb Ar library 1899.Pp 1900The 1901.Ar library 1902parameter may be a system library, such as 1903.Cm libz 1904or 1905.Cm libpam , 1906in which case a small library description is printed next to the linker 1907invocation; or a custom library, in which case the library name is 1908printed in quotes. 1909This is most commonly used in the 1910.Em SYNOPSIS 1911section as described in 1912.Sx MANUAL STRUCTURE . 1913.Pp 1914Examples: 1915.Dl \&.Lb libz 1916.Dl \&.Lb libmandoc 1917.Ss \&Li 1918Denotes text that should be in a 1919.Li literal 1920font mode. 1921Note that this is a presentation term and should not be used for 1922stylistically decorating technical terms. 1923.Pp 1924On terminal output devices, this is often indistinguishable from 1925normal text. 1926.Pp 1927See also 1928.Sx \&Bf , 1929.Sx \&Em , 1930.Sx \&No , 1931and 1932.Sx \&Sy . 1933.Ss \&Lk 1934Format a hyperlink. 1935Its syntax is as follows: 1936.Pp 1937.D1 Pf \. Sx \&Lk Ar uri Op Ar name 1938.Pp 1939Examples: 1940.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq 1941.Dl \&.Lk http://bsd.lv 1942.Pp 1943See also 1944.Sx \&Mt . 1945.Ss \&Lp 1946Synonym for 1947.Sx \&Pp . 1948.Ss \&Ms 1949Display a mathematical symbol. 1950Its syntax is as follows: 1951.Pp 1952.D1 Pf \. Sx \&Ms Ar symbol 1953.Pp 1954Examples: 1955.Dl \&.Ms sigma 1956.Dl \&.Ms aleph 1957.Ss \&Mt 1958Format a 1959.Dq mailto: 1960hyperlink. 1961Its syntax is as follows: 1962.Pp 1963.D1 Pf \. Sx \&Mt Ar address 1964.Pp 1965Examples: 1966.Dl \&.Mt discuss@manpages.bsd.lv 1967.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 1968.Ss \&Nd 1969A one line description of the manual's content. 1970This is the mandatory last macro of the 1971.Em NAME 1972section and not appropriate for other sections. 1973.Pp 1974Examples: 1975.Dl Pf . Sx \&Nd mdoc language reference 1976.Dl Pf . Sx \&Nd format and display UNIX manuals 1977.Pp 1978The 1979.Sx \&Nd 1980macro technically accepts child macros and terminates with a subsequent 1981.Sx \&Sh 1982invocation. 1983Do not assume this behaviour: some 1984.Xr whatis 1 1985database generators are not smart enough to parse more than the line 1986arguments and will display macros verbatim. 1987.Pp 1988See also 1989.Sx \&Nm . 1990.Ss \&Nm 1991The name of the manual page, or \(em in particular in section 1, 6, 1992and 8 pages \(em of an additional command or feature documented in 1993the manual page. 1994When first invoked, the 1995.Sx \&Nm 1996macro expects a single argument, the name of the manual page. 1997Usually, the first invocation happens in the 1998.Em NAME 1999section of the page. 2000The specified name will be remembered and used whenever the macro is 2001called again without arguments later in the page. 2002The 2003.Sx \&Nm 2004macro uses 2005.Sx Block full-implicit 2006semantics when invoked as the first macro on an input line in the 2007.Em SYNOPSIS 2008section; otherwise, it uses ordinary 2009.Sx In-line 2010semantics. 2011.Pp 2012Examples: 2013.Bd -literal -offset indent 2014\&.Sh SYNOPSIS 2015\&.Nm cat 2016\&.Op Fl benstuv 2017\&.Op Ar 2018.Ed 2019.Pp 2020In the 2021.Em SYNOPSIS 2022of section 2, 3 and 9 manual pages, use the 2023.Sx \&Fn 2024macro rather than 2025.Sx \&Nm 2026to mark up the name of the manual page. 2027.Ss \&No 2028Normal text. 2029Closes the scope of any preceding in-line macro. 2030When used after physical formatting macros like 2031.Sx \&Em 2032or 2033.Sx \&Sy , 2034switches back to the standard font face and weight. 2035Can also be used to embed plain text strings in macro lines 2036using semantic annotation macros. 2037.Pp 2038Examples: 2039.Dl ".Em italic , Sy bold , No and roman" 2040.Pp 2041.Bd -literal -offset indent -compact 2042\&.Sm off 2043\&.Cm :C No / Ar pattern No / Ar replacement No / 2044\&.Sm on 2045.Ed 2046.Pp 2047See also 2048.Sx \&Em , 2049.Sx \&Li , 2050and 2051.Sx \&Sy . 2052.Ss \&Ns 2053Suppress a space between the output of the preceding macro 2054and the following text or macro. 2055Following invocation, input is interpreted as normal text 2056just like after an 2057.Sx \&No 2058macro. 2059.Pp 2060This has no effect when invoked at the start of a macro line. 2061.Pp 2062Examples: 2063.Dl ".Ar name Ns = Ns Ar value" 2064.Dl ".Cm :M Ns Ar pattern" 2065.Dl ".Fl o Ns Ar output" 2066.Pp 2067See also 2068.Sx \&No 2069and 2070.Sx \&Sm . 2071.Ss \&Nx 2072Format the 2073.Nx 2074version provided as an argument, or a default value if 2075no argument is provided. 2076.Pp 2077Examples: 2078.Dl \&.Nx 5.01 2079.Dl \&.Nx 2080.Pp 2081See also 2082.Sx \&At , 2083.Sx \&Bsx , 2084.Sx \&Bx , 2085.Sx \&Dx , 2086.Sx \&Fx , 2087and 2088.Sx \&Ox . 2089.Ss \&Oc 2090Close multi-line 2091.Sx \&Oo 2092context. 2093.Ss \&Oo 2094Multi-line version of 2095.Sx \&Op . 2096.Pp 2097Examples: 2098.Bd -literal -offset indent -compact 2099\&.Oo 2100\&.Op Fl flag Ns Ar value 2101\&.Oc 2102.Ed 2103.Ss \&Op 2104Optional part of a command line. 2105Prints the argument(s) in brackets. 2106This is most often used in the 2107.Em SYNOPSIS 2108section of section 1 and 8 manual pages. 2109.Pp 2110Examples: 2111.Dl \&.Op \&Fl a \&Ar b 2112.Dl \&.Op \&Ar a | b 2113.Pp 2114See also 2115.Sx \&Oo . 2116.Ss \&Os 2117Operating system version for display in the page footer. 2118This is the mandatory third macro of 2119any 2120.Nm 2121file. 2122Its syntax is as follows: 2123.Pp 2124.D1 Pf \. Sx \&Os Op Ar system Op Ar version 2125.Pp 2126The optional 2127.Ar system 2128parameter specifies the relevant operating system or environment. 2129It is suggested to leave it unspecified, in which case 2130.Xr mandoc 1 2131uses its 2132.Fl Ios 2133argument or, if that isn't specified either, 2134.Fa sysname 2135and 2136.Fa release 2137as returned by 2138.Xr uname 3 . 2139.Pp 2140Examples: 2141.Dl \&.Os 2142.Dl \&.Os KTH/CSC/TCS 2143.Dl \&.Os BSD 4.3 2144.Pp 2145See also 2146.Sx \&Dd 2147and 2148.Sx \&Dt . 2149.Ss \&Ot 2150This macro is obsolete. 2151Use 2152.Sx \&Ft 2153instead; with 2154.Xr mandoc 1 , 2155both have the same effect. 2156.Pp 2157Historical 2158.Nm 2159packages described it as 2160.Dq "old function type (FORTRAN)" . 2161.Ss \&Ox 2162Format the 2163.Ox 2164version provided as an argument, or a default value 2165if no argument is provided. 2166.Pp 2167Examples: 2168.Dl \&.Ox 4.5 2169.Dl \&.Ox 2170.Pp 2171See also 2172.Sx \&At , 2173.Sx \&Bsx , 2174.Sx \&Bx , 2175.Sx \&Dx , 2176.Sx \&Fx , 2177and 2178.Sx \&Nx . 2179.Ss \&Pa 2180An absolute or relative file system path, or a file or directory name. 2181If an argument is not provided, the character 2182.Sq \(ti 2183is used as a default. 2184.Pp 2185Examples: 2186.Dl \&.Pa /usr/bin/mandoc 2187.Dl \&.Pa /usr/share/man/man7/mdoc.7 2188.Pp 2189See also 2190.Sx \&Lk . 2191.Ss \&Pc 2192Close parenthesised context opened by 2193.Sx \&Po . 2194.Ss \&Pf 2195Removes the space between its argument and the following macro. 2196Its syntax is as follows: 2197.Pp 2198.D1 .Pf Ar prefix macro arguments ... 2199.Pp 2200This is equivalent to: 2201.Pp 2202.D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ... 2203.Pp 2204The 2205.Ar prefix 2206argument is not parsed for macro names or delimiters, 2207but used verbatim as if it were escaped. 2208.Pp 2209Examples: 2210.Dl ".Pf $ Ar variable_name" 2211.Dl ".Pf . Ar macro_name" 2212.Dl ".Pf 0x Ar hex_digits" 2213.Pp 2214See also 2215.Sx \&Ns 2216and 2217.Sx \&Sm . 2218.Ss \&Po 2219Multi-line version of 2220.Sx \&Pq . 2221.Ss \&Pp 2222Break a paragraph. 2223This will assert vertical space between prior and subsequent macros 2224and/or text. 2225.Pp 2226Paragraph breaks are not needed before or after 2227.Sx \&Sh 2228or 2229.Sx \&Ss 2230macros or before displays 2231.Pq Sx \&Bd 2232or lists 2233.Pq Sx \&Bl 2234unless the 2235.Fl compact 2236flag is given. 2237.Ss \&Pq 2238Parenthesised enclosure. 2239.Pp 2240See also 2241.Sx \&Po . 2242.Ss \&Qc 2243Close quoted context opened by 2244.Sx \&Qo . 2245.Ss \&Ql 2246In-line literal display. 2247This can for example be used for complete command invocations and 2248for multi-word code fragments when more specific markup is not 2249appropriate and an indented display is not desired. 2250While 2251.Xr mandoc 1 2252always encloses the arguments in single quotes, other formatters 2253usually omit the quotes on non-terminal output devices when the 2254arguments have three or more characters. 2255.Pp 2256See also 2257.Sx \&Dl 2258and 2259.Sx \&Bd 2260.Fl literal . 2261.Ss \&Qo 2262Multi-line version of 2263.Sx \&Qq . 2264.Ss \&Qq 2265Encloses its arguments in 2266.Qq typewriter 2267double-quotes. 2268Consider using 2269.Sx \&Dq . 2270.Pp 2271See also 2272.Sx \&Dq , 2273.Sx \&Sq , 2274and 2275.Sx \&Qo . 2276.Ss \&Re 2277Close an 2278.Sx \&Rs 2279block. 2280Does not have any tail arguments. 2281.Ss \&Rs 2282Begin a bibliographic 2283.Pq Dq reference 2284block. 2285Does not have any head arguments. 2286The block macro may only contain 2287.Sx \&%A , 2288.Sx \&%B , 2289.Sx \&%C , 2290.Sx \&%D , 2291.Sx \&%I , 2292.Sx \&%J , 2293.Sx \&%N , 2294.Sx \&%O , 2295.Sx \&%P , 2296.Sx \&%Q , 2297.Sx \&%R , 2298.Sx \&%T , 2299.Sx \&%U , 2300and 2301.Sx \&%V 2302child macros (at least one must be specified). 2303.Pp 2304Examples: 2305.Bd -literal -offset indent -compact 2306\&.Rs 2307\&.%A J. E. Hopcroft 2308\&.%A J. D. Ullman 2309\&.%B Introduction to Automata Theory, Languages, and Computation 2310\&.%I Addison-Wesley 2311\&.%C Reading, Massachusetts 2312\&.%D 1979 2313\&.Re 2314.Ed 2315.Pp 2316If an 2317.Sx \&Rs 2318block is used within a SEE ALSO section, a vertical space is asserted 2319before the rendered output, else the block continues on the current 2320line. 2321.Ss \&Rv 2322Insert a standard sentence regarding a function call's return value of 0 2323on success and \-1 on error, with the 2324.Va errno 2325libc global variable set on error. 2326Its syntax is as follows: 2327.Pp 2328.D1 Pf \. Sx \&Rv Fl std Op Ar function ... 2329.Pp 2330If 2331.Ar function 2332is not specified, the document's name set by 2333.Sx \&Nm 2334is used. 2335Multiple 2336.Ar function 2337arguments are treated as separate functions. 2338.Pp 2339See also 2340.Sx \&Ex . 2341.Ss \&Sc 2342Close single-quoted context opened by 2343.Sx \&So . 2344.Ss \&Sh 2345Begin a new section. 2346For a list of conventional manual sections, see 2347.Sx MANUAL STRUCTURE . 2348These sections should be used unless it's absolutely necessary that 2349custom sections be used. 2350.Pp 2351Section names should be unique so that they may be keyed by 2352.Sx \&Sx . 2353Although this macro is parsed, it should not consist of child node or it 2354may not be linked with 2355.Sx \&Sx . 2356.Pp 2357See also 2358.Sx \&Pp , 2359.Sx \&Ss , 2360and 2361.Sx \&Sx . 2362.Ss \&Sm 2363Switches the spacing mode for output generated from macros. 2364Its syntax is as follows: 2365.Pp 2366.D1 Pf \. Sx \&Sm Op Cm on | off 2367.Pp 2368By default, spacing is 2369.Cm on . 2370When switched 2371.Cm off , 2372no white space is inserted between macro arguments and between the 2373output generated from adjacent macros, but text lines 2374still get normal spacing between words and sentences. 2375.Pp 2376When called without an argument, the 2377.Sx \&Sm 2378macro toggles the spacing mode. 2379Using this is not recommended because it makes the code harder to read. 2380.Ss \&So 2381Multi-line version of 2382.Sx \&Sq . 2383.Ss \&Sq 2384Encloses its arguments in 2385.Sq typewriter 2386single-quotes. 2387.Pp 2388See also 2389.Sx \&Dq , 2390.Sx \&Qq , 2391and 2392.Sx \&So . 2393.Ss \&Ss 2394Begin a new subsection. 2395Unlike with 2396.Sx \&Sh , 2397there is no convention for the naming of subsections. 2398Except 2399.Em DESCRIPTION , 2400the conventional sections described in 2401.Sx MANUAL STRUCTURE 2402rarely have subsections. 2403.Pp 2404Sub-section names should be unique so that they may be keyed by 2405.Sx \&Sx . 2406Although this macro is parsed, it should not consist of child node or it 2407may not be linked with 2408.Sx \&Sx . 2409.Pp 2410See also 2411.Sx \&Pp , 2412.Sx \&Sh , 2413and 2414.Sx \&Sx . 2415.Ss \&St 2416Replace an abbreviation for a standard with the full form. 2417The following standards are recognised. 2418Where multiple lines are given without a blank line in between, 2419they all refer to the same standard, and using the first form 2420is recommended. 2421.Bl -tag -width 1n 2422.It C language standards 2423.Pp 2424.Bl -tag -width "-p1003.1g-2000" -compact 2425.It \-ansiC 2426.St -ansiC 2427.It \-ansiC-89 2428.St -ansiC-89 2429.It \-isoC 2430.St -isoC 2431.It \-isoC-90 2432.St -isoC-90 2433.br 2434The original C standard. 2435.Pp 2436.It \-isoC-amd1 2437.St -isoC-amd1 2438.Pp 2439.It \-isoC-tcor1 2440.St -isoC-tcor1 2441.Pp 2442.It \-isoC-tcor2 2443.St -isoC-tcor2 2444.Pp 2445.It \-isoC-99 2446.St -isoC-99 2447.br 2448The second major version of the C language standard. 2449.Pp 2450.It \-isoC-2011 2451.St -isoC-2011 2452.br 2453The third major version of the C language standard. 2454.El 2455.It POSIX.1 before the Single UNIX Specification 2456.Pp 2457.Bl -tag -width "-p1003.1g-2000" -compact 2458.It \-p1003.1-88 2459.St -p1003.1-88 2460.It \-p1003.1 2461.St -p1003.1 2462.br 2463The original POSIX standard, based on ANSI C. 2464.Pp 2465.It \-p1003.1-90 2466.St -p1003.1-90 2467.It \-iso9945-1-90 2468.St -iso9945-1-90 2469.br 2470The first update of POSIX.1. 2471.Pp 2472.It \-p1003.1b-93 2473.St -p1003.1b-93 2474.It \-p1003.1b 2475.St -p1003.1b 2476.br 2477Real-time extensions. 2478.Pp 2479.It \-p1003.1c-95 2480.St -p1003.1c-95 2481.br 2482POSIX thread interfaces. 2483.Pp 2484.It \-p1003.1i-95 2485.St -p1003.1i-95 2486.br 2487Technical Corrigendum. 2488.Pp 2489.It \-p1003.1-96 2490.St -p1003.1-96 2491.It \-iso9945-1-96 2492.St -iso9945-1-96 2493.br 2494Includes POSIX.1-1990, 1b, 1c, and 1i. 2495.El 2496.It X/Open Portability Guide version 4 and related standards 2497.Pp 2498.Bl -tag -width "-p1003.1g-2000" -compact 2499.It \-xpg3 2500.St -xpg3 2501.br 2502An XPG4 precursor, published in 1989. 2503.Pp 2504.It \-p1003.2 2505.St -p1003.2 2506.It \-p1003.2-92 2507.St -p1003.2-92 2508.It \-iso9945-2-93 2509.St -iso9945-2-93 2510.br 2511An XCU4 precursor. 2512.Pp 2513.It \-p1003.2a-92 2514.St -p1003.2a-92 2515.br 2516Updates to POSIX.2. 2517.Pp 2518.It \-xpg4 2519.St -xpg4 2520.br 2521Based on POSIX.1 and POSIX.2, published in 1992. 2522.El 2523.It Single UNIX Specification version 1 and related standards 2524.Pp 2525.Bl -tag -width "-p1003.1g-2000" -compact 2526.It \-susv1 2527.St -susv1 2528.It \-xpg4.2 2529.St -xpg4.2 2530.br 2531This standard was published in 1994. 2532It was used as the basis for UNIX 95 certification. 2533The following three refer to parts of it. 2534.Pp 2535.It \-xsh4.2 2536.St -xsh4.2 2537.Pp 2538.It \-xcurses4.2 2539.St -xcurses4.2 2540.Pp 2541.It \-p1003.1g-2000 2542.St -p1003.1g-2000 2543.br 2544Networking APIs, including sockets. 2545.Pp 2546.It \-svid4 2547.St -svid4 , 2548.br 2549Published in 1995. 2550.El 2551.It Single UNIX Specification version 2 and related standards 2552.Pp 2553.Bl -tag -width "-p1003.1g-2000" -compact 2554.It \-susv2 2555.St -susv2 2556This Standard was published in 1997 2557and is also called X/Open Portability Guide version 5. 2558It was used as the basis for UNIX 98 certification. 2559The following refer to parts of it. 2560.Pp 2561.It \-xbd5 2562.St -xbd5 2563.Pp 2564.It \-xsh5 2565.St -xsh5 2566.Pp 2567.It \-xcu5 2568.St -xcu5 2569.Pp 2570.It \-xns5 2571.St -xns5 2572.It \-xns5.2 2573.St -xns5.2 2574.El 2575.It Single UNIX Specification version 3 2576.Pp 2577.Bl -tag -width "-p1003.1-2001" -compact 2578.It \-p1003.1-2001 2579.St -p1003.1-2001 2580.It \-susv3 2581.St -susv3 2582.br 2583This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2584It is also called X/Open Portability Guide version 6. 2585It is used as the basis for UNIX 03 certification. 2586.Pp 2587.It \-p1003.1-2004 2588.St -p1003.1-2004 2589.br 2590The second and last Technical Corrigendum. 2591.El 2592.It Single UNIX Specification version 4 2593.Pp 2594.Bl -tag -width "-p1003.1g-2000" -compact 2595.It \-p1003.1-2008 2596.St -p1003.1-2008 2597.It \-susv4 2598.St -susv4 2599.br 2600This standard is also called 2601X/Open Portability Guide version 7. 2602.El 2603.It Other standards 2604.Pp 2605.Bl -tag -width "-p1003.1g-2000" -compact 2606.It \-ieee754 2607.St -ieee754 2608.br 2609Floating-point arithmetic. 2610.Pp 2611.It \-iso8601 2612.St -iso8601 2613.br 2614Representation of dates and times, published in 1988. 2615.Pp 2616.It \-iso8802-3 2617.St -iso8802-3 2618.br 2619Ethernet local area networks. 2620.Pp 2621.It \-ieee1275-94 2622.St -ieee1275-94 2623.El 2624.El 2625.Ss \&Sx 2626Reference a section or subsection in the same manual page. 2627The referenced section or subsection name must be identical to the 2628enclosed argument, including whitespace. 2629.Pp 2630Examples: 2631.Dl \&.Sx MANUAL STRUCTURE 2632.Pp 2633See also 2634.Sx \&Sh 2635and 2636.Sx \&Ss . 2637.Ss \&Sy 2638Request a boldface font. 2639.Pp 2640This is most often used to indicate importance or seriousness (not to be 2641confused with stress emphasis, see 2642.Sx \&Em ) . 2643When none of the semantic macros fit, it is also adequate for syntax 2644elements that have to be given or that appear verbatim. 2645.Pp 2646Examples: 2647.Bd -literal -compact -offset indent 2648\&.Sy Warning : 2649If 2650\&.Sy s 2651appears in the owner permissions, set-user-ID mode is set. 2652This utility replaces the former 2653\&.Sy dumpdir 2654program. 2655.Ed 2656.Pp 2657See also 2658.Sx \&Bf , 2659.Sx \&Em , 2660.Sx \&Li , 2661and 2662.Sx \&No . 2663.Ss \&Ta 2664Table cell separator in 2665.Sx \&Bl Fl column 2666lists; can only be used below 2667.Sx \&It . 2668.Ss \&Tn 2669Supported only for compatibility, do not use this in new manuals. 2670Even though the macro name 2671.Pq Dq tradename 2672suggests a semantic function, historic usage is inconsistent, mostly 2673using it as a presentation-level macro to request a small caps font. 2674.Ss \&Ud 2675Supported only for compatibility, do not use this in new manuals. 2676Prints out 2677.Dq currently under development. 2678.Ss \&Ux 2679Supported only for compatibility, do not use this in new manuals. 2680Prints out 2681.Dq Ux . 2682.Ss \&Va 2683A variable name. 2684.Pp 2685Examples: 2686.Dl \&.Va foo 2687.Dl \&.Va const char *bar ; 2688.Pp 2689For function arguments and parameters, use 2690.Sx \&Fa 2691instead. 2692For declarations of global variables in the 2693.Em SYNOPSIS 2694section, use 2695.Sx \&Vt . 2696.Ss \&Vt 2697A variable type. 2698.Pp 2699This is also used for indicating global variables in the 2700.Em SYNOPSIS 2701section, in which case a variable name is also specified. 2702Note that it accepts 2703.Sx Block partial-implicit 2704syntax when invoked as the first macro on an input line in the 2705.Em SYNOPSIS 2706section, else it accepts ordinary 2707.Sx In-line 2708syntax. 2709In the former case, this macro starts a new output line, 2710and a blank line is inserted in front if there is a preceding 2711function definition or include directive. 2712.Pp 2713Examples: 2714.Dl \&.Vt unsigned char 2715.Dl \&.Vt extern const char * const sys_signame[] \&; 2716.Pp 2717For parameters in function prototypes, use 2718.Sx \&Fa 2719instead, for function return types 2720.Sx \&Ft , 2721and for variable names outside the 2722.Em SYNOPSIS 2723section 2724.Sx \&Va , 2725even when including a type with the name. 2726See also 2727.Sx MANUAL STRUCTURE . 2728.Ss \&Xc 2729Close a scope opened by 2730.Sx \&Xo . 2731.Ss \&Xo 2732Extend the header of an 2733.Sx \&It 2734macro or the body of a partial-implicit block macro 2735beyond the end of the input line. 2736This macro originally existed to work around the 9-argument limit 2737of historic 2738.Xr roff 7 . 2739.Ss \&Xr 2740Link to another manual 2741.Pq Qq cross-reference . 2742Its syntax is as follows: 2743.Pp 2744.D1 Pf \. Sx \&Xr Ar name section 2745.Pp 2746Cross reference the 2747.Ar name 2748and 2749.Ar section 2750number of another man page. 2751.Pp 2752Examples: 2753.Dl \&.Xr mandoc 1 2754.Dl \&.Xr mandoc 1 \&; 2755.Dl \&.Xr mandoc 1 \&Ns s behaviour 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 2 3040.El 3041.Ss Delimiters 3042When a macro argument consists of one single input character 3043considered as a delimiter, the argument gets special handling. 3044This does not apply when delimiters appear in arguments containing 3045more than one character. 3046Consequently, to prevent special handling and just handle it 3047like any other argument, a delimiter can be escaped by prepending 3048a zero-width space 3049.Pq Sq \e& . 3050In text lines, delimiters never need escaping, but may be used 3051as normal punctuation. 3052.Pp 3053For many macros, when the leading arguments are opening delimiters, 3054these delimiters are put before the macro scope, 3055and when the trailing arguments are closing delimiters, 3056these delimiters are put after the macro scope. 3057Spacing is suppressed after opening delimiters 3058and before closing delimiters. 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, which does not suppress spacing: 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 GNU troff 3148.Pq Qq groff . 3149.Pp 3150The following problematic behaviour is found in groff: 3151.Pp 3152.Bl -dash -compact 3153.It 3154.Sx \&Dd 3155with non-standard arguments behaves very strangely. 3156When there are three arguments, they are printed verbatim. 3157Any other number of arguments is replaced by the current date, 3158but without any arguments the string 3159.Dq Epoch 3160is printed. 3161.It 3162.Sx \&Lk 3163only accepts a single link-name argument; the remainder is misformatted. 3164.It 3165.Sx \&Pa 3166does not format its arguments when used in the FILES section under 3167certain list types. 3168.It 3169.Sx \&Ta 3170can only be called by other macros, but not at the beginning of a line. 3171.It 3172.Sx \&%C 3173is not implemented (up to and including groff-1.22.2). 3174.It 3175.Sq \ef 3176.Pq font face 3177and 3178.Sq \eF 3179.Pq font family face 3180.Sx Text Decoration 3181escapes behave irregularly when specified within line-macro scopes. 3182.It 3183Negative scaling units return to prior lines. 3184Instead, mandoc truncates them to zero. 3185.El 3186.Pp 3187The following features are unimplemented in mandoc: 3188.Pp 3189.Bl -dash -compact 3190.It 3191.Sx \&Bd 3192.Fl file Ar file 3193is unsupported for security reasons. 3194.It 3195.Sx \&Bd 3196.Fl filled 3197does not adjust the right margin, but is an alias for 3198.Sx \&Bd 3199.Fl ragged . 3200.It 3201.Sx \&Bd 3202.Fl literal 3203does not use a literal font, but is an alias for 3204.Sx \&Bd 3205.Fl unfilled . 3206.It 3207.Sx \&Bd 3208.Fl offset Cm center 3209and 3210.Fl offset Cm right 3211don't work. 3212Groff does not implement centered and flush-right rendering either, 3213but produces large indentations. 3214.El 3215.Sh SEE ALSO 3216.Xr man 1 , 3217.Xr mandoc 1 , 3218.Xr eqn 7 , 3219.Xr man 7 , 3220.Xr mandoc_char 7 , 3221.Xr roff 7 , 3222.Xr tbl 7 3223.Pp 3224The web page 3225.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3226provides a few tutorial-style pages for beginners, an extensive style 3227guide for advanced authors, and an alphabetic index helping to choose 3228the best macros for various kinds of content. 3229.Sh HISTORY 3230The 3231.Nm 3232language first appeared as a troff macro package in 3233.Bx 4.4 . 3234It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3235in groff-1.17. 3236The standalone implementation that is part of the 3237.Xr mandoc 1 3238utility written by Kristaps Dzonsons appeared in 3239.Ox 4.6 . 3240.Sh AUTHORS 3241The 3242.Nm 3243reference was written by 3244.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3245