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