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