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