1.\" $OpenBSD: man.7,v 1.40 2014/12/28 15:22:42 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org> 5.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: December 28 2014 $ 20.Dt MAN 7 21.Os 22.Sh NAME 23.Nm man 24.Nd legacy formatting language for manual pages 25.Sh DESCRIPTION 26Traditionally, the 27.Nm man 28language has been used to write 29.Ux 30manuals for the 31.Xr man 1 32utility. 33It supports limited control of presentational details like fonts, 34indentation and spacing. 35This reference document describes the structure of manual pages 36and the syntax and usage of the man language. 37.Pp 38.Bf -emphasis 39Do not use 40.Nm 41to write your manuals: 42.Ef 43It lacks support for semantic markup. 44Use the 45.Xr mdoc 7 46language, instead. 47.Pp 48In a 49.Nm 50document, lines beginning with the control character 51.Sq \&. 52are called 53.Dq macro lines . 54The first word is the macro name. 55It usually consists of two capital letters. 56For a list of available macros, see 57.Sx MACRO OVERVIEW . 58The words following the macro name are arguments to the macro. 59.Pp 60Lines not beginning with the control character are called 61.Dq text lines . 62They provide free-form text to be printed; the formatting of the text 63depends on the respective processing context: 64.Bd -literal -offset indent 65\&.SH Macro lines change control state. 66Text lines are interpreted within the current state. 67.Ed 68.Pp 69Many aspects of the basic syntax of the 70.Nm 71language are based on the 72.Xr roff 7 73language; see the 74.Em LANGUAGE SYNTAX 75and 76.Em MACRO SYNTAX 77sections in the 78.Xr roff 7 79manual for details, in particular regarding 80comments, escape sequences, whitespace, and quoting. 81.Sh MANUAL STRUCTURE 82Each 83.Nm 84document must contain the 85.Sx \&TH 86macro describing the document's section and title. 87It may occur anywhere in the document, although conventionally it 88appears as the first macro. 89.Pp 90Beyond 91.Sx \&TH , 92at least one macro or text line must appear in the document. 93.Pp 94The following is a well-formed skeleton 95.Nm 96file for a utility 97.Qq progname : 98.Bd -literal -offset indent 99\&.TH PROGNAME 1 2009-10-10 100\&.SH NAME 101\efBprogname\efR \e(en one line about what it does 102\&.\e\(dq .SH LIBRARY 103\&.\e\(dq For sections 2, 3, and 9 only. 104\&.\e\(dq Not used in OpenBSD. 105\&.SH SYNOPSIS 106\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR 107\&.SH DESCRIPTION 108The \efBfoo\efR utility processes files ... 109\&.\e\(dq .Sh CONTEXT 110\&.\e\(dq For section 9 functions only. 111\&.\e\(dq .SH IMPLEMENTATION NOTES 112\&.\e\(dq Not used in OpenBSD. 113\&.\e\(dq .SH RETURN VALUES 114\&.\e\(dq For sections 2, 3, and 9 function return values only. 115\&.\e\(dq .SH ENVIRONMENT 116\&.\e\(dq For sections 1, 6, 7, and 8 only. 117\&.\e\(dq .SH FILES 118\&.\e\(dq .SH EXIT STATUS 119\&.\e\(dq For sections 1, 6, and 8 only. 120\&.\e\(dq .SH EXAMPLES 121\&.\e\(dq .SH DIAGNOSTICS 122\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 123\&.\e\(dq .SH ERRORS 124\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. 125\&.\e\(dq .SH SEE ALSO 126\&.\e\(dq .BR foobar ( 1 ) 127\&.\e\(dq .SH STANDARDS 128\&.\e\(dq .SH HISTORY 129\&.\e\(dq .SH AUTHORS 130\&.\e\(dq .SH CAVEATS 131\&.\e\(dq .SH BUGS 132\&.\e\(dq .SH SECURITY CONSIDERATIONS 133\&.\e\(dq Not used in OpenBSD. 134.Ed 135.Pp 136The sections in a 137.Nm 138document are conventionally ordered as they appear above. 139Sections should be composed as follows: 140.Bl -ohang -offset indent 141.It Em NAME 142The name(s) and a short description of the documented material. 143The syntax for this is generally as follows: 144.Pp 145.D1 \efBname\efR \e(en description 146.It Em LIBRARY 147The name of the library containing the documented material, which is 148assumed to be a function in a section 2 or 3 manual. 149For functions in the C library, this may be as follows: 150.Pp 151.D1 Standard C Library (libc, -lc) 152.It Em SYNOPSIS 153Documents the utility invocation syntax, function call syntax, or device 154configuration. 155.Pp 156For the first, utilities (sections 1, 6, and 8), this is 157generally structured as follows: 158.Pp 159.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... 160.Pp 161For the second, function calls (sections 2, 3, 9): 162.Pp 163.D1 \&.B char *name(char *\efIarg\efR); 164.Pp 165And for the third, configurations (section 4): 166.Pp 167.D1 \&.B name* at cardbus ? function ? 168.Pp 169Manuals not in these sections generally don't need a 170.Em SYNOPSIS . 171.It Em DESCRIPTION 172This expands upon the brief, one-line description in 173.Em NAME . 174It usually contains a break-down of the options (if documenting a 175command). 176.It Em CONTEXT 177This section lists the contexts in which functions can be called in section 9. 178The contexts are autoconf, process, or interrupt. 179.It Em IMPLEMENTATION NOTES 180Implementation-specific notes should be kept here. 181This is useful when implementing standard functions that may have side 182effects or notable algorithmic implications. 183.It Em RETURN VALUES 184This section documents the return values of functions in sections 2, 3, and 9. 185.It Em ENVIRONMENT 186Documents any usages of environment variables, e.g., 187.Xr environ 7 . 188.It Em FILES 189Documents files used. 190It's helpful to document both the file name and a short description of how 191the file is used (created, modified, etc.). 192.It Em EXIT STATUS 193This section documents the command exit status for 194section 1, 6, and 8 utilities. 195Historically, this information was described in 196.Em DIAGNOSTICS , 197a practise that is now discouraged. 198.It Em EXAMPLES 199Example usages. 200This often contains snippets of well-formed, 201well-tested invocations. 202Make sure that examples work properly! 203.It Em DIAGNOSTICS 204Documents error conditions. 205In section 4 and 9 manuals, these are usually messages 206printed by the kernel to the console and to the kernel log. 207In section 1, 6, 7, and 8, these are usually messages 208printed by userland programs to the standard error output. 209.Pp 210Historically, this section was used in place of 211.Em EXIT STATUS 212for manuals in sections 1, 6, and 8; however, this practise is 213discouraged. 214.It Em ERRORS 215Documents 216.Xr errno 2 217settings in sections 2, 3, 4, and 9. 218.It Em SEE ALSO 219References other manuals with related topics. 220This section should exist for most manuals. 221.Pp 222.D1 \&.BR bar \&( 1 \&), 223.Pp 224Cross-references should conventionally be ordered 225first by section, then alphabetically. 226.It Em STANDARDS 227References any standards implemented or used, such as 228.Pp 229.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) 230.Pp 231If not adhering to any standards, the 232.Em HISTORY 233section should be used. 234.It Em HISTORY 235A brief history of the subject, including where support first appeared. 236.It Em AUTHORS 237Credits to the person or persons who wrote the code and/or documentation. 238Authors should generally be noted by both name and email address. 239.It Em CAVEATS 240Common misuses and misunderstandings should be explained 241in this section. 242.It Em BUGS 243Known bugs, limitations, and work-arounds should be described 244in this section. 245.It Em SECURITY CONSIDERATIONS 246Documents any security precautions that operators should consider. 247.El 248.Sh MACRO OVERVIEW 249This overview is sorted such that macros of similar purpose are listed 250together, to help find the best macro for any given purpose. 251Deprecated macros are not included in the overview, but can be found 252in the alphabetical reference below. 253.Ss Page header and footer meta-data 254.Bl -column "PP, LP, P" description 255.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume 256.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument) 257.It Sx UC Ta display BSD version in the page footer (<= 1 argument) 258.El 259.Ss Sections and paragraphs 260.Bl -column "PP, LP, P" description 261.It Sx SH Ta section header (one line) 262.It Sx SS Ta subsection header (one line) 263.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments) 264.It Sx RS , RE Ta reset the left margin: Op Ar width 265.It Sx IP Ta indented paragraph: Op Ar head Op Ar width 266.It Sx TP Ta tagged paragraph: Op Ar width 267.It Sx HP Ta hanged paragraph: Op Ar width 268.It Sx PD Ta set vertical paragraph distance: Op Ar height 269.It Sx \&br Ta force output line break in text mode (no arguments) 270.It Sx \&sp Ta force vertical space: Op Ar height 271.It Sx fi , nf Ta fill mode and no-fill mode (no arguments) 272.It Sx in Ta additional indent: Op Ar width 273.El 274.Ss Physical markup 275.Bl -column "PP, LP, P" description 276.It Sx B Ta boldface font 277.It Sx I Ta italic font 278.It Sx R Ta roman (default) font 279.It Sx SB Ta small boldface font 280.It Sx SM Ta small roman font 281.It Sx BI Ta alternate between boldface and italic fonts 282.It Sx BR Ta alternate between boldface and roman fonts 283.It Sx IB Ta alternate between italic and boldface fonts 284.It Sx IR Ta alternate between italic and roman fonts 285.It Sx RB Ta alternate between roman and boldface fonts 286.It Sx RI Ta alternate between roman and italic fonts 287.El 288.Sh MACRO REFERENCE 289This section is a canonical reference to all macros, arranged 290alphabetically. 291For the scoping of individual macros, see 292.Sx MACRO SYNTAX . 293.Ss \&AT 294Sets the volume for the footer for compatibility with man pages from 295.At 296releases. 297The optional arguments specify which release it is from. 298.Ss \&B 299Text is rendered in bold face. 300.Pp 301See also 302.Sx \&I 303and 304.Sx \&R . 305.Ss \&BI 306Text is rendered alternately in bold face and italic. 307Thus, 308.Sq .BI this word and that 309causes 310.Sq this 311and 312.Sq and 313to render in bold face, while 314.Sq word 315and 316.Sq that 317render in italics. 318Whitespace between arguments is omitted in output. 319.Pp 320Examples: 321.Pp 322.Dl \&.BI bold italic bold italic 323.Pp 324The output of this example will be emboldened 325.Dq bold 326and italicised 327.Dq italic , 328with spaces stripped between arguments. 329.Pp 330See also 331.Sx \&IB , 332.Sx \&BR , 333.Sx \&RB , 334.Sx \&RI , 335and 336.Sx \&IR . 337.Ss \&BR 338Text is rendered alternately in bold face and roman (the default font). 339Whitespace between arguments is omitted in output. 340.Pp 341See 342.Sx \&BI 343for an equivalent example. 344.Pp 345See also 346.Sx \&BI , 347.Sx \&IB , 348.Sx \&RB , 349.Sx \&RI , 350and 351.Sx \&IR . 352.Ss \&DT 353Has no effect. 354Included for compatibility. 355.Ss \&EE 356This is a non-standard GNU extension, included only for compatibility. 357In 358.Xr mandoc 1 , 359it does the same as 360.Sx \&fi . 361.Ss \&EX 362This is a non-standard GNU extension, included only for compatibility. 363In 364.Xr mandoc 1 , 365it does the same as 366.Sx \&nf . 367.Ss \&HP 368Begin a paragraph whose initial output line is left-justified, but 369subsequent output lines are indented, with the following syntax: 370.Bd -filled -offset indent 371.Pf \. Sx \&HP 372.Op Cm width 373.Ed 374.Pp 375The 376.Cm width 377argument is a 378.Xr roff 7 379scaling width. 380If specified, it's saved for later paragraph left-margins; if unspecified, the 381saved or default width is used. 382.Pp 383See also 384.Sx \&IP , 385.Sx \&LP , 386.Sx \&P , 387.Sx \&PP , 388and 389.Sx \&TP . 390.Ss \&I 391Text is rendered in italics. 392.Pp 393See also 394.Sx \&B 395and 396.Sx \&R . 397.Ss \&IB 398Text is rendered alternately in italics and bold face. 399Whitespace between arguments is omitted in output. 400.Pp 401See 402.Sx \&BI 403for an equivalent example. 404.Pp 405See also 406.Sx \&BI , 407.Sx \&BR , 408.Sx \&RB , 409.Sx \&RI , 410and 411.Sx \&IR . 412.Ss \&IP 413Begin an indented paragraph with the following syntax: 414.Bd -filled -offset indent 415.Pf \. Sx \&IP 416.Op Cm head Op Cm width 417.Ed 418.Pp 419The 420.Cm width 421argument is a 422.Xr roff 7 423scaling width defining the left margin. 424It's saved for later paragraph left-margins; if unspecified, the saved or 425default width is used. 426.Pp 427The 428.Cm head 429argument is used as a leading term, flushed to the left margin. 430This is useful for bulleted paragraphs and so on. 431.Pp 432See also 433.Sx \&HP , 434.Sx \&LP , 435.Sx \&P , 436.Sx \&PP , 437and 438.Sx \&TP . 439.Ss \&IR 440Text is rendered alternately in italics and roman (the default font). 441Whitespace between arguments is omitted in output. 442.Pp 443See 444.Sx \&BI 445for an equivalent example. 446.Pp 447See also 448.Sx \&BI , 449.Sx \&IB , 450.Sx \&BR , 451.Sx \&RB , 452and 453.Sx \&RI . 454.Ss \&LP 455Begin an undecorated paragraph. 456The scope of a paragraph is closed by a subsequent paragraph, 457sub-section, section, or end of file. 458The saved paragraph left-margin width is reset to the default. 459.Pp 460See also 461.Sx \&HP , 462.Sx \&IP , 463.Sx \&P , 464.Sx \&PP , 465and 466.Sx \&TP . 467.Ss \&OP 468Optional command-line argument. 469This is a non-standard GNU extension, included only for compatibility. 470It has the following syntax: 471.Bd -filled -offset indent 472.Pf \. Sx \&OP 473.Cm key Op Cm value 474.Ed 475.Pp 476The 477.Cm key 478is usually a command-line flag and 479.Cm value 480its argument. 481.Ss \&P 482Synonym for 483.Sx \&LP . 484.Pp 485See also 486.Sx \&HP , 487.Sx \&IP , 488.Sx \&LP , 489.Sx \&PP , 490and 491.Sx \&TP . 492.Ss \&PD 493Specify the vertical space to be inserted before each new paragraph. 494.br 495The syntax is as follows: 496.Bd -filled -offset indent 497.Pf \. Sx \&PD 498.Op Cm height 499.Ed 500.Pp 501The 502.Cm height 503argument is a 504.Xr roff 7 505scaling width. 506It defaults to 507.Cm 1v . 508If the unit is omitted, 509.Cm v 510is assumed. 511.Pp 512This macro affects the spacing before any subsequent instances of 513.Sx \&HP , 514.Sx \&IP , 515.Sx \&LP , 516.Sx \&P , 517.Sx \&PP , 518.Sx \&SH , 519.Sx \&SS , 520and 521.Sx \&TP . 522.Ss \&PP 523Synonym for 524.Sx \&LP . 525.Pp 526See also 527.Sx \&HP , 528.Sx \&IP , 529.Sx \&LP , 530.Sx \&P , 531and 532.Sx \&TP . 533.Ss \&R 534Text is rendered in roman (the default font). 535.Pp 536See also 537.Sx \&I 538and 539.Sx \&B . 540.Ss \&RB 541Text is rendered alternately in roman (the default font) and bold face. 542Whitespace between arguments is omitted in output. 543.Pp 544See 545.Sx \&BI 546for an equivalent example. 547.Pp 548See also 549.Sx \&BI , 550.Sx \&IB , 551.Sx \&BR , 552.Sx \&RI , 553and 554.Sx \&IR . 555.Ss \&RE 556Explicitly close out the scope of a prior 557.Sx \&RS . 558The default left margin is restored to the state of the original 559.Sx \&RS 560invocation. 561.Ss \&RI 562Text is rendered alternately in roman (the default font) and italics. 563Whitespace between arguments is omitted in output. 564.Pp 565See 566.Sx \&BI 567for an equivalent example. 568.Pp 569See also 570.Sx \&BI , 571.Sx \&IB , 572.Sx \&BR , 573.Sx \&RB , 574and 575.Sx \&IR . 576.Ss \&RS 577Temporarily reset the default left margin. 578This has the following syntax: 579.Bd -filled -offset indent 580.Pf \. Sx \&RS 581.Op Cm width 582.Ed 583.Pp 584The 585.Cm width 586argument is a 587.Xr roff 7 588scaling width. 589If not specified, the saved or default width is used. 590.Pp 591See also 592.Sx \&RE . 593.Ss \&SB 594Text is rendered in small size (one point smaller than the default font) 595bold face. 596.Ss \&SH 597Begin a section. 598The scope of a section is only closed by another section or the end of 599file. 600The paragraph left-margin width is reset to the default. 601.Ss \&SM 602Text is rendered in small size (one point smaller than the default 603font). 604.Ss \&SS 605Begin a sub-section. 606The scope of a sub-section is closed by a subsequent sub-section, 607section, or end of file. 608The paragraph left-margin width is reset to the default. 609.Ss \&TH 610Sets the title of the manual page for use in the page header 611and footer with the following syntax: 612.Bd -filled -offset indent 613.Pf \. Sx \&TH 614.Ar title section date 615.Op Ar source Op Ar volume 616.Ed 617.Pp 618Conventionally, the document 619.Ar title 620is given in all caps. 621The recommended 622.Ar date 623format is 624.Sy YYYY-MM-DD 625as specified in the ISO-8601 standard; 626if the argument does not conform, it is printed verbatim. 627If the 628.Ar date 629is empty or not specified, the current date is used. 630The optional 631.Ar source 632string specifies the organisation providing the utility. 633When unspecified, 634.Xr mandoc 1 635uses its 636.Fl Ios 637argument. 638The 639.Ar volume 640string replaces the default rendered volume, which is dictated by the 641manual section. 642.Pp 643Examples: 644.Pp 645.Dl \&.TH CVS 5 "1992-02-12" GNU 646.Ss \&TP 647Begin a paragraph where the head, if exceeding the indentation width, is 648followed by a newline; if not, the body follows on the same line after a 649buffer to the indentation width. 650Subsequent output lines are indented. 651The syntax is as follows: 652.Bd -filled -offset indent 653.Pf \. Sx \&TP 654.Op Cm width 655.Ed 656.Pp 657The 658.Cm width 659argument is a 660.Xr roff 7 661scaling width. 662If specified, it's saved for later paragraph left-margins; if 663unspecified, the saved or default width is used. 664.Pp 665See also 666.Sx \&HP , 667.Sx \&IP , 668.Sx \&LP , 669.Sx \&P , 670and 671.Sx \&PP . 672.Ss \&UC 673Sets the volume for the footer for compatibility with man pages from 674.Bx 675releases. 676The optional first argument specifies which release it is from. 677.Ss \&UE 678End a uniform resource identifier block. 679This is a non-standard GNU extension, included only for compatibility. 680See 681.Sx \&UE . 682.Ss \&UR 683Begin a uniform resource identifier block. 684This is a non-standard GNU extension, included only for compatibility. 685It has the following syntax: 686.Bd -literal -offset indent 687.Pf \. Sx \&UR Ar uri 688link description to be shown 689.Pf \. Sx UE 690.Ed 691.Ss \&br 692Breaks the current line. 693Consecutive invocations have no further effect. 694.Pp 695See also 696.Sx \&sp . 697.Ss \&fi 698End literal mode begun by 699.Sx \&nf . 700.Ss \&in 701Indent relative to the current indentation: 702.Pp 703.D1 Pf \. Sx \&in Op Cm width 704.Pp 705If 706.Cm width 707is signed, the new offset is relative. 708Otherwise, it is absolute. 709This value is reset upon the next paragraph, section, or sub-section. 710.Ss \&na 711Don't align to the right margin. 712.Ss \&nf 713Begin literal mode: all subsequent free-form lines have their end of 714line boundaries preserved. 715May be ended by 716.Sx \&fi . 717Literal mode is implicitly ended by 718.Sx \&SH 719or 720.Sx \&SS . 721.Ss \&sp 722Insert vertical spaces into output with the following syntax: 723.Bd -filled -offset indent 724.Pf \. Sx \&sp 725.Op Cm height 726.Ed 727.Pp 728The 729.Cm height 730argument is a scaling width as described in 731.Xr roff 7 . 732If 0, this is equivalent to the 733.Sx \&br 734macro. 735Defaults to 1, if unspecified. 736.Pp 737See also 738.Sx \&br . 739.Sh MACRO SYNTAX 740The 741.Nm 742macros are classified by scope: line scope or block scope. 743Line macros are only scoped to the current line (and, in some 744situations, the subsequent line). 745Block macros are scoped to the current line and subsequent lines until 746closed by another block macro. 747.Ss Line Macros 748Line macros are generally scoped to the current line, with the body 749consisting of zero or more arguments. 750If a macro is scoped to the next line and the line arguments are empty, 751the next line, which must be text, is used instead. 752Thus: 753.Bd -literal -offset indent 754\&.I 755foo 756.Ed 757.Pp 758is equivalent to 759.Sq \&.I foo . 760If next-line macros are invoked consecutively, only the last is used. 761If a next-line macro is followed by a non-next-line macro, an error is 762raised, except for 763.Sx \&br , 764.Sx \&sp , 765and 766.Sx \&na . 767.Pp 768The syntax is as follows: 769.Bd -literal -offset indent 770\&.YO \(lBbody...\(rB 771\(lBbody...\(rB 772.Ed 773.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 774.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 775.It Sx \&AT Ta <=1 Ta current Ta \& 776.It Sx \&B Ta n Ta next-line Ta \& 777.It Sx \&BI Ta n Ta current Ta \& 778.It Sx \&BR Ta n Ta current Ta \& 779.It Sx \&DT Ta 0 Ta current Ta \& 780.It Sx \&EE Ta 0 Ta current Ta compat 781.It Sx \&EX Ta 0 Ta current Ta compat 782.It Sx \&I Ta n Ta next-line Ta \& 783.It Sx \&IB Ta n Ta current Ta \& 784.It Sx \&IR Ta n Ta current Ta \& 785.It Sx \&OP Ta 0, 1 Ta current Ta compat 786.It Sx \&PD Ta 1 Ta current Ta \& 787.It Sx \&R Ta n Ta next-line Ta \& 788.It Sx \&RB Ta n Ta current Ta \& 789.It Sx \&RI Ta n Ta current Ta \& 790.It Sx \&SB Ta n Ta next-line Ta \& 791.It Sx \&SM Ta n Ta next-line Ta \& 792.It Sx \&TH Ta >1, <6 Ta current Ta \& 793.It Sx \&UC Ta <=1 Ta current Ta \& 794.It Sx \&br Ta 0 Ta current Ta compat 795.It Sx \&fi Ta 0 Ta current Ta compat 796.It Sx \&in Ta 1 Ta current Ta compat 797.It Sx \&na Ta 0 Ta current Ta compat 798.It Sx \&nf Ta 0 Ta current Ta compat 799.It Sx \&sp Ta 1 Ta current Ta compat 800.El 801.Pp 802Macros marked as 803.Qq compat 804are included for compatibility with the significant corpus of existing 805manuals that mix dialects of roff. 806These macros should not be used for portable 807.Nm 808manuals. 809.Ss Block Macros 810Block macros comprise a head and body. 811As with in-line macros, the head is scoped to the current line and, in 812one circumstance, the next line (the next-line stipulations as in 813.Sx Line Macros 814apply here as well). 815.Pp 816The syntax is as follows: 817.Bd -literal -offset indent 818\&.YO \(lBhead...\(rB 819\(lBhead...\(rB 820\(lBbody...\(rB 821.Ed 822.Pp 823The closure of body scope may be to the section, where a macro is closed 824by 825.Sx \&SH ; 826sub-section, closed by a section or 827.Sx \&SS ; 828part, closed by a section, sub-section, or 829.Sx \&RE ; 830or paragraph, closed by a section, sub-section, part, 831.Sx \&HP , 832.Sx \&IP , 833.Sx \&LP , 834.Sx \&P , 835.Sx \&PP , 836or 837.Sx \&TP . 838No closure refers to an explicit block closing macro. 839.Pp 840As a rule, block macros may not be nested; thus, calling a block macro 841while another block macro scope is open, and the open scope is not 842implicitly closed, is syntactically incorrect. 843.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 844.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 845.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 846.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 847.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 848.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 849.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 850.It Sx \&RE Ta 0 Ta current Ta none Ta compat 851.It Sx \&RS Ta 1 Ta current Ta part Ta compat 852.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 853.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 854.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 855.It Sx \&UE Ta 0 Ta current Ta none Ta compat 856.It Sx \&UR Ta 1 Ta current Ta part Ta compat 857.El 858.Pp 859Macros marked 860.Qq compat 861are as mentioned in 862.Sx Line Macros . 863.Pp 864If a block macro is next-line scoped, it may only be followed by in-line 865macros for decorating text. 866.Ss Font handling 867In 868.Nm 869documents, both 870.Sx Physical markup 871macros and 872.Xr roff 7 873.Ql \ef 874font escape sequences can be used to choose fonts. 875In text lines, the effect of manual font selection by escape sequences 876only lasts until the next macro invocation; in macro lines, it only lasts 877until the end of the macro scope. 878Note that macros like 879.Sx \&BR 880open and close a font scope for each argument. 881.Sh COMPATIBILITY 882This section mentions some areas of questionable portability between 883implementations of the 884.Nm 885language. 886More incompatibilities exist. 887.Pp 888.Bl -dash -compact 889.It 890Do not depend on 891.Sx \&SH 892or 893.Sx \&SS 894to close out a literal context opened with 895.Sx \&nf . 896This behaviour may not be portable. 897.It 898troff suppresses a newline before 899.Sq \(aq 900macro output; in mandoc, it is an alias for the standard 901.Sq \&. 902control character. 903.It 904In page header lines, GNU troff versions up to and including 1.21 905only print 906.Ar volume 907names explicitly specified in the 908.Sx \&TH 909macro; mandoc and newer groff print the default volume name 910corresponding to the 911.Ar section 912number when no 913.Ar volume 914is given, like in 915.Xr mdoc 7 . 916.El 917.Pp 918The 919.Sx EE , 920.Sx EX , 921.Sx OP , 922.Sx UE , 923and 924.Sx UR 925macros are part of the GNU extended 926.Nm 927macro set, and may not be portable to non-GNU troff implementations. 928.Sh SEE ALSO 929.Xr man 1 , 930.Xr mandoc 1 , 931.Xr eqn 7 , 932.Xr mandoc_char 7 , 933.Xr mdoc 7 , 934.Xr roff 7 , 935.Xr tbl 7 936.Sh HISTORY 937The 938.Nm 939language first appeared as a macro package for the roff typesetting 940system in 941.At v7 . 942It was later rewritten by James Clark as a macro package for groff. 943Eric S. Raymond wrote the extended 944.Nm 945macros for groff in 2007. 946The stand-alone implementation that is part of the 947.Xr mandoc 1 948utility written by Kristaps Dzonsons appeared in 949.Ox 4.6 . 950.Sh AUTHORS 951This 952.Nm 953reference was written by 954.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 955.Sh CAVEATS 956Do not use this language. 957Use 958.Xr mdoc 7 , 959instead. 960