1This is groff, produced by makeinfo version 4.2 from ./groff.texinfo. 2 3This manual documents GNU `troff' version 1.18. 4 5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc. 6 7 Permission is granted to copy, distribute and/or modify this 8 document under the terms of the GNU Free Documentation License, 9 Version 1.1 or any later version published by the Free Software 10 Foundation; with no Invariant Sections, with the Front-Cover texts 11 being `A GNU Manual," and with the Back-Cover Texts as in (a) 12 below. A copy of the license is included in the section entitled 13 `GNU Free Documentation License." 14 15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and 16 modify this GNU Manual, like GNU software. Copies published by 17 the Free Software Foundation raise funds for GNU development." 18 19INFO-DIR-SECTION Miscellaneous 20START-INFO-DIR-ENTRY 21* Groff: (groff). The GNU troff document formatting system. 22END-INFO-DIR-ENTRY 23 24 25File: groff, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference 26 27Strings 28======= 29 30 `gtroff' has string variables, which are entirely for user 31convenience (i.e. there are no built-in strings exept `.T', but even 32this is a read-write string variable). 33 34 - Request: .ds name [string] 35 - Request: .ds1 name [string] 36 - Escape: \*N 37 - Escape: \*(NM 38 - Escape: \*[NAME ARG1 ARG2 ...] 39 Define and access a string variable NAME (one-character name N, 40 two-character name NM). If NAME already exists, `ds' overwrites 41 the previous definition. Only the syntax form using brackets can 42 take arguments which are handled identically to macro arguments; 43 the single exception is that a closing bracket as an argument must 44 be enclosed in double quotes. *Note Request Arguments::, and 45 *Note Parameters::. 46 47 Example: 48 49 50 .ds foo a \\$1 test 51 . 52 This is \*[foo nice]. 53 => This is a nice test. 54 55 The `\*' escape "interpolates" (expands in-place) a 56 previously-defined string variable. To be more precise, the stored 57 string is pushed onto the input stack which is then parsed by 58 `gtroff'. Similar to number registers, it is possible to nest 59 strings, i.e. string variables can be called within string 60 variables. 61 62 If the string named by the `\*' escape does not exist, it is 63 defined as empty, and a warning of type `mac' is emitted (see 64 *Note Debugging::, for more details). 65 66 *Caution:* Unlike other requests, the second argument to the `ds' 67 request takes up the entire line including trailing spaces. This 68 means that comments on a line with such a request can introduce 69 unwanted space into a string. 70 71 72 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 73 74 Instead the comment should be put on another line or have the 75 comment escape adjacent with the end of the string. 76 77 78 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 79 80 To produce leading space the string can be started with a double 81 quote. No trailing quote is needed; in fact, any trailing quote is 82 included in your string. 83 84 85 .ds sign " Yours in a white wine sauce, 86 87 Strings are not limited to a single line of text. A string can 88 span several lines by escaping the newlines with a backslash. The 89 resulting string is stored _without_ the newlines. 90 91 92 .ds foo lots and lots \ 93 of text are on these \ 94 next several lines 95 96 It is not possible to have real newlines in a string. To put a 97 single double quote character into a string, use two consecutive 98 double quote characters. 99 100 The `ds1' request turns off compatibility mode while interpreting 101 a string. To be more precise, a "compatibility save" input token 102 is inserted at the beginning of the string, and a "compatibility 103 restore" input token at the end. 104 105 106 .nr xxx 12345 107 .ds aa The value of xxx is \\n[xxx]. 108 .ds1 bb The value of xxx ix \\n[xxx]. 109 . 110 .cp 1 111 . 112 \*(aa 113 => warning: number register `[' not defined 114 => The value of xxx is 0xxx]. 115 \*(bb 116 => The value of xxx ix 12345. 117 118 Strings, macros, and diversions (and boxes) share the same name 119 space. Internally, even the same mechanism is used to store them. 120 This has some interesting consequences. For example, it is 121 possible to call a macro with string syntax and vice versa. 122 123 124 .de xxx 125 a funny test. 126 .. 127 This is \*[xxx] 128 => This is a funny test. 129 130 .ds yyy a funny test 131 This is 132 .yyy 133 => This is a funny test. 134 135 Diversions and boxes can be also called with string syntax. 136 137 Another consequence is that you can copy one-line diversions or 138 boxes to a string. 139 140 141 .di xxx 142 a \fItest\fR 143 .br 144 .di 145 .ds yyy This is \*[xxx]\c 146 \*[yyy]. 147 => This is a test. 148 149 As the previous example shows, it is possible to store formatted 150 output in strings. The `\c' escape prevents the insertion of an 151 additional blank line in the output. 152 153 Copying diversions longer than a single output line produces 154 unexpected results. 155 156 157 .di xxx 158 a funny 159 .br 160 test 161 .br 162 .di 163 .ds yyy This is \*[xxx]\c 164 \*[yyy]. 165 => test This is a funny. 166 167 Usually, it is not predictable whether a diversion contains one or 168 more output lines, so this mechanism should be avoided. With UNIX 169 `troff', this was the only solution to strip off a final newline 170 from a diversion. Another disadvantage is that the spaces in the 171 copied string are already formatted, making them unstretchable. 172 This can cause ugly results. 173 174 A clean solution to this problem is available in GNU `troff', 175 using the requests `chop' to remove the final newline of a 176 diversion, and `unformat' to make the horizontal spaces 177 stretchable again. 178 179 180 .box xxx 181 a funny 182 .br 183 test 184 .br 185 .box 186 .chop xxx 187 .unformat xxx 188 This is \*[xxx]. 189 => This is a funny test. 190 191 *Note Gtroff Internals::, for more information. 192 193 - Request: .as name [string] 194 - Request: .as1 name [string] 195 The `as' request is similar to `ds' but appends STRING to the 196 string stored as NAME instead of redefining it. If NAME doesn't 197 exist yet, it is created. 198 199 200 .as sign " with shallots, onions and garlic, 201 202 The `as1' request is similar to `as', but compatibility mode is 203 switched off while the appended string is interpreted. To be more 204 precise, a "compatibility save" input token is inserted at the 205 beginning of the appended string, and a "compatibility restore" 206 input token at the end. 207 208 Rudimentary string manipulation routines are given with the next two 209requests. 210 211 - Request: .substring str n1 [n2] 212 Replace the string named STR with the substring defined by the 213 indices N1 and N2. The first character in the string has index 0. 214 If N2 is omitted, it is taken to be equal to the string's length. 215 If the index value N1 or N2 is negative, it is counted from the 216 end of the string, going backwards: The last character has 217 index -1, the character before the last character has index -2, 218 etc. 219 220 221 .ds xxx abcdefgh 222 .substring xxx 1 -4 223 \*[xxx] 224 => bcde 225 226 227 - Request: .length reg str 228 Compute the number of characters of STR and return it in the 229 number register REG. If REG doesn't exist, it is created. `str' 230 is read in copy mode. 231 232 233 .ds xxx abcd\h'3i'efgh 234 .length yyy \n[xxx] 235 \n[yyy] 236 => 14 237 238 239 - Request: .rn xx yy 240 Rename the request, macro, diversion, or string XX to YY. 241 242 - Request: .rm xx 243 Remove the request, macro, diversion, or string XX. `gtroff' 244 treats subsequent invocations as if the object had never been 245 defined. 246 247 - Request: .als new old 248 Create an alias named NEW for the request, string, macro, or 249 diversion object named OLD. The new name and the old name are 250 exactly equivalent (it is similar to a hard rather than a soft 251 link). If OLD is undefined, `gtroff' generates a warning of type 252 `mac' and ignores the request. 253 254 - Request: .chop xx 255 Remove (chop) the last character from the macro, string, or 256 diversion named XX. This is useful for removing the newline from 257 the end of diversions that are to be interpolated as strings. 258 This command can be used repeatedly; see *Note Gtroff Internals::, 259 for details on nodes inserted additionally by `gtroff'. 260 261 *Note Identifiers::, and *Note Comments::. 262 263 264File: groff, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference 265 266Conditionals and Loops 267====================== 268 269* Menu: 270 271* Operators in Conditionals:: 272* if-else:: 273* while:: 274 275 276File: groff, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops 277 278Operators in Conditionals 279------------------------- 280 281 In `if' and `while' requests, there are several more operators 282available: 283 284`e' 285`o' 286 True if the current page is even or odd numbered (respectively). 287 288`n' 289 True if the document is being processed in nroff mode (i.e., the 290 `.nroff' command has been issued). 291 292`t' 293 True if the document is being processed in troff mode (i.e., the 294 `.troff' command has been issued). 295 296`v' 297 Always false. This condition is for compatibility with other 298 `troff' versions only. 299 300`'XXX'YYY'' 301 True if the string XXX is equal to the string YYY. Other 302 characters can be used in place of the single quotes; the same set 303 of delimiters as for the `\D' escape is used (*note Escapes::). 304 `gtroff' formats the strings before being compared: 305 306 307 .ie "|"\fR|\fP" \ 308 true 309 .el \ 310 false 311 => true 312 313 The resulting motions, glyph sizes, and fonts have to match,(1) 314 (*note Operators in Conditionals-Footnote-1::) and not the 315 individual motion, size, and font requests. In the previous 316 example, `|' and `\fR|\fP' both result in a roman `|' glyph with 317 the same point size and at the same location on the page, so the 318 strings are equal. If `.ft I' had been added before the `.ie', 319 the result would be "false" because (the first) `|' produces an 320 italic `|' rather than a roman one. 321 322`r XXX' 323 True if there is a number register named XXX. 324 325`d XXX' 326 True if there is a string, macro, diversion, or request named XXX. 327 328`m XXX' 329 True if there is a color named XXX. 330 331`c G' 332 True if there is a glyph G available(2) (*note Operators in 333 Conditionals-Footnote-2::); G is either an ASCII character or a 334 special character (`\(GG' or `\[GGG]'); the condition is also true 335 if G has been defined by the `char' request. 336 337 Note that these operators can't be combined with other operators like 338`:' or `&'; only a leading `!' (without whitespace between the 339exclamation mark and the operator) can be used to negate the result. 340 341 342 .nr xxx 1 343 .ie !r xxx \ 344 true 345 .el \ 346 false 347 => false 348 349 A whitespace after `!' always evaluates to zero (this bizarre 350behaviour is due to compatibility with UNIX `troff'). 351 352 353 .nr xxx 1 354 .ie ! r xxx \ 355 true 356 .el \ 357 false 358 => r xxx true 359 360 It is possible to omit the whitespace before the argument to the 361`r', `d', and `c' operators. 362 363 *Note Expressions::. 364 365 366File: groff, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals 367 368 (1) The created output nodes must be identical. *Note Gtroff 369Internals::. 370 371 (2) The name of this conditional operator is a misnomer since it 372tests names of output glyphs. 373 374 375File: groff, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops 376 377if-else 378------- 379 380 `gtroff' has if-then-else constructs like other languages, although 381the formatting can be painful. 382 383 - Request: .if expr anything 384 Evaluate the expression EXPR, and executes ANYTHING (the remainder 385 of the line) if EXPR evaluates to non-zero (true). ANYTHING is 386 interpreted as though it was on a line by itself (except that 387 leading spaces are swallowed). *Note Expressions::, for more info. 388 389 390 .nr xxx 1 391 .nr yyy 2 392 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 393 => true 394 395 396 - Request: .nop anything 397 Executes ANYTHING. This is similar to `.if 1'. 398 399 - Request: .ie expr anything 400 - Request: .el anything 401 Use the `ie' and `el' requests to write an if-then-else. The 402 first request is the `if' part and the latter is the `else' part. 403 404 405 .ie n .ls 2 \" double-spacing in nroff 406 .el .ls 1 \" single-spacing in troff 407 408 409 - Escape: \{ 410 - Escape: \} 411 In many cases, an if (or if-else) construct needs to execute more 412 than one request. This can be done using the `\{' and `\}' 413 escapes. The following example shows the possible ways to use 414 these escapes (note the position of the opening and closing 415 braces). 416 417 418 .ie t \{\ 419 . ds lq `` 420 . ds rq '' 421 .\} 422 .el \ 423 .\{\ 424 . ds lq " 425 . ds rq "\} 426 427 428 *Note Expressions::. 429 430 431File: groff, Node: while, Prev: if-else, Up: Conditionals and Loops 432 433while 434----- 435 436 `gtroff' provides a looping construct using the `while' request, 437which is used much like the `if' (and related) requests. 438 439 - Request: .while expr anything 440 Evaluate the expression EXPR, and repeatedly execute ANYTHING (the 441 remainder of the line) until EXPR evaluates to 0. 442 443 444 .nr a 0 1 445 .while (\na < 9) \{\ 446 \n+a, 447 .\} 448 \n+a 449 => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 450 451 Some remarks. 452 453 * The body of a `while' request is treated like the body of a 454 `de' request: `gtroff' temporarily stores it in a macro which 455 is deleted after the loop has been exited. It can 456 considerably slow down a macro if the body of the `while' 457 request (within the macro) is large. Each time the macro is 458 executed, the `while' body is parsed and stored again as a 459 temporary macro. 460 461 462 .de xxx 463 . nr num 10 464 . while (\\n[num] > 0) \{\ 465 . \" many lines of code 466 . nr num -1 467 . \} 468 .. 469 470 The traditional and ofter better solution (UNIX `troff' 471 doesn't have the `while' request) is to use a recursive macro 472 instead which is parsed only once during its definition. 473 474 475 .de yyy 476 . if (\\n[num] > 0) \{\ 477 . \" many lines of code 478 . nr num -1 479 . yyy 480 . \} 481 .. 482 . 483 .de xxx 484 . nr num 10 485 . yyy 486 .. 487 488 Note that the number of available recursion levels is set 489 to 1000 (this is a compile-time constant value of `gtroff'). 490 491 * The closing brace of a `while' body must end a line. 492 493 494 .if 1 \{\ 495 . nr a 0 1 496 . while (\n[a] < 10) \{\ 497 . nop \n+[a] 498 .\}\} 499 => unbalanced \{ \} 500 501 502 - Request: .break 503 Break out of a `while' loop. Be sure not to confuse this with the 504 `br' request (causing a line break). 505 506 - Request: .continue 507 Finish the current iteration of a `while' loop, immediately 508 restarting the next iteration. 509 510 *Note Expressions::. 511 512 513File: groff, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference 514 515Writing Macros 516============== 517 518 A "macro" is a collection of text and embedded commands which can be 519invoked multiple times. Use macros to define common operations. 520 521 - Request: .de name [end] 522 - Request: .de1 name [end] 523 - Request: .dei name [end] 524 Define a new macro named NAME. `gtroff' copies subsequent lines 525 (starting with the next one) into an internal buffer until it 526 encounters the line `..' (two dots). The optional second argument 527 to `de' changes this to a macro to `.END'. 528 529 There can be whitespace after the first dot in the line containing 530 the ending token (either `.' or macro `END'). 531 532 Here a small example macro called `P' which causes a break and 533 inserts some vertical space. It could be used to separate 534 paragraphs. 535 536 537 .de P 538 . br 539 . sp .8v 540 .. 541 542 The following example defines a macro within another. Remember 543 that expansion must be protected twice; once for reading the macro 544 and once for executing. 545 546 547 \# a dummy macro to avoid a warning 548 .de end 549 .. 550 . 551 .de foo 552 . de bar end 553 . nop \f[B]Hallo \\\\$1!\f[] 554 . end 555 .. 556 . 557 .foo 558 .bar Joe 559 => Hallo Joe! 560 561 Since `\f' has no expansion, it isn't necessary to protect its 562 backslash. Had we defined another macro within `bar' which takes 563 a parameter, eight backslashes would be necessary before `$1'. 564 565 The `de1' request turns off compatibility mode while executing the 566 macro. On entry, the current compatibility mode is saved and 567 restored at exit. 568 569 570 .nr xxx 12345 571 . 572 .de aa 573 The value of xxx is \\n[xxx]. 574 .. 575 .de1 bb 576 The value of xxx ix \\n[xxx]. 577 .. 578 . 579 .cp 1 580 . 581 .aa 582 => warning: number register ' not defined 583 => The value of xxx is 0xxx]. 584 .bb 585 => The value of xxx ix 12345. 586 587 The `dei' request defines a macro indirectly. That is, it expands 588 strings whose names are NAME or END before performing the append. 589 590 This: 591 592 593 .ds xx aa 594 .ds yy bb 595 .dei xx yy 596 597 is equivalent to: 598 599 600 .de aa bb 601 602 Using `trace.tmac', you can trace calls to `de' and `de1'. 603 604 Note that macro identifiers are shared with identifiers for 605 strings and diversions. 606 607 - Request: .am xx 608 - Request: .am1 xx 609 - Request: .ami xx yy 610 Works similarly to `de' except it appends onto the macro named XX. 611 So, to make the previously defined `P' macro actually do indented 612 instead of block paragraphs, add the necessary code to the 613 existing macro like this: 614 615 616 .am P 617 .ti +5n 618 .. 619 620 The `am1' request turns off compatibility mode while executing the 621 appended macro piece. To be more precise, a "compatibility save" 622 input token is inserted at the beginning of the appended code, and 623 a "compatibility restore" input token at the end. 624 625 The `ami' request appends indirectly, meaning that `gtroff' 626 expands strings whose names are XX or YY before performing the 627 append. 628 629 Using `trace.tmac', you can trace calls to `am' and `am1'. 630 631 *Note Strings::, for the `als' request to rename a macro. 632 633 The `de', `am', `di', `da', `ds', and `as' requests (together with 634its variants) only create a new object if the name of the macro, 635diversion or string diversion is currently undefined or if it is 636defined to be a request; normally they modify the value of an existing 637object. 638 639 - Request: .return 640 Exit a macro, immediately returning to the caller. 641 642* Menu: 643 644* Copy-in Mode:: 645* Parameters:: 646 647 648File: groff, Node: Copy-in Mode, Next: Parameters, Prev: Writing Macros, Up: Writing Macros 649 650Copy-in Mode 651------------ 652 653 When `gtroff' reads in the text for a macro, string, or diversion, 654it copies the text (including request lines, but excluding escapes) into 655an internal buffer. Escapes are converted into an internal form, 656except for `\n', `\$', `\*', `\\' and `\<RET>' which are evaluated and 657inserted into the text where the escape was located. This is known as 658"copy-in" mode or "copy" mode. 659 660 What this means is that you can specify when these escapes are to be 661evaluated (either at copy-in time or at the time of use) by insulating 662the escapes with an extra backslash. Compare this to the `\def' and 663`\edef' commands in TeX. 664 665 The following example prints the numbers 20 and 10: 666 667 668 .nr x 20 669 .de y 670 .nr x 10 671 \&\nx 672 \&\\nx 673 .. 674 .y 675 676 677File: groff, Node: Parameters, Prev: Copy-in Mode, Up: Writing Macros 678 679Parameters 680---------- 681 682 The arguments to a macro or string can be examined using a variety of 683escapes. 684 685 - Register: \n[.$] 686 The number of arguments passed to a macro or string. This is a 687 read-only number register. 688 689 Any individual argument can be retrieved with one of the following 690escapes: 691 692 - Escape: \$N 693 - Escape: \$(NN 694 - Escape: \$[NNN] 695 Retrieve the Nth, NNth or NNNth argument. As usual, the first 696 form only accepts a single number (larger than zero), the second a 697 two-digit number (larger or equal to 10), and the third any 698 positive integer value (larger than zero). Macros and strings can 699 have an unlimited number of arguments. Note that due to copy-in 700 mode, use two backslashes on these in actual use to prevent 701 interpolation until the macro is actually invoked. 702 703 - Request: .shift [n] 704 Shift the arguments 1 position, or as many positions as specified 705 by its argument. After executing this request, argument I becomes 706 argument I-N; arguments 1 to N are no longer available. Shifting 707 by negative amounts is currently undefined. 708 709 - Escape: \$* 710 - Escape: \$@ 711 In some cases it is convenient to use all of the arguments at once 712 (for example, to pass the arguments along to another macro). The 713 `\$*' escape concatenates all the arguments separated by spaces. A 714 similar escape is `\$@', which concatenates all the arguments with 715 each surrounded by double quotes, and separated by spaces. If not 716 in compatibility mode, the input level of double quotes is 717 preserved (see *Note Request Arguments::). 718 719 - Escape: \$0 720 The name used to invoke the current macro. The `als' request can 721 make a macro have more than one name. 722 723 724 .de generic-macro 725 . ... 726 . if \\n[error] \{\ 727 . tm \\$0: Houston, we have a problem. 728 . return 729 . \} 730 .. 731 . 732 .als foo generic-macro 733 .als bar generic-macro 734 735 736 *Note Request Arguments::. 737 738 739File: groff, Node: Page Motions, Next: Drawing Requests, Prev: Writing Macros, Up: gtroff Reference 740 741Page Motions 742============ 743 744 *Note Manipulating Spacing::, for a discussion of the main request 745for vertical motion, `sp'. 746 747 - Request: .mk [reg] 748 - Request: .rt [dist] 749 The request `mk' can be used to mark a location on a page, for 750 movement to later. This request takes a register name as an 751 argument in which to store the current page location. With no 752 argument it stores the location in an internal register. The 753 results of this can be used later by the `rt' or the `sp' request 754 (or the `\v' escape). 755 756 The `rt' request returns _upwards_ to the location marked with the 757 last `mk' request. If used with an argument, return to a position 758 which distance from the top of the page is DIST (no previous call 759 to `mk' is necessary in this case). Default scaling indicator is 760 `v'. 761 762 Here a primitive solution for a two-column macro. 763 764 765 .nr column-length 1.5i 766 .nr column-gap 4m 767 .nr bottom-margin 1m 768 . 769 770 771 .de 2c 772 . br 773 . mk 774 . ll \\n[column-length]u 775 . wh -\\n[bottom-margin]u 2c-trap 776 . nr right-side 0 777 .. 778 . 779 780 781 .de 2c-trap 782 . ie \\n[right-side] \{\ 783 . nr right-side 0 784 . po -(\\n[column-length]u + \\n[column-gap]u) 785 . \" remove trap 786 . wh -\\n[bottom-margin]u 787 . \} 788 . el \{\ 789 . \" switch to right side 790 . nr right-side 1 791 . po +(\\n[column-length]u + \\n[column-gap]u) 792 . rt 793 . \} 794 .. 795 . 796 797 798 .pl 1.5i 799 .ll 4i 800 This is a small test which shows how the 801 rt request works in combination with mk. 802 803 .2c 804 Starting here, text is typeset in two columns. 805 Note that this implementation isn't robust 806 and thus not suited for a real two-column 807 macro. 808 809 Result: 810 811 812 This is a small test which shows how the 813 rt request works in combination with mk. 814 815 Starting here, isn't robust 816 text is typeset and thus not 817 in two columns. suited for a 818 Note that this real two-column 819 implementation macro. 820 821 822 The following escapes give fine control of movements about the page. 823 824 - Escape: \v'E' 825 Move vertically, usually from the current location on the page (if 826 no absolute position operator `|' is used). The argument E 827 specifies the distance to move; positive is downwards and negative 828 upwards. The default scaling indicator for this escape is `v'. 829 Beware, however, that `gtroff' continues text processing at the 830 point where the motion ends, so you should always balance motions 831 to avoid interference with text processing. 832 833 `\v' doesn't trigger a trap. This can be quite useful; for 834 example, consider a page bottom trap macro which prints a marker 835 in the margin to indicate continuation of a footnote or something 836 similar. 837 838 There are some special-case escapes for vertical motion. 839 840 - Escape: \r 841 Move upwards 1v. 842 843 - Escape: \u 844 Move upwards .5v. 845 846 - Escape: \d 847 Move down .5v. 848 849 - Escape: \h'E' 850 Move horizontally, usually from the current location (if no 851 absolute position operator `|' is used). The expression E 852 indicates how far to move: positive is rightwards and negative 853 leftwards. The default scaling indicator for this escape is `m'. 854 855 There are a number of special-case escapes for horizontal motion. 856 857 - Escape: \<SP> 858 An unbreakable and unpaddable (i.e. not expanded during filling) 859 space. (Note: This is a backslash followed by a space.) 860 861 - Escape: \~ 862 An unbreakable space that stretches like a normal inter-word space 863 when a line is adjusted. 864 865 - Escape: \| 866 A 1/6th em space. Ignored for TTY output devices (rounded to 867 zero). 868 869 - Escape: \^ 870 A 1/12th em space. Ignored for TTY output devices (rounded to 871 zero). 872 873 - Escape: \0 874 A space the size of a digit. 875 876 The following string sets the TeX logo: 877 878 879 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 880 881 - Escape: \w'TEXT' 882 - Register: \n[st] 883 - Register: \n[sb] 884 - Register: \n[rst] 885 - Register: \n[rsb] 886 - Register: \n[ct] 887 - Register: \n[ssc] 888 - Register: \n[skw] 889 Return the width of the specified TEXT in basic units. This 890 allows horizontal movement based on the width of some arbitrary 891 text (e.g. given as an argument to a macro). 892 893 894 The length of the string `abc' is \w'abc'u. 895 => The length of the string `abc' is 72u. 896 897 Font changes may occur in TEXT which don't affect current settings. 898 899 After use, `\w' sets several registers: 900 901 `st' 902 `sb' 903 The highest and lowest point of the baseline, respectively, 904 in TEXT. 905 906 `rst' 907 `rsb' 908 Like the `st' and `sb' registers, but takes account of the 909 heights and depths of glyphs. With other words, this gives 910 the highest and lowest point of TEXT. 911 912 `ct' 913 Defines the kinds of glyphs occurring in TEXT: 914 915 0 916 only short glyphs, no descenders or tall glyphs. 917 918 1 919 at least one descender. 920 921 2 922 at least one tall glyph. 923 924 3 925 at least one each of a descender and a tall glyph. 926 927 `ssc' 928 The amount of horizontal space (possibly negative) that 929 should be added to the last glyph before a subscript. 930 931 `skw' 932 How far to right of the center of the last glyph in the `\w' 933 argument, the center of an accent from a roman font should be 934 placed over that glyph. 935 936 - Escape: \kP 937 - Escape: \k(PS 938 - Escape: \k[POSITION] 939 Store the current horizontal position in the _input_ line in 940 number register with name POSITION (one-character name P, 941 two-character name PS). Use this, for example, to return to the 942 beginning of a string for highlighting or other decoration. 943 944 - Register: \n[hp] 945 The current horizontal position at the input line. 946 947 - Register: \n[.k] 948 A read-only number register containing the current horizontal 949 output position. 950 951 - Escape: \o'ABC' 952 Overstrike glyphs A, B, C, ...; the glyphs are centered, and the 953 resulting spacing is the largest width of the affected glyphs. 954 955 - Escape: \zG 956 Print glyph G with zero width, i.e., without spacing. Use this to 957 overstrike glyphs left-aligned. 958 959 - Escape: \Z'ANYTHING' 960 Print ANYTHING, then restore the horizontal and vertical position. 961 The argument may not contain tabs or leaders. 962 963 The following is an example of a strike-through macro: 964 965 966 .de ST 967 .nr ww \w'\\$1' 968 \Z@\v'-.25m'\l'\\n[ww]u'@\\$1 969 .. 970 . 971 This is 972 .ST "a test" 973 an actual emergency! 974 975 976 977File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference 978 979Drawing Requests 980================ 981 982 `gtroff' provides a number of ways to draw lines and other figures 983on the page. Used in combination with the page motion commands (see 984*Note Page Motions::, for more info), a wide variety of figures can be 985drawn. However, for complex drawings these operations can be quite 986cumbersome, and it may be wise to use graphic preprocessors like `gpic' 987or `ggrn'. *Note gpic::, and *Note ggrn::, for more information. 988 989 All drawing is done via escapes. 990 991 - Escape: \l'L' 992 - Escape: \l'LG' 993 Draw a line horizontally. L is the length of the line to be 994 drawn. If it is positive, start the line at the current location 995 and draw to the right; its end point is the new current location. 996 Negative values are handled differently: The line starts at the 997 current location and draws to the left, but the current location 998 doesn't move. 999 1000 L can also be specified absolutely (i.e. with a leading `|') which 1001 draws back to the beginning of the input line. Default scaling 1002 indicator is `m'. 1003 1004 The optional second parameter G is a glyph to draw the line with. 1005 If this second argument is not specified, `gtroff' uses the 1006 underscore glyph, `\[ru]'. 1007 1008 To separate the two arguments (to prevent `gtroff' from 1009 interpreting a drawing glyph as a scaling indicator if the glyph is 1010 represented by a single character) use `\&'. 1011 1012 Here a small useful example: 1013 1014 1015 .de box 1016 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 1017 .. 1018 1019 Note that this works by outputting a box rule (a vertical line), 1020 then the text given as an argument and then another box rule. 1021 Finally, the line drawing escapes both draw from the current 1022 location to the beginning of the _input_ line - this works because 1023 the line length is negative, not moving the current point. 1024 1025 - Escape: \L'L' 1026 - Escape: \L'LG' 1027 Draw vertical lines. Its parameters are similar to the `\l' 1028 escape, except that the default scaling indicator is `v'. The 1029 movement is downwards for positive values, and upwards for 1030 negative values. The default glyph is the box rule glyph, 1031 `\[br]'. As with the vertical motion escapes, text processing 1032 blindly continues where the line ends. 1033 1034 1035 This is a \L'3v'test. 1036 1037 Here the result, produced with `grotty'. 1038 1039 1040 This is a 1041 | 1042 | 1043 |test. 1044 1045 1046 - Escape: \D'COMMAND ARG ...' 1047 The `\D' escape provides a variety of drawing functions. Note 1048 that on character devices, only vertical and horizontal lines are 1049 supported within `grotty'; other devices may only support a subset 1050 of the available drawing functions. 1051 1052 The default scaling indicator for all subcommands of `\D' is `m' 1053 for horizontal distances and `v' for vertical ones. Exceptions 1054 are `\D'f ...'' and `\D't ...'' which use `u' as the default. 1055 1056 `\D'l DX DY'' 1057 Draw a line from the current location to the relative point 1058 specified by (DX,DY). 1059 1060 The following example is a macro for creating a box around a 1061 text string; for simplicity, the box margin is taken as a 1062 fixed value, 0.2m. 1063 1064 1065 .de BOX 1066 . nr @wd \w'\\$1' 1067 \h'.2m'\ 1068 \h'-.2m'\v'(.2m - \\n[rsb]u)'\ 1069 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 1070 \D'l (\\n[@wd]u + .4m) 0'\ 1071 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 1072 \D'l -(\\n[@wd]u + .4m) 0'\ 1073 \h'.2m'\v'-(.2m - \\n[rsb]u)'\ 1074 \\$1\ 1075 \h'.2m' 1076 .. 1077 1078 First, the width of the string is stored in register `@wd'. 1079 Then, four lines are drawn to form a box, properly offset by 1080 the box margin. The registers `rst' and `rsb' are set by the 1081 `\w' escape, containing the largest height and depth of the 1082 whole string. 1083 1084 `\D'c D'' 1085 Draw a circle with a diameter of D with the leftmost point at 1086 the current position. 1087 1088 `\D'C D'' 1089 Draw a solid circle with the same parameters as an outlined 1090 circle. No outline is drawn. 1091 1092 `\D'e X Y'' 1093 Draw an ellipse with a horizontal diameter of X and a vertical 1094 diameter of Y with the leftmost point at the current position. 1095 1096 `\D'E X Y'' 1097 Draw a solid ellipse with the same parameters as an outlined 1098 ellipse. No outline is drawn. 1099 1100 `\D'a DX1 DY1 DX2 DY2'' 1101 Draw an arc clockwise from the current location through the 1102 two specified relative locations (DX1,DY1) and (DX2,DY2). 1103 The coordinates of the first point are relative to the 1104 current position, and the coordinates of the second point are 1105 relative to the first point. 1106 1107 `\D'~ DX1 DY1 DX2 DY2 ...'' 1108 Draw a spline from the current location to the relative point 1109 (DX1,DY1) and then to (DX2,DY2), and so on. 1110 1111 `\D'f N'' 1112 Set the shade of gray to be used for filling solid objects 1113 to N; N must be an integer between 0 and 1000, where 0 1114 corresponds solid white and 1000 to solid black, and values 1115 in between correspond to intermediate shades of gray. This 1116 applies only to solid circles, solid ellipses, and solid 1117 polygons. By default, a level of 1000 is used. 1118 1119 `\D'p DX1 DY1 DX2 DY2 ...'' 1120 Draw a polygon from the current location to the relative 1121 position (DX1,DY1) and then to (DX2,DY2) and so on. When the 1122 specified data points are exhausted, a line is drawn back to 1123 the starting point. 1124 1125 `\D'P DX1 DY1 DX2 DY2 ...'' 1126 Draw a solid polygon with the same parameters as an outlined 1127 polygon. No outline is drawn. 1128 1129 Here a better variant of the box macro to fill the box with 1130 some color. Note that the box must be drawn before the text 1131 since colors in `gtroff' are not transparent; the filled 1132 polygon would hide the text completely. 1133 1134 1135 .de BOX 1136 . nr @wd \w'\\$1' 1137 \h'.2m'\ 1138 \h'-.2m'\v'(.2m - \\n[rsb]u)'\ 1139 \M[lightcyan]\ 1140 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 1141 (\\n[@wd]u + .4m) 0 \ 1142 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 1143 -(\\n[@wd]u + .4m) 0'\ 1144 \h'.2m'\v'-(.2m - \\n[rsb]u)'\ 1145 \M[]\ 1146 \\$1\ 1147 \h'.2m' 1148 .. 1149 1150 `\D't N'' 1151 Set the current line thickness to N machine units. A value of 1152 zero selects the smallest available line thickness. A 1153 negative value makes the line thickness proportional to the 1154 current point size (this is the default behaviour of AT&T 1155 `troff'). 1156 1157 *Note Graphics Commands::. 1158 1159 - Escape: \b'STRING' 1160 "Pile" a sequence of glyphs vertically, and center it vertically 1161 on the current line. Use it to build large brackets and braces. 1162 1163 Here an example how to create a large opening brace: 1164 1165 1166 \b'\[lt]\[bv]\[lk]\[bv]\[lb]' 1167 1168 The first glyph is on the top, the last glyph in STRING is at the 1169 bottom. Note that `gtroff' separates the glyphs vertically by 1m, 1170 and the whole object is centered 0.5m above the current baseline; 1171 the largest glyph width is used as the width for the whole object. 1172 This rather unflexible positioning algorithm doesn't work with 1173 `-Tdvi' since the bracket pieces vary in height for this device. 1174 Instead, use the `eqn' preprocessor. 1175 1176 *Note Manipulating Spacing::, how to adjust the vertical spacing 1177 with the `\x' escape. 1178 1179 1180File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference 1181 1182Traps 1183===== 1184 1185 "Traps" are locations, which, when reached, call a specified macro. 1186These traps can occur at a given location on the page, at a given 1187location in the current diversion, at a blank line, after a certain 1188number of input lines, or at the end of input. 1189 1190 Setting a trap is also called "planting". It is also said that a 1191trap is "sprung" if the associated macro is executed. 1192 1193* Menu: 1194 1195* Page Location Traps:: 1196* Diversion Traps:: 1197* Input Line Traps:: 1198* Blank Line Traps:: 1199* End-of-input Traps:: 1200 1201 1202File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps 1203 1204Page Location Traps 1205------------------- 1206 1207 "Page location traps" perform an action when `gtroff' reaches or 1208passes a certain vertical location on the page. Page location traps 1209have a variety of purposes, including: 1210 1211 * setting headers and footers 1212 1213 * setting body text in multiple columns 1214 1215 * setting footnotes 1216 1217 - Request: .vpt flag 1218 - Register: \n[.vpt] 1219 Enable vertical position traps if FLAG is non-zero, or disables 1220 them otherwise. Vertical position traps are traps set by the `wh' 1221 or `dt' requests. Traps set by the `it' request are not vertical 1222 position traps. The parameter that controls whether vertical 1223 position traps are enabled is global. Initially vertical position 1224 traps are enabled. The current setting of this is available in the 1225 `.vpt' read-only number register. 1226 1227 - Request: .wh dist [macro] 1228 Set a page location trap. Positive values for DIST set the trap 1229 relative to the top of the page; negative values set the trap 1230 relative to the bottom of the page. Default scaling indicator is 1231 `v'. 1232 1233 MACRO is the name of the macro to execute when the trap is sprung. 1234 If MACRO is missing, remove the first trap (if any) at DIST. 1235 1236 The following is a simple example of how many macro packages set 1237 headers and footers. 1238 1239 1240 .de hd \" Page header 1241 ' sp .5i 1242 . tl 'Title''date' 1243 ' sp .3i 1244 .. 1245 . 1246 .de fo \" Page footer 1247 ' sp 1v 1248 . tl ''%'' 1249 ' bp 1250 .. 1251 . 1252 .wh 0 hd \" trap at top of the page 1253 .wh -1i fo \" trap one inch from bottom 1254 1255 A trap at or below the bottom of the page is ignored; it can be 1256 made active by either moving it up or increasing the page length 1257 so that the trap is on the page. 1258 1259 It is possible to have more than one trap at the same location; to 1260 do so, the traps must be defined at different locations, then 1261 moved together with the `ch' request; otherwise the second trap 1262 would replace the first one. Earlier defined traps hide later 1263 defined traps if moved to the same position (the many empty lines 1264 caused by the `bp' request are omitted): 1265 1266 1267 .de a 1268 . nop a 1269 .. 1270 .de b 1271 . nop b 1272 .. 1273 .de c 1274 . nop c 1275 .. 1276 . 1277 .wh 1i a 1278 .wh 2i b 1279 .wh 3i c 1280 .bp 1281 => a b c 1282 1283 1284 .ch b 1i 1285 .ch c 1i 1286 .bp 1287 => a 1288 1289 1290 .ch a 0.5i 1291 .bp 1292 => a b 1293 1294 1295 - Register: \n[.t] 1296 A read-only number register holding the distance to the next trap. 1297 1298 If there are no traps between the current position and the bottom 1299 of the page, it contains the distance to the page bottom. In a 1300 diversion, the distance to the page bottom is infinite (the 1301 returned value is the biggest integer which can be represented in 1302 `groff') if there are no diversion traps. 1303 1304 - Request: .ch macro dist 1305 Change the location of a trap. The first argument is the name of 1306 the macro to be invoked at the trap, and the second argument is 1307 the new location for the trap (note that the parameters are 1308 specified the opposite of the `wh' request). This is useful for 1309 building up footnotes in a diversion to allow more space at the 1310 bottom of the page for them. 1311 1312 Default scaling indicator for DIST is `v'. If DIST is missing, 1313 the trap is removed. 1314 1315 1316 - Register: \n[.ne] 1317 The read-only number register `.ne' contains the amount of space 1318 that was needed in the last `ne' request that caused a trap to be 1319 sprung. Useful in conjunction with the `.trunc' register. *Note 1320 Page Control::, for more information. 1321 1322 - Register: \n[.trunc] 1323 A read-only register containing the amount of vertical space 1324 truncated by the most recently sprung vertical position trap, or, 1325 if the trap was sprung by an `ne' request, minus the amount of 1326 vertical motion produced by the `ne' request. In other words, at 1327 the point a trap is sprung, it represents the difference of what 1328 the vertical position would have been but for the trap, and what 1329 the vertical position actually is. 1330 1331 1332File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps 1333 1334Diversion Traps 1335--------------- 1336 1337 - Request: .dt dist macro 1338 Set a trap _within_ a diversion. DIST is the location of the trap 1339 (identical to the `.wh' request; default scaling indicator is `v') 1340 and MACRO is the name of the macro to be invoked. The number 1341 register `.t' still works within diversions. *Note Diversions::, 1342 for more information. 1343 1344 1345File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps 1346 1347Input Line Traps 1348---------------- 1349 1350 - Request: .it n macro 1351 - Request: .itc n macro 1352 Set an input line trap. N is the number of lines of input which 1353 may be read before springing the trap, MACRO is the macro to be 1354 invoked. Request lines are not counted as input lines. 1355 1356 For example, one possible use is to have a macro which prints the 1357 next N lines in a bold font. 1358 1359 1360 .de B 1361 . it \\$1 B-end 1362 . ft B 1363 .. 1364 . 1365 .de B-end 1366 . ft R 1367 .. 1368 1369 The `itc' request is identical, except that a line interrupted 1370 with `\c' counts as one input line. 1371 1372 Both requests are associated with the current environment (*note 1373 Environments::); switching to another environment disables the 1374 current input trap, and going back reactivates it, restoring the 1375 number of already processed lines. 1376 1377 1378File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps 1379 1380Blank Line Traps 1381---------------- 1382 1383 - Request: .blm macro 1384 Set a blank line trap. `gtroff' executes MACRO when it encounters 1385 a blank line in the input file. 1386 1387 1388File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps 1389 1390End-of-input Traps 1391------------------ 1392 1393 - Request: .em macro 1394 Set a trap at the end of input. MACRO is executed after the last 1395 line of the input file has been processed. 1396 1397 For example, if the document had to have a section at the bottom 1398 of the last page for someone to approve it, the `em' request could 1399 be used. 1400 1401 1402 .de approval 1403 . ne 5v 1404 . sp |(\\n[.t] - 6v) 1405 . in +4i 1406 . lc _ 1407 . br 1408 Approved:\t\a 1409 . sp 1410 Date:\t\t\a 1411 .. 1412 . 1413 .em approval 1414 1415 1416