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