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