1.\" $OpenBSD: mdoc.7,v 1.93 2012/06/20 22:00:23 jmc 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 $Mdocdate: June 20 2012 $ 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 scaling width as described in 824.Xr roff 7 . 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 scaling widths as described in 930.Xr roff 7 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 scaling width syntax described in 960.Xr roff 7 961or 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 1286.Op Ar arch 1287.Oc 1288.Oc 1289.Ed 1290.Pp 1291Its arguments are as follows: 1292.Bl -tag -width Ds -offset Ds 1293.It Ar title 1294The document's title (name), defaulting to 1295.Dq UNKNOWN 1296if unspecified. 1297It should be capitalised. 1298.It Ar section 1299The manual section. 1300This may be one of 1301.Ar 1 1302.Pq utilities , 1303.Ar 2 1304.Pq system calls , 1305.Ar 3 1306.Pq libraries , 1307.Ar 3p 1308.Pq Perl libraries , 1309.Ar 4 1310.Pq devices , 1311.Ar 5 1312.Pq file formats , 1313.Ar 6 1314.Pq games , 1315.Ar 7 1316.Pq miscellaneous , 1317.Ar 8 1318.Pq system utilities , 1319.Ar 9 1320.Pq kernel functions , 1321.Ar X11 1322.Pq X Window System , 1323.Ar X11R6 1324.Pq X Window System , 1325.Ar unass 1326.Pq unassociated , 1327.Ar local 1328.Pq local system , 1329.Ar draft 1330.Pq draft manual , 1331or 1332.Ar paper 1333.Pq paper . 1334It should correspond to the manual's filename suffix and defaults to 1335.Dq 1 1336if unspecified. 1337.It Ar volume 1338This overrides the volume inferred from 1339.Ar section . 1340This field is optional, and if specified, must be one of 1341.Ar USD 1342.Pq users' supplementary documents , 1343.Ar PS1 1344.Pq programmers' supplementary documents , 1345.Ar AMD 1346.Pq administrators' supplementary documents , 1347.Ar SMM 1348.Pq system managers' manuals , 1349.Ar URM 1350.Pq users' reference manuals , 1351.Ar PRM 1352.Pq programmers' reference manuals , 1353.Ar KM 1354.Pq kernel manuals , 1355.Ar IND 1356.Pq master index , 1357.Ar MMI 1358.Pq master index , 1359.Ar LOCAL 1360.Pq local manuals , 1361.Ar LOC 1362.Pq local manuals , 1363or 1364.Ar CON 1365.Pq contributed manuals . 1366.It Ar arch 1367This specifies the machine architecture a manual page applies to, 1368where relevant. 1369For 1370.Ox , 1371the following are valid architectures: 1372.Cm alpha , 1373.Cm amd64 , 1374.Cm armish , 1375.Cm aviion , 1376.Cm beagle , 1377.Cm hp300 , 1378.Cm hppa , 1379.Cm hppa64 , 1380.Cm i386 , 1381.Cm ia64 , 1382.Cm landisk , 1383.Cm loongson , 1384.Cm luna88k , 1385.Cm macppc , 1386.Cm mips64 , 1387.Cm mvme68k , 1388.Cm mvme88k , 1389.Cm palm , 1390.Cm sgi , 1391.Cm socppc , 1392.Cm solbourne , 1393.Cm sparc , 1394.Cm sparc64 , 1395.Cm vax , 1396and 1397.Cm zaurus . 1398.El 1399.Pp 1400Examples: 1401.Dl \&.Dt FOO 1 1402.Dl \&.Dt FOO 4 KM 1403.Dl \&.Dt FOO 9 i386 1404.Pp 1405See also 1406.Sx \&Dd 1407and 1408.Sx \&Os . 1409.Ss \&Dv 1410Defined variables such as preprocessor constants, constant symbols, 1411enumeration values, and so on. 1412.Pp 1413Examples: 1414.Dl \&.Dv NULL 1415.Dl \&.Dv BUFSIZ 1416.Dl \&.Dv STDOUT_FILENO 1417.Pp 1418See also 1419.Sx \&Er 1420and 1421.Sx \&Ev 1422for special-purpose constants and 1423.Sx \&Va 1424for variable symbols. 1425.Ss \&Dx 1426Format the DragonFly BSD version provided as an argument, or a default 1427value if no argument is provided. 1428.Pp 1429Examples: 1430.Dl \&.Dx 2.4.1 1431.Dl \&.Dx 1432.Pp 1433See also 1434.Sx \&At , 1435.Sx \&Bsx , 1436.Sx \&Bx , 1437.Sx \&Fx , 1438.Sx \&Nx , 1439.Sx \&Ox , 1440and 1441.Sx \&Ux . 1442.Ss \&Ec 1443Close a scope started by 1444.Sx \&Eo . 1445Its syntax is as follows: 1446.Pp 1447.D1 Pf \. Sx \&Ec Op Ar TERM 1448.Pp 1449The 1450.Ar TERM 1451argument is used as the enclosure tail, for example, specifying \e(rq 1452will emulate 1453.Sx \&Dc . 1454.Ss \&Ed 1455End a display context started by 1456.Sx \&Bd . 1457.Ss \&Ef 1458End a font mode context started by 1459.Sx \&Bf . 1460.Ss \&Ek 1461End a keep context started by 1462.Sx \&Bk . 1463.Ss \&El 1464End a list context started by 1465.Sx \&Bl . 1466.Pp 1467See also 1468.Sx \&Bl 1469and 1470.Sx \&It . 1471.Ss \&Em 1472Denotes text that should be 1473.Em emphasised . 1474Note that this is a presentation term and should not be used for 1475stylistically decorating technical terms. 1476Depending on the output device, this is usually represented 1477using an italic font or underlined characters. 1478.Pp 1479Examples: 1480.Dl \&.Em Warnings! 1481.Dl \&.Em Remarks : 1482.Pp 1483See also 1484.Sx \&Bf , 1485.Sx \&Li , 1486.Sx \&No , 1487and 1488.Sx \&Sy . 1489.Ss \&En 1490This macro is obsolete and not implemented in 1491.Xr mandoc 1 . 1492.Ss \&Eo 1493An arbitrary enclosure. 1494Its syntax is as follows: 1495.Pp 1496.D1 Pf \. Sx \&Eo Op Ar TERM 1497.Pp 1498The 1499.Ar TERM 1500argument is used as the enclosure head, for example, specifying \e(lq 1501will emulate 1502.Sx \&Do . 1503.Ss \&Er 1504Error constants for definitions of the 1505.Va errno 1506libc global variable. 1507This is most often used in section 2 and 3 manual pages. 1508.Pp 1509Examples: 1510.Dl \&.Er EPERM 1511.Dl \&.Er ENOENT 1512.Pp 1513See also 1514.Sx \&Dv 1515for general constants. 1516.Ss \&Es 1517This macro is obsolete and not implemented. 1518.Ss \&Ev 1519Environmental variables such as those specified in 1520.Xr environ 7 . 1521.Pp 1522Examples: 1523.Dl \&.Ev DISPLAY 1524.Dl \&.Ev PATH 1525.Pp 1526See also 1527.Sx \&Dv 1528for general constants. 1529.Ss \&Ex 1530Insert a standard sentence regarding command exit values of 0 on success 1531and >0 on failure. 1532This is most often used in section 1, 6, and 8 manual pages. 1533Its syntax is as follows: 1534.Pp 1535.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... 1536.Pp 1537If 1538.Ar utility 1539is not specified, the document's name set by 1540.Sx \&Nm 1541is used. 1542Multiple 1543.Ar utility 1544arguments are treated as separate utilities. 1545.Pp 1546See also 1547.Sx \&Rv . 1548.Ss \&Fa 1549Function argument. 1550Its syntax is as follows: 1551.Bd -ragged -offset indent 1552.Pf \. Sx \&Fa 1553.Op Cm argtype 1554.Cm argname 1555.Ed 1556.Pp 1557This may be invoked for names with or without the corresponding type. 1558It is also used to specify the field name of a structure. 1559Most often, the 1560.Sx \&Fa 1561macro is used in the 1562.Em SYNOPSIS 1563within 1564.Sx \&Fo 1565section when documenting multi-line function prototypes. 1566If invoked with multiple arguments, the arguments are separated by a 1567comma. 1568Furthermore, if the following macro is another 1569.Sx \&Fa , 1570the last argument will also have a trailing comma. 1571.Pp 1572Examples: 1573.Dl \&.Fa \(dqconst char *p\(dq 1574.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1575.Dl \&.Fa foo 1576.Pp 1577See also 1578.Sx \&Fo . 1579.Ss \&Fc 1580End a function context started by 1581.Sx \&Fo . 1582.Ss \&Fd 1583Historically used to document include files. 1584This usage has been deprecated in favour of 1585.Sx \&In . 1586Do not use this macro. 1587.Pp 1588See also 1589.Sx MANUAL STRUCTURE 1590and 1591.Sx \&In . 1592.Ss \&Fl 1593Command-line flag or option. 1594Used when listing arguments to command-line utilities. 1595Prints a fixed-width hyphen 1596.Sq \- 1597directly followed by each argument. 1598If no arguments are provided, a hyphen is printed followed by a space. 1599If the argument is a macro, a hyphen is prefixed to the subsequent macro 1600output. 1601.Pp 1602Examples: 1603.Dl ".Fl R Op Fl H | L | P" 1604.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1605.Dl ".Fl type Cm d Fl name Pa CVS" 1606.Dl ".Fl Ar signal_number" 1607.Dl ".Fl o Fl" 1608.Pp 1609See also 1610.Sx \&Cm . 1611.Ss \&Fn 1612A function name. 1613Its syntax is as follows: 1614.Bd -ragged -offset indent 1615.Pf \. Ns Sx \&Fn 1616.Op Ar functype 1617.Ar funcname 1618.Op Oo Ar argtype Oc Ar argname 1619.Ed 1620.Pp 1621Function arguments are surrounded in parenthesis and 1622are delimited by commas. 1623If no arguments are specified, blank parenthesis are output. 1624In the 1625.Em SYNOPSIS 1626section, this macro starts a new output line, 1627and a blank line is automatically inserted between function definitions. 1628.Pp 1629Examples: 1630.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1631.Dl \&.Fn funcname \(dqint arg0\(dq 1632.Dl \&.Fn funcname arg0 1633.Pp 1634.Bd -literal -offset indent -compact 1635\&.Ft functype 1636\&.Fn funcname 1637.Ed 1638.Pp 1639When referring to a function documented in another manual page, use 1640.Sx \&Xr 1641instead. 1642See also 1643.Sx MANUAL STRUCTURE , 1644.Sx \&Fo , 1645and 1646.Sx \&Ft . 1647.Ss \&Fo 1648Begin a function block. 1649This is a multi-line version of 1650.Sx \&Fn . 1651Its syntax is as follows: 1652.Pp 1653.D1 Pf \. Sx \&Fo Ar funcname 1654.Pp 1655Invocations usually occur in the following context: 1656.Bd -ragged -offset indent 1657.Pf \. Sx \&Ft Ar functype 1658.br 1659.Pf \. Sx \&Fo Ar funcname 1660.br 1661.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname 1662.br 1663\&.\.\. 1664.br 1665.Pf \. Sx \&Fc 1666.Ed 1667.Pp 1668A 1669.Sx \&Fo 1670scope is closed by 1671.Sx \&Fc . 1672.Pp 1673See also 1674.Sx MANUAL STRUCTURE , 1675.Sx \&Fa , 1676.Sx \&Fc , 1677and 1678.Sx \&Ft . 1679.Ss \&Fr 1680This macro is obsolete and not implemented in 1681.Xr mandoc 1 . 1682.Pp 1683It was used to show function return values. 1684The syntax was: 1685.Pp 1686.Dl Pf . Sx \&Fr Ar value 1687.Ss \&Ft 1688A function type. 1689Its syntax is as follows: 1690.Pp 1691.D1 Pf \. Sx \&Ft Ar functype 1692.Pp 1693In the 1694.Em SYNOPSIS 1695section, a new output line is started after this macro. 1696.Pp 1697Examples: 1698.Dl \&.Ft int 1699.Bd -literal -offset indent -compact 1700\&.Ft functype 1701\&.Fn funcname 1702.Ed 1703.Pp 1704See also 1705.Sx MANUAL STRUCTURE , 1706.Sx \&Fn , 1707and 1708.Sx \&Fo . 1709.Ss \&Fx 1710Format the 1711.Fx 1712version provided as an argument, or a default value 1713if no argument is provided. 1714.Pp 1715Examples: 1716.Dl \&.Fx 7.1 1717.Dl \&.Fx 1718.Pp 1719See also 1720.Sx \&At , 1721.Sx \&Bsx , 1722.Sx \&Bx , 1723.Sx \&Dx , 1724.Sx \&Nx , 1725.Sx \&Ox , 1726and 1727.Sx \&Ux . 1728.Ss \&Hf 1729This macro is not implemented in 1730.Xr mandoc 1 . 1731.Pp 1732It was used to include the contents of a (header) file literally. 1733The syntax was: 1734.Pp 1735.Dl Pf . Sx \&Hf Ar filename 1736.Ss \&Ic 1737Designate an internal or interactive command. 1738This is similar to 1739.Sx \&Cm 1740but used for instructions rather than values. 1741.Pp 1742Examples: 1743.Dl \&.Ic :wq 1744.Dl \&.Ic hash 1745.Dl \&.Ic alias 1746.Pp 1747Note that using 1748.Sx \&Bd Fl literal 1749or 1750.Sx \&D1 1751is preferred for displaying code; the 1752.Sx \&Ic 1753macro is used when referring to specific instructions. 1754.Ss \&In 1755An 1756.Dq include 1757file. 1758When invoked as the first macro on an input line in the 1759.Em SYNOPSIS 1760section, the argument is displayed in angle brackets 1761and preceded by 1762.Dq #include , 1763and a blank line is inserted in front if there is a preceding 1764function declaration. 1765This is most often used in section 2, 3, and 9 manual pages. 1766.Pp 1767Examples: 1768.Dl \&.In sys/types.h 1769.Pp 1770See also 1771.Sx MANUAL STRUCTURE . 1772.Ss \&It 1773A list item. 1774The syntax of this macro depends on the list type. 1775.Pp 1776Lists 1777of type 1778.Fl hang , 1779.Fl ohang , 1780.Fl inset , 1781and 1782.Fl diag 1783have the following syntax: 1784.Pp 1785.D1 Pf \. Sx \&It Ar args 1786.Pp 1787Lists of type 1788.Fl bullet , 1789.Fl dash , 1790.Fl enum , 1791.Fl hyphen 1792and 1793.Fl item 1794have the following syntax: 1795.Pp 1796.D1 Pf \. Sx \&It 1797.Pp 1798with subsequent lines interpreted within the scope of the 1799.Sx \&It 1800until either a closing 1801.Sx \&El 1802or another 1803.Sx \&It . 1804.Pp 1805The 1806.Fl tag 1807list has the following syntax: 1808.Pp 1809.D1 Pf \. Sx \&It Op Cm args 1810.Pp 1811Subsequent lines are interpreted as with 1812.Fl bullet 1813and family. 1814The line arguments correspond to the list's left-hand side; body 1815arguments correspond to the list's contents. 1816.Pp 1817The 1818.Fl column 1819list is the most complicated. 1820Its syntax is as follows: 1821.Pp 1822.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... 1823.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... 1824.Pp 1825The arguments consist of one or more lines of text and macros 1826representing a complete table line. 1827Cells within the line are delimited by tabs or by the special 1828.Sx \&Ta 1829block macro. 1830The tab cell delimiter may only be used within the 1831.Sx \&It 1832line itself; on following lines, only the 1833.Sx \&Ta 1834macro can be used to delimit cells, and 1835.Sx \&Ta 1836is only recognised as a macro when called by other macros, 1837not as the first macro on a line. 1838.Pp 1839Note that quoted strings may span tab-delimited cells on an 1840.Sx \&It 1841line. 1842For example, 1843.Pp 1844.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; 1845.Pp 1846will preserve the semicolon whitespace except for the last. 1847.Pp 1848See also 1849.Sx \&Bl . 1850.Ss \&Lb 1851Specify a library. 1852The syntax is as follows: 1853.Pp 1854.D1 Pf \. Sx \&Lb Ar library 1855.Pp 1856The 1857.Ar library 1858parameter may be a system library, such as 1859.Cm libz 1860or 1861.Cm libpam , 1862in which case a small library description is printed next to the linker 1863invocation; or a custom library, in which case the library name is 1864printed in quotes. 1865This is most commonly used in the 1866.Em SYNOPSIS 1867section as described in 1868.Sx MANUAL STRUCTURE . 1869.Pp 1870Examples: 1871.Dl \&.Lb libz 1872.Dl \&.Lb mdoc 1873.Ss \&Li 1874Denotes text that should be in a 1875.Li literal 1876font mode. 1877Note that this is a presentation term and should not be used for 1878stylistically decorating technical terms. 1879.Pp 1880On terminal output devices, this is often indistinguishable from 1881normal text. 1882.Pp 1883See also 1884.Sx \&Bf , 1885.Sx \&Em , 1886.Sx \&No , 1887and 1888.Sx \&Sy . 1889.Ss \&Lk 1890Format a hyperlink. 1891Its syntax is as follows: 1892.Pp 1893.D1 Pf \. Sx \&Lk Ar uri Op Ar name 1894.Pp 1895Examples: 1896.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq 1897.Dl \&.Lk http://bsd.lv 1898.Pp 1899See also 1900.Sx \&Mt . 1901.Ss \&Lp 1902Synonym for 1903.Sx \&Pp . 1904.Ss \&Ms 1905Display a mathematical symbol. 1906Its syntax is as follows: 1907.Pp 1908.D1 Pf \. Sx \&Ms Ar symbol 1909.Pp 1910Examples: 1911.Dl \&.Ms sigma 1912.Dl \&.Ms aleph 1913.Ss \&Mt 1914Format a 1915.Dq mailto: 1916hyperlink. 1917Its syntax is as follows: 1918.Pp 1919.D1 Pf \. Sx \&Mt Ar address 1920.Pp 1921Examples: 1922.Dl \&.Mt discuss@manpages.bsd.lv 1923.Ss \&Nd 1924A one line description of the manual's content. 1925This may only be invoked in the 1926.Em SYNOPSIS 1927section subsequent the 1928.Sx \&Nm 1929macro. 1930.Pp 1931Examples: 1932.Dl Pf . Sx \&Nd mdoc language reference 1933.Dl Pf . Sx \&Nd format and display UNIX manuals 1934.Pp 1935The 1936.Sx \&Nd 1937macro technically accepts child macros and terminates with a subsequent 1938.Sx \&Sh 1939invocation. 1940Do not assume this behaviour: some 1941.Xr whatis 1 1942database generators are not smart enough to parse more than the line 1943arguments and will display macros verbatim. 1944.Pp 1945See also 1946.Sx \&Nm . 1947.Ss \&Nm 1948The name of the manual page, or \(em in particular in section 1, 6, 1949and 8 pages \(em of an additional command or feature documented in 1950the manual page. 1951When first invoked, the 1952.Sx \&Nm 1953macro expects a single argument, the name of the manual page. 1954Usually, the first invocation happens in the 1955.Em NAME 1956section of the page. 1957The specified name will be remembered and used whenever the macro is 1958called again without arguments later in the page. 1959The 1960.Sx \&Nm 1961macro uses 1962.Sx Block full-implicit 1963semantics when invoked as the first macro on an input line in the 1964.Em SYNOPSIS 1965section; otherwise, it uses ordinary 1966.Sx In-line 1967semantics. 1968.Pp 1969Examples: 1970.Bd -literal -offset indent 1971\&.Sh SYNOPSIS 1972\&.Nm cat 1973\&.Op Fl benstuv 1974\&.Op Ar 1975.Ed 1976.Pp 1977In the 1978.Em SYNOPSIS 1979of section 2, 3 and 9 manual pages, use the 1980.Sx \&Fn 1981macro rather than 1982.Sx \&Nm 1983to mark up the name of the manual page. 1984.Ss \&No 1985Normal text. 1986Closes the scope of any preceding in-line macro. 1987When used after physical formatting macros like 1988.Sx \&Em 1989or 1990.Sx \&Sy , 1991switches back to the standard font face and weight. 1992Can also be used to embed plain text strings in macro lines 1993using semantic annotation macros. 1994.Pp 1995Examples: 1996.Dl ".Em italic , Sy bold , No and roman" 1997.Pp 1998.Bd -literal -offset indent -compact 1999\&.Sm off 2000\&.Cm :C No / Ar pattern No / Ar replacement No / 2001\&.Sm on 2002.Ed 2003.Pp 2004See also 2005.Sx \&Em , 2006.Sx \&Li , 2007and 2008.Sx \&Sy . 2009.Ss \&Ns 2010Suppress a space between the output of the preceding macro 2011and the following text or macro. 2012Following invocation, input is interpreted as normal text 2013just like after an 2014.Sx \&No 2015macro. 2016.Pp 2017This has no effect when invoked at the start of a macro line. 2018.Pp 2019Examples: 2020.Dl ".Ar name Ns = Ns Ar value" 2021.Dl ".Cm :M Ns Ar pattern" 2022.Dl ".Fl o Ns Ar output" 2023.Pp 2024See also 2025.Sx \&No 2026and 2027.Sx \&Sm . 2028.Ss \&Nx 2029Format the 2030.Nx 2031version provided as an argument, or a default value if 2032no argument is provided. 2033.Pp 2034Examples: 2035.Dl \&.Nx 5.01 2036.Dl \&.Nx 2037.Pp 2038See also 2039.Sx \&At , 2040.Sx \&Bsx , 2041.Sx \&Bx , 2042.Sx \&Dx , 2043.Sx \&Fx , 2044.Sx \&Ox , 2045and 2046.Sx \&Ux . 2047.Ss \&Oc 2048Close multi-line 2049.Sx \&Oo 2050context. 2051.Ss \&Oo 2052Multi-line version of 2053.Sx \&Op . 2054.Pp 2055Examples: 2056.Bd -literal -offset indent -compact 2057\&.Oo 2058\&.Op Fl flag Ns Ar value 2059\&.Oc 2060.Ed 2061.Ss \&Op 2062Optional part of a command line. 2063Prints the argument(s) in brackets. 2064This is most often used in the 2065.Em SYNOPSIS 2066section of section 1 and 8 manual pages. 2067.Pp 2068Examples: 2069.Dl \&.Op \&Fl a \&Ar b 2070.Dl \&.Op \&Ar a | b 2071.Pp 2072See also 2073.Sx \&Oo . 2074.Ss \&Os 2075Document operating system version. 2076This is the mandatory third macro of 2077any 2078.Nm 2079file. 2080Its syntax is as follows: 2081.Pp 2082.D1 Pf \. Sx \&Os Op Ar system Op Ar version 2083.Pp 2084The optional 2085.Ar system 2086parameter specifies the relevant operating system or environment. 2087Left unspecified, it defaults to the local operating system version. 2088This is the suggested form. 2089.Pp 2090Examples: 2091.Dl \&.Os 2092.Dl \&.Os KTH/CSC/TCS 2093.Dl \&.Os BSD 4.3 2094.Pp 2095See also 2096.Sx \&Dd 2097and 2098.Sx \&Dt . 2099.Ss \&Ot 2100This macro is obsolete and not implemented in 2101.Xr mandoc 1 . 2102.Pp 2103Historical 2104.Xr mdoc 7 2105packages described it as 2106.Dq "old function type (FORTRAN)" . 2107.Ss \&Ox 2108Format the 2109.Ox 2110version provided as an argument, or a default value 2111if no argument is provided. 2112.Pp 2113Examples: 2114.Dl \&.Ox 4.5 2115.Dl \&.Ox 2116.Pp 2117See also 2118.Sx \&At , 2119.Sx \&Bsx , 2120.Sx \&Bx , 2121.Sx \&Dx , 2122.Sx \&Fx , 2123.Sx \&Nx , 2124and 2125.Sx \&Ux . 2126.Ss \&Pa 2127An absolute or relative file system path, or a file or directory name. 2128If an argument is not provided, the character 2129.Sq \(ti 2130is used as a default. 2131.Pp 2132Examples: 2133.Dl \&.Pa /usr/bin/mandoc 2134.Dl \&.Pa /usr/share/man/man7/mdoc.7 2135.Pp 2136See also 2137.Sx \&Lk . 2138.Ss \&Pc 2139Close parenthesised context opened by 2140.Sx \&Po . 2141.Ss \&Pf 2142Removes the space between its argument 2143.Pq Dq prefix 2144and the following macro. 2145Its syntax is as follows: 2146.Pp 2147.D1 .Pf Ar prefix macro arguments ... 2148.Pp 2149This is equivalent to: 2150.Pp 2151.D1 .No Ar prefix No \&Ns Ar macro arguments ... 2152.Pp 2153Examples: 2154.Dl ".Pf $ Ar variable_name" 2155.Dl ".Pf 0x Ar hex_digits" 2156.Pp 2157See also 2158.Sx \&Ns 2159and 2160.Sx \&Sm . 2161.Ss \&Po 2162Multi-line version of 2163.Sx \&Pq . 2164.Ss \&Pp 2165Break a paragraph. 2166This will assert vertical space between prior and subsequent macros 2167and/or text. 2168.Pp 2169Paragraph breaks are not needed before or after 2170.Sx \&Sh 2171or 2172.Sx \&Ss 2173macros or before displays 2174.Pq Sx \&Bd 2175or lists 2176.Pq Sx \&Bl 2177unless the 2178.Fl compact 2179flag is given. 2180.Ss \&Pq 2181Parenthesised enclosure. 2182.Pp 2183See also 2184.Sx \&Po . 2185.Ss \&Qc 2186Close quoted context opened by 2187.Sx \&Qo . 2188.Ss \&Ql 2189Format a single-quoted literal. 2190See also 2191.Sx \&Qq 2192and 2193.Sx \&Sq . 2194.Ss \&Qo 2195Multi-line version of 2196.Sx \&Qq . 2197.Ss \&Qq 2198Encloses its arguments in 2199.Qq typewriter 2200double-quotes. 2201Consider using 2202.Sx \&Dq . 2203.Pp 2204See also 2205.Sx \&Dq , 2206.Sx \&Sq , 2207and 2208.Sx \&Qo . 2209.Ss \&Re 2210Close an 2211.Sx \&Rs 2212block. 2213Does not have any tail arguments. 2214.Ss \&Rs 2215Begin a bibliographic 2216.Pq Dq reference 2217block. 2218Does not have any head arguments. 2219The block macro may only contain 2220.Sx \&%A , 2221.Sx \&%B , 2222.Sx \&%C , 2223.Sx \&%D , 2224.Sx \&%I , 2225.Sx \&%J , 2226.Sx \&%N , 2227.Sx \&%O , 2228.Sx \&%P , 2229.Sx \&%Q , 2230.Sx \&%R , 2231.Sx \&%T , 2232.Sx \&%U , 2233and 2234.Sx \&%V 2235child macros (at least one must be specified). 2236.Pp 2237Examples: 2238.Bd -literal -offset indent -compact 2239\&.Rs 2240\&.%A J. E. Hopcroft 2241\&.%A J. D. Ullman 2242\&.%B Introduction to Automata Theory, Languages, and Computation 2243\&.%I Addison-Wesley 2244\&.%C Reading, Massachusettes 2245\&.%D 1979 2246\&.Re 2247.Ed 2248.Pp 2249If an 2250.Sx \&Rs 2251block is used within a SEE ALSO section, a vertical space is asserted 2252before the rendered output, else the block continues on the current 2253line. 2254.Ss \&Rv 2255Insert a standard sentence regarding a function call's return value of 0 2256on success and \-1 on error, with the 2257.Va errno 2258libc global variable set on error. 2259Its syntax is as follows: 2260.Pp 2261.D1 Pf \. Sx \&Rv Fl std Op Ar function ... 2262.Pp 2263If 2264.Ar function 2265is not specified, the document's name set by 2266.Sx \&Nm 2267is used. 2268Multiple 2269.Ar function 2270arguments are treated as separate functions. 2271.Pp 2272See also 2273.Sx \&Ex . 2274.Ss \&Sc 2275Close single-quoted context opened by 2276.Sx \&So . 2277.Ss \&Sh 2278Begin a new section. 2279For a list of conventional manual sections, see 2280.Sx MANUAL STRUCTURE . 2281These sections should be used unless it's absolutely necessary that 2282custom sections be used. 2283.Pp 2284Section names should be unique so that they may be keyed by 2285.Sx \&Sx . 2286Although this macro is parsed, it should not consist of child node or it 2287may not be linked with 2288.Sx \&Sx . 2289.Pp 2290See also 2291.Sx \&Pp , 2292.Sx \&Ss , 2293and 2294.Sx \&Sx . 2295.Ss \&Sm 2296Switches the spacing mode for output generated from macros. 2297Its syntax is as follows: 2298.Pp 2299.D1 Pf \. Sx \&Sm Cm on | off 2300.Pp 2301By default, spacing is 2302.Cm on . 2303When switched 2304.Cm off , 2305no white space is inserted between macro arguments and between the 2306output generated from adjacent macros, but text lines 2307still get normal spacing between words and sentences. 2308.Ss \&So 2309Multi-line version of 2310.Sx \&Sq . 2311.Ss \&Sq 2312Encloses its arguments in 2313.Sq typewriter 2314single-quotes. 2315.Pp 2316See also 2317.Sx \&Dq , 2318.Sx \&Qq , 2319and 2320.Sx \&So . 2321.Ss \&Ss 2322Begin a new subsection. 2323Unlike with 2324.Sx \&Sh , 2325there is no convention for the naming of subsections. 2326Except 2327.Em DESCRIPTION , 2328the conventional sections described in 2329.Sx MANUAL STRUCTURE 2330rarely have subsections. 2331.Pp 2332Sub-section names should be unique so that they may be keyed by 2333.Sx \&Sx . 2334Although this macro is parsed, it should not consist of child node or it 2335may not be linked with 2336.Sx \&Sx . 2337.Pp 2338See also 2339.Sx \&Pp , 2340.Sx \&Sh , 2341and 2342.Sx \&Sx . 2343.Ss \&St 2344Replace an abbreviation for a standard with the full form. 2345The following standards are recognised: 2346.Pp 2347.Bl -tag -width "-p1003.1g-2000X" -compact 2348.It \-p1003.1-88 2349.St -p1003.1-88 2350.It \-p1003.1-90 2351.St -p1003.1-90 2352.It \-p1003.1-96 2353.St -p1003.1-96 2354.It \-p1003.1-2001 2355.St -p1003.1-2001 2356.It \-p1003.1-2004 2357.St -p1003.1-2004 2358.It \-p1003.1-2008 2359.St -p1003.1-2008 2360.It \-p1003.1 2361.St -p1003.1 2362.It \-p1003.1b 2363.St -p1003.1b 2364.It \-p1003.1b-93 2365.St -p1003.1b-93 2366.It \-p1003.1c-95 2367.St -p1003.1c-95 2368.It \-p1003.1g-2000 2369.St -p1003.1g-2000 2370.It \-p1003.1i-95 2371.St -p1003.1i-95 2372.It \-p1003.2-92 2373.St -p1003.2-92 2374.It \-p1003.2a-92 2375.St -p1003.2a-92 2376.It \-p1387.2-95 2377.St -p1387.2-95 2378.It \-p1003.2 2379.St -p1003.2 2380.It \-p1387.2 2381.St -p1387.2 2382.It \-isoC 2383.St -isoC 2384.It \-isoC-90 2385.St -isoC-90 2386.It \-isoC-amd1 2387.St -isoC-amd1 2388.It \-isoC-tcor1 2389.St -isoC-tcor1 2390.It \-isoC-tcor2 2391.St -isoC-tcor2 2392.It \-isoC-99 2393.St -isoC-99 2394.It \-isoC-2011 2395.St -isoC-2011 2396.It \-iso9945-1-90 2397.St -iso9945-1-90 2398.It \-iso9945-1-96 2399.St -iso9945-1-96 2400.It \-iso9945-2-93 2401.St -iso9945-2-93 2402.It \-ansiC 2403.St -ansiC 2404.It \-ansiC-89 2405.St -ansiC-89 2406.It \-ansiC-99 2407.St -ansiC-99 2408.It \-ieee754 2409.St -ieee754 2410.It \-iso8802-3 2411.St -iso8802-3 2412.It \-iso8601 2413.St -iso8601 2414.It \-ieee1275-94 2415.St -ieee1275-94 2416.It \-xpg3 2417.St -xpg3 2418.It \-xpg4 2419.St -xpg4 2420.It \-xpg4.2 2421.St -xpg4.2 2422.It \-xpg4.3 2423.St -xpg4.3 2424.It \-xbd5 2425.St -xbd5 2426.It \-xcu5 2427.St -xcu5 2428.It \-xsh5 2429.St -xsh5 2430.It \-xns5 2431.St -xns5 2432.It \-xns5.2 2433.St -xns5.2 2434.It \-xns5.2d2.0 2435.St -xns5.2d2.0 2436.It \-xcurses4.2 2437.St -xcurses4.2 2438.It \-susv2 2439.St -susv2 2440.It \-susv3 2441.St -susv3 2442.It \-svid4 2443.St -svid4 2444.El 2445.Ss \&Sx 2446Reference a section or subsection in the same manual page. 2447The referenced section or subsection name must be identical to the 2448enclosed argument, including whitespace. 2449.Pp 2450Examples: 2451.Dl \&.Sx MANUAL STRUCTURE 2452.Pp 2453See also 2454.Sx \&Sh 2455and 2456.Sx \&Ss . 2457.Ss \&Sy 2458Format enclosed arguments in symbolic 2459.Pq Dq boldface . 2460Note that this is a presentation term and should not be used for 2461stylistically decorating technical terms. 2462.Pp 2463See also 2464.Sx \&Bf , 2465.Sx \&Em , 2466.Sx \&Li , 2467and 2468.Sx \&No . 2469.Ss \&Ta 2470Table cell separator in 2471.Sx \&Bl Fl column 2472lists; can only be used below 2473.Sx \&It . 2474.Ss \&Tn 2475Format a tradename. 2476.Pp 2477Since this macro is often implemented to use a small caps font, 2478it has historically been used for acronyms (like ASCII) as well. 2479Such usage is not recommended because it would use the same macro 2480sometimes for semantical annotation, sometimes for physical formatting. 2481.Pp 2482Examples: 2483.Dl \&.Tn IBM 2484.Ss \&Ud 2485Prints out 2486.Dq currently under development. 2487.Ss \&Ux 2488Format the UNIX name. 2489Accepts no argument. 2490.Pp 2491Examples: 2492.Dl \&.Ux 2493.Pp 2494See also 2495.Sx \&At , 2496.Sx \&Bsx , 2497.Sx \&Bx , 2498.Sx \&Dx , 2499.Sx \&Fx , 2500.Sx \&Nx , 2501and 2502.Sx \&Ox . 2503.Ss \&Va 2504A variable name. 2505.Pp 2506Examples: 2507.Dl \&.Va foo 2508.Dl \&.Va const char *bar ; 2509.Ss \&Vt 2510A variable type. 2511This is also used for indicating global variables in the 2512.Em SYNOPSIS 2513section, in which case a variable name is also specified. 2514Note that it accepts 2515.Sx Block partial-implicit 2516syntax when invoked as the first macro on an input line in the 2517.Em SYNOPSIS 2518section, else it accepts ordinary 2519.Sx In-line 2520syntax. 2521In the former case, this macro starts a new output line, 2522and a blank line is inserted in front if there is a preceding 2523function definition or include directive. 2524.Pp 2525Note that this should not be confused with 2526.Sx \&Ft , 2527which is used for function return types. 2528.Pp 2529Examples: 2530.Dl \&.Vt unsigned char 2531.Dl \&.Vt extern const char * const sys_signame[] \&; 2532.Pp 2533See also 2534.Sx MANUAL STRUCTURE 2535and 2536.Sx \&Va . 2537.Ss \&Xc 2538Close a scope opened by 2539.Sx \&Xo . 2540.Ss \&Xo 2541Extend the header of an 2542.Sx \&It 2543macro or the body of a partial-implicit block macro 2544beyond the end of the input line. 2545This macro originally existed to work around the 9-argument limit 2546of historic 2547.Xr roff 7 . 2548.Ss \&Xr 2549Link to another manual 2550.Pq Qq cross-reference . 2551Its syntax is as follows: 2552.Pp 2553.D1 Pf \. Sx \&Xr Ar name section 2554.Pp 2555The 2556.Ar name 2557and 2558.Ar section 2559are the name and section of the linked manual. 2560If 2561.Ar section 2562is followed by non-punctuation, an 2563.Sx \&Ns 2564is inserted into the token stream. 2565This behaviour is for compatibility with 2566GNU troff. 2567.Pp 2568Examples: 2569.Dl \&.Xr mandoc 1 2570.Dl \&.Xr mandoc 1 \&; 2571.Dl \&.Xr mandoc 1 \&Ns s behaviour 2572.Ss \&br 2573Emits a line-break. 2574This macro should not be used; it is implemented for compatibility with 2575historical manuals. 2576.Pp 2577Consider using 2578.Sx \&Pp 2579in the event of natural paragraph breaks. 2580.Ss \&sp 2581Emits vertical space. 2582This macro should not be used; it is implemented for compatibility with 2583historical manuals. 2584Its syntax is as follows: 2585.Pp 2586.D1 Pf \. Sx \&sp Op Ar height 2587.Pp 2588The 2589.Ar height 2590argument is a scaling width as described in 2591.Xr roff 7 . 2592If unspecified, 2593.Sx \&sp 2594asserts a single vertical space. 2595.Sh MACRO SYNTAX 2596The syntax of a macro depends on its classification. 2597In this section, 2598.Sq \-arg 2599refers to macro arguments, which may be followed by zero or more 2600.Sq parm 2601parameters; 2602.Sq \&Yo 2603opens the scope of a macro; and if specified, 2604.Sq \&Yc 2605closes it out. 2606.Pp 2607The 2608.Em Callable 2609column indicates that the macro may also be called by passing its name 2610as an argument to another macro. 2611For example, 2612.Sq \&.Op \&Fl O \&Ar file 2613produces 2614.Sq Op Fl O Ar file . 2615To prevent a macro call and render the macro name literally, 2616escape it by prepending a zero-width space, 2617.Sq \e& . 2618For example, 2619.Sq \&Op \e&Fl O 2620produces 2621.Sq Op \&Fl O . 2622If a macro is not callable but its name appears as an argument 2623to another macro, it is interpreted as opaque text. 2624For example, 2625.Sq \&.Fl \&Sh 2626produces 2627.Sq Fl \&Sh . 2628.Pp 2629The 2630.Em Parsed 2631column indicates whether the macro may call other macros by receiving 2632their names as arguments. 2633If a macro is not parsed but the name of another macro appears 2634as an argument, it is interpreted as opaque text. 2635.Pp 2636The 2637.Em Scope 2638column, if applicable, describes closure rules. 2639.Ss Block full-explicit 2640Multi-line scope closed by an explicit closing macro. 2641All macros contains bodies; only 2642.Sx \&Bf 2643and 2644.Pq optionally 2645.Sx \&Bl 2646contain a head. 2647.Bd -literal -offset indent 2648\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2649\(lBbody...\(rB 2650\&.Yc 2651.Ed 2652.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2653.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2654.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed 2655.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef 2656.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek 2657.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El 2658.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd 2659.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf 2660.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk 2661.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl 2662.El 2663.Ss Block full-implicit 2664Multi-line scope closed by end-of-file or implicitly by another macro. 2665All macros have bodies; some 2666.Po 2667.Sx \&It Fl bullet , 2668.Fl hyphen , 2669.Fl dash , 2670.Fl enum , 2671.Fl item 2672.Pc 2673don't have heads; only one 2674.Po 2675.Sx \&It 2676in 2677.Sx \&Bl Fl column 2678.Pc 2679has multiple heads. 2680.Bd -literal -offset indent 2681\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2682\(lBbody...\(rB 2683.Ed 2684.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2685.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2686.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El 2687.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh 2688.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss 2689.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh 2690.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss 2691.El 2692.Pp 2693Note that the 2694.Sx \&Nm 2695macro is a 2696.Sx Block full-implicit 2697macro only when invoked as the first macro 2698in a 2699.Em SYNOPSIS 2700section line, else it is 2701.Sx In-line . 2702.Ss Block partial-explicit 2703Like block full-explicit, but also with single-line scope. 2704Each has at least a body and, in limited circumstances, a head 2705.Po 2706.Sx \&Fo , 2707.Sx \&Eo 2708.Pc 2709and/or tail 2710.Pq Sx \&Ec . 2711.Bd -literal -offset indent 2712\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2713\(lBbody...\(rB 2714\&.Yc \(lBtail...\(rB 2715 2716\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2717\(lBbody...\(rB \&Yc \(lBtail...\(rB 2718.Ed 2719.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2720.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2721.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao 2722.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac 2723.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo 2724.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc 2725.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro 2726.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc 2727.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do 2728.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc 2729.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo 2730.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec 2731.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo 2732.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc 2733.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo 2734.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc 2735.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po 2736.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc 2737.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo 2738.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc 2739.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs 2740.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re 2741.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So 2742.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc 2743.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo 2744.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc 2745.El 2746.Ss Block partial-implicit 2747Like block full-implicit, but with single-line scope closed by the 2748end of the line. 2749.Bd -literal -offset indent 2750\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 2751.Ed 2752.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 2753.It Em Macro Ta Em Callable Ta Em Parsed 2754.It Sx \&Aq Ta Yes Ta Yes 2755.It Sx \&Bq Ta Yes Ta Yes 2756.It Sx \&Brq Ta Yes Ta Yes 2757.It Sx \&D1 Ta \&No Ta \&Yes 2758.It Sx \&Dl Ta \&No Ta Yes 2759.It Sx \&Dq Ta Yes Ta Yes 2760.It Sx \&Op Ta Yes Ta Yes 2761.It Sx \&Pq Ta Yes Ta Yes 2762.It Sx \&Ql Ta Yes Ta Yes 2763.It Sx \&Qq Ta Yes Ta Yes 2764.It Sx \&Sq Ta Yes Ta Yes 2765.It Sx \&Vt Ta Yes Ta Yes 2766.El 2767.Pp 2768Note that the 2769.Sx \&Vt 2770macro is a 2771.Sx Block partial-implicit 2772only when invoked as the first macro 2773in a 2774.Em SYNOPSIS 2775section line, else it is 2776.Sx In-line . 2777.Ss Special block macro 2778The 2779.Sx \&Ta 2780macro can only be used below 2781.Sx \&It 2782in 2783.Sx \&Bl Fl column 2784lists. 2785It delimits blocks representing table cells; 2786these blocks have bodies, but no heads. 2787.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2788.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2789.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It 2790.El 2791.Ss In-line 2792Closed by the end of the line, fixed argument lengths, 2793and/or subsequent macros. 2794In-line macros have only text children. 2795If a number (or inequality) of arguments is 2796.Pq n , 2797then the macro accepts an arbitrary number of arguments. 2798.Bd -literal -offset indent 2799\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 2800 2801\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 2802 2803\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 2804.Ed 2805.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 2806.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 2807.It Sx \&%A Ta \&No Ta \&No Ta >0 2808.It Sx \&%B Ta \&No Ta \&No Ta >0 2809.It Sx \&%C Ta \&No Ta \&No Ta >0 2810.It Sx \&%D Ta \&No Ta \&No Ta >0 2811.It Sx \&%I Ta \&No Ta \&No Ta >0 2812.It Sx \&%J Ta \&No Ta \&No Ta >0 2813.It Sx \&%N Ta \&No Ta \&No Ta >0 2814.It Sx \&%O Ta \&No Ta \&No Ta >0 2815.It Sx \&%P Ta \&No Ta \&No Ta >0 2816.It Sx \&%Q Ta \&No Ta \&No Ta >0 2817.It Sx \&%R Ta \&No Ta \&No Ta >0 2818.It Sx \&%T Ta \&No Ta \&No Ta >0 2819.It Sx \&%U Ta \&No Ta \&No Ta >0 2820.It Sx \&%V Ta \&No Ta \&No Ta >0 2821.It Sx \&Ad Ta Yes Ta Yes Ta >0 2822.It Sx \&An Ta Yes Ta Yes Ta >0 2823.It Sx \&Ap Ta Yes Ta Yes Ta 0 2824.It Sx \&Ar Ta Yes Ta Yes Ta n 2825.It Sx \&At Ta Yes Ta Yes Ta 1 2826.It Sx \&Bsx Ta Yes Ta Yes Ta n 2827.It Sx \&Bt Ta \&No Ta \&No Ta 0 2828.It Sx \&Bx Ta Yes Ta Yes Ta n 2829.It Sx \&Cd Ta Yes Ta Yes Ta >0 2830.It Sx \&Cm Ta Yes Ta Yes Ta >0 2831.It Sx \&Db Ta \&No Ta \&No Ta 1 2832.It Sx \&Dd Ta \&No Ta \&No Ta n 2833.It Sx \&Dt Ta \&No Ta \&No Ta n 2834.It Sx \&Dv Ta Yes Ta Yes Ta >0 2835.It Sx \&Dx Ta Yes Ta Yes Ta n 2836.It Sx \&Em Ta Yes Ta Yes Ta >0 2837.It Sx \&En Ta \&No Ta \&No Ta 0 2838.It Sx \&Er Ta Yes Ta Yes Ta >0 2839.It Sx \&Es Ta \&No Ta \&No Ta 0 2840.It Sx \&Ev Ta Yes Ta Yes Ta >0 2841.It Sx \&Ex Ta \&No Ta \&No Ta n 2842.It Sx \&Fa Ta Yes Ta Yes Ta >0 2843.It Sx \&Fd Ta \&No Ta \&No Ta >0 2844.It Sx \&Fl Ta Yes Ta Yes Ta n 2845.It Sx \&Fn Ta Yes Ta Yes Ta >0 2846.It Sx \&Fr Ta \&No Ta \&No Ta n 2847.It Sx \&Ft Ta Yes Ta Yes Ta >0 2848.It Sx \&Fx Ta Yes Ta Yes Ta n 2849.It Sx \&Hf Ta \&No Ta \&No Ta n 2850.It Sx \&Ic Ta Yes Ta Yes Ta >0 2851.It Sx \&In Ta \&No Ta \&No Ta 1 2852.It Sx \&Lb Ta \&No Ta \&No Ta 1 2853.It Sx \&Li Ta Yes Ta Yes Ta >0 2854.It Sx \&Lk Ta Yes Ta Yes Ta >0 2855.It Sx \&Lp Ta \&No Ta \&No Ta 0 2856.It Sx \&Ms Ta Yes Ta Yes Ta >0 2857.It Sx \&Mt Ta Yes Ta Yes Ta >0 2858.It Sx \&Nm Ta Yes Ta Yes Ta n 2859.It Sx \&No Ta Yes Ta Yes Ta 0 2860.It Sx \&Ns Ta Yes Ta Yes Ta 0 2861.It Sx \&Nx Ta Yes Ta Yes Ta n 2862.It Sx \&Os Ta \&No Ta \&No Ta n 2863.It Sx \&Ot Ta \&No Ta \&No Ta n 2864.It Sx \&Ox Ta Yes Ta Yes Ta n 2865.It Sx \&Pa Ta Yes Ta Yes Ta n 2866.It Sx \&Pf Ta Yes Ta Yes Ta 1 2867.It Sx \&Pp Ta \&No Ta \&No Ta 0 2868.It Sx \&Rv Ta \&No Ta \&No Ta n 2869.It Sx \&Sm Ta \&No Ta \&No Ta 1 2870.It Sx \&St Ta \&No Ta Yes Ta 1 2871.It Sx \&Sx Ta Yes Ta Yes Ta >0 2872.It Sx \&Sy Ta Yes Ta Yes Ta >0 2873.It Sx \&Tn Ta Yes Ta Yes Ta >0 2874.It Sx \&Ud Ta \&No Ta \&No Ta 0 2875.It Sx \&Ux Ta Yes Ta Yes Ta n 2876.It Sx \&Va Ta Yes Ta Yes Ta n 2877.It Sx \&Vt Ta Yes Ta Yes Ta >0 2878.It Sx \&Xr Ta Yes Ta Yes Ta >0 2879.It Sx \&br Ta \&No Ta \&No Ta 0 2880.It Sx \&sp Ta \&No Ta \&No Ta 1 2881.El 2882.Ss Delimiters 2883When a macro argument consists of one single input character 2884considered as a delimiter, the argument gets special handling. 2885This does not apply when delimiters appear in arguments containing 2886more than one character. 2887Consequently, to prevent special handling and just handle it 2888like any other argument, a delimiter can be escaped by prepending 2889a zero-width space 2890.Pq Sq \e& . 2891In text lines, delimiters never need escaping, but may be used 2892as normal punctuation. 2893.Pp 2894For many macros, when the leading arguments are opening delimiters, 2895these delimiters are put before the macro scope, 2896and when the trailing arguments are closing delimiters, 2897these delimiters are put after the macro scope. 2898For example, 2899.Pp 2900.D1 Pf \. \&Aq "( [ word ] ) ." 2901.Pp 2902renders as: 2903.Pp 2904.D1 Aq ( [ word ] ) . 2905.Pp 2906Opening delimiters are: 2907.Pp 2908.Bl -tag -width Ds -offset indent -compact 2909.It \&( 2910left parenthesis 2911.It \&[ 2912left bracket 2913.El 2914.Pp 2915Closing delimiters are: 2916.Pp 2917.Bl -tag -width Ds -offset indent -compact 2918.It \&. 2919period 2920.It \&, 2921comma 2922.It \&: 2923colon 2924.It \&; 2925semicolon 2926.It \&) 2927right parenthesis 2928.It \&] 2929right bracket 2930.It \&? 2931question mark 2932.It \&! 2933exclamation mark 2934.El 2935.Pp 2936Note that even a period preceded by a backslash 2937.Pq Sq \e.\& 2938gets this special handling; use 2939.Sq \e&. 2940to prevent that. 2941.Pp 2942Many in-line macros interrupt their scope when they encounter 2943delimiters, and resume their scope when more arguments follow that 2944are not delimiters. 2945For example, 2946.Pp 2947.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 2948.Pp 2949renders as: 2950.Pp 2951.D1 Fl a ( b | c \*(Ba d ) e 2952.Pp 2953This applies to both opening and closing delimiters, 2954and also to the middle delimiter: 2955.Pp 2956.Bl -tag -width Ds -offset indent -compact 2957.It \&| 2958vertical bar 2959.El 2960.Pp 2961As a special case, the predefined string \e*(Ba is handled and rendered 2962in the same way as a plain 2963.Sq \&| 2964character. 2965Using this predefined string is not recommended in new manuals. 2966.Ss Font handling 2967In 2968.Nm 2969documents, usage of semantic markup is recommended in order to have 2970proper fonts automatically selected; only when no fitting semantic markup 2971is available, consider falling back to 2972.Sx Physical markup 2973macros. 2974Whenever any 2975.Nm 2976macro switches the 2977.Xr roff 7 2978font mode, it will automatically restore the previous font when exiting 2979its scope. 2980Manually switching the font using the 2981.Xr roff 7 2982.Ql \ef 2983font escape sequences is never required. 2984.Sh COMPATIBILITY 2985This section documents compatibility between mandoc and other other 2986troff implementations, at this time limited to GNU troff 2987.Pq Qq groff . 2988The term 2989.Qq historic groff 2990refers to groff versions before 1.17, 2991which featured a significant update of the 2992.Pa doc.tmac 2993file. 2994.Pp 2995Heirloom troff, the other significant troff implementation accepting 2996\-mdoc, is similar to historic groff. 2997.Pp 2998The following problematic behaviour is found in groff: 2999.ds hist (Historic groff only.) 3000.Pp 3001.Bl -dash -compact 3002.It 3003Display macros 3004.Po 3005.Sx \&Bd , 3006.Sx \&Dl , 3007and 3008.Sx \&D1 3009.Pc 3010may not be nested. 3011\*[hist] 3012.It 3013.Sx \&At 3014with unknown arguments produces no output at all. 3015\*[hist] 3016Newer groff and mandoc print 3017.Qq AT&T UNIX 3018and the arguments. 3019.It 3020.Sx \&Bl Fl column 3021does not recognise trailing punctuation characters when they immediately 3022precede tabulator characters, but treats them as normal text and 3023outputs a space before them. 3024.It 3025.Sx \&Bd Fl ragged compact 3026does not start a new line. 3027\*[hist] 3028.It 3029.Sx \&Dd 3030with non-standard arguments behaves very strangely. 3031When there are three arguments, they are printed verbatim. 3032Any other number of arguments is replaced by the current date, 3033but without any arguments the string 3034.Dq Epoch 3035is printed. 3036.It 3037.Sx \&Fl 3038does not print a dash for an empty argument. 3039\*[hist] 3040.It 3041.Sx \&Fn 3042does not start a new line unless invoked as the line macro in the 3043.Em SYNOPSIS 3044section. 3045\*[hist] 3046.It 3047.Sx \&Fo 3048with 3049.Pf non- Sx \&Fa 3050children causes inconsistent spacing between arguments. 3051In mandoc, a single space is always inserted between arguments. 3052.It 3053.Sx \&Ft 3054in the 3055.Em SYNOPSIS 3056causes inconsistent vertical spacing, depending on whether a prior 3057.Sx \&Fn 3058has been invoked. 3059See 3060.Sx \&Ft 3061and 3062.Sx \&Fn 3063for the normalised behaviour in mandoc. 3064.It 3065.Sx \&In 3066ignores additional arguments and is not treated specially in the 3067.Em SYNOPSIS . 3068\*[hist] 3069.It 3070.Sx \&It 3071sometimes requires a 3072.Fl nested 3073flag. 3074\*[hist] 3075In new groff and mandoc, any list may be nested by default and 3076.Fl enum 3077lists will restart the sequence only for the sub-list. 3078.It 3079.Sx \&Li 3080followed by a delimiter is incorrectly used in some manuals 3081instead of properly quoting that character, which sometimes works with 3082historic groff. 3083.It 3084.Sx \&Lk 3085only accepts a single link-name argument; the remainder is misformatted. 3086.It 3087.Sx \&Pa 3088does not format its arguments when used in the FILES section under 3089certain list types. 3090.It 3091.Sx \&Ta 3092can only be called by other macros, but not at the beginning of a line. 3093.It 3094.Sx \&%C 3095is not implemented. 3096.It 3097Historic groff only allows up to eight or nine arguments per macro input 3098line, depending on the exact situation. 3099Providing more arguments causes garbled output. 3100The number of arguments on one input line is not limited with mandoc. 3101.It 3102Historic groff has many un-callable macros. 3103Most of these (excluding some block-level macros) are callable 3104in new groff and mandoc. 3105.It 3106.Sq \(ba 3107(vertical bar) is not fully supported as a delimiter. 3108\*[hist] 3109.It 3110.Sq \ef 3111.Pq font face 3112and 3113.Sq \ef 3114.Pq font family face 3115.Sx Text Decoration 3116escapes behave irregularly when specified within line-macro scopes. 3117.It 3118Negative scaling units return to prior lines. 3119Instead, mandoc truncates them to zero. 3120.El 3121.Pp 3122The following features are unimplemented in mandoc: 3123.Pp 3124.Bl -dash -compact 3125.It 3126.Sx \&Bd 3127.Fl file Ar file . 3128.It 3129.Sx \&Bd 3130.Fl offset Ar center 3131and 3132.Fl offset Ar right . 3133Groff does not implement centred and flush-right rendering either, 3134but produces large indentations. 3135.It 3136The 3137.Sq \eh 3138.Pq horizontal position , 3139.Sq \ev 3140.Pq vertical position , 3141.Sq \em 3142.Pq text colour , 3143.Sq \eM 3144.Pq text filling colour , 3145.Sq \ez 3146.Pq zero-length character , 3147.Sq \ew 3148.Pq string length , 3149.Sq \ek 3150.Pq horizontal position marker , 3151.Sq \eo 3152.Pq text overstrike , 3153and 3154.Sq \es 3155.Pq text size 3156escape sequences are all discarded in mandoc. 3157.It 3158The 3159.Sq \ef 3160scaling unit is accepted by mandoc, but rendered as the default unit. 3161.It 3162In quoted literals, groff allows pairwise double-quotes to produce a 3163standalone double-quote in formatted output. 3164This is not supported by mandoc. 3165.El 3166.Sh SEE ALSO 3167.Xr man 1 , 3168.Xr mandoc 1 , 3169.Xr eqn 7 , 3170.Xr man 7 , 3171.Xr mandoc_char 7 , 3172.Xr roff 7 , 3173.Xr tbl 7 3174.Sh HISTORY 3175The 3176.Nm 3177language first appeared as a troff macro package in 3178.Bx 4.4 . 3179It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3180in groff-1.17. 3181The standalone implementation that is part of the 3182.Xr mandoc 1 3183utility written by Kristaps Dzonsons appeared in 3184.Ox 4.6 . 3185.Sh AUTHORS 3186The 3187.Nm 3188reference was written by 3189.An Kristaps Dzonsons , 3190.Mt kristaps@bsd.lv . 3191