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