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