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