1.\" $Id: roff.7,v 1.27 2011/02/09 10:03:02 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: February 9 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 text following an 452.Sq \&.\e} 453escape sequence is discarded. 454Furthermore, if an explicit closing sequence 455.Sq \e} 456is specified in a free-form line, the entire line is accepted within the 457scope of the prior request, not only the text preceding the close, with the 458.Sq \e} 459collapsing into a zero-width space. 460.Ss \&ig 461Ignore input. 462Its syntax can be either 463.Bd -literal -offset indent 464.Pf . Cm \&ig 465.Ar ignored text 466\&.. 467.Ed 468.Pp 469or 470.Bd -literal -offset indent 471.Pf . Cm \&ig Ar end 472.Ar ignored text 473.Pf . Ar end 474.Ed 475.Pp 476In the first case, input is ignored until a 477.Sq \&.. 478request is encountered on its own line. 479In the second case, input is ignored until the specified 480.Sq Pf . Ar end 481macro is encountered. 482Do not use the escape character 483.Sq \e 484anywhere in the definition of 485.Ar end ; 486it would cause very strange behaviour. 487.Pp 488When the 489.Ar end 490macro is a roff request or a roff macro, like in 491.Pp 492.D1 \&.ig if 493.Pp 494the subsequent invocation of 495.Sx \&if 496will first terminate the 497.Ar ignored text , 498then be invoked as usual. 499Otherwise, it only terminates the 500.Ar ignored text , 501and arguments following it or the 502.Sq \&.. 503request are discarded. 504.Ss \&ne 505Declare the need for the specified minimum vertical space 506before the next trap or the bottom of the page. 507This line-scoped request is currently ignored. 508.Ss \&nh 509Turn off automatic hyphenation mode. 510This line-scoped request is currently ignored. 511.Ss \&rm 512Remove a request, macro or string. 513This request is intended to have one argument, 514the name of the request, macro or string to be undefined. 515Currently, it is ignored including its arguments, 516and the number of arguments is not checked. 517.Ss \&nr 518Define a register. 519A register is an arbitrary string value that defines some sort of state, 520which influences parsing and/or formatting. 521Its syntax is as follows: 522.Pp 523.D1 Pf \. Cm \&nr Ar name Ar value 524.Pp 525The 526.Ar value 527may, at the moment, only be an integer. 528So far, only the following register 529.Ar name 530is recognised: 531.Bl -tag -width Ds 532.It Cm nS 533If set to a positive integer value, certain 534.Xr mdoc 7 535macros will behave in the same way as in the 536.Em SYNOPSIS 537section. 538If set to 0, these macros will behave in the same way as outside the 539.Em SYNOPSIS 540section, even when called within the 541.Em SYNOPSIS 542section itself. 543Note that starting a new 544.Xr mdoc 7 545section with the 546.Cm \&Sh 547macro will reset this register. 548.El 549.Ss \&ns 550Turn on no-space mode. 551This line-scoped request is intended to take no arguments. 552Currently, it is ignored including its arguments, 553and the number of arguments is not checked. 554.Ss \&ps 555Change point size. 556This line-scoped request is intended to take one numerical argument. 557Currently, it is ignored including its arguments, 558and the number of arguments is not checked. 559.Ss \&so 560Include a source file. 561Its syntax is as follows: 562.Pp 563.D1 Pf \. Cm \&so Ar file 564.Pp 565The 566.Ar file 567will be read and its contents processed as input in place of the 568.Sq \&.so 569request line. 570To avoid inadvertant inclusion of unrelated files, 571.Xr mandoc 1 572only accepts relative paths not containing the strings 573.Qq ../ 574and 575.Qq /.. . 576.Ss \&ta 577Set tab stops. 578This line-scoped request can take an arbitrary number of arguments. 579Currently, it is ignored including its arguments. 580.Ss \&tr 581Output character translation. 582This request is intended to have one argument, 583consisting of an even number of characters. 584Currently, it is ignored including its arguments, 585and the number of arguments is not checked. 586.Ss \&T& 587Re-start a table layout, retaining the options of the prior table 588invocation. 589See 590.Sx \&TS . 591.Ss \&TE 592End a table context. 593See 594.Sx \&TS . 595.Ss \&TS 596Begin a table, which formats input in aligned rows and columns. 597See 598.Xr tbl 7 599for a description of the tbl language. 600.Sh COMPATIBILITY 601This section documents compatibility between mandoc and other other 602.Nm 603implementations, at this time limited to GNU troff 604.Pq Qq groff . 605The term 606.Qq historic groff 607refers to groff version 1.15. 608.Pp 609.Bl -dash -compact 610.It 611In mandoc, the 612.Sx \&EQ , 613.Sx \&TE , 614.Sx \&TS , 615and 616.Sx \&T& , 617macros are considered regular macros. 618In all other 619.Nm 620implementations, these are special macros that must be specified without 621spacing between the control character (which must be a period) and the 622macro name. 623.It 624The 625.Cm nS 626register is only compatible with OpenBSD's groff-1.15. 627.It 628Historic groff did not accept white-space before a custom 629.Ar end 630macro for the 631.Sx \&ig 632request. 633.It 634The 635.Sx \&if 636and family would print funny white-spaces with historic groff when 637using the next-line syntax. 638.El 639.Sh SEE ALSO 640.Xr mandoc 1 , 641.Xr eqn 7 , 642.Xr man 7 , 643.Xr mandoc_char 7 , 644.Xr mdoc 7 , 645.Xr tbl 7 646.Rs 647.%A Joseph F. Ossanna 648.%A Brian W. Kernighan 649.%I AT&T Bell Laboratories 650.%T Troff User's Manual 651.%R Computing Science Technical Report 652.%N 54 653.%C Murray Hill, New Jersey 654.%D 1976 and 1992 655.%U http://www.kohala.com/start/troff/cstr54.ps 656.Re 657.Rs 658.%A Joseph F. Ossanna 659.%A Brian W. Kernighan 660.%A Gunnar Ritter 661.%T Heirloom Documentation Tools Nroff/Troff User's Manual 662.%D September 17, 2007 663.%U http://heirloom.sourceforge.net/doctools/troff.pdf 664.Re 665.Sh HISTORY 666The RUNOFF typesetting system was written in PL/1 for the CTSS 667operating system by Jerome ("Jerry") E. Saltzer in 1961. 668It was first used as the main documentation tool by Multics since 1963. 669Robert ("Bob") H. Morris ported it to the GE-635 and called it 670.Nm , 671Doug McIlroy rewrote it in BCPL in 1969, 672Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973, 673and Brian W. Kernighan rewrote it in C in 1975. 674.Sh AUTHORS 675.An -nosplit 676This partial 677.Nm 678reference was written by 679.An Kristaps Dzonsons Aq kristaps@bsd.lv 680and 681.An Ingo Schwarze Aq schwarze@openbsd.org . 682