1.\" $OpenBSD: man.7,v 1.46 2017/05/05 15:54:28 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: May 5 2017 $ 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 fi , nf Ta fill mode and no-fill mode (no arguments) 270.It Sx in Ta additional indent: Op Ar width 271.El 272.Ss Physical markup 273.Bl -column "PP, LP, P" description 274.It Sx B Ta boldface font 275.It Sx I Ta italic font 276.It Sx R Ta roman (default) font 277.It Sx SB Ta small boldface font 278.It Sx SM Ta small roman font 279.It Sx BI Ta alternate between boldface and italic fonts 280.It Sx BR Ta alternate between boldface and roman fonts 281.It Sx IB Ta alternate between italic and boldface fonts 282.It Sx IR Ta alternate between italic and roman fonts 283.It Sx RB Ta alternate between roman and boldface fonts 284.It Sx RI Ta alternate between roman and italic fonts 285.El 286.Sh MACRO REFERENCE 287This section is a canonical reference to all macros, arranged 288alphabetically. 289For the scoping of individual macros, see 290.Sx MACRO SYNTAX . 291.Ss \&AT 292Sets the volume for the footer for compatibility with man pages from 293.At 294releases. 295The optional arguments specify which release it is from. 296.Ss \&B 297Text is rendered in bold face. 298.Pp 299See also 300.Sx \&I 301and 302.Sx \&R . 303.Ss \&BI 304Text is rendered alternately in bold face and italic. 305Thus, 306.Sq .BI this word and that 307causes 308.Sq this 309and 310.Sq and 311to render in bold face, while 312.Sq word 313and 314.Sq that 315render in italics. 316Whitespace between arguments is omitted in output. 317.Pp 318Examples: 319.Pp 320.Dl \&.BI bold italic bold italic 321.Pp 322The output of this example will be emboldened 323.Dq bold 324and italicised 325.Dq italic , 326with spaces stripped between arguments. 327.Pp 328See also 329.Sx \&IB , 330.Sx \&BR , 331.Sx \&RB , 332.Sx \&RI , 333and 334.Sx \&IR . 335.Ss \&BR 336Text is rendered alternately in bold face and roman (the default font). 337Whitespace between arguments is omitted in output. 338.Pp 339See 340.Sx \&BI 341for an equivalent example. 342.Pp 343See also 344.Sx \&BI , 345.Sx \&IB , 346.Sx \&RB , 347.Sx \&RI , 348and 349.Sx \&IR . 350.Ss \&DT 351Has no effect. 352Included for compatibility. 353.Ss \&EE 354This is a non-standard GNU extension, included only for compatibility. 355In 356.Xr mandoc 1 , 357it does the same as 358.Sx \&fi . 359.Ss \&EX 360This is a non-standard GNU extension, included only for compatibility. 361In 362.Xr mandoc 1 , 363it does the same as 364.Sx \&nf . 365.Ss \&HP 366Begin a paragraph whose initial output line is left-justified, but 367subsequent output lines are indented, with the following syntax: 368.Bd -filled -offset indent 369.Pf \. Sx \&HP 370.Op Ar width 371.Ed 372.Pp 373The 374.Ar width 375argument is a 376.Xr roff 7 377scaling width. 378If specified, it's saved for later paragraph left-margins; if unspecified, the 379saved or default width is used. 380.Pp 381See also 382.Sx \&IP , 383.Sx \&LP , 384.Sx \&P , 385.Sx \&PP , 386and 387.Sx \&TP . 388.Ss \&I 389Text is rendered in italics. 390.Pp 391See also 392.Sx \&B 393and 394.Sx \&R . 395.Ss \&IB 396Text is rendered alternately in italics and bold face. 397Whitespace between arguments is omitted in output. 398.Pp 399See 400.Sx \&BI 401for an equivalent example. 402.Pp 403See also 404.Sx \&BI , 405.Sx \&BR , 406.Sx \&RB , 407.Sx \&RI , 408and 409.Sx \&IR . 410.Ss \&IP 411Begin an indented paragraph with the following syntax: 412.Bd -filled -offset indent 413.Pf \. Sx \&IP 414.Op Ar head Op Ar width 415.Ed 416.Pp 417The 418.Ar width 419argument is a 420.Xr roff 7 421scaling width defining the left margin. 422It's saved for later paragraph left-margins; if unspecified, the saved or 423default width is used. 424.Pp 425The 426.Ar head 427argument is used as a leading term, flushed to the left margin. 428This is useful for bulleted paragraphs and so on. 429.Pp 430See also 431.Sx \&HP , 432.Sx \&LP , 433.Sx \&P , 434.Sx \&PP , 435and 436.Sx \&TP . 437.Ss \&IR 438Text is rendered alternately in italics and roman (the default font). 439Whitespace between arguments is omitted in output. 440.Pp 441See 442.Sx \&BI 443for an equivalent example. 444.Pp 445See also 446.Sx \&BI , 447.Sx \&IB , 448.Sx \&BR , 449.Sx \&RB , 450and 451.Sx \&RI . 452.Ss \&LP 453Begin an undecorated paragraph. 454The scope of a paragraph is closed by a subsequent paragraph, 455sub-section, section, or end of file. 456The saved paragraph left-margin width is reset to the default. 457.Pp 458See also 459.Sx \&HP , 460.Sx \&IP , 461.Sx \&P , 462.Sx \&PP , 463and 464.Sx \&TP . 465.Ss \&OP 466Optional command-line argument. 467This is a non-standard GNU extension, included only for compatibility. 468It has the following syntax: 469.Bd -filled -offset indent 470.Pf \. Sx \&OP 471.Ar key Op Ar value 472.Ed 473.Pp 474The 475.Ar key 476is usually a command-line flag and 477.Ar value 478its argument. 479.Ss \&P 480Synonym for 481.Sx \&LP . 482.Pp 483See also 484.Sx \&HP , 485.Sx \&IP , 486.Sx \&LP , 487.Sx \&PP , 488and 489.Sx \&TP . 490.Ss \&PD 491Specify the vertical space to be inserted before each new paragraph. 492.br 493The syntax is as follows: 494.Bd -filled -offset indent 495.Pf \. Sx \&PD 496.Op Ar height 497.Ed 498.Pp 499The 500.Ar height 501argument is a 502.Xr roff 7 503scaling width. 504It defaults to 505.Cm 1v . 506If the unit is omitted, 507.Cm v 508is assumed. 509.Pp 510This macro affects the spacing before any subsequent instances of 511.Sx \&HP , 512.Sx \&IP , 513.Sx \&LP , 514.Sx \&P , 515.Sx \&PP , 516.Sx \&SH , 517.Sx \&SS , 518and 519.Sx \&TP . 520.Ss \&PP 521Synonym for 522.Sx \&LP . 523.Pp 524See also 525.Sx \&HP , 526.Sx \&IP , 527.Sx \&LP , 528.Sx \&P , 529and 530.Sx \&TP . 531.Ss \&R 532Text is rendered in roman (the default font). 533.Pp 534See also 535.Sx \&I 536and 537.Sx \&B . 538.Ss \&RB 539Text is rendered alternately in roman (the default font) and bold face. 540Whitespace between arguments is omitted in output. 541.Pp 542See 543.Sx \&BI 544for an equivalent example. 545.Pp 546See also 547.Sx \&BI , 548.Sx \&IB , 549.Sx \&BR , 550.Sx \&RI , 551and 552.Sx \&IR . 553.Ss \&RE 554Explicitly close out the scope of a prior 555.Sx \&RS . 556The default left margin is restored to the state before that 557.Sx \&RS 558invocation. 559.Pp 560The syntax is as follows: 561.Bd -filled -offset indent 562.Pf \. Sx \&RE 563.Op Ar level 564.Ed 565.Pp 566Without an argument, the most recent 567.Sx \&RS 568block is closed out. 569If 570.Ar level 571is 1, all open 572.Sx \&RS 573blocks are closed out. 574Otherwise, 575.Ar level No \(mi 1 576nested 577.Sx \&RS 578blocks remain open. 579.Ss \&RI 580Text is rendered alternately in roman (the default font) and italics. 581Whitespace between arguments is omitted in output. 582.Pp 583See 584.Sx \&BI 585for an equivalent example. 586.Pp 587See also 588.Sx \&BI , 589.Sx \&IB , 590.Sx \&BR , 591.Sx \&RB , 592and 593.Sx \&IR . 594.Ss \&RS 595Temporarily reset the default left margin. 596This has the following syntax: 597.Bd -filled -offset indent 598.Pf \. Sx \&RS 599.Op Ar width 600.Ed 601.Pp 602The 603.Ar width 604argument is a 605.Xr roff 7 606scaling width. 607If not specified, the saved or default width is used. 608.Pp 609See also 610.Sx \&RE . 611.Ss \&SB 612Text is rendered in small size (one point smaller than the default font) 613bold face. 614.Ss \&SH 615Begin a section. 616The scope of a section is only closed by another section or the end of 617file. 618The paragraph left-margin width is reset to the default. 619.Ss \&SM 620Text is rendered in small size (one point smaller than the default 621font). 622.Ss \&SS 623Begin a sub-section. 624The scope of a sub-section is closed by a subsequent sub-section, 625section, or end of file. 626The paragraph left-margin width is reset to the default. 627.Ss \&TH 628Sets the title of the manual page for use in the page header 629and footer with the following syntax: 630.Bd -filled -offset indent 631.Pf \. Sx \&TH 632.Ar title section date 633.Op Ar source Op Ar volume 634.Ed 635.Pp 636Conventionally, the document 637.Ar title 638is given in all caps. 639The recommended 640.Ar date 641format is 642.Sy YYYY-MM-DD 643as specified in the ISO-8601 standard; 644if the argument does not conform, it is printed verbatim. 645If the 646.Ar date 647is empty or not specified, the current date is used. 648The optional 649.Ar source 650string specifies the organisation providing the utility. 651When unspecified, 652.Xr mandoc 1 653uses its 654.Fl Ios 655argument. 656The 657.Ar volume 658string replaces the default rendered volume, which is dictated by the 659manual section. 660.Pp 661Examples: 662.Pp 663.Dl \&.TH CVS 5 "1992-02-12" GNU 664.Ss \&TP 665Begin a paragraph where the head, if exceeding the indentation width, is 666followed by a newline; if not, the body follows on the same line after a 667buffer to the indentation width. 668Subsequent output lines are indented. 669The syntax is as follows: 670.Bd -filled -offset indent 671.Pf \. Sx \&TP 672.Op Ar width 673.Ed 674.Pp 675The 676.Ar width 677argument is a 678.Xr roff 7 679scaling width. 680If specified, it's saved for later paragraph left-margins; if 681unspecified, the saved or default width is used. 682.Pp 683See also 684.Sx \&HP , 685.Sx \&IP , 686.Sx \&LP , 687.Sx \&P , 688and 689.Sx \&PP . 690.Ss \&UC 691Sets the volume for the footer for compatibility with man pages from 692.Bx 693releases. 694The optional first argument specifies which release it is from. 695.Ss \&UE 696End a uniform resource identifier block. 697This is a non-standard GNU extension, included only for compatibility. 698See 699.Sx \&UE . 700.Ss \&UR 701Begin a uniform resource identifier block. 702This is a non-standard GNU extension, included only for compatibility. 703It has the following syntax: 704.Bd -literal -offset indent 705.Pf \. Sx \&UR Ar uri 706link description to be shown 707.Pf \. Sx UE 708.Ed 709.Ss \&fi 710End literal mode begun by 711.Sx \&nf . 712.Ss \&in 713Indent relative to the current indentation: 714.Pp 715.D1 Pf \. Sx \&in Op Ar width 716.Pp 717If 718.Ar width 719is signed, the new offset is relative. 720Otherwise, it is absolute. 721This value is reset upon the next paragraph, section, or sub-section. 722.Ss \&nf 723Begin literal mode: all subsequent free-form lines have their end of 724line boundaries preserved. 725May be ended by 726.Sx \&fi . 727Literal mode is implicitly ended by 728.Sx \&SH 729or 730.Sx \&SS . 731.Sh MACRO SYNTAX 732The 733.Nm 734macros are classified by scope: line scope or block scope. 735Line macros are only scoped to the current line (and, in some 736situations, the subsequent line). 737Block macros are scoped to the current line and subsequent lines until 738closed by another block macro. 739.Ss Line Macros 740Line macros are generally scoped to the current line, with the body 741consisting of zero or more arguments. 742If a macro is scoped to the next line and the line arguments are empty, 743the next line, which must be text, is used instead. 744Thus: 745.Bd -literal -offset indent 746\&.I 747foo 748.Ed 749.Pp 750is equivalent to 751.Sq \&.I foo . 752If next-line macros are invoked consecutively, only the last is used. 753If a next-line macro is followed by a non-next-line macro, an error is 754raised. 755.Pp 756The syntax is as follows: 757.Bd -literal -offset indent 758\&.YO \(lBbody...\(rB 759\(lBbody...\(rB 760.Ed 761.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 762.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 763.It Sx \&AT Ta <=1 Ta current Ta \& 764.It Sx \&B Ta n Ta next-line Ta \& 765.It Sx \&BI Ta n Ta current Ta \& 766.It Sx \&BR Ta n Ta current Ta \& 767.It Sx \&DT Ta 0 Ta current Ta \& 768.It Sx \&EE Ta 0 Ta current Ta compat 769.It Sx \&EX Ta 0 Ta current Ta compat 770.It Sx \&I Ta n Ta next-line Ta \& 771.It Sx \&IB Ta n Ta current Ta \& 772.It Sx \&IR Ta n Ta current Ta \& 773.It Sx \&OP Ta 0, 1 Ta current Ta compat 774.It Sx \&PD Ta 1 Ta current Ta \& 775.It Sx \&R Ta n Ta next-line Ta \& 776.It Sx \&RB Ta n Ta current Ta \& 777.It Sx \&RI Ta n Ta current Ta \& 778.It Sx \&SB Ta n Ta next-line Ta \& 779.It Sx \&SM Ta n Ta next-line Ta \& 780.It Sx \&TH Ta >1, <6 Ta current Ta \& 781.It Sx \&UC Ta <=1 Ta current Ta \& 782.It Sx \&fi Ta 0 Ta current Ta compat 783.It Sx \&in Ta 1 Ta current Ta compat 784.It Sx \&nf Ta 0 Ta current Ta compat 785.El 786.Pp 787Macros marked as 788.Qq compat 789are included for compatibility with the significant corpus of existing 790manuals that mix dialects of roff. 791These macros should not be used for portable 792.Nm 793manuals. 794.Ss Block Macros 795Block macros comprise a head and body. 796As with in-line macros, the head is scoped to the current line and, in 797one circumstance, the next line (the next-line stipulations as in 798.Sx Line Macros 799apply here as well). 800.Pp 801The syntax is as follows: 802.Bd -literal -offset indent 803\&.YO \(lBhead...\(rB 804\(lBhead...\(rB 805\(lBbody...\(rB 806.Ed 807.Pp 808The closure of body scope may be to the section, where a macro is closed 809by 810.Sx \&SH ; 811sub-section, closed by a section or 812.Sx \&SS ; 813part, closed by a section, sub-section, or 814.Sx \&RE ; 815or paragraph, closed by a section, sub-section, part, 816.Sx \&HP , 817.Sx \&IP , 818.Sx \&LP , 819.Sx \&P , 820.Sx \&PP , 821or 822.Sx \&TP . 823No closure refers to an explicit block closing macro. 824.Pp 825As a rule, block macros may not be nested; thus, calling a block macro 826while another block macro scope is open, and the open scope is not 827implicitly closed, is syntactically incorrect. 828.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 829.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 830.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 831.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 832.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 833.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 834.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 835.It Sx \&RE Ta 0 Ta current Ta none Ta compat 836.It Sx \&RS Ta 1 Ta current Ta part Ta compat 837.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 838.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 839.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 840.It Sx \&UE Ta 0 Ta current Ta none Ta compat 841.It Sx \&UR Ta 1 Ta current Ta part Ta compat 842.El 843.Pp 844Macros marked 845.Qq compat 846are as mentioned in 847.Sx Line Macros . 848.Pp 849If a block macro is next-line scoped, it may only be followed by in-line 850macros for decorating text. 851.Ss Font handling 852In 853.Nm 854documents, both 855.Sx Physical markup 856macros and 857.Xr roff 7 858.Ql \ef 859font escape sequences can be used to choose fonts. 860In text lines, the effect of manual font selection by escape sequences 861only lasts until the next macro invocation; in macro lines, it only lasts 862until the end of the macro scope. 863Note that macros like 864.Sx \&BR 865open and close a font scope for each argument. 866.Sh SEE ALSO 867.Xr man 1 , 868.Xr mandoc 1 , 869.Xr eqn 7 , 870.Xr mandoc_char 7 , 871.Xr mdoc 7 , 872.Xr roff 7 , 873.Xr tbl 7 874.Sh HISTORY 875The 876.Nm 877language first appeared as a macro package for the roff typesetting 878system in 879.At v7 . 880It was later rewritten by James Clark as a macro package for groff. 881Eric S. Raymond wrote the extended 882.Nm 883macros for groff in 2007. 884The stand-alone implementation that is part of the 885.Xr mandoc 1 886utility written by Kristaps Dzonsons appeared in 887.Ox 4.6 . 888.Sh AUTHORS 889This 890.Nm 891reference was written by 892.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 893.Sh CAVEATS 894Do not use this language. 895Use 896.Xr mdoc 7 , 897instead. 898