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