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