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