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