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