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