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