1.\" $OpenBSD: man.7,v 1.44 2015/01/29 00:33:14 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011-2015 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: January 29 2015 $ 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 Ar width 373.Ed 374.Pp 375The 376.Ar 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 Ar head Op Ar width 417.Ed 418.Pp 419The 420.Ar 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.Ar 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.Ar key Op Ar value 474.Ed 475.Pp 476The 477.Ar key 478is usually a command-line flag and 479.Ar 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 Ar height 499.Ed 500.Pp 501The 502.Ar 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 before that 559.Sx \&RS 560invocation. 561.Pp 562The syntax is as follows: 563.Bd -filled -offset indent 564.Pf \. Sx \&RE 565.Op Ar level 566.Ed 567.Pp 568Without an argument, the most recent 569.Sx \&RS 570block is closed out. 571If 572.Ar level 573is 1, all open 574.Sx \&RS 575blocks are closed out. 576Otherwise, 577.Ar level No \(mi 1 578nested 579.Sx \&RS 580blocks remain open. 581.Ss \&RI 582Text is rendered alternately in roman (the default font) and italics. 583Whitespace between arguments is omitted in output. 584.Pp 585See 586.Sx \&BI 587for an equivalent example. 588.Pp 589See also 590.Sx \&BI , 591.Sx \&IB , 592.Sx \&BR , 593.Sx \&RB , 594and 595.Sx \&IR . 596.Ss \&RS 597Temporarily reset the default left margin. 598This has the following syntax: 599.Bd -filled -offset indent 600.Pf \. Sx \&RS 601.Op Ar width 602.Ed 603.Pp 604The 605.Ar width 606argument is a 607.Xr roff 7 608scaling width. 609If not specified, the saved or default width is used. 610.Pp 611See also 612.Sx \&RE . 613.Ss \&SB 614Text is rendered in small size (one point smaller than the default font) 615bold face. 616.Ss \&SH 617Begin a section. 618The scope of a section is only closed by another section or the end of 619file. 620The paragraph left-margin width is reset to the default. 621.Ss \&SM 622Text is rendered in small size (one point smaller than the default 623font). 624.Ss \&SS 625Begin a sub-section. 626The scope of a sub-section is closed by a subsequent sub-section, 627section, or end of file. 628The paragraph left-margin width is reset to the default. 629.Ss \&TH 630Sets the title of the manual page for use in the page header 631and footer with the following syntax: 632.Bd -filled -offset indent 633.Pf \. Sx \&TH 634.Ar title section date 635.Op Ar source Op Ar volume 636.Ed 637.Pp 638Conventionally, the document 639.Ar title 640is given in all caps. 641The recommended 642.Ar date 643format is 644.Sy YYYY-MM-DD 645as specified in the ISO-8601 standard; 646if the argument does not conform, it is printed verbatim. 647If the 648.Ar date 649is empty or not specified, the current date is used. 650The optional 651.Ar source 652string specifies the organisation providing the utility. 653When unspecified, 654.Xr mandoc 1 655uses its 656.Fl Ios 657argument. 658The 659.Ar volume 660string replaces the default rendered volume, which is dictated by the 661manual section. 662.Pp 663Examples: 664.Pp 665.Dl \&.TH CVS 5 "1992-02-12" GNU 666.Ss \&TP 667Begin a paragraph where the head, if exceeding the indentation width, is 668followed by a newline; if not, the body follows on the same line after a 669buffer to the indentation width. 670Subsequent output lines are indented. 671The syntax is as follows: 672.Bd -filled -offset indent 673.Pf \. Sx \&TP 674.Op Ar width 675.Ed 676.Pp 677The 678.Ar width 679argument is a 680.Xr roff 7 681scaling width. 682If specified, it's saved for later paragraph left-margins; if 683unspecified, the saved or default width is used. 684.Pp 685See also 686.Sx \&HP , 687.Sx \&IP , 688.Sx \&LP , 689.Sx \&P , 690and 691.Sx \&PP . 692.Ss \&UC 693Sets the volume for the footer for compatibility with man pages from 694.Bx 695releases. 696The optional first argument specifies which release it is from. 697.Ss \&UE 698End a uniform resource identifier block. 699This is a non-standard GNU extension, included only for compatibility. 700See 701.Sx \&UE . 702.Ss \&UR 703Begin a uniform resource identifier block. 704This is a non-standard GNU extension, included only for compatibility. 705It has the following syntax: 706.Bd -literal -offset indent 707.Pf \. Sx \&UR Ar uri 708link description to be shown 709.Pf \. Sx UE 710.Ed 711.Ss \&br 712Breaks the current line. 713Consecutive invocations have no further effect. 714.Pp 715See also 716.Sx \&sp . 717.Ss \&fi 718End literal mode begun by 719.Sx \&nf . 720.Ss \&in 721Indent relative to the current indentation: 722.Pp 723.D1 Pf \. Sx \&in Op Ar width 724.Pp 725If 726.Ar width 727is signed, the new offset is relative. 728Otherwise, it is absolute. 729This value is reset upon the next paragraph, section, or sub-section. 730.Ss \&nf 731Begin literal mode: all subsequent free-form lines have their end of 732line boundaries preserved. 733May be ended by 734.Sx \&fi . 735Literal mode is implicitly ended by 736.Sx \&SH 737or 738.Sx \&SS . 739.Ss \&sp 740Insert vertical spaces into output with the following syntax: 741.Bd -filled -offset indent 742.Pf \. Sx \&sp 743.Op Ar height 744.Ed 745.Pp 746The 747.Ar height 748argument is a scaling width as described in 749.Xr roff 7 . 750If 0, this is equivalent to the 751.Sx \&br 752macro. 753Defaults to 1, if unspecified. 754.Pp 755See also 756.Sx \&br . 757.Sh MACRO SYNTAX 758The 759.Nm 760macros are classified by scope: line scope or block scope. 761Line macros are only scoped to the current line (and, in some 762situations, the subsequent line). 763Block macros are scoped to the current line and subsequent lines until 764closed by another block macro. 765.Ss Line Macros 766Line macros are generally scoped to the current line, with the body 767consisting of zero or more arguments. 768If a macro is scoped to the next line and the line arguments are empty, 769the next line, which must be text, is used instead. 770Thus: 771.Bd -literal -offset indent 772\&.I 773foo 774.Ed 775.Pp 776is equivalent to 777.Sq \&.I foo . 778If next-line macros are invoked consecutively, only the last is used. 779If a next-line macro is followed by a non-next-line macro, an error is 780raised, except for 781.Sx \&br 782and 783.Sx \&sp . 784.Pp 785The syntax is as follows: 786.Bd -literal -offset indent 787\&.YO \(lBbody...\(rB 788\(lBbody...\(rB 789.Ed 790.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 791.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 792.It Sx \&AT Ta <=1 Ta current Ta \& 793.It Sx \&B Ta n Ta next-line Ta \& 794.It Sx \&BI Ta n Ta current Ta \& 795.It Sx \&BR Ta n Ta current Ta \& 796.It Sx \&DT Ta 0 Ta current Ta \& 797.It Sx \&EE Ta 0 Ta current Ta compat 798.It Sx \&EX Ta 0 Ta current Ta compat 799.It Sx \&I Ta n Ta next-line Ta \& 800.It Sx \&IB Ta n Ta current Ta \& 801.It Sx \&IR Ta n Ta current Ta \& 802.It Sx \&OP Ta 0, 1 Ta current Ta compat 803.It Sx \&PD Ta 1 Ta current Ta \& 804.It Sx \&R Ta n Ta next-line Ta \& 805.It Sx \&RB Ta n Ta current Ta \& 806.It Sx \&RI Ta n Ta current Ta \& 807.It Sx \&SB Ta n Ta next-line Ta \& 808.It Sx \&SM Ta n Ta next-line Ta \& 809.It Sx \&TH Ta >1, <6 Ta current Ta \& 810.It Sx \&UC Ta <=1 Ta current Ta \& 811.It Sx \&br Ta 0 Ta current Ta compat 812.It Sx \&fi Ta 0 Ta current Ta compat 813.It Sx \&in Ta 1 Ta current Ta compat 814.It Sx \&nf Ta 0 Ta current Ta compat 815.It Sx \&sp Ta 1 Ta current Ta compat 816.El 817.Pp 818Macros marked as 819.Qq compat 820are included for compatibility with the significant corpus of existing 821manuals that mix dialects of roff. 822These macros should not be used for portable 823.Nm 824manuals. 825.Ss Block Macros 826Block macros comprise a head and body. 827As with in-line macros, the head is scoped to the current line and, in 828one circumstance, the next line (the next-line stipulations as in 829.Sx Line Macros 830apply here as well). 831.Pp 832The syntax is as follows: 833.Bd -literal -offset indent 834\&.YO \(lBhead...\(rB 835\(lBhead...\(rB 836\(lBbody...\(rB 837.Ed 838.Pp 839The closure of body scope may be to the section, where a macro is closed 840by 841.Sx \&SH ; 842sub-section, closed by a section or 843.Sx \&SS ; 844part, closed by a section, sub-section, or 845.Sx \&RE ; 846or paragraph, closed by a section, sub-section, part, 847.Sx \&HP , 848.Sx \&IP , 849.Sx \&LP , 850.Sx \&P , 851.Sx \&PP , 852or 853.Sx \&TP . 854No closure refers to an explicit block closing macro. 855.Pp 856As a rule, block macros may not be nested; thus, calling a block macro 857while another block macro scope is open, and the open scope is not 858implicitly closed, is syntactically incorrect. 859.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 860.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 861.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 862.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 863.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 864.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 865.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 866.It Sx \&RE Ta 0 Ta current Ta none Ta compat 867.It Sx \&RS Ta 1 Ta current Ta part Ta compat 868.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 869.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 870.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 871.It Sx \&UE Ta 0 Ta current Ta none Ta compat 872.It Sx \&UR Ta 1 Ta current Ta part Ta compat 873.El 874.Pp 875Macros marked 876.Qq compat 877are as mentioned in 878.Sx Line Macros . 879.Pp 880If a block macro is next-line scoped, it may only be followed by in-line 881macros for decorating text. 882.Ss Font handling 883In 884.Nm 885documents, both 886.Sx Physical markup 887macros and 888.Xr roff 7 889.Ql \ef 890font escape sequences can be used to choose fonts. 891In text lines, the effect of manual font selection by escape sequences 892only lasts until the next macro invocation; in macro lines, it only lasts 893until the end of the macro scope. 894Note that macros like 895.Sx \&BR 896open and close a font scope for each argument. 897.Sh SEE ALSO 898.Xr man 1 , 899.Xr mandoc 1 , 900.Xr eqn 7 , 901.Xr mandoc_char 7 , 902.Xr mdoc 7 , 903.Xr roff 7 , 904.Xr tbl 7 905.Sh HISTORY 906The 907.Nm 908language first appeared as a macro package for the roff typesetting 909system in 910.At v7 . 911It was later rewritten by James Clark as a macro package for groff. 912Eric S. Raymond wrote the extended 913.Nm 914macros for groff in 2007. 915The stand-alone implementation that is part of the 916.Xr mandoc 1 917utility written by Kristaps Dzonsons appeared in 918.Ox 4.6 . 919.Sh AUTHORS 920This 921.Nm 922reference was written by 923.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 924.Sh CAVEATS 925Do not use this language. 926Use 927.Xr mdoc 7 , 928instead. 929