1.\" $Id: man.7,v 1.148 2021/08/05 14:31:14 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org> 5.\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org> 6.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: August 5 2021 $ 21.Dt MAN 7 22.Os 23.Sh NAME 24.Nm man 25.Nd legacy formatting language for manual pages 26.Sh DESCRIPTION 27The 28.Nm man 29language was the standard formatting language for 30.At 31manual pages from 1979 to 1989. 32Do not use it to write new manual pages: it is a purely presentational 33language and lacks support for semantic markup. 34Use the 35.Xr mdoc 7 36language, instead. 37.Pp 38In a 39.Nm 40document, lines beginning with the control character 41.Sq \&. 42are called 43.Dq macro lines . 44The first word is the macro name. 45It usually consists of two capital letters. 46For a list of portable macros, see 47.Sx MACRO OVERVIEW . 48The words following the macro name are arguments to the macro. 49.Pp 50Lines not beginning with the control character are called 51.Dq text lines . 52They provide free-form text to be printed; the formatting of the text 53depends on the respective processing context: 54.Bd -literal -offset indent 55\&.SH Macro lines change control state. 56Text lines are interpreted within the current state. 57.Ed 58.Pp 59Many aspects of the basic syntax of the 60.Nm 61language are based on the 62.Xr roff 7 63language; see the 64.Em LANGUAGE SYNTAX 65and 66.Em MACRO SYNTAX 67sections in the 68.Xr roff 7 69manual for details, in particular regarding 70comments, escape sequences, whitespace, and quoting. 71.Pp 72Each 73.Nm 74document starts with the 75.Ic TH 76macro specifying the document's name and section, followed by the 77.Sx NAME 78section formatted as follows: 79.Bd -literal -offset indent 80\&.TH PROGNAME 1 1979-01-10 81\&.SH NAME 82\efBprogname\efR \e(en one line about what it does 83.Ed 84.Sh MACRO OVERVIEW 85This overview is sorted such that macros of similar purpose are listed 86together. 87Deprecated and non-portable macros are not included in the overview, 88but can be found in the alphabetical reference below. 89.Ss Page header and footer meta-data 90.Bl -column "RS, RE" description 91.It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume 92.It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument) 93.It Ic UC Ta display BSD version in the page footer (<= 1 argument) 94.El 95.Ss Sections and paragraphs 96.Bl -column "RS, RE" description 97.It Ic SH Ta section header (one line) 98.It Ic SS Ta subsection header (one line) 99.It Ic PP Ta start an undecorated paragraph (no arguments) 100.It Ic RS , RE Ta reset the left margin: Op Ar width 101.It Ic IP Ta indented paragraph: Op Ar head Op Ar width 102.It Ic TP Ta tagged paragraph: Op Ar width 103.It Ic PD Ta set vertical paragraph distance: Op Ar height 104.It Ic in Ta additional indent: Op Ar width 105.El 106.Ss Physical markup 107.Bl -column "RS, RE" description 108.It Ic B Ta boldface font 109.It Ic I Ta italic font 110.It Ic SB Ta small boldface font 111.It Ic SM Ta small roman font 112.It Ic BI Ta alternate between boldface and italic fonts 113.It Ic BR Ta alternate between boldface and roman fonts 114.It Ic IB Ta alternate between italic and boldface fonts 115.It Ic IR Ta alternate between italic and roman fonts 116.It Ic RB Ta alternate between roman and boldface fonts 117.It Ic RI Ta alternate between roman and italic fonts 118.El 119.Sh MACRO REFERENCE 120This section is a canonical reference to all macros, arranged 121alphabetically. 122For the scoping of individual macros, see 123.Sx MACRO SYNTAX . 124.Bl -tag -width 3n 125.It Ic AT 126Sets the volume for the footer for compatibility with man pages from 127.At 128releases. 129The optional arguments specify which release it is from. 130This macro is an extension that first appeared in 131.Bx 4.3 . 132.It Ic B 133Text is rendered in bold face. 134.It Ic BI 135Text is rendered alternately in bold face and italic. 136Thus, 137.Sq .BI this word and that 138causes 139.Sq this 140and 141.Sq and 142to render in bold face, while 143.Sq word 144and 145.Sq that 146render in italics. 147Whitespace between arguments is omitted in output. 148.Pp 149Example: 150.Pp 151.Dl \&.BI bold italic bold italic 152.It Ic BR 153Text is rendered alternately in bold face and roman (the default font). 154Whitespace between arguments is omitted in output. 155See also 156.Ic BI . 157.It Ic DT 158Restore the default tabulator positions. 159They are at intervals of 0.5 inches. 160This has no effect unless the tabulator positions were changed with the 161.Xr roff 7 162.Ic ta 163request. 164.It Ic EE 165This is a non-standard Version 9 166.At 167extension later adopted by GNU. 168In 169.Xr mandoc 1 , 170it does the same as the 171.Xr roff 7 172.Ic fi 173request (switch to fill mode). 174.It Ic EX 175This is a non-standard Version 9 176.At 177extension later adopted by GNU. 178In 179.Xr mandoc 1 , 180it does the same as the 181.Xr roff 7 182.Ic nf 183request (switch to no-fill mode). 184.It Ic HP 185Begin a paragraph whose initial output line is left-justified, but 186subsequent output lines are indented, with the following syntax: 187.Pp 188.D1 Pf . Ic HP Op Ar width 189.Pp 190The 191.Ar width 192argument is a 193.Xr roff 7 194scaling width. 195If specified, it's saved for later paragraph left margins; 196if unspecified, the saved or default width is used. 197.Pp 198This macro is portable, but deprecated 199because it has no good representation in HTML output, 200usually ending up indistinguishable from 201.Ic PP . 202.It Ic I 203Text is rendered in italics. 204.It Ic IB 205Text is rendered alternately in italics and bold face. 206Whitespace between arguments is omitted in output. 207See also 208.Ic BI . 209.It Ic IP 210Begin an indented paragraph with the following syntax: 211.Pp 212.D1 Pf . Ic IP Op Ar head Op Ar width 213.Pp 214The 215.Ar width 216argument is a 217.Xr roff 7 218scaling width defining the left margin. 219It's saved for later paragraph left-margins; if unspecified, the saved or 220default width is used. 221.Pp 222The 223.Ar head 224argument is used as a leading term, flushed to the left margin. 225This is useful for bulleted paragraphs and so on. 226.It Ic IR 227Text is rendered alternately in italics and roman (the default font). 228Whitespace between arguments is omitted in output. 229See also 230.Ic BI . 231.It Ic LP 232A synonym for 233.Ic PP . 234.It Ic ME 235End a mailto block started with 236.Ic MT . 237This is a non-standard GNU extension. 238.It Ic MT 239Begin a mailto block. 240This is a non-standard GNU extension. 241It has the following syntax: 242.Bd -unfilled -offset indent 243.Pf . Ic MT Ar address 244link description to be shown 245.Pf . Ic ME 246.Ed 247.It Ic OP 248Optional command-line argument. 249This is a non-standard DWB extension. 250It has the following syntax: 251.Pp 252.D1 Pf . Ic OP Ar key Op Ar value 253.Pp 254The 255.Ar key 256is usually a command-line flag and 257.Ar value 258its argument. 259.It Ic P 260This synonym for 261.Ic PP 262is an 263.At III 264extension later adopted by 265.Bx 4.3 . 266.It Ic PD 267Specify the vertical space to be inserted before each new paragraph. 268.br 269The syntax is as follows: 270.Pp 271.D1 Pf . Ic PD Op Ar height 272.Pp 273The 274.Ar height 275argument is a 276.Xr roff 7 277scaling width. 278It defaults to 279.Cm 1v . 280If the unit is omitted, 281.Cm v 282is assumed. 283.Pp 284This macro affects the spacing before any subsequent instances of 285.Ic HP , 286.Ic IP , 287.Ic LP , 288.Ic P , 289.Ic PP , 290.Ic SH , 291.Ic SS , 292.Ic SY , 293and 294.Ic TP . 295.It Ic PP 296Begin an undecorated paragraph. 297The scope of a paragraph is closed by a subsequent paragraph, 298sub-section, section, or end of file. 299The saved paragraph left-margin width is reset to the default. 300.It Ic RB 301Text is rendered alternately in roman (the default font) and bold face. 302Whitespace between arguments is omitted in output. 303See also 304.Ic BI . 305.It Ic RE 306Explicitly close out the scope of a prior 307.Ic RS . 308The default left margin is restored to the state before that 309.Ic RS 310invocation. 311.Pp 312The syntax is as follows: 313.Pp 314.D1 Pf . Ic RE Op Ar level 315.Pp 316Without an argument, the most recent 317.Ic RS 318block is closed out. 319If 320.Ar level 321is 1, all open 322.Ic RS 323blocks are closed out. 324Otherwise, 325.Ar level No \(mi 1 326nested 327.Ic RS 328blocks remain open. 329.It Ic RI 330Text is rendered alternately in roman (the default font) and italics. 331Whitespace between arguments is omitted in output. 332See also 333.Ic BI . 334.It Ic RS 335Temporarily reset the default left margin. 336This has the following syntax: 337.Pp 338.D1 Pf . Ic RS Op Ar width 339.Pp 340The 341.Ar width 342argument is a 343.Xr roff 7 344scaling width. 345If not specified, the saved or default width is used. 346.Pp 347See also 348.Ic RE . 349.It Ic SB 350Text is rendered in small size (one point smaller than the default font) 351bold face. 352This macro is an extension that probably first appeared in SunOS 4.0 353and was later adopted by GNU and by 354.Bx 4.4 . 355.It Ic SH 356Begin a section. 357The scope of a section is only closed by another section or the end of 358file. 359The paragraph left-margin width is reset to the default. 360.It Ic SM 361Text is rendered in small size (one point smaller than the default 362font). 363.It Ic SS 364Begin a sub-section. 365The scope of a sub-section is closed by a subsequent sub-section, 366section, or end of file. 367The paragraph left-margin width is reset to the default. 368.It Ic SY 369Begin a synopsis block with the following syntax: 370.Bd -unfilled -offset indent 371.Pf . Ic SY Ar command 372.Ar arguments 373.Pf . Ic YS 374.Ed 375.Pp 376This is a non-standard GNU extension 377and very rarely used even in GNU manual pages. 378Formatting is similar to 379.Ic IP . 380.It Ic TH 381Set the name of the manual page for use in the page header 382and footer with the following syntax: 383.Pp 384.D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume 385.Pp 386Conventionally, the document 387.Ar name 388is given in all caps. 389The 390.Ar section 391is usually a single digit, in a few cases followed by a letter. 392The recommended 393.Ar date 394format is 395.Sy YYYY-MM-DD 396as specified in the ISO-8601 standard; 397if the argument does not conform, it is printed verbatim. 398If the 399.Ar date 400is empty or not specified, the current date is used. 401The optional 402.Ar source 403string specifies the organisation providing the utility. 404When unspecified, 405.Xr mandoc 1 406uses its 407.Fl Ios 408argument. 409The 410.Ar volume 411string replaces the default volume title of the 412.Ar section . 413.Pp 414Examples: 415.Pp 416.Dl \&.TH CVS 5 "1992-02-12" GNU 417.It Ic TP 418Begin a paragraph where the head, if exceeding the indentation width, is 419followed by a newline; if not, the body follows on the same line after 420advancing to the indentation width. 421Subsequent output lines are indented. 422The syntax is as follows: 423.Bd -unfilled -offset indent 424.Pf . Ic TP Op Ar width 425.Ar head No \e" one line 426.Ar body 427.Ed 428.Pp 429The 430.Ar width 431argument is a 432.Xr roff 7 433scaling width. 434If specified, it's saved for later paragraph left-margins; if 435unspecified, the saved or default width is used. 436.It Ic TQ 437Like 438.Ic TP , 439except that no vertical spacing is inserted before the paragraph. 440This is a non-standard GNU extension 441and very rarely used even in GNU manual pages. 442.It Ic UC 443Sets the volume for the footer for compatibility with man pages from 444.Bx 445releases. 446The optional first argument specifies which release it is from. 447This macro is an extension that first appeared in 448.Bx 3 . 449.It Ic UE 450End a uniform resource identifier block started with 451.Ic UR . 452This is a non-standard GNU extension. 453.It Ic UR 454Begin a uniform resource identifier block. 455This is a non-standard GNU extension. 456It has the following syntax: 457.Bd -unfilled -offset indent 458.Pf . Ic UR Ar uri 459link description to be shown 460.Pf . Ic UE 461.Ed 462.It Ic YS 463End a synopsis block started with 464.Ic SY . 465This is a non-standard GNU extension. 466.It Ic in 467Indent relative to the current indentation: 468.Pp 469.D1 Pf . Ic in Op Ar width 470.Pp 471If 472.Ar width 473is signed, the new offset is relative. 474Otherwise, it is absolute. 475This value is reset upon the next paragraph, section, or sub-section. 476.El 477.Sh MACRO SYNTAX 478The 479.Nm 480macros are classified by scope: line scope or block scope. 481Line macros are only scoped to the current line (and, in some 482situations, the subsequent line). 483Block macros are scoped to the current line and subsequent lines until 484closed by another block macro. 485.Ss Line Macros 486Line macros are generally scoped to the current line, with the body 487consisting of zero or more arguments. 488If a macro is scoped to the next line and the line arguments are empty, 489the next line, which must be text, is used instead. 490Thus: 491.Bd -literal -offset indent 492\&.I 493foo 494.Ed 495.Pp 496is equivalent to 497.Sq .I foo . 498If next-line macros are invoked consecutively, only the last is used. 499If a next-line macro is followed by a non-next-line macro, an error is 500raised. 501.Pp 502The syntax is as follows: 503.Bd -literal -offset indent 504\&.YO \(lBbody...\(rB 505\(lBbody...\(rB 506.Ed 507.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 508.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 509.It Ic AT Ta <=1 Ta current Ta \& 510.It Ic B Ta n Ta next-line Ta \& 511.It Ic BI Ta n Ta current Ta \& 512.It Ic BR Ta n Ta current Ta \& 513.It Ic DT Ta 0 Ta current Ta \& 514.It Ic EE Ta 0 Ta current Ta Version 9 At 515.It Ic EX Ta 0 Ta current Ta Version 9 At 516.It Ic I Ta n Ta next-line Ta \& 517.It Ic IB Ta n Ta current Ta \& 518.It Ic IR Ta n Ta current Ta \& 519.It Ic OP Ta >=1 Ta current Ta DWB 520.It Ic PD Ta 1 Ta current Ta \& 521.It Ic RB Ta n Ta current Ta \& 522.It Ic RI Ta n Ta current Ta \& 523.It Ic SB Ta n Ta next-line Ta \& 524.It Ic SM Ta n Ta next-line Ta \& 525.It Ic TH Ta >1, <6 Ta current Ta \& 526.It Ic UC Ta <=1 Ta current Ta \& 527.It Ic in Ta 1 Ta current Ta Xr roff 7 528.El 529.Ss Block Macros 530Block macros comprise a head and body. 531As with in-line macros, the head is scoped to the current line and, in 532one circumstance, the next line (the next-line stipulations as in 533.Sx Line Macros 534apply here as well). 535.Pp 536The syntax is as follows: 537.Bd -literal -offset indent 538\&.YO \(lBhead...\(rB 539\(lBhead...\(rB 540\(lBbody...\(rB 541.Ed 542.Pp 543The closure of body scope may be to the section, where a macro is closed 544by 545.Ic SH ; 546sub-section, closed by a section or 547.Ic SS ; 548or paragraph, closed by a section, sub-section, 549.Ic HP , 550.Ic IP , 551.Ic LP , 552.Ic P , 553.Ic PP , 554.Ic RE , 555.Ic SY , 556or 557.Ic TP . 558No closure refers to an explicit block closing macro. 559.Pp 560As a rule, block macros may not be nested; thus, calling a block macro 561while another block macro scope is open, and the open scope is not 562implicitly closed, is syntactically incorrect. 563.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 564.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 565.It Ic HP Ta <2 Ta current Ta paragraph Ta \& 566.It Ic IP Ta <3 Ta current Ta paragraph Ta \& 567.It Ic LP Ta 0 Ta current Ta paragraph Ta \& 568.It Ic ME Ta 0 Ta none Ta none Ta GNU 569.It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU 570.It Ic P Ta 0 Ta current Ta paragraph Ta \& 571.It Ic PP Ta 0 Ta current Ta paragraph Ta \& 572.It Ic RE Ta <=1 Ta current Ta none Ta \& 573.It Ic RS Ta 1 Ta current Ta to \&RE Ta \& 574.It Ic SH Ta >0 Ta next-line Ta section Ta \& 575.It Ic SS Ta >0 Ta next-line Ta sub-section Ta \& 576.It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU 577.It Ic TP Ta n Ta next-line Ta paragraph Ta \& 578.It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU 579.It Ic UE Ta 0 Ta current Ta none Ta GNU 580.It Ic UR Ta 1 Ta current Ta part Ta GNU 581.It Ic YS Ta 0 Ta none Ta none Ta GNU 582.El 583.Pp 584If a block macro is next-line scoped, it may only be followed by in-line 585macros for decorating text. 586.Ss Font handling 587In 588.Nm 589documents, both 590.Sx Physical markup 591macros and 592.Xr roff 7 593.Ql \ef 594font escape sequences can be used to choose fonts. 595In text lines, the effect of manual font selection by escape sequences 596only lasts until the next macro invocation; in macro lines, it only lasts 597until the end of the macro scope. 598Note that macros like 599.Ic BR 600open and close a font scope for each argument. 601.Sh SEE ALSO 602.Xr man 1 , 603.Xr mandoc 1 , 604.Xr eqn 7 , 605.Xr mandoc_char 7 , 606.Xr mdoc 7 , 607.Xr roff 7 , 608.Xr tbl 7 609.Sh HISTORY 610The 611.Nm 612language first appeared as a macro package for the roff typesetting 613system in 614.At v7 . 615.Pp 616The stand-alone implementation that is part of the 617.Xr mandoc 1 618utility first appeared in 619.Ox 4.6 . 620.Sh AUTHORS 621.An -nosplit 622.An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu 623designed and implemented the original version of these macros, 624wrote the original version of this manual page, 625and was the first to use them when he edited volume 1 of the 626.At v7 627manual pages. 628.Pp 629.An James Clark 630later rewrote the macros for groff. 631.An Eric S. Raymond Aq Mt esr@thyrsus.com 632and 633.An Werner Lemberg Aq Mt wl@gnu.org 634added the extended 635.Nm 636macros to groff in 2007. 637.Pp 638The 639.Xr mandoc 1 640program and this 641.Nm 642reference were written by 643.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 644