1.\" $Id: man.7,v 1.127 2014/06/22 16:39:45 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: June 22 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 with the following syntax: 611.Bd -filled -offset indent 612.Pf \. Sx \&TH 613.Ar title section date 614.Op Ar source Op Ar volume 615.Ed 616.Pp 617Conventionally, the document 618.Ar title 619is given in all caps. 620The recommended 621.Ar date 622format is 623.Sy YYYY-MM-DD 624as specified in the ISO-8601 standard; 625if the argument does not conform, it is printed verbatim. 626If the 627.Ar date 628is empty or not specified, the current date is used. 629The optional 630.Ar source 631string specifies the organisation providing the utility. 632The 633.Ar volume 634string replaces the default rendered volume, which is dictated by the 635manual section. 636.Pp 637Examples: 638.Pp 639.Dl \&.TH CVS 5 "1992-02-12" GNU 640.Ss \&TP 641Begin a paragraph where the head, if exceeding the indentation width, is 642followed by a newline; if not, the body follows on the same line after a 643buffer to the indentation width. 644Subsequent output lines are indented. 645The syntax is as follows: 646.Bd -filled -offset indent 647.Pf \. Sx \&TP 648.Op Cm width 649.Ed 650.Pp 651The 652.Cm width 653argument is a 654.Xr roff 7 655scaling width. 656If specified, it's saved for later paragraph left-margins; if 657unspecified, the saved or default width is used. 658.Pp 659See also 660.Sx \&HP , 661.Sx \&IP , 662.Sx \&LP , 663.Sx \&P , 664and 665.Sx \&PP . 666.Ss \&UC 667Sets the volume for the footer for compatibility with man pages from 668.Bx 669releases. 670The optional first argument specifies which release it is from. 671.Ss \&UE 672End a uniform resource identifier block. 673This is a non-standard GNU extension, included only for compatibility. 674See 675.Sx \&UE . 676.Ss \&UR 677Begin a uniform resource identifier block. 678This is a non-standard GNU extension, included only for compatibility. 679It has the following syntax: 680.Bd -literal -offset indent 681.Pf \. Sx \&UR Ar uri 682link description to be shown 683.Pf \. Sx UE 684.Ed 685.Ss \&br 686Breaks the current line. 687Consecutive invocations have no further effect. 688.Pp 689See also 690.Sx \&sp . 691.Ss \&fi 692End literal mode begun by 693.Sx \&nf . 694.Ss \&in 695Indent relative to the current indentation: 696.Pp 697.D1 Pf \. Sx \&in Op Cm width 698.Pp 699If 700.Cm width 701is signed, the new offset is relative. 702Otherwise, it is absolute. 703This value is reset upon the next paragraph, section, or sub-section. 704.Ss \&na 705Don't align to the right margin. 706.Ss \&nf 707Begin literal mode: all subsequent free-form lines have their end of 708line boundaries preserved. 709May be ended by 710.Sx \&fi . 711Literal mode is implicitly ended by 712.Sx \&SH 713or 714.Sx \&SS . 715.Ss \&sp 716Insert vertical spaces into output with the following syntax: 717.Bd -filled -offset indent 718.Pf \. Sx \&sp 719.Op Cm height 720.Ed 721.Pp 722The 723.Cm height 724argument is a scaling width as described in 725.Xr roff 7 . 726If 0, this is equivalent to the 727.Sx \&br 728macro. 729Defaults to 1, if unspecified. 730.Pp 731See also 732.Sx \&br . 733.Sh MACRO SYNTAX 734The 735.Nm 736macros are classified by scope: line scope or block scope. 737Line macros are only scoped to the current line (and, in some 738situations, the subsequent line). 739Block macros are scoped to the current line and subsequent lines until 740closed by another block macro. 741.Ss Line Macros 742Line macros are generally scoped to the current line, with the body 743consisting of zero or more arguments. 744If a macro is scoped to the next line and the line arguments are empty, 745the next line, which must be text, is used instead. 746Thus: 747.Bd -literal -offset indent 748\&.I 749foo 750.Ed 751.Pp 752is equivalent to 753.Sq \&.I foo . 754If next-line macros are invoked consecutively, only the last is used. 755If a next-line macro is followed by a non-next-line macro, an error is 756raised, except for 757.Sx \&br , 758.Sx \&sp , 759and 760.Sx \&na . 761.Pp 762The syntax is as follows: 763.Bd -literal -offset indent 764\&.YO \(lBbody...\(rB 765\(lBbody...\(rB 766.Ed 767.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 768.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 769.It Sx \&AT Ta <=1 Ta current Ta \& 770.It Sx \&B Ta n Ta next-line Ta \& 771.It Sx \&BI Ta n Ta current Ta \& 772.It Sx \&BR Ta n Ta current Ta \& 773.It Sx \&DT Ta 0 Ta current Ta \& 774.It Sx \&EE Ta 0 Ta current Ta compat 775.It Sx \&EX Ta 0 Ta current Ta compat 776.It Sx \&I Ta n Ta next-line Ta \& 777.It Sx \&IB Ta n Ta current Ta \& 778.It Sx \&IR Ta n Ta current Ta \& 779.It Sx \&OP Ta 0, 1 Ta current Ta compat 780.It Sx \&PD Ta 1 Ta current Ta \& 781.It Sx \&R Ta n Ta next-line Ta \& 782.It Sx \&RB Ta n Ta current Ta \& 783.It Sx \&RI Ta n Ta current Ta \& 784.It Sx \&SB Ta n Ta next-line Ta \& 785.It Sx \&SM Ta n Ta next-line Ta \& 786.It Sx \&TH Ta >1, <6 Ta current Ta \& 787.It Sx \&UC Ta <=1 Ta current Ta \& 788.It Sx \&br Ta 0 Ta current Ta compat 789.It Sx \&fi Ta 0 Ta current Ta compat 790.It Sx \&in Ta 1 Ta current Ta compat 791.It Sx \&na Ta 0 Ta current Ta compat 792.It Sx \&nf Ta 0 Ta current Ta compat 793.It Sx \&sp Ta 1 Ta current Ta compat 794.El 795.Pp 796Macros marked as 797.Qq compat 798are included for compatibility with the significant corpus of existing 799manuals that mix dialects of roff. 800These macros should not be used for portable 801.Nm 802manuals. 803.Ss Block Macros 804Block macros comprise a head and body. 805As with in-line macros, the head is scoped to the current line and, in 806one circumstance, the next line (the next-line stipulations as in 807.Sx Line Macros 808apply here as well). 809.Pp 810The syntax is as follows: 811.Bd -literal -offset indent 812\&.YO \(lBhead...\(rB 813\(lBhead...\(rB 814\(lBbody...\(rB 815.Ed 816.Pp 817The closure of body scope may be to the section, where a macro is closed 818by 819.Sx \&SH ; 820sub-section, closed by a section or 821.Sx \&SS ; 822part, closed by a section, sub-section, or 823.Sx \&RE ; 824or paragraph, closed by a section, sub-section, part, 825.Sx \&HP , 826.Sx \&IP , 827.Sx \&LP , 828.Sx \&P , 829.Sx \&PP , 830or 831.Sx \&TP . 832No closure refers to an explicit block closing macro. 833.Pp 834As a rule, block macros may not be nested; thus, calling a block macro 835while another block macro scope is open, and the open scope is not 836implicitly closed, is syntactically incorrect. 837.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 838.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 839.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 840.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 841.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 842.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 843.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 844.It Sx \&RE Ta 0 Ta current Ta none Ta compat 845.It Sx \&RS Ta 1 Ta current Ta part Ta compat 846.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 847.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 848.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 849.It Sx \&UE Ta 0 Ta current Ta none Ta compat 850.It Sx \&UR Ta 1 Ta current Ta part Ta compat 851.El 852.Pp 853Macros marked 854.Qq compat 855are as mentioned in 856.Sx Line Macros . 857.Pp 858If a block macro is next-line scoped, it may only be followed by in-line 859macros for decorating text. 860.Ss Font handling 861In 862.Nm 863documents, both 864.Sx Physical markup 865macros and 866.Xr roff 7 867.Ql \ef 868font escape sequences can be used to choose fonts. 869In text lines, the effect of manual font selection by escape sequences 870only lasts until the next macro invocation; in macro lines, it only lasts 871until the end of the macro scope. 872Note that macros like 873.Sx \&BR 874open and close a font scope for each argument. 875.Sh COMPATIBILITY 876This section mentions some areas of questionable portability between 877implementations of the 878.Nm 879language. 880More incompatibilities exist. 881.Pp 882.Bl -dash -compact 883.It 884Do not depend on 885.Sx \&SH 886or 887.Sx \&SS 888to close out a literal context opened with 889.Sx \&nf . 890This behaviour may not be portable. 891.It 892troff suppresses a newline before 893.Sq \(aq 894macro output; in mandoc, it is an alias for the standard 895.Sq \&. 896control character. 897.It 898In page header lines, GNU troff versions up to and including 1.21 899only print 900.Ar volume 901names explicitly specified in the 902.Sx \&TH 903macro; mandoc and newer groff print the default volume name 904corresponding to the 905.Ar section 906number when no 907.Ar volume 908is given, like in 909.Xr mdoc 7 . 910.El 911.Pp 912The 913.Sx EE , 914.Sx EX , 915.Sx OP , 916.Sx UE , 917and 918.Sx UR 919macros are part of the GNU extended 920.Nm 921macro set, and may not be portable to non-GNU troff implementations. 922.Sh SEE ALSO 923.Xr man 1 , 924.Xr mandoc 1 , 925.Xr eqn 7 , 926.Xr mandoc_char 7 , 927.Xr mdoc 7 , 928.Xr roff 7 , 929.Xr tbl 7 930.Sh HISTORY 931The 932.Nm 933language first appeared as a macro package for the roff typesetting 934system in 935.At v7 . 936It was later rewritten by James Clark as a macro package for groff. 937Eric S. Raymond wrote the extended 938.Nm 939macros for groff in 2007. 940The stand-alone implementation that is part of the 941.Xr mandoc 1 942utility written by Kristaps Dzonsons appeared in 943.Ox 4.6 . 944.Sh AUTHORS 945This 946.Nm 947reference was written by 948.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 949.Sh CAVEATS 950Do not use this language. 951Use 952.Xr mdoc 7 , 953instead. 954