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