1.\" $Id: roff.7,v 1.29 2011/05/24 15:22:14 kristaps Exp $ 2.\" 3.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: May 24 2011 $ 19.Dt ROFF 7 20.Os 21.Sh NAME 22.Nm roff 23.Nd roff language reference for mandoc 24.Sh DESCRIPTION 25The 26.Nm roff 27language is a general purpose text formatting language. 28In particular, it serves as the basis for the 29.Xr mdoc 7 30and 31.Xr man 7 32manual formatting macro languages. 33This manual describes the subset of the 34.Nm 35language accepted by the 36.Xr mandoc 1 37utility. 38.Pp 39Input lines beginning with the control characters 40.Sq \&. 41or 42.Sq \(aq 43are parsed for requests and macros. 44These define the document structure, change the processing state 45and manipulate the formatting. 46Some requests and macros also produce formatted output, 47while others do not. 48.Pp 49All other input lines provide free-form text to be printed; 50the formatting of free-form text depends on the respective 51processing context. 52.Sh LANGUAGE SYNTAX 53.Nm 54documents may contain only graphable 7-bit ASCII characters, the space 55character, and, in certain circumstances, the tab character. 56To produce other characters in the output, use the escape sequences 57documented in the 58.Xr mandoc_char 7 59manual. 60.Sh REQUEST SYNTAX 61A request or macro line consists of: 62.Pp 63.Bl -enum -compact 64.It 65the control character 66.Sq \&. 67or 68.Sq \(aq 69at the beginning of the line, 70.It 71optionally an arbitrary amount of whitespace, 72.It 73the name of the request or the macro, which is one word of arbitrary 74length, terminated by whitespace, 75.It 76and zero or more arguments delimited by whitespace. 77.El 78.Pp 79Thus, the following request lines are all equivalent: 80.Bd -literal -offset indent 81\&.ig end 82\&.ig end 83\&. ig end 84.Ed 85.Sh MACRO SYNTAX 86Macros can be defined by the 87.Sx \&de 88request. 89When called, they follow the same syntax as requests, except that 90macro arguments may optionally be quoted by enclosing them 91in double quote characters 92.Pq Sq \(dq . 93To be recognized as the beginning of a quoted argument, the opening 94quote character must be preceded by a space character. 95.Pp 96A quoted argument may contain whitespace, and pairs of double quote 97characters 98.Pq Sq Qq 99resolve to single double quote characters. 100A quoted argument extends to the next double quote character that is not 101part of a pair, or to the end of the input line, whichever comes earlier. 102Leaving out the terminating double quote character at the end of the line 103is discouraged. 104For clarity, if more arguments follow on the same input line, 105it is recommended to follow the terminating double quote character 106by a space character; in case the next character after the terminating 107double quote character is anything else, it is regarded as the beginning 108of the next, unquoted argument. 109.Pp 110Both in quoted and unquoted arguments, pairs of backslashes 111.Pq Sq \e\e 112resolve to single backslashes. 113In unquoted arguments, space characters can alternatively be included 114by preceding them with a backslash 115.Pq Sq \e\~ , 116but quoting is usually better for clarity. 117.Sh REQUEST REFERENCE 118The 119.Xr mandoc 1 120.Nm 121parser recognizes the following requests. 122Note that the 123.Nm 124language defines many more requests not implemented in 125.Xr mandoc 1 . 126.Ss \&ad 127Set line adjustment mode. 128This line-scoped request is intended to have one argument to select 129normal, left, right, or center adjustment for subsequent text. 130Currently, it is ignored including its arguments, 131and the number of arguments is not checked. 132.Ss \&am 133Append to a macro definition. 134The syntax of this request is the same as that of 135.Sx \&de . 136It is currently ignored by 137.Xr mandoc 1 , 138as are its children. 139.Ss \&ami 140Append to a macro definition, specifying the macro name indirectly. 141The syntax of this request is the same as that of 142.Sx \&dei . 143It is currently ignored by 144.Xr mandoc 1 , 145as are its children. 146.Ss \&am1 147Append to a macro definition, switching roff compatibility mode off 148during macro execution. 149The syntax of this request is the same as that of 150.Sx \&de1 . 151It is currently ignored by 152.Xr mandoc 1 , 153as are its children. 154.Ss \&de 155Define a 156.Nm 157macro. 158Its syntax can be either 159.Bd -literal -offset indent 160.Pf . Cm \&de Ar name 161.Ar macro definition 162\&.. 163.Ed 164.Pp 165or 166.Bd -literal -offset indent 167.Pf . Cm \&de Ar name Ar end 168.Ar macro definition 169.Pf . Ar end 170.Ed 171.Pp 172Both forms define or redefine the macro 173.Ar name 174to represent the 175.Ar macro definition , 176which may consist of one or more input lines, including the newline 177characters terminating each line, optionally containing calls to 178.Nm 179requests, 180.Nm 181macros or high-level macros like 182.Xr man 7 183or 184.Xr mdoc 7 185macros, whichever applies to the document in question. 186.Pp 187Specifying a custom 188.Ar end 189macro works in the same way as for 190.Sx \&ig ; 191namely, the call to 192.Sq Pf . Ar end 193first ends the 194.Ar macro definition , 195and after that, it is also evaluated as a 196.Nm 197request or 198.Nm 199macro, but not as a high-level macro. 200.Pp 201The macro can be invoked later using the syntax 202.Pp 203.D1 Pf . Ar name Op Ar argument Op Ar argument ... 204.Pp 205Regarding argument parsing, see 206.Sx MACRO SYNTAX 207above. 208.Pp 209The line invoking the macro will be replaced 210in the input stream by the 211.Ar macro definition , 212replacing all occurrences of 213.No \e\e$ Ns Ar N , 214where 215.Ar N 216is a digit, by the 217.Ar N Ns th Ar argument . 218For example, 219.Bd -literal -offset indent 220\&.de ZN 221\efI\e^\e\e$1\e^\efP\e\e$2 222\&.. 223\&.ZN XtFree . 224.Ed 225.Pp 226produces 227.Pp 228.D1 \efI\e^XtFree\e^\efP. 229.Pp 230in the input stream, and thus in the output: \fI\^XtFree\^\fP. 231.Pp 232Since macros and user-defined strings share a common string table, 233defining a macro 234.Ar name 235clobbers the user-defined string 236.Ar name , 237and the 238.Ar macro definition 239can also be printed using the 240.Sq \e* 241string interpolation syntax described below 242.Sx ds , 243but this is rarely useful because every macro definition contains at least 244one explicit newline character. 245.Pp 246In order to prevent endless recursion, both groff and 247.Xr mandoc 1 248limit the stack depth for expanding macros and strings 249to a large, but finite number. 250Do not rely on the exact value of this limit. 251.Ss \&dei 252Define a 253.Nm 254macro, specifying the macro name indirectly. 255The syntax of this request is the same as that of 256.Sx \&de . 257It is currently ignored by 258.Xr mandoc 1 , 259as are its children. 260.Ss \&de1 261Define a 262.Nm 263macro that will be executed with 264.Nm 265compatibility mode switched off during macro execution. 266This is a GNU extension not available in traditional 267.Nm 268implementations and not even in older versions of groff. 269Since 270.Xr mandoc 1 271does not implement 272.Nm 273compatibility mode at all, it handles this request as an alias for 274.Sx \&de . 275.Ss \&ds 276Define a user-defined string. 277Its syntax is as follows: 278.Pp 279.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string 280.Pp 281The 282.Ar name 283and 284.Ar string 285arguments are space-separated. 286If the 287.Ar string 288begins with a double-quote character, that character will not be part 289of the string. 290All remaining characters on the input line form the 291.Ar string , 292including whitespace and double-quote characters, even trailing ones. 293.Pp 294The 295.Ar string 296can be interpolated into subsequent text by using 297.No \e* Ns Bq Ar name 298for a 299.Ar name 300of arbitrary length, or \e*(NN or \e*N if the length of 301.Ar name 302is two or one characters, respectively. 303Interpolation can be prevented by escaping the leading backslash; 304that is, an asterisk preceded by an even number of backslashes 305does not trigger string interpolation. 306.Pp 307Since user-defined strings and macros share a common string table, 308defining a string 309.Ar name 310clobbers the macro 311.Ar name , 312and the 313.Ar name 314used for defining a string can also be invoked as a macro, 315in which case the following input line will be appended to the 316.Ar string , 317forming a new input line passed to the 318.Nm 319parser. 320For example, 321.Bd -literal -offset indent 322\&.ds badidea .S 323\&.badidea 324H SYNOPSIS 325.Ed 326.Pp 327invokes the 328.Cm SH 329macro when used in a 330.Xr man 7 331document. 332Such abuse is of course strongly discouraged. 333.Ss \&el 334The 335.Qq else 336half of an if/else conditional. 337Pops a result off the stack of conditional evaluations pushed by 338.Sx \&ie 339and uses it as its conditional. 340If no stack entries are present (e.g., due to no prior 341.Sx \&ie 342calls) 343then false is assumed. 344The syntax of this request is similar to 345.Sx \&if 346except that the conditional is missing. 347.Ss \&EN 348End an equation block. 349See 350.Sx \&EQ . 351.Ss \&EQ 352Begin an equation block. 353See 354.Xr eqn 7 355for a description of the equation language. 356.Ss \&hy 357Set automatic hyphenation mode. 358This line-scoped request is currently ignored. 359.Ss \&ie 360The 361.Qq if 362half of an if/else conditional. 363The result of the conditional is pushed into a stack used by subsequent 364invocations of 365.Sx \&el , 366which may be separated by any intervening input (or not exist at all). 367Its syntax is equivalent to 368.Sx \&if . 369.Ss \&if 370Begins a conditional. 371Right now, the conditional evaluates to true 372if and only if it starts with the letter 373.Sy n , 374indicating processing in nroff style as opposed to troff style. 375If a conditional is false, its children are not processed, but are 376syntactically interpreted to preserve the integrity of the input 377document. 378Thus, 379.Pp 380.D1 \&.if t .ig 381.Pp 382will discard the 383.Sq \&.ig , 384which may lead to interesting results, but 385.Pp 386.D1 \&.if t .if t \e{\e 387.Pp 388will continue to syntactically interpret to the block close of the final 389conditional. 390Sub-conditionals, in this case, obviously inherit the truth value of 391the parent. 392This request has the following syntax: 393.Bd -literal -offset indent 394\&.if COND \e{\e 395BODY... 396\&.\e} 397.Ed 398.Bd -literal -offset indent 399\&.if COND \e{ BODY 400BODY... \e} 401.Ed 402.Bd -literal -offset indent 403\&.if COND \e{ BODY 404BODY... 405\&.\e} 406.Ed 407.Bd -literal -offset indent 408\&.if COND \e 409BODY 410.Ed 411.Pp 412COND is a conditional statement. 413roff allows for complicated conditionals; mandoc is much simpler. 414At this time, mandoc supports only 415.Sq n , 416evaluating to true; 417and 418.Sq t , 419.Sq e , 420and 421.Sq o , 422evaluating to false. 423All other invocations are read up to the next end of line or space and 424evaluate as false. 425.Pp 426If the BODY section is begun by an escaped brace 427.Sq \e{ , 428scope continues until a closing-brace escape sequence 429.Sq \.\e} . 430If the BODY is not enclosed in braces, scope continues until 431the end of the line. 432If the COND is followed by a BODY on the same line, whether after a 433brace or not, then requests and macros 434.Em must 435begin with a control character. 436It is generally more intuitive, in this case, to write 437.Bd -literal -offset indent 438\&.if COND \e{\e 439\&.foo 440bar 441\&.\e} 442.Ed 443.Pp 444than having the request or macro follow as 445.Pp 446.D1 \&.if COND \e{ .foo 447.Pp 448The scope of a conditional is always parsed, but only executed if the 449conditional evaluates to true. 450.Pp 451Note that the 452.Sq \e} 453is converted into a zero-width escape sequence if not passed as a 454standalone macro 455.Sq \&.\e} . 456For example, 457.Pp 458.D1 \&.Fl a \e} b 459.Pp 460will result in 461.Sq \e} 462being considered an argument of the 463.Sq \&Fl 464macro. 465.Ss \&ig 466Ignore input. 467Its syntax can be either 468.Bd -literal -offset indent 469.Pf . Cm \&ig 470.Ar ignored text 471\&.. 472.Ed 473.Pp 474or 475.Bd -literal -offset indent 476.Pf . Cm \&ig Ar end 477.Ar ignored text 478.Pf . Ar end 479.Ed 480.Pp 481In the first case, input is ignored until a 482.Sq \&.. 483request is encountered on its own line. 484In the second case, input is ignored until the specified 485.Sq Pf . Ar end 486macro is encountered. 487Do not use the escape character 488.Sq \e 489anywhere in the definition of 490.Ar end ; 491it would cause very strange behaviour. 492.Pp 493When the 494.Ar end 495macro is a roff request or a roff macro, like in 496.Pp 497.D1 \&.ig if 498.Pp 499the subsequent invocation of 500.Sx \&if 501will first terminate the 502.Ar ignored text , 503then be invoked as usual. 504Otherwise, it only terminates the 505.Ar ignored text , 506and arguments following it or the 507.Sq \&.. 508request are discarded. 509.Ss \&ne 510Declare the need for the specified minimum vertical space 511before the next trap or the bottom of the page. 512This line-scoped request is currently ignored. 513.Ss \&nh 514Turn off automatic hyphenation mode. 515This line-scoped request is currently ignored. 516.Ss \&rm 517Remove a request, macro or string. 518This request is intended to have one argument, 519the name of the request, macro or string to be undefined. 520Currently, it is ignored including its arguments, 521and the number of arguments is not checked. 522.Ss \&nr 523Define a register. 524A register is an arbitrary string value that defines some sort of state, 525which influences parsing and/or formatting. 526Its syntax is as follows: 527.Pp 528.D1 Pf \. Cm \&nr Ar name Ar value 529.Pp 530The 531.Ar value 532may, at the moment, only be an integer. 533So far, only the following register 534.Ar name 535is recognised: 536.Bl -tag -width Ds 537.It Cm nS 538If set to a positive integer value, certain 539.Xr mdoc 7 540macros will behave in the same way as in the 541.Em SYNOPSIS 542section. 543If set to 0, these macros will behave in the same way as outside the 544.Em SYNOPSIS 545section, even when called within the 546.Em SYNOPSIS 547section itself. 548Note that starting a new 549.Xr mdoc 7 550section with the 551.Cm \&Sh 552macro will reset this register. 553.El 554.Ss \&ns 555Turn on no-space mode. 556This line-scoped request is intended to take no arguments. 557Currently, it is ignored including its arguments, 558and the number of arguments is not checked. 559.Ss \&ps 560Change point size. 561This line-scoped request is intended to take one numerical argument. 562Currently, it is ignored including its arguments, 563and the number of arguments is not checked. 564.Ss \&so 565Include a source file. 566Its syntax is as follows: 567.Pp 568.D1 Pf \. Cm \&so Ar file 569.Pp 570The 571.Ar file 572will be read and its contents processed as input in place of the 573.Sq \&.so 574request line. 575To avoid inadvertent inclusion of unrelated files, 576.Xr mandoc 1 577only accepts relative paths not containing the strings 578.Qq ../ 579and 580.Qq /.. . 581.Ss \&ta 582Set tab stops. 583This line-scoped request can take an arbitrary number of arguments. 584Currently, it is ignored including its arguments. 585.Ss \&tr 586Output character translation. 587This request is intended to have one argument, 588consisting of an even number of characters. 589Currently, it is ignored including its arguments, 590and the number of arguments is not checked. 591.Ss \&T& 592Re-start a table layout, retaining the options of the prior table 593invocation. 594See 595.Sx \&TS . 596.Ss \&TE 597End a table context. 598See 599.Sx \&TS . 600.Ss \&TS 601Begin a table, which formats input in aligned rows and columns. 602See 603.Xr tbl 7 604for a description of the tbl language. 605.Sh COMPATIBILITY 606This section documents compatibility between mandoc and other other 607.Nm 608implementations, at this time limited to GNU troff 609.Pq Qq groff . 610The term 611.Qq historic groff 612refers to groff version 1.15. 613.Pp 614.Bl -dash -compact 615.It 616In mandoc, the 617.Sx \&EQ , 618.Sx \&TE , 619.Sx \&TS , 620and 621.Sx \&T& , 622macros are considered regular macros. 623In all other 624.Nm 625implementations, these are special macros that must be specified without 626spacing between the control character (which must be a period) and the 627macro name. 628.It 629The 630.Cm nS 631register is only compatible with OpenBSD's groff-1.15. 632.It 633Historic groff did not accept white-space before a custom 634.Ar end 635macro for the 636.Sx \&ig 637request. 638.It 639The 640.Sx \&if 641and family would print funny white-spaces with historic groff when 642using the next-line syntax. 643.El 644.Sh SEE ALSO 645.Xr mandoc 1 , 646.Xr eqn 7 , 647.Xr man 7 , 648.Xr mandoc_char 7 , 649.Xr mdoc 7 , 650.Xr tbl 7 651.Rs 652.%A Joseph F. Ossanna 653.%A Brian W. Kernighan 654.%I AT&T Bell Laboratories 655.%T Troff User's Manual 656.%R Computing Science Technical Report 657.%N 54 658.%C Murray Hill, New Jersey 659.%D 1976 and 1992 660.%U http://www.kohala.com/start/troff/cstr54.ps 661.Re 662.Rs 663.%A Joseph F. Ossanna 664.%A Brian W. Kernighan 665.%A Gunnar Ritter 666.%T Heirloom Documentation Tools Nroff/Troff User's Manual 667.%D September 17, 2007 668.%U http://heirloom.sourceforge.net/doctools/troff.pdf 669.Re 670.Sh HISTORY 671The RUNOFF typesetting system was written in PL/1 for the CTSS 672operating system by Jerome ("Jerry") E. Saltzer in 1961. 673It was first used as the main documentation tool by Multics since 1963. 674Robert ("Bob") H. Morris ported it to the GE-635 and called it 675.Nm , 676Doug McIlroy rewrote it in BCPL in 1969, 677Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973, 678and Brian W. Kernighan rewrote it in C in 1975. 679.Sh AUTHORS 680.An -nosplit 681This partial 682.Nm 683reference was written by 684.An Kristaps Dzonsons Aq kristaps@bsd.lv 685and 686.An Ingo Schwarze Aq schwarze@openbsd.org . 687