1.\" $Id: man.7,v 1.143 2019/03/02 22:04:40 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011-2015,2017,2018,2019 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: March 2 2019 $ 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. 130.It Ic B 131Text is rendered in bold face. 132.It Ic BI 133Text is rendered alternately in bold face and italic. 134Thus, 135.Sq .BI this word and that 136causes 137.Sq this 138and 139.Sq and 140to render in bold face, while 141.Sq word 142and 143.Sq that 144render in italics. 145Whitespace between arguments is omitted in output. 146.Pp 147Example: 148.Pp 149.Dl \&.BI bold italic bold italic 150.It Ic BR 151Text is rendered alternately in bold face and roman (the default font). 152Whitespace between arguments is omitted in output. 153See also 154.Ic BI . 155.It Ic DT 156Restore the default tabulator positions. 157They are at intervals of 0.5 inches. 158This has no effect unless the tabulator positions were changed with the 159.Xr roff 7 160.Ic ta 161request. 162.It Ic EE 163This is a non-standard GNU extension. 164In 165.Xr mandoc 1 , 166it does the same as the 167.Xr roff 7 168.Ic fi 169request (switch to fill mode). 170.It Ic EX 171This is a non-standard GNU extension. 172In 173.Xr mandoc 1 , 174it does the same as the 175.Xr roff 7 176.Ic nf 177request (switch to no-fill mode). 178.It Ic HP 179Begin a paragraph whose initial output line is left-justified, but 180subsequent output lines are indented, with the following syntax: 181.Pp 182.D1 Pf . Ic HP Op Ar width 183.Pp 184The 185.Ar width 186argument is a 187.Xr roff 7 188scaling width. 189If specified, it's saved for later paragraph left margins; 190if unspecified, the saved or default width is used. 191.Pp 192This macro is portable, but deprecated 193because it has no good representation in HTML output, 194usually ending up indistinguishable from 195.Ic PP . 196.It Ic I 197Text is rendered in italics. 198.It Ic IB 199Text is rendered alternately in italics and bold face. 200Whitespace between arguments is omitted in output. 201See also 202.Ic BI . 203.It Ic IP 204Begin an indented paragraph with the following syntax: 205.Pp 206.D1 Pf . Ic IP Op Ar head Op Ar width 207.Pp 208The 209.Ar width 210argument is a 211.Xr roff 7 212scaling width defining the left margin. 213It's saved for later paragraph left-margins; if unspecified, the saved or 214default width is used. 215.Pp 216The 217.Ar head 218argument is used as a leading term, flushed to the left margin. 219This is useful for bulleted paragraphs and so on. 220.It Ic IR 221Text is rendered alternately in italics and roman (the default font). 222Whitespace between arguments is omitted in output. 223See also 224.Ic BI . 225.It Ic LP 226A synonym for 227.Ic PP . 228.It Ic ME 229End a mailto block started with 230.Ic MT . 231This is a non-standard GNU extension. 232.It Ic MT 233Begin a mailto block. 234This is a non-standard GNU extension. 235It has the following syntax: 236.Bd -unfilled -offset indent 237.Pf . Ic MT Ar address 238link description to be shown 239.Pf . Ic ME 240.Ed 241.It Ic OP 242Optional command-line argument. 243This is a non-standard GNU extension. 244It has the following syntax: 245.Pp 246.D1 Pf . Ic OP Ar key Op Ar value 247.Pp 248The 249.Ar key 250is usually a command-line flag and 251.Ar value 252its argument. 253.It Ic P 254A synonym for 255.Ic PP . 256.It Ic PD 257Specify the vertical space to be inserted before each new paragraph. 258.br 259The syntax is as follows: 260.Pp 261.D1 Pf . Ic PD Op Ar height 262.Pp 263The 264.Ar height 265argument is a 266.Xr roff 7 267scaling width. 268It defaults to 269.Cm 1v . 270If the unit is omitted, 271.Cm v 272is assumed. 273.Pp 274This macro affects the spacing before any subsequent instances of 275.Ic HP , 276.Ic IP , 277.Ic LP , 278.Ic P , 279.Ic PP , 280.Ic SH , 281.Ic SS , 282.Ic SY , 283and 284.Ic TP . 285.It Ic PP 286Begin an undecorated paragraph. 287The scope of a paragraph is closed by a subsequent paragraph, 288sub-section, section, or end of file. 289The saved paragraph left-margin width is reset to the default. 290.It Ic RB 291Text is rendered alternately in roman (the default font) and bold face. 292Whitespace between arguments is omitted in output. 293See also 294.Ic BI . 295.It Ic RE 296Explicitly close out the scope of a prior 297.Ic RS . 298The default left margin is restored to the state before that 299.Ic RS 300invocation. 301.Pp 302The syntax is as follows: 303.Pp 304.D1 Pf . Ic RE Op Ar level 305.Pp 306Without an argument, the most recent 307.Ic RS 308block is closed out. 309If 310.Ar level 311is 1, all open 312.Ic RS 313blocks are closed out. 314Otherwise, 315.Ar level No \(mi 1 316nested 317.Ic RS 318blocks remain open. 319.It Ic RI 320Text is rendered alternately in roman (the default font) and italics. 321Whitespace between arguments is omitted in output. 322See also 323.Ic BI . 324.It Ic RS 325Temporarily reset the default left margin. 326This has the following syntax: 327.Pp 328.D1 Pf . Ic RS Op Ar width 329.Pp 330The 331.Ar width 332argument is a 333.Xr roff 7 334scaling width. 335If not specified, the saved or default width is used. 336.Pp 337See also 338.Ic RE . 339.It Ic SB 340Text is rendered in small size (one point smaller than the default font) 341bold face. 342.It Ic SH 343Begin a section. 344The scope of a section is only closed by another section or the end of 345file. 346The paragraph left-margin width is reset to the default. 347.It Ic SM 348Text is rendered in small size (one point smaller than the default 349font). 350.It Ic SS 351Begin a sub-section. 352The scope of a sub-section is closed by a subsequent sub-section, 353section, or end of file. 354The paragraph left-margin width is reset to the default. 355.It Ic SY 356Begin a synopsis block with the following syntax: 357.Bd -unfilled -offset indent 358.Pf . Ic SY Ar command 359.Ar arguments 360.Pf . Ic YS 361.Ed 362.Pp 363This is a non-standard GNU extension 364and very rarely used even in GNU manual pages. 365Formatting is similar to 366.Ic IP . 367.It Ic TH 368Set the name of the manual page for use in the page header 369and footer with the following syntax: 370.Pp 371.D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume 372.Pp 373Conventionally, the document 374.Ar name 375is given in all caps. 376The 377.Ar section 378is usually a single digit, in a few cases followed by a letter. 379The recommended 380.Ar date 381format is 382.Sy YYYY-MM-DD 383as specified in the ISO-8601 standard; 384if the argument does not conform, it is printed verbatim. 385If the 386.Ar date 387is empty or not specified, the current date is used. 388The optional 389.Ar source 390string specifies the organisation providing the utility. 391When unspecified, 392.Xr mandoc 1 393uses its 394.Fl Ios 395argument. 396The 397.Ar volume 398string replaces the default volume title of the 399.Ar section . 400.Pp 401Examples: 402.Pp 403.Dl \&.TH CVS 5 "1992-02-12" GNU 404.It Ic TP 405Begin a paragraph where the head, if exceeding the indentation width, is 406followed by a newline; if not, the body follows on the same line after 407advancing to the indentation width. 408Subsequent output lines are indented. 409The syntax is as follows: 410.Bd -unfilled -offset indent 411.Pf . Ic TP Op Ar width 412.Ar head No \e" one line 413.Ar body 414.Ed 415.Pp 416The 417.Ar width 418argument is a 419.Xr roff 7 420scaling width. 421If specified, it's saved for later paragraph left-margins; if 422unspecified, the saved or default width is used. 423.It Ic TQ 424Like 425.Ic TP , 426except that no vertical spacing is inserted before the paragraph. 427This is a non-standard GNU extension 428and very rarely used even in GNU manual pages. 429.It Ic UC 430Sets the volume for the footer for compatibility with man pages from 431.Bx 432releases. 433The optional first argument specifies which release it is from. 434.It Ic UE 435End a uniform resource identifier block started with 436.Ic UR . 437This is a non-standard GNU extension. 438.It Ic UR 439Begin a uniform resource identifier block. 440This is a non-standard GNU extension. 441It has the following syntax: 442.Bd -unfilled -offset indent 443.Pf . Ic UR Ar uri 444link description to be shown 445.Pf . Ic UE 446.Ed 447.It Ic YS 448End a synopsis block started with 449.Ic SY . 450This is a non-standard GNU extension. 451.It Ic in 452Indent relative to the current indentation: 453.Pp 454.D1 Pf . Ic in Op Ar width 455.Pp 456If 457.Ar width 458is signed, the new offset is relative. 459Otherwise, it is absolute. 460This value is reset upon the next paragraph, section, or sub-section. 461.El 462.Sh MACRO SYNTAX 463The 464.Nm 465macros are classified by scope: line scope or block scope. 466Line macros are only scoped to the current line (and, in some 467situations, the subsequent line). 468Block macros are scoped to the current line and subsequent lines until 469closed by another block macro. 470.Ss Line Macros 471Line macros are generally scoped to the current line, with the body 472consisting of zero or more arguments. 473If a macro is scoped to the next line and the line arguments are empty, 474the next line, which must be text, is used instead. 475Thus: 476.Bd -literal -offset indent 477\&.I 478foo 479.Ed 480.Pp 481is equivalent to 482.Sq .I foo . 483If next-line macros are invoked consecutively, only the last is used. 484If a next-line macro is followed by a non-next-line macro, an error is 485raised. 486.Pp 487The syntax is as follows: 488.Bd -literal -offset indent 489\&.YO \(lBbody...\(rB 490\(lBbody...\(rB 491.Ed 492.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 493.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 494.It Ic AT Ta <=1 Ta current Ta \& 495.It Ic B Ta n Ta next-line Ta \& 496.It Ic BI Ta n Ta current Ta \& 497.It Ic BR Ta n Ta current Ta \& 498.It Ic DT Ta 0 Ta current Ta \& 499.It Ic EE Ta 0 Ta current Ta GNU 500.It Ic EX Ta 0 Ta current Ta GNU 501.It Ic I Ta n Ta next-line Ta \& 502.It Ic IB Ta n Ta current Ta \& 503.It Ic IR Ta n Ta current Ta \& 504.It Ic OP Ta >=1 Ta current Ta GNU 505.It Ic PD Ta 1 Ta current Ta \& 506.It Ic RB Ta n Ta current Ta \& 507.It Ic RI Ta n Ta current Ta \& 508.It Ic SB Ta n Ta next-line Ta \& 509.It Ic SM Ta n Ta next-line Ta \& 510.It Ic TH Ta >1, <6 Ta current Ta \& 511.It Ic UC Ta <=1 Ta current Ta \& 512.It Ic in Ta 1 Ta current Ta Xr roff 7 513.El 514.Ss Block Macros 515Block macros comprise a head and body. 516As with in-line macros, the head is scoped to the current line and, in 517one circumstance, the next line (the next-line stipulations as in 518.Sx Line Macros 519apply here as well). 520.Pp 521The syntax is as follows: 522.Bd -literal -offset indent 523\&.YO \(lBhead...\(rB 524\(lBhead...\(rB 525\(lBbody...\(rB 526.Ed 527.Pp 528The closure of body scope may be to the section, where a macro is closed 529by 530.Ic SH ; 531sub-section, closed by a section or 532.Ic SS ; 533or paragraph, closed by a section, sub-section, 534.Ic HP , 535.Ic IP , 536.Ic LP , 537.Ic P , 538.Ic PP , 539.Ic RE , 540.Ic SY , 541or 542.Ic TP . 543No closure refers to an explicit block closing macro. 544.Pp 545As a rule, block macros may not be nested; thus, calling a block macro 546while another block macro scope is open, and the open scope is not 547implicitly closed, is syntactically incorrect. 548.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 549.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 550.It Ic HP Ta <2 Ta current Ta paragraph Ta \& 551.It Ic IP Ta <3 Ta current Ta paragraph Ta \& 552.It Ic LP Ta 0 Ta current Ta paragraph Ta \& 553.It Ic ME Ta 0 Ta none Ta none Ta GNU 554.It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU 555.It Ic P Ta 0 Ta current Ta paragraph Ta \& 556.It Ic PP Ta 0 Ta current Ta paragraph Ta \& 557.It Ic RE Ta <=1 Ta current Ta none Ta \& 558.It Ic RS Ta 1 Ta current Ta to \&RE Ta \& 559.It Ic SH Ta >0 Ta next-line Ta section Ta \& 560.It Ic SS Ta >0 Ta next-line Ta sub-section Ta \& 561.It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU 562.It Ic TP Ta n Ta next-line Ta paragraph Ta \& 563.It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU 564.It Ic UE Ta 0 Ta current Ta none Ta GNU 565.It Ic UR Ta 1 Ta current Ta part Ta GNU 566.It Ic YS Ta 0 Ta none Ta none Ta GNU 567.El 568.Pp 569If a block macro is next-line scoped, it may only be followed by in-line 570macros for decorating text. 571.Ss Font handling 572In 573.Nm 574documents, both 575.Sx Physical markup 576macros and 577.Xr roff 7 578.Ql \ef 579font escape sequences can be used to choose fonts. 580In text lines, the effect of manual font selection by escape sequences 581only lasts until the next macro invocation; in macro lines, it only lasts 582until the end of the macro scope. 583Note that macros like 584.Ic BR 585open and close a font scope for each argument. 586.Sh SEE ALSO 587.Xr man 1 , 588.Xr mandoc 1 , 589.Xr eqn 7 , 590.Xr mandoc_char 7 , 591.Xr mdoc 7 , 592.Xr roff 7 , 593.Xr tbl 7 594.Sh HISTORY 595The 596.Nm 597language first appeared as a macro package for the roff typesetting 598system in 599.At v7 . 600It was later rewritten by James Clark as a macro package for groff. 601Eric S. Raymond wrote the extended 602.Nm 603macros for groff in 2007. 604The stand-alone implementation that is part of the 605.Xr mandoc 1 606utility written by Kristaps Dzonsons appeared in 607.Ox 4.6 . 608.Sh AUTHORS 609This 610.Nm 611reference was written by 612.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 613