1.\" $OpenBSD: man.7,v 1.34 2013/12/31 15:15:47 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: December 31 2013 $ 19.Dt MAN 7 20.Os 21.Sh NAME 22.Nm man 23.Nd legacy formatting language for manual pages 24.Sh DESCRIPTION 25Traditionally, the 26.Nm man 27language has been used to write 28.Ux 29manuals for the 30.Xr man 1 31utility. 32It supports limited control of presentational details like fonts, 33indentation and spacing. 34This reference document describes the structure of manual pages 35and the syntax and usage of the man language. 36.Pp 37.Bf -emphasis 38Do not use 39.Nm 40to write your manuals: 41.Ef 42It lacks support for semantic markup. 43Use the 44.Xr mdoc 7 45language, instead. 46.Pp 47In a 48.Nm 49document, lines beginning with the control character 50.Sq \&. 51are called 52.Dq macro lines . 53The first word is the macro name. 54It usually consists of two capital letters. 55For a list of available macros, see 56.Sx MACRO OVERVIEW . 57The words following the macro name are arguments to the macro. 58.Pp 59Lines not beginning with the control character are called 60.Dq text lines . 61They provide free-form text to be printed; the formatting of the text 62depends on the respective processing context: 63.Bd -literal -offset indent 64\&.SH Macro lines change control state. 65Text lines are interpreted within the current state. 66.Ed 67.Pp 68Many aspects of the basic syntax of the 69.Nm 70language are based on the 71.Xr roff 7 72language; see the 73.Em LANGUAGE SYNTAX 74and 75.Em MACRO SYNTAX 76sections in the 77.Xr roff 7 78manual for details, in particular regarding 79comments, escape sequences, whitespace, and quoting. 80.Sh MANUAL STRUCTURE 81Each 82.Nm 83document must contain the 84.Sx \&TH 85macro describing the document's section and title. 86It may occur anywhere in the document, although conventionally it 87appears as the first macro. 88.Pp 89Beyond 90.Sx \&TH , 91at least one macro or text line must appear in the document. 92.Pp 93The following is a well-formed skeleton 94.Nm 95file for a utility 96.Qq progname : 97.Bd -literal -offset indent 98\&.TH PROGNAME 1 2009-10-10 99\&.SH NAME 100\efBprogname\efR \e(en a description goes here 101\&.\e\(dq .SH LIBRARY 102\&.\e\(dq For sections 2 & 3 only. 103\&.\e\(dq Not used in OpenBSD. 104\&.SH SYNOPSIS 105\efBprogname\efR [\efB\e-options\efR] arguments... 106\&.SH DESCRIPTION 107The \efBfoo\efR utility processes files... 108\&.\e\(dq .SH IMPLEMENTATION NOTES 109\&.\e\(dq Not used in OpenBSD. 110\&.\e\(dq .SH RETURN VALUES 111\&.\e\(dq For sections 2, 3, & 9 only. 112\&.\e\(dq .SH ENVIRONMENT 113\&.\e\(dq For sections 1, 6, 7, & 8 only. 114\&.\e\(dq .SH FILES 115\&.\e\(dq .SH EXIT STATUS 116\&.\e\(dq For sections 1, 6, & 8 only. 117\&.\e\(dq .SH EXAMPLES 118\&.\e\(dq .SH DIAGNOSTICS 119\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. 120\&.\e\(dq .SH ERRORS 121\&.\e\(dq For sections 2, 3, & 9 only. 122\&.\e\(dq .SH SEE ALSO 123\&.\e\(dq .BR foo ( 1 ) 124\&.\e\(dq .SH STANDARDS 125\&.\e\(dq .SH HISTORY 126\&.\e\(dq .SH AUTHORS 127\&.\e\(dq .SH CAVEATS 128\&.\e\(dq .SH BUGS 129\&.\e\(dq .SH SECURITY CONSIDERATIONS 130\&.\e\(dq Not used in OpenBSD. 131.Ed 132.Pp 133The sections in a 134.Nm 135document are conventionally ordered as they appear above. 136Sections should be composed as follows: 137.Bl -ohang -offset indent 138.It Em NAME 139The name(s) and a short description of the documented material. 140The syntax for this is generally as follows: 141.Pp 142.D1 \efBname\efR \e(en description 143.It Em LIBRARY 144The name of the library containing the documented material, which is 145assumed to be a function in a section 2 or 3 manual. 146For functions in the C library, this may be as follows: 147.Pp 148.D1 Standard C Library (libc, -lc) 149.It Em SYNOPSIS 150Documents the utility invocation syntax, function call syntax, or device 151configuration. 152.Pp 153For the first, utilities (sections 1, 6, and 8), this is 154generally structured as follows: 155.Pp 156.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... 157.Pp 158For the second, function calls (sections 2, 3, 9): 159.Pp 160.D1 \&.B char *name(char *\efIarg\efR); 161.Pp 162And for the third, configurations (section 4): 163.Pp 164.D1 \&.B name* at cardbus ? function ? 165.Pp 166Manuals not in these sections generally don't need a 167.Em SYNOPSIS . 168.It Em DESCRIPTION 169This expands upon the brief, one-line description in 170.Em NAME . 171It usually contains a break-down of the options (if documenting a 172command). 173.It Em IMPLEMENTATION NOTES 174Implementation-specific notes should be kept here. 175This is useful when implementing standard functions that may have side 176effects or notable algorithmic implications. 177.It Em RETURN VALUES 178This section documents the return values of functions in sections 2, 3, and 9. 179.It Em ENVIRONMENT 180Documents any usages of environment variables, e.g., 181.Xr environ 7 . 182.It Em FILES 183Documents files used. 184It's helpful to document both the file name and a short description of how 185the file is used (created, modified, etc.). 186.It Em EXIT STATUS 187This section documents the command exit status for 188section 1, 6, and 8 utilities. 189Historically, this information was described in 190.Em DIAGNOSTICS , 191a practise that is now discouraged. 192.It Em EXAMPLES 193Example usages. 194This often contains snippets of well-formed, 195well-tested invocations. 196Make sure that examples work properly! 197.It Em DIAGNOSTICS 198Documents error conditions. 199This is most useful in section 4 manuals. 200Historically, this section was used in place of 201.Em EXIT STATUS 202for manuals in sections 1, 6, and 8; however, this practise is 203discouraged. 204.It Em ERRORS 205Documents error handling in sections 2, 3, and 9. 206.It Em SEE ALSO 207References other manuals with related topics. 208This section should exist for most manuals. 209.Pp 210.D1 \&.BR bar \&( 1 \&), 211.Pp 212Cross-references should conventionally be ordered 213first by section, then alphabetically. 214.It Em STANDARDS 215References any standards implemented or used, such as 216.Pp 217.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) 218.Pp 219If not adhering to any standards, the 220.Em HISTORY 221section should be used. 222.It Em HISTORY 223A brief history of the subject, including where support first appeared. 224.It Em AUTHORS 225Credits to the person or persons who wrote the code and/or documentation. 226Authors should generally be noted by both name and email address. 227.It Em CAVEATS 228Common misuses and misunderstandings should be explained 229in this section. 230.It Em BUGS 231Known bugs, limitations, and work-arounds should be described 232in this section. 233.It Em SECURITY CONSIDERATIONS 234Documents any security precautions that operators should consider. 235.El 236.Sh MACRO OVERVIEW 237This overview is sorted such that macros of similar purpose are listed 238together, to help find the best macro for any given purpose. 239Deprecated macros are not included in the overview, but can be found 240in the alphabetical reference below. 241.Ss Page header and footer meta-data 242.Bl -column "PP, LP, P" description 243.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume 244.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument) 245.It Sx UC Ta display BSD version in the page footer (<= 1 argument) 246.El 247.Ss Sections and paragraphs 248.Bl -column "PP, LP, P" description 249.It Sx SH Ta section header (one line) 250.It Sx SS Ta subsection header (one line) 251.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments) 252.It Sx RS , RE Ta reset the left margin: Op Ar width 253.It Sx IP Ta indented paragraph: Op Ar head Op Ar width 254.It Sx TP Ta tagged paragraph: Op Ar width 255.It Sx HP Ta hanged paragraph: Op Ar width 256.It Sx PD Ta set vertical paragraph distance: Op Ar height 257.It Sx \&br Ta force output line break in text mode (no arguments) 258.It Sx \&sp Ta force vertical space: Op Ar height 259.It Sx fi , nf Ta fill mode and no-fill mode (no arguments) 260.It Sx in Ta additional indent: Op Ar width 261.El 262.Ss Physical markup 263.Bl -column "PP, LP, P" description 264.It Sx B Ta boldface font 265.It Sx I Ta italic font 266.It Sx R Ta roman (default) font 267.It Sx SB Ta small boldface font 268.It Sx SM Ta small roman font 269.It Sx BI Ta alternate between boldface and italic fonts 270.It Sx BR Ta alternate between boldface and roman fonts 271.It Sx IB Ta alternate between italic and boldface fonts 272.It Sx IR Ta alternate between italic and roman fonts 273.It Sx RB Ta alternate between roman and boldface fonts 274.It Sx RI Ta alternate between roman and italic fonts 275.El 276.Sh MACRO REFERENCE 277This section is a canonical reference to all macros, arranged 278alphabetically. 279For the scoping of individual macros, see 280.Sx MACRO SYNTAX . 281.Ss \&AT 282Sets the volume for the footer for compatibility with man pages from 283.Tn AT&T UNIX 284releases. 285The optional arguments specify which release it is from. 286.Ss \&B 287Text is rendered in bold face. 288.Pp 289See also 290.Sx \&I 291and 292.Sx \&R . 293.Ss \&BI 294Text is rendered alternately in bold face and italic. 295Thus, 296.Sq .BI this word and that 297causes 298.Sq this 299and 300.Sq and 301to render in bold face, while 302.Sq word 303and 304.Sq that 305render in italics. 306Whitespace between arguments is omitted in output. 307.Pp 308Examples: 309.Pp 310.Dl \&.BI bold italic bold italic 311.Pp 312The output of this example will be emboldened 313.Dq bold 314and italicised 315.Dq italic , 316with spaces stripped between arguments. 317.Pp 318See also 319.Sx \&IB , 320.Sx \&BR , 321.Sx \&RB , 322.Sx \&RI , 323and 324.Sx \&IR . 325.Ss \&BR 326Text is rendered alternately in bold face and roman (the default font). 327Whitespace between arguments is omitted in output. 328.Pp 329See 330.Sx \&BI 331for an equivalent example. 332.Pp 333See also 334.Sx \&BI , 335.Sx \&IB , 336.Sx \&RB , 337.Sx \&RI , 338and 339.Sx \&IR . 340.Ss \&DT 341Has no effect. 342Included for compatibility. 343.Ss \&EE 344This is a non-standard GNU extension, included only for compatibility. 345In 346.Xr mandoc 1 , 347it does the same as 348.Sx \&fi . 349.Ss \&EX 350This is a non-standard GNU extension, included only for compatibility. 351In 352.Xr mandoc 1 , 353it does the same as 354.Sx \&nf . 355.Ss \&HP 356Begin a paragraph whose initial output line is left-justified, but 357subsequent output lines are indented, with the following syntax: 358.Bd -filled -offset indent 359.Pf \. Sx \&HP 360.Op Cm width 361.Ed 362.Pp 363The 364.Cm width 365argument is a 366.Xr roff 7 367scaling width. 368If specified, it's saved for later paragraph left-margins; if unspecified, the 369saved or default width is used. 370.Pp 371See also 372.Sx \&IP , 373.Sx \&LP , 374.Sx \&P , 375.Sx \&PP , 376and 377.Sx \&TP . 378.Ss \&I 379Text is rendered in italics. 380.Pp 381See also 382.Sx \&B 383and 384.Sx \&R . 385.Ss \&IB 386Text is rendered alternately in italics and bold face. 387Whitespace between arguments is omitted in output. 388.Pp 389See 390.Sx \&BI 391for an equivalent example. 392.Pp 393See also 394.Sx \&BI , 395.Sx \&BR , 396.Sx \&RB , 397.Sx \&RI , 398and 399.Sx \&IR . 400.Ss \&IP 401Begin an indented paragraph with the following syntax: 402.Bd -filled -offset indent 403.Pf \. Sx \&IP 404.Op Cm head Op Cm width 405.Ed 406.Pp 407The 408.Cm width 409argument is a 410.Xr roff 7 411scaling width defining the left margin. 412It's saved for later paragraph left-margins; if unspecified, the saved or 413default width is used. 414.Pp 415The 416.Cm head 417argument is used as a leading term, flushed to the left margin. 418This is useful for bulleted paragraphs and so on. 419.Pp 420See also 421.Sx \&HP , 422.Sx \&LP , 423.Sx \&P , 424.Sx \&PP , 425and 426.Sx \&TP . 427.Ss \&IR 428Text is rendered alternately in italics and roman (the default font). 429Whitespace between arguments is omitted in output. 430.Pp 431See 432.Sx \&BI 433for an equivalent example. 434.Pp 435See also 436.Sx \&BI , 437.Sx \&IB , 438.Sx \&BR , 439.Sx \&RB , 440and 441.Sx \&RI . 442.Ss \&LP 443Begin an undecorated paragraph. 444The scope of a paragraph is closed by a subsequent paragraph, 445sub-section, section, or end of file. 446The saved paragraph left-margin width is reset to the default. 447.Pp 448See also 449.Sx \&HP , 450.Sx \&IP , 451.Sx \&P , 452.Sx \&PP , 453and 454.Sx \&TP . 455.Ss \&OP 456Optional command-line argument. 457This is a non-standard GNU extension, included only for compatibility. 458It has the following syntax: 459.Bd -filled -offset indent 460.Pf \. Sx \&OP 461.Cm key Op Cm value 462.Ed 463.Pp 464The 465.Cm key 466is usually a command-line flag and 467.Cm value 468its argument. 469.Ss \&P 470Synonym for 471.Sx \&LP . 472.Pp 473See also 474.Sx \&HP , 475.Sx \&IP , 476.Sx \&LP , 477.Sx \&PP , 478and 479.Sx \&TP . 480.Ss \&PD 481Specify the vertical space to be inserted before each new paragraph. 482.br 483The syntax is as follows: 484.Bd -filled -offset indent 485.Pf \. Sx \&PD 486.Op Cm height 487.Ed 488.Pp 489The 490.Cm height 491argument is a 492.Xr roff 7 493scaling width. 494It defaults to 495.Cm 1v . 496If the unit is omitted, 497.Cm v 498is assumed. 499.Pp 500This macro affects the spacing before any subsequent instances of 501.Sx \&HP , 502.Sx \&IP , 503.Sx \&LP , 504.Sx \&P , 505.Sx \&PP , 506.Sx \&SH , 507.Sx \&SS , 508and 509.Sx \&TP . 510.Ss \&PP 511Synonym for 512.Sx \&LP . 513.Pp 514See also 515.Sx \&HP , 516.Sx \&IP , 517.Sx \&LP , 518.Sx \&P , 519and 520.Sx \&TP . 521.Ss \&R 522Text is rendered in roman (the default font). 523.Pp 524See also 525.Sx \&I 526and 527.Sx \&B . 528.Ss \&RB 529Text is rendered alternately in roman (the default font) and bold face. 530Whitespace between arguments is omitted in output. 531.Pp 532See 533.Sx \&BI 534for an equivalent example. 535.Pp 536See also 537.Sx \&BI , 538.Sx \&IB , 539.Sx \&BR , 540.Sx \&RI , 541and 542.Sx \&IR . 543.Ss \&RE 544Explicitly close out the scope of a prior 545.Sx \&RS . 546The default left margin is restored to the state of the original 547.Sx \&RS 548invocation. 549.Ss \&RI 550Text is rendered alternately in roman (the default font) and italics. 551Whitespace between arguments is omitted in output. 552.Pp 553See 554.Sx \&BI 555for an equivalent example. 556.Pp 557See also 558.Sx \&BI , 559.Sx \&IB , 560.Sx \&BR , 561.Sx \&RB , 562and 563.Sx \&IR . 564.Ss \&RS 565Temporarily reset the default left margin. 566This has the following syntax: 567.Bd -filled -offset indent 568.Pf \. Sx \&RS 569.Op Cm width 570.Ed 571.Pp 572The 573.Cm width 574argument is a 575.Xr roff 7 576scaling width. 577If not specified, the saved or default width is used. 578.Pp 579See also 580.Sx \&RE . 581.Ss \&SB 582Text is rendered in small size (one point smaller than the default font) 583bold face. 584.Ss \&SH 585Begin a section. 586The scope of a section is only closed by another section or the end of 587file. 588The paragraph left-margin width is reset to the default. 589.Ss \&SM 590Text is rendered in small size (one point smaller than the default 591font). 592.Ss \&SS 593Begin a sub-section. 594The scope of a sub-section is closed by a subsequent sub-section, 595section, or end of file. 596The paragraph left-margin width is reset to the default. 597.Ss \&TH 598Sets the title of the manual page with the following syntax: 599.Bd -filled -offset indent 600.Pf \. Sx \&TH 601.Ar title section date 602.Op Ar source Op Ar volume 603.Ed 604.Pp 605Conventionally, the document 606.Ar title 607is given in all caps. 608The recommended 609.Ar date 610format is 611.Sy YYYY-MM-DD 612as specified in the ISO-8601 standard; 613if the argument does not conform, it is printed verbatim. 614If the 615.Ar date 616is empty or not specified, the current date is used. 617The optional 618.Ar source 619string specifies the organisation providing the utility. 620The 621.Ar volume 622string replaces the default rendered volume, which is dictated by the 623manual section. 624.Pp 625Examples: 626.Pp 627.Dl \&.TH CVS 5 "1992-02-12" GNU 628.Ss \&TP 629Begin a paragraph where the head, if exceeding the indentation width, is 630followed by a newline; if not, the body follows on the same line after a 631buffer to the indentation width. 632Subsequent output lines are indented. 633The syntax is as follows: 634.Bd -filled -offset indent 635.Pf \. Sx \&TP 636.Op Cm width 637.Ed 638.Pp 639The 640.Cm width 641argument is a 642.Xr roff 7 643scaling width. 644If specified, it's saved for later paragraph left-margins; if 645unspecified, the saved or default width is used. 646.Pp 647See also 648.Sx \&HP , 649.Sx \&IP , 650.Sx \&LP , 651.Sx \&P , 652and 653.Sx \&PP . 654.Ss \&UC 655Sets the volume for the footer for compatibility with man pages from 656.Bx 657releases. 658The optional first argument specifies which release it is from. 659.Ss \&UE 660End a uniform resource identifier block. 661This is a non-standard GNU extension, included only for compatibility. 662See 663.Sx \&UE . 664.Ss \&UR 665Begin a uniform resource identifier block. 666This is a non-standard GNU extension, included only for compatibility. 667It has the following syntax: 668.Bd -literal -offset indent 669.Pf \. Sx \&UR Ar uri 670link description to be shown 671.Pf \. Sx UE 672.Ed 673.Ss \&br 674Breaks the current line. 675Consecutive invocations have no further effect. 676.Pp 677See also 678.Sx \&sp . 679.Ss \&fi 680End literal mode begun by 681.Sx \&nf . 682.Ss \&in 683Indent relative to the current indentation: 684.Pp 685.D1 Pf \. Sx \&in Op Cm width 686.Pp 687If 688.Cm width 689is signed, the new offset is relative. 690Otherwise, it is absolute. 691This value is reset upon the next paragraph, section, or sub-section. 692.Ss \&na 693Don't align to the right margin. 694.Ss \&nf 695Begin literal mode: all subsequent free-form lines have their end of 696line boundaries preserved. 697May be ended by 698.Sx \&fi . 699Literal mode is implicitly ended by 700.Sx \&SH 701or 702.Sx \&SS . 703.Ss \&sp 704Insert vertical spaces into output with the following syntax: 705.Bd -filled -offset indent 706.Pf \. Sx \&sp 707.Op Cm height 708.Ed 709.Pp 710The 711.Cm height 712argument is a scaling width as described in 713.Xr roff 7 . 714If 0, this is equivalent to the 715.Sx \&br 716macro. 717Defaults to 1, if unspecified. 718.Pp 719See also 720.Sx \&br . 721.Sh MACRO SYNTAX 722The 723.Nm 724macros are classified by scope: line scope or block scope. 725Line macros are only scoped to the current line (and, in some 726situations, the subsequent line). 727Block macros are scoped to the current line and subsequent lines until 728closed by another block macro. 729.Ss Line Macros 730Line macros are generally scoped to the current line, with the body 731consisting of zero or more arguments. 732If a macro is scoped to the next line and the line arguments are empty, 733the next line, which must be text, is used instead. 734Thus: 735.Bd -literal -offset indent 736\&.I 737foo 738.Ed 739.Pp 740is equivalent to 741.Sq \&.I foo . 742If next-line macros are invoked consecutively, only the last is used. 743If a next-line macro is followed by a non-next-line macro, an error is 744raised, except for 745.Sx \&br , 746.Sx \&sp , 747and 748.Sx \&na . 749.Pp 750The syntax is as follows: 751.Bd -literal -offset indent 752\&.YO \(lBbody...\(rB 753\(lBbody...\(rB 754.Ed 755.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 756.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 757.It Sx \&AT Ta <=1 Ta current Ta \& 758.It Sx \&B Ta n Ta next-line Ta \& 759.It Sx \&BI Ta n Ta current Ta \& 760.It Sx \&BR Ta n Ta current Ta \& 761.It Sx \&DT Ta 0 Ta current Ta \& 762.It Sx \&EE Ta 0 Ta current Ta compat 763.It Sx \&EX Ta 0 Ta current Ta compat 764.It Sx \&I Ta n Ta next-line Ta \& 765.It Sx \&IB Ta n Ta current Ta \& 766.It Sx \&IR Ta n Ta current Ta \& 767.It Sx \&OP Ta 0, 1 Ta current Ta compat 768.It Sx \&PD Ta 1 Ta current Ta \& 769.It Sx \&R Ta n Ta next-line Ta \& 770.It Sx \&RB Ta n Ta current Ta \& 771.It Sx \&RI Ta n Ta current Ta \& 772.It Sx \&SB Ta n Ta next-line Ta \& 773.It Sx \&SM Ta n Ta next-line Ta \& 774.It Sx \&TH Ta >1, <6 Ta current Ta \& 775.It Sx \&UC Ta <=1 Ta current Ta \& 776.It Sx \&br Ta 0 Ta current Ta compat 777.It Sx \&fi Ta 0 Ta current Ta compat 778.It Sx \&in Ta 1 Ta current Ta compat 779.It Sx \&na Ta 0 Ta current Ta compat 780.It Sx \&nf Ta 0 Ta current Ta compat 781.It Sx \&sp Ta 1 Ta current Ta compat 782.El 783.Pp 784Macros marked as 785.Qq compat 786are included for compatibility with the significant corpus of existing 787manuals that mix dialects of roff. 788These macros should not be used for portable 789.Nm 790manuals. 791.Ss Block Macros 792Block macros comprise a head and body. 793As with in-line macros, the head is scoped to the current line and, in 794one circumstance, the next line (the next-line stipulations as in 795.Sx Line Macros 796apply here as well). 797.Pp 798The syntax is as follows: 799.Bd -literal -offset indent 800\&.YO \(lBhead...\(rB 801\(lBhead...\(rB 802\(lBbody...\(rB 803.Ed 804.Pp 805The closure of body scope may be to the section, where a macro is closed 806by 807.Sx \&SH ; 808sub-section, closed by a section or 809.Sx \&SS ; 810part, closed by a section, sub-section, or 811.Sx \&RE ; 812or paragraph, closed by a section, sub-section, part, 813.Sx \&HP , 814.Sx \&IP , 815.Sx \&LP , 816.Sx \&P , 817.Sx \&PP , 818or 819.Sx \&TP . 820No closure refers to an explicit block closing macro. 821.Pp 822As a rule, block macros may not be nested; thus, calling a block macro 823while another block macro scope is open, and the open scope is not 824implicitly closed, is syntactically incorrect. 825.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 826.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 827.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 828.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 829.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 830.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 831.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 832.It Sx \&RE Ta 0 Ta current Ta none Ta compat 833.It Sx \&RS Ta 1 Ta current Ta part Ta compat 834.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 835.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 836.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 837.It Sx \&UE Ta 0 Ta current Ta none Ta compat 838.It Sx \&UR Ta 1 Ta current Ta part Ta compat 839.El 840.Pp 841Macros marked 842.Qq compat 843are as mentioned in 844.Sx Line Macros . 845.Pp 846If a block macro is next-line scoped, it may only be followed by in-line 847macros for decorating text. 848.Ss Font handling 849In 850.Nm 851documents, both 852.Sx Physical markup 853macros and 854.Xr roff 7 855.Ql \ef 856font escape sequences can be used to choose fonts. 857In text lines, the effect of manual font selection by escape sequences 858only lasts until the next macro invocation; in macro lines, it only lasts 859until the end of the macro scope. 860Note that macros like 861.Sx \&BR 862open and close a font scope for each argument. 863.Sh COMPATIBILITY 864This section documents areas of questionable portability between 865implementations of the 866.Nm 867language. 868.Pp 869.Bl -dash -compact 870.It 871Do not depend on 872.Sx \&SH 873or 874.Sx \&SS 875to close out a literal context opened with 876.Sx \&nf . 877This behaviour may not be portable. 878.It 879In quoted literals, GNU troff allowed pair-wise double-quotes to produce 880a standalone double-quote in formatted output. 881It is not known whether this behaviour is exhibited by other formatters. 882.It 883troff suppresses a newline before 884.Sq \(aq 885macro output; in mandoc, it is an alias for the standard 886.Sq \&. 887control character. 888.It 889The 890.Sq \eh 891.Pq horizontal position , 892.Sq \ev 893.Pq vertical position , 894.Sq \em 895.Pq text colour , 896.Sq \eM 897.Pq text filling colour , 898.Sq \ez 899.Pq zero-length character , 900.Sq \ew 901.Pq string length , 902.Sq \ek 903.Pq horizontal position marker , 904.Sq \eo 905.Pq text overstrike , 906and 907.Sq \es 908.Pq text size 909escape sequences are all discarded in mandoc. 910.It 911The 912.Sq \ef 913scaling unit is accepted by mandoc, but rendered as the default unit. 914.It 915The 916.Sx \&sp 917macro does not accept negative values in mandoc. 918In GNU troff, this would result in strange behaviour. 919.It 920In page header lines, GNU troff versions up to and including 1.21 921only print 922.Ar volume 923names explicitly specified in the 924.Sx \&TH 925macro; mandoc and newer groff print the default volume name 926corresponding to the 927.Ar section 928number when no 929.Ar volume 930is given, like in 931.Xr mdoc 7 . 932.El 933.Pp 934The 935.Sx OP 936macro is part of the extended 937.Nm 938macro set, and may not be portable to non-GNU troff implementations. 939.Sh SEE ALSO 940.Xr man 1 , 941.Xr mandoc 1 , 942.Xr eqn 7 , 943.Xr mandoc_char 7 , 944.Xr mdoc 7 , 945.Xr roff 7 , 946.Xr tbl 7 947.Sh HISTORY 948The 949.Nm 950language first appeared as a macro package for the roff typesetting 951system in 952.At v7 . 953It was later rewritten by James Clark as a macro package for groff. 954Eric S. Raymond wrote the extended 955.Nm 956macros for groff in 2007. 957The stand-alone implementation that is part of the 958.Xr mandoc 1 959utility written by Kristaps Dzonsons appeared in 960.Ox 4.6 . 961.Sh AUTHORS 962This 963.Nm 964reference was written by 965.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 966.Sh CAVEATS 967Do not use this language. 968Use 969.Xr mdoc 7 , 970instead. 971