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