1.\" $OpenBSD: man.7,v 1.30 2012/07/29 13:35:41 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011, 2012 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: July 29 2012 $ 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 656BSD releases. 657The optional first argument specifies which release it is from. 658.Ss \&br 659Breaks the current line. 660Consecutive invocations have no further effect. 661.Pp 662See also 663.Sx \&sp . 664.Ss \&fi 665End literal mode begun by 666.Sx \&nf . 667.Ss \&in 668Indent relative to the current indentation: 669.Pp 670.D1 Pf \. Sx \&in Op Cm width 671.Pp 672If 673.Cm width 674is signed, the new offset is relative. 675Otherwise, it is absolute. 676This value is reset upon the next paragraph, section, or sub-section. 677.Ss \&na 678Don't align to the right margin. 679.Ss \&nf 680Begin literal mode: all subsequent free-form lines have their end of 681line boundaries preserved. 682May be ended by 683.Sx \&fi . 684Literal mode is implicitly ended by 685.Sx \&SH 686or 687.Sx \&SS . 688.Ss \&sp 689Insert vertical spaces into output with the following syntax: 690.Bd -filled -offset indent 691.Pf \. Sx \&sp 692.Op Cm height 693.Ed 694.Pp 695The 696.Cm height 697argument is a scaling width as described in 698.Xr roff 7 . 699If 0, this is equivalent to the 700.Sx \&br 701macro. 702Defaults to 1, if unspecified. 703.Pp 704See also 705.Sx \&br . 706.Sh MACRO SYNTAX 707The 708.Nm 709macros are classified by scope: line scope or block scope. 710Line macros are only scoped to the current line (and, in some 711situations, the subsequent line). 712Block macros are scoped to the current line and subsequent lines until 713closed by another block macro. 714.Ss Line Macros 715Line macros are generally scoped to the current line, with the body 716consisting of zero or more arguments. 717If a macro is scoped to the next line and the line arguments are empty, 718the next line, which must be text, is used instead. 719Thus: 720.Bd -literal -offset indent 721\&.I 722foo 723.Ed 724.Pp 725is equivalent to 726.Sq \&.I foo . 727If next-line macros are invoked consecutively, only the last is used. 728If a next-line macro is followed by a non-next-line macro, an error is 729raised, except for 730.Sx \&br , 731.Sx \&sp , 732and 733.Sx \&na . 734.Pp 735The syntax is as follows: 736.Bd -literal -offset indent 737\&.YO \(lBbody...\(rB 738\(lBbody...\(rB 739.Ed 740.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 741.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 742.It Sx \&AT Ta <=1 Ta current Ta \& 743.It Sx \&B Ta n Ta next-line Ta \& 744.It Sx \&BI Ta n Ta current Ta \& 745.It Sx \&BR Ta n Ta current Ta \& 746.It Sx \&DT Ta 0 Ta current Ta \& 747.It Sx \&I Ta n Ta next-line Ta \& 748.It Sx \&IB Ta n Ta current Ta \& 749.It Sx \&IR Ta n Ta current Ta \& 750.It Sx \&OP Ta 0, 1 Ta current Ta compat 751.It Sx \&R Ta n Ta next-line Ta \& 752.It Sx \&RB Ta n Ta current Ta \& 753.It Sx \&RI Ta n Ta current Ta \& 754.It Sx \&SB Ta n Ta next-line Ta \& 755.It Sx \&SM Ta n Ta next-line Ta \& 756.It Sx \&TH Ta >1, <6 Ta current Ta \& 757.It Sx \&UC Ta <=1 Ta current Ta \& 758.It Sx \&br Ta 0 Ta current Ta compat 759.It Sx \&fi Ta 0 Ta current Ta compat 760.It Sx \&in Ta 1 Ta current Ta compat 761.It Sx \&na Ta 0 Ta current Ta compat 762.It Sx \&nf Ta 0 Ta current Ta compat 763.It Sx \&sp Ta 1 Ta current Ta compat 764.El 765.Pp 766Macros marked as 767.Qq compat 768are included for compatibility with the significant corpus of existing 769manuals that mix dialects of roff. 770These macros should not be used for portable 771.Nm 772manuals. 773.Ss Block Macros 774Block macros comprise a head and body. 775As with in-line macros, the head is scoped to the current line and, in 776one circumstance, the next line (the next-line stipulations as in 777.Sx Line Macros 778apply here as well). 779.Pp 780The syntax is as follows: 781.Bd -literal -offset indent 782\&.YO \(lBhead...\(rB 783\(lBhead...\(rB 784\(lBbody...\(rB 785.Ed 786.Pp 787The closure of body scope may be to the section, where a macro is closed 788by 789.Sx \&SH ; 790sub-section, closed by a section or 791.Sx \&SS ; 792part, closed by a section, sub-section, or 793.Sx \&RE ; 794or paragraph, closed by a section, sub-section, part, 795.Sx \&HP , 796.Sx \&IP , 797.Sx \&LP , 798.Sx \&P , 799.Sx \&PP , 800or 801.Sx \&TP . 802No closure refers to an explicit block closing macro. 803.Pp 804As a rule, block macros may not be nested; thus, calling a block macro 805while another block macro scope is open, and the open scope is not 806implicitly closed, is syntactically incorrect. 807.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 808.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 809.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 810.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 811.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 812.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 813.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 814.It Sx \&RE Ta 0 Ta current Ta none Ta compat 815.It Sx \&RS Ta 1 Ta current Ta part Ta compat 816.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 817.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 818.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 819.El 820.Pp 821Macros marked 822.Qq compat 823are as mentioned in 824.Sx Line Macros . 825.Pp 826If a block macro is next-line scoped, it may only be followed by in-line 827macros for decorating text. 828.Ss Font handling 829In 830.Nm 831documents, both 832.Sx Physical markup 833macros and 834.Xr roff 7 835.Ql \ef 836font escape sequences can be used to choose fonts. 837In text lines, the effect of manual font selection by escape sequences 838only lasts until the next macro invocation; in macro lines, it only lasts 839until the end of the macro scope. 840Note that macros like 841.Sx \&BR 842open and close a font scope for each argument. 843.Sh COMPATIBILITY 844This section documents areas of questionable portability between 845implementations of the 846.Nm 847language. 848.Pp 849.Bl -dash -compact 850.It 851Do not depend on 852.Sx \&SH 853or 854.Sx \&SS 855to close out a literal context opened with 856.Sx \&nf . 857This behaviour may not be portable. 858.It 859In quoted literals, GNU troff allowed pair-wise double-quotes to produce 860a standalone double-quote in formatted output. 861It is not known whether this behaviour is exhibited by other formatters. 862.It 863troff suppresses a newline before 864.Sq \(aq 865macro output; in mandoc, it is an alias for the standard 866.Sq \&. 867control character. 868.It 869The 870.Sq \eh 871.Pq horizontal position , 872.Sq \ev 873.Pq vertical position , 874.Sq \em 875.Pq text colour , 876.Sq \eM 877.Pq text filling colour , 878.Sq \ez 879.Pq zero-length character , 880.Sq \ew 881.Pq string length , 882.Sq \ek 883.Pq horizontal position marker , 884.Sq \eo 885.Pq text overstrike , 886and 887.Sq \es 888.Pq text size 889escape sequences are all discarded in mandoc. 890.It 891The 892.Sq \ef 893scaling unit is accepted by mandoc, but rendered as the default unit. 894.It 895The 896.Sx \&sp 897macro does not accept negative values in mandoc. 898In GNU troff, this would result in strange behaviour. 899.It 900In page header lines, GNU troff versions up to and including 1.21 901only print 902.Ar volume 903names explicitly specified in the 904.Sx \&TH 905macro; mandoc and newer groff print the default volume name 906corresponding to the 907.Ar section 908number when no 909.Ar volume 910is given, like in 911.Xr mdoc 7 . 912.El 913.Pp 914The 915.Sx OP 916macro is part of the extended 917.Nm 918macro set, and may not be portable to non-GNU troff implementations. 919.Sh SEE ALSO 920.Xr man 1 , 921.Xr mandoc 1 , 922.Xr eqn 7 , 923.Xr mandoc_char 7 , 924.Xr mdoc 7 , 925.Xr roff 7 , 926.Xr tbl 7 927.Sh HISTORY 928The 929.Nm 930language first appeared as a macro package for the roff typesetting 931system in 932.At v7 . 933It was later rewritten by James Clark as a macro package for groff. 934Eric S. Raymond wrote the extended 935.Nm 936macros for groff in 2007. 937The stand-alone implementation that is part of the 938.Xr mandoc 1 939utility written by Kristaps Dzonsons appeared in 940.Ox 4.6 . 941.Sh AUTHORS 942This 943.Nm 944reference was written by 945.An Kristaps Dzonsons , 946.Mt kristaps@bsd.lv . 947.Sh CAVEATS 948Do not use this language. 949Use 950.Xr mdoc 7 , 951instead. 952