/contrib/groff/doc/groff-2
#! | 4910 lines | 3933 code | 977 blank | 0 comment | 0 complexity | 49d6f50ba96bba8de8a1912d8cbd463c MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1This is groff, produced by makeinfo version 4.8 from ./groff.texinfo. 2 3 This manual documents GNU `troff' version 1.19.2. 4 5 Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 Free Software 6Foundation, Inc. 7 8 Permission is granted to copy, distribute and/or modify this 9 document under the terms of the GNU Free Documentation License, 10 Version 1.1 or any later version published by the Free Software 11 Foundation; with no Invariant Sections, with the Front-Cover texts 12 being `A GNU Manual," and with the Back-Cover Texts as in (a) 13 below. A copy of the license is included in the section entitled 14 `GNU Free Documentation License." 15 16 (a) The FSF's Back-Cover Text is: `You have freedom to copy and 17 modify this GNU Manual, like GNU software. Copies published by 18 the Free Software Foundation raise funds for GNU development." 19 20INFO-DIR-SECTION Typesetting 21START-INFO-DIR-ENTRY 22* Groff: (groff). The GNU troff document formatting system. 23END-INFO-DIR-ENTRY 24 25 26File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference 27 285.23 Drawing Requests 29===================== 30 31`gtroff' provides a number of ways to draw lines and other figures on 32the page. Used in combination with the page motion commands (see *Note 33Page Motions::, for more info), a wide variety of figures can be drawn. 34However, for complex drawings these operations can be quite 35cumbersome, and it may be wise to use graphic preprocessors like `gpic' 36or `ggrn'. *Note gpic::, and *Note ggrn::, for more information. 37 38 All drawing is done via escapes. 39 40 -- Escape: \l'l' 41 -- Escape: \l'lg' 42 Draw a line horizontally. L is the length of the line to be 43 drawn. If it is positive, start the line at the current location 44 and draw to the right; its end point is the new current location. 45 Negative values are handled differently: The line starts at the 46 current location and draws to the left, but the current location 47 doesn't move. 48 49 L can also be specified absolutely (i.e. with a leading `|') which 50 draws back to the beginning of the input line. Default scaling 51 indicator is `m'. 52 53 The optional second parameter G is a glyph to draw the line with. 54 If this second argument is not specified, `gtroff' uses the 55 underscore glyph, `\[ru]'. 56 57 To separate the two arguments (to prevent `gtroff' from 58 interpreting a drawing glyph as a scaling indicator if the glyph is 59 represented by a single character) use `\&'. 60 61 Here a small useful example: 62 63 64 .de box 65 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 66 .. 67 68 Note that this works by outputting a box rule (a vertical line), 69 then the text given as an argument and then another box rule. 70 Finally, the line drawing escapes both draw from the current 71 location to the beginning of the _input_ line - this works because 72 the line length is negative, not moving the current point. 73 74 -- Escape: \L'l' 75 -- Escape: \L'lg' 76 Draw vertical lines. Its parameters are similar to the `\l' 77 escape, except that the default scaling indicator is `v'. The 78 movement is downwards for positive values, and upwards for 79 negative values. The default glyph is the box rule glyph, 80 `\[br]'. As with the vertical motion escapes, text processing 81 blindly continues where the line ends. 82 83 84 This is a \L'3v'test. 85 86 Here the result, produced with `grotty'. 87 88 89 This is a 90 | 91 | 92 |test. 93 94 95 -- Escape: \D'command arg ...' 96 The `\D' escape provides a variety of drawing functions. Note 97 that on character devices, only vertical and horizontal lines are 98 supported within `grotty'; other devices may only support a subset 99 of the available drawing functions. 100 101 The default scaling indicator for all subcommands of `\D' is `m' 102 for horizontal distances and `v' for vertical ones. Exceptions 103 are `\D'f ...'' and `\D't ...'' which use `u' as the default, and 104 `\D'FX ...'' which arguments are treated similar to the `defcolor' 105 request. 106 107 `\D'l DX DY'' 108 Draw a line from the current location to the relative point 109 specified by (DX,DY), where positive values mean down and 110 right, respectively. The end point of the line is the new 111 current location. 112 113 The following example is a macro for creating a box around a 114 text string; for simplicity, the box margin is taken as a 115 fixed value, 0.2m. 116 117 118 .de BOX 119 . nr @wd \w'\\$1' 120 \h'.2m'\ 121 \h'-.2m'\v'(.2m - \\n[rsb]u)'\ 122 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 123 \D'l (\\n[@wd]u + .4m) 0'\ 124 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 125 \D'l -(\\n[@wd]u + .4m) 0'\ 126 \h'.2m'\v'-(.2m - \\n[rsb]u)'\ 127 \\$1\ 128 \h'.2m' 129 .. 130 131 First, the width of the string is stored in register `@wd'. 132 Then, four lines are drawn to form a box, properly offset by 133 the box margin. The registers `rst' and `rsb' are set by the 134 `\w' escape, containing the largest height and depth of the 135 whole string. 136 137 `\D'c D'' 138 Draw a circle with a diameter of D with the leftmost point at 139 the current position. After drawing, the current location is 140 positioned at the rightmost point of the circle. 141 142 `\D'C D'' 143 Draw a solid circle with the same parameters and behaviour as 144 an outlined circle. No outline is drawn. 145 146 `\D'e X Y'' 147 Draw an ellipse with a horizontal diameter of X and a vertical 148 diameter of Y with the leftmost point at the current position. 149 After drawing, the current location is positioned at the 150 rightmost point of the ellipse. 151 152 `\D'E X Y'' 153 Draw a solid ellipse with the same parameters and behaviour 154 as an outlined ellipse. No outline is drawn. 155 156 `\D'a DX1 DY1 DX2 DY2'' 157 Draw an arc clockwise from the current location through the 158 two specified relative locations (DX1,DY1) and (DX2,DY2). 159 The coordinates of the first point are relative to the 160 current position, and the coordinates of the second point are 161 relative to the first point. After drawing, the current 162 position is moved to the final point of the arc. 163 164 `\D'~ DX1 DY1 DX2 DY2 ...'' 165 Draw a spline from the current location to the relative point 166 (DX1,DY1) and then to (DX2,DY2), and so on. The current 167 position is moved to the terminal point of the drawn curve. 168 169 `\D'f N'' 170 Set the shade of gray to be used for filling solid objects 171 to N; N must be an integer between 0 and 1000, where 0 172 corresponds solid white and 1000 to solid black, and values 173 in between correspond to intermediate shades of gray. This 174 applies only to solid circles, solid ellipses, and solid 175 polygons. By default, a level of 1000 is used. 176 177 Despite of being silly, the current point is moved 178 horizontally to the right by N. 179 180 Don't use this command! It has the serious drawback that it 181 will be always rounded to the next integer multiple of the 182 horizontal resolution (the value of the `hor' keyword in the 183 `DESC' file). Use `\M' (*note Colors::) or `\D'Fg ...'' 184 instead. 185 186 `\D'p DX1 DY1 DX2 DY2 ...'' 187 Draw a polygon from the current location to the relative 188 position (DX1,DY1) and then to (DX2,DY2) and so on. When the 189 specified data points are exhausted, a line is drawn back to 190 the starting point. The current position is changed by 191 adding the sum of all arguments with odd index to the actual 192 horizontal position and the even ones to the vertical 193 position. 194 195 `\D'P DX1 DY1 DX2 DY2 ...'' 196 Draw a solid polygon with the same parameters and behaviour 197 as an outlined polygon. No outline is drawn. 198 199 Here a better variant of the box macro to fill the box with 200 some color. Note that the box must be drawn before the text 201 since colors in `gtroff' are not transparent; the filled 202 polygon would hide the text completely. 203 204 205 .de BOX 206 . nr @wd \w'\\$1' 207 \h'.2m'\ 208 \h'-.2m'\v'(.2m - \\n[rsb]u)'\ 209 \M[lightcyan]\ 210 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 211 (\\n[@wd]u + .4m) 0 \ 212 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 213 -(\\n[@wd]u + .4m) 0'\ 214 \h'.2m'\v'-(.2m - \\n[rsb]u)'\ 215 \M[]\ 216 \\$1\ 217 \h'.2m' 218 .. 219 220 `\D't N'' 221 Set the current line thickness to N machine units. A value of 222 zero selects the smallest available line thickness. A 223 negative value makes the line thickness proportional to the 224 current point size (this is the default behaviour of AT&T 225 `troff'). 226 227 Despite of being silly, the current point is moved 228 horizontally to the right by N. 229 230 `\D'FSCHEME COLOR_COMPONENTS'' 231 Change current fill color. SCHEME is a single letter 232 denoting the color scheme: `r' (rgb), `c' (cmy), `k' (cmyk), 233 `g' (gray), or `d' (default color). The color components use 234 exactly the same syntax as in the `defcolor' request (*note 235 Colors::); the command `\D'Fd'' doesn't take an argument. 236 237 _No_ position changing! 238 239 Examples: 240 241 242 \D'Fg .3' \" same gray as \D'f 700' \D'Fr #0000ff' \" 243 blue 244 245 *Note Graphics Commands::. 246 247 -- Escape: \b'string' 248 "Pile" a sequence of glyphs vertically, and center it vertically 249 on the current line. Use it to build large brackets and braces. 250 251 Here an example how to create a large opening brace: 252 253 254 \b'\[lt]\[bv]\[lk]\[bv]\[lb]' 255 256 The first glyph is on the top, the last glyph in STRING is at the 257 bottom. Note that `gtroff' separates the glyphs vertically by 1m, 258 and the whole object is centered 0.5m above the current baseline; 259 the largest glyph width is used as the width for the whole object. 260 This rather unflexible positioning algorithm doesn't work with 261 `-Tdvi' since the bracket pieces vary in height for this device. 262 Instead, use the `eqn' preprocessor. 263 264 *Note Manipulating Spacing::, how to adjust the vertical spacing 265 with the `\x' escape. 266 267 268File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference 269 2705.24 Traps 271========== 272 273"Traps" are locations, which, when reached, call a specified macro. 274These traps can occur at a given location on the page, at a given 275location in the current diversion, at a blank line, after a certain 276number of input lines, or at the end of input. 277 278 Setting a trap is also called "planting". It is also said that a 279trap is "sprung" if the associated macro is executed. 280 281* Menu: 282 283* Page Location Traps:: 284* Diversion Traps:: 285* Input Line Traps:: 286* Blank Line Traps:: 287* End-of-input Traps:: 288 289 290File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps 291 2925.24.1 Page Location Traps 293-------------------------- 294 295"Page location traps" perform an action when `gtroff' reaches or passes 296a certain vertical location on the page. Page location traps have a 297variety of purposes, including: 298 299 * setting headers and footers 300 301 * setting body text in multiple columns 302 303 * setting footnotes 304 305 -- Request: .vpt flag 306 -- Register: \n[.vpt] 307 Enable vertical position traps if FLAG is non-zero, or disables 308 them otherwise. Vertical position traps are traps set by the `wh' 309 or `dt' requests. Traps set by the `it' request are not vertical 310 position traps. The parameter that controls whether vertical 311 position traps are enabled is global. Initially vertical position 312 traps are enabled. The current setting of this is available in the 313 `.vpt' read-only number register. 314 315 Note that a page can't be ejected if `vpt' is set to zero. 316 317 -- Request: .wh dist [macro] 318 Set a page location trap. Non-negative values for DIST set the 319 trap relative to the top of the page; negative values set the trap 320 relative to the bottom of the page. Default scaling indicator is 321 `v'. 322 323 MACRO is the name of the macro to execute when the trap is sprung. 324 If MACRO is missing, remove the first trap (if any) at DIST. 325 326 The following is a simple example of how many macro packages set 327 headers and footers. 328 329 330 .de hd \" Page header 331 ' sp .5i 332 . tl 'Title''date' 333 ' sp .3i 334 .. 335 . 336 .de fo \" Page footer 337 ' sp 1v 338 . tl ''%'' 339 ' bp 340 .. 341 . 342 .wh 0 hd \" trap at top of the page 343 .wh -1i fo \" trap one inch from bottom 344 345 A trap at or below the bottom of the page is ignored; it can be 346 made active by either moving it up or increasing the page length 347 so that the trap is on the page. 348 349 It is possible to have more than one trap at the same location; to 350 do so, the traps must be defined at different locations, then 351 moved together with the `ch' request; otherwise the second trap 352 would replace the first one. Earlier defined traps hide later 353 defined traps if moved to the same position (the many empty lines 354 caused by the `bp' request are omitted in the following example): 355 356 357 .de a 358 . nop a 359 .. 360 .de b 361 . nop b 362 .. 363 .de c 364 . nop c 365 .. 366 . 367 .wh 1i a 368 .wh 2i b 369 .wh 3i c 370 .bp 371 => a b c 372 373 374 .ch b 1i 375 .ch c 1i 376 .bp 377 => a 378 379 380 .ch a 0.5i 381 .bp 382 => a b 383 384 385 -- Register: \n[.t] 386 A read-only number register holding the distance to the next trap. 387 388 If there are no traps between the current position and the bottom 389 of the page, it contains the distance to the page bottom. In a 390 diversion, the distance to the page bottom is infinite (the 391 returned value is the biggest integer which can be represented in 392 `groff') if there are no diversion traps. 393 394 -- Request: .ch macro [dist] 395 Change the location of a trap. The first argument is the name of 396 the macro to be invoked at the trap, and the second argument is 397 the new location for the trap (note that the parameters are 398 specified in opposite order as in the `wh' request). This is 399 useful for building up footnotes in a diversion to allow more 400 space at the bottom of the page for them. 401 402 Default scaling indicator for DIST is `v'. If DIST is missing, 403 the trap is removed. 404 405 406 -- Register: \n[.ne] 407 The read-only number register `.ne' contains the amount of space 408 that was needed in the last `ne' request that caused a trap to be 409 sprung. Useful in conjunction with the `.trunc' register. *Note 410 Page Control::, for more information. 411 412 Since the `.ne' register is only set by traps it doesn't make much 413 sense to use it outside of trap macros. 414 415 -- Register: \n[.trunc] 416 A read-only register containing the amount of vertical space 417 truncated by the most recently sprung vertical position trap, or, 418 if the trap was sprung by an `ne' request, minus the amount of 419 vertical motion produced by the `ne' request. In other words, at 420 the point a trap is sprung, it represents the difference of what 421 the vertical position would have been but for the trap, and what 422 the vertical position actually is. 423 424 Since the `.trunc' register is only set by traps it doesn't make 425 much sense to use it outside of trap macros. 426 427 -- Register: \n[.pe] 428 A read-only register which is set to 1 while a page is ejected with 429 the `bp' request (or by the end of input). 430 431 Outside of traps this register is always zero. In the following 432 example, only the second call to `x' is caused by `bp'. 433 434 435 .de x 436 \&.pe=\\n[.pe] 437 .br 438 .. 439 .wh 1v x 440 .wh 4v x 441 A line. 442 .br 443 Another line. 444 .br 445 => A line. 446 .pe=0 447 Another line. 448 449 .pe=1 450 451 452 An important fact to consider while designing macros is that 453diversions and traps do not interact normally. For example, if a trap 454invokes a header macro (while outputting a diversion) which tries to 455change the font on the current page, the effect will not be visible 456before the diversion has completely been printed (except for input 457protected with `\!' or `\?') since the data in the diversion is already 458formatted. In most cases, this is not the expected behaviour. 459 460 461File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps 462 4635.24.2 Diversion Traps 464---------------------- 465 466 -- Request: .dt [dist macro] 467 Set a trap _within_ a diversion. DIST is the location of the trap 468 (identical to the `wh' request; default scaling indicator is `v') 469 and MACRO is the name of the macro to be invoked. If called 470 without arguments, the diversion trap is removed. 471 472 Note that there exists only a single diversion trap. 473 474 The number register `.t' still works within diversions. *Note 475 Diversions::, for more information. 476 477 478File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps 479 4805.24.3 Input Line Traps 481----------------------- 482 483 -- Request: .it n macro 484 -- Request: .itc n macro 485 Set an input line trap. N is the number of lines of input which 486 may be read before springing the trap, MACRO is the macro to be 487 invoked. Request lines are not counted as input lines. 488 489 For example, one possible use is to have a macro which prints the 490 next N lines in a bold font. 491 492 493 .de B 494 . it \\$1 B-end 495 . ft B 496 .. 497 . 498 .de B-end 499 . ft R 500 .. 501 502 The `itc' request is identical except that an interrupted text 503 line (ending with `\c') is not counted as a separate line. 504 505 Both requests are associated with the current environment (*note 506 Environments::); switching to another environment disables the 507 current input trap, and going back reactivates it, restoring the 508 number of already processed lines. 509 510 511File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps 512 5135.24.4 Blank Line Traps 514----------------------- 515 516 -- Request: .blm macro 517 Set a blank line trap. `gtroff' executes MACRO when it encounters 518 a blank line in the input file. 519 520 521File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps 522 5235.24.5 End-of-input Traps 524------------------------- 525 526 -- Request: .em macro 527 Set a trap at the end of input. MACRO is executed after the last 528 line of the input file has been processed. 529 530 For example, if the document had to have a section at the bottom 531 of the last page for someone to approve it, the `em' request could 532 be used. 533 534 535 .de approval 536 . ne 5v 537 . sp |(\\n[.t] - 6v) 538 . in +4i 539 . lc _ 540 . br 541 Approved:\t\a 542 . sp 543 Date:\t\t\a 544 .. 545 . 546 .em approval 547 548 549 550File: groff, Node: Diversions, Next: Environments, Prev: Traps, Up: gtroff Reference 551 5525.25 Diversions 553=============== 554 555In `gtroff' it is possible to "divert" text into a named storage area. 556Due to the similarity to defining macros it is sometimes said to be 557stored in a macro. This is used for saving text for output at a later 558time, which is useful for keeping blocks of text on the same page, 559footnotes, tables of contents, and indices. 560 561 For orthogonality it is said that `gtroff' is in the "top-level 562diversion" if no diversion is active (i.e., the data is diverted to the 563output device). 564 565 -- Request: .di macro 566 -- Request: .da macro 567 Begin a diversion. Like the `de' request, it takes an argument of 568 a macro name to divert subsequent text into. The `da' macro 569 appends to an existing diversion. 570 571 `di' or `da' without an argument ends the diversion. 572 573 -- Request: .box macro 574 -- Request: .boxa macro 575 Begin (or appends to) a diversion like the `di' and `da' requests. 576 The difference is that `box' and `boxa' do not include a 577 partially-filled line in the diversion. 578 579 Compare this: 580 581 582 Before the box. 583 .box xxx 584 In the box. 585 .br 586 .box 587 After the box. 588 .br 589 => Before the box. After the box. 590 .xxx 591 => In the box. 592 593 with this: 594 595 596 Before the diversion. 597 .di yyy 598 In the diversion. 599 .br 600 .di 601 After the diversion. 602 .br 603 => After the diversion. 604 .yyy 605 => Before the diversion. In the diversion. 606 607 `box' or `boxa' without an argument ends the diversion. 608 609 -- Register: \n[.z] 610 -- Register: \n[.d] 611 Diversions may be nested. The read-only number register `.z' 612 contains the name of the current diversion (this is a string-valued 613 register). The read-only number register `.d' contains the current 614 vertical place in the diversion. If not in a diversion it is the 615 same as register `nl'. 616 617 -- Register: \n[.h] 618 The "high-water mark" on the current page. It corresponds to the 619 text baseline of the lowest line on the page. This is a read-only 620 register. 621 622 623 .tm .h==\n[.h], nl==\n[nl] 624 => .h==0, nl==-1 625 This is a test. 626 .br 627 .sp 2 628 .tm .h==\n[.h], nl==\n[nl] 629 => .h==40, nl==120 630 631 As can be seen in the previous example, empty lines are not 632 considered in the return value of the `.h' register. 633 634 -- Register: \n[dn] 635 -- Register: \n[dl] 636 After completing a diversion, the read-write number registers `dn' 637 and `dl' contain the vertical and horizontal size of the diversion. 638 Note that only the just processed lines are counted: For the 639 computation of `dn' and `dl', the requests `da' and `boxa' are 640 handled as if `di' and `box' had been used - lines which have been 641 already stored in a macro are not taken into account. 642 643 644 .\" Center text both horizontally & vertically 645 . 646 .\" Enclose macro definitions in .eo and .ec 647 .\" to avoid the doubling of the backslash 648 .eo 649 .\" macro .(c starts centering mode 650 .de (c 651 . br 652 . ev (c 653 . evc 0 654 . in 0 655 . nf 656 . di @c 657 .. 658 659 660 .\" macro .)c terminates centering mode 661 .de )c 662 . br 663 . ev 664 . di 665 . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 666 . sp \n[@s]u 667 . ce 1000 668 . @c 669 . ce 0 670 . sp \n[@s]u 671 . br 672 . fi 673 . rr @s 674 . rm @s 675 . rm @c 676 .. 677 .\" End of macro definitions, restore escape mechanism 678 .ec 679 680 681 -- Escape: \! 682 -- Escape: \?anything\? 683 Prevent requests, macros, and escapes from being interpreted when 684 read into a diversion. Both escapes take the given text and 685 "transparently" embed it into the diversion. This is useful for 686 macros which shouldn't be invoked until the diverted text is 687 actually output. 688 689 The `\!' escape transparently embeds text up to and including the 690 end of the line. The `\?' escape transparently embeds text until 691 the next occurrence of the `\?' escape. Example: 692 693 694 \?ANYTHING\? 695 696 ANYTHING may not contain newlines; use `\!' to embed newlines in 697 a diversion. The escape sequence `\?' is also recognized in copy 698 mode and turned into a single internal code; it is this code that 699 terminates ANYTHING. Thus the following example prints 4. 700 701 702 .nr x 1 703 .nf 704 .di d 705 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 706 .di 707 .nr x 2 708 .di e 709 .d 710 .di 711 .nr x 3 712 .di f 713 .e 714 .di 715 .nr x 4 716 .f 717 718 Both escapes read the data in copy mode. 719 720 If `\!' is used in the top-level diversion, its argument is 721 directly embedded into the `gtroff' intermediate output. This can 722 be used for example to control a postprocessor which processes the 723 data before it is sent to the device driver. 724 725 The `\?' escape used in the top-level diversion produces no output 726 at all; its argument is simply ignored. 727 728 -- Request: .output string 729 Emit STRING directly to the `gtroff' intermediate output (subject 730 to copy-mode interpretation); this is similar to `\!' used at the 731 top level. An initial double quote in STRING is stripped off to 732 allow initial blanks. 733 734 This request can't be used before the first page has started - if 735 you get an error, simply insert `.br' before the `output' request. 736 737 Without argument, `output' is ignored. 738 739 Use with caution! It is normally only needed for mark-up used by a 740 postprocessor which does something with the output before sending 741 it to the output device, filtering out STRING again. 742 743 -- Request: .asciify div 744 "Unformat" the diversion specified by DIV in such a way that ASCII 745 characters, characters translated with the `trin' request, space 746 characters, and some escape sequences that were formatted and 747 diverted are treated like ordinary input characters when the 748 diversion is reread. It can be also used for gross hacks; for 749 example, the following sets register `n' to 1. 750 751 752 .tr @. 753 .di x 754 @nr n 1 755 .br 756 .di 757 .tr @@ 758 .asciify x 759 .x 760 761 *Note Copy-in Mode::. 762 763 -- Request: .unformat div 764 Like `asciify', unformat the specified diversion. However, 765 `unformat' only unformats spaces and tabs between words. 766 Unformatted tabs are treated as input tokens, and spaces are 767 stretchable again. 768 769 The vertical size of lines is not preserved; glyph information 770 (font, font size, space width, etc.) is retained. 771 772 773File: groff, Node: Environments, Next: Suppressing output, Prev: Diversions, Up: gtroff Reference 774 7755.26 Environments 776================= 777 778It happens frequently that some text should be printed in a certain 779format regardless of what may be in effect at the time, for example, in 780a trap invoked macro to print headers and footers. To solve this 781`gtroff' processes text in "environments". An environment contains 782most of the parameters that control text processing. It is possible to 783switch amongst these environments; by default `gtroff' processes text 784in environment 0. The following is the information kept in an 785environment. 786 787 * font parameters (size, family, style, glyph height and slant, space 788 and sentence space size) 789 790 * page parameters (line length, title length, vertical spacing, line 791 spacing, indentation, line numbering, centering, right-justifying, 792 underlining, hyphenation data) 793 794 * fill and adjust mode 795 796 * tab stops, tab and leader characters, escape character, no-break 797 and hyphen indicators, margin character data 798 799 * partially collected lines 800 801 * input traps 802 803 * drawing and fill colours 804 805 These environments may be given arbitrary names (see *Note 806Identifiers::, for more info). Old versions of `troff' only had 807environments named `0', `1', and `2'. 808 809 -- Request: .ev [env] 810 -- Register: \n[.ev] 811 Switch to another environment. The argument ENV is the name of 812 the environment to switch to. With no argument, `gtroff' switches 813 back to the previous environment. There is no limit on the number 814 of named environments; they are created the first time that they 815 are referenced. The `.ev' read-only register contains the name or 816 number of the current environment. This is a string-valued 817 register. 818 819 Note that a call to `ev' (with argument) pushes the previously 820 active environment onto a stack. If, say, environments `foo', 821 `bar', and `zap' are called (in that order), the first `ev' 822 request without parameter switches back to environment `bar' 823 (which is popped off the stack), and a second call switches back 824 to environment `foo'. 825 826 Here is an example: 827 828 829 .ev footnote-env 830 .fam N 831 .ps 6 832 .vs 8 833 .ll -.5i 834 .ev 835 836 ... 837 838 .ev footnote-env 839 \(dg Note the large, friendly letters. 840 .ev 841 842 843 -- Request: .evc env 844 Copy the environment ENV into the current environment. 845 846 The following environment data is not copied: 847 848 * Partially filled lines. 849 850 * The status whether the previous line was interrupted. 851 852 * The number of lines still to center, or to right-justify, or 853 to underline (with or without underlined spaces); they are 854 set to zero. 855 856 * The status whether a temporary indentation is active. 857 858 * Input traps and its associated data. 859 860 * Line numbering mode is disabled; it can be reactivated with 861 `.nm +0'. 862 863 * The number of consecutive hyphenated lines (set to zero). 864 865 -- Register: \n[.w] 866 -- Register: \n[.cht] 867 -- Register: \n[.cdp] 868 -- Register: \n[.csk] 869 The `\n[.w]' register contains the width of the last glyph added 870 to the current environment. 871 872 The `\n[.cht]' register contains the height of the last glyph 873 added to the current environment. 874 875 The `\n[.cdp]' register contains the depth of the last glyph added 876 to the current environment. It is positive for glyphs extending 877 below the baseline. 878 879 The `\n[.csk]' register contains the "skew" (how far to the right 880 of the glyph's center that `gtroff' should place an accent) of the 881 last glyph added to the current environment. 882 883 -- Register: \n[.n] 884 The `\n[.n]' register contains the length of the previous output 885 line in the current environment. 886 887 888File: groff, Node: Suppressing output, Next: Colors, Prev: Environments, Up: gtroff Reference 889 8905.27 Suppressing output 891======================= 892 893 -- Escape: \Onum 894 Disable or enable output depending on the value of NUM: 895 896 `\O0' 897 Disable any glyphs from being emitted to the device driver, 898 provided that the escape occurs at the outer level (see 899 `\O[3]' and `\O[4]'). Motion is not suppressed so 900 effectively `\O[0]' means _pen up_. 901 902 `\O1' 903 Enable output of glyphs, provided that the escape occurs at 904 the outer level. 905 906 `\O0' and `\O1' also reset the four registers `opminx', `opminy', 907 `opmaxx', and `opmaxy' to -1. *Note Register Index::. These four 908 registers mark the top left and bottom right hand corners of a box 909 which encompasses all written glyphs. 910 911 For example the input text: 912 913 914 Hello \O[0]world \O[1]this is a test. 915 916 produces the following output: 917 918 919 Hello this is a test. 920 921 `\O2' 922 Provided that the escape occurs at the outer level, enable 923 output of glyphs and also write out to `stderr' the page 924 number and four registers encompassing the glyphs previously 925 written since the last call to `\O'. 926 927 `\O3' 928 Begin a nesting level. At start-up, `gtroff' is at outer 929 level. 930 931 `\O4' 932 End a nesting level. 933 934 `\O[5PFILENAME]' 935 This escape is `grohtml' specific. Provided that this escape 936 occurs at the outer nesting level write the `filename' to 937 `stderr'. The position of the image, P, must be specified 938 and must be one of `l', `r', `c', or `i' (left, right, 939 centered, inline). FILENAME will be associated with the 940 production of the next inline image. 941 942 943File: groff, Node: Colors, Next: I/O, Prev: Suppressing output, Up: gtroff Reference 944 9455.28 Colors 946=========== 947 948 -- Request: .color [n] 949 -- Register: \n[.color] 950 If N is missing or non-zero, activate colors (this is the default); 951 otherwise, turn it off. 952 953 The read-only number register `.color' is 1 if colors are active, 954 0 otherwise. 955 956 Internally, `color' sets a global flag; it does not produce a 957 token. Similar to the `cp' request, you should use it at the 958 beginning of your document to control color output. 959 960 Colors can be also turned off with the `-c' command line option. 961 962 -- Request: .defcolor ident scheme color_components 963 Define color with name IDENT. SCHEME can be one of the following 964 values: `rgb' (three components), `cmy' (three components), `cmyk' 965 (four components), and `gray' or `grey' (one component). 966 967 Color components can be given either as a hexadecimal string or as 968 positive decimal integers in the range 0-65535. A hexadecimal 969 string contains all color components concatenated. It must start 970 with either `#' or `##'; the former specifies hex values in the 971 range 0-255 (which are internally multiplied by 257), the latter 972 in the range 0-65535. Examples: `#FFC0CB' (pink), `##ffff0000ffff' 973 (magenta). The default color name value is device-specific 974 (usually black). It is possible that the default color for `\m' 975 and `\M' is not identical. 976 977 A new scaling indicator `f' has been introduced which multiplies 978 its value by 65536; this makes it convenient to specify color 979 components as fractions in the range 0 to 1 (1f equals 65536u). 980 Example: 981 982 983 .defcolor darkgreen rgb 0.1f 0.5f 0.2f 984 985 Note that `f' is the default scaling indicator for the `defcolor' 986 request, thus the above statement is equivalent to 987 988 989 .defcolor darkgreen rgb 0.1 0.5 0.2 990 991 992 -- Request: .gcolor [color] 993 -- Escape: \mc 994 -- Escape: \m(co 995 -- Escape: \m[color] 996 -- Register: \n[.m] 997 Set (glyph) drawing color. The following examples show how to 998 turn the next four words red. 999 1000 1001 .gcolor red 1002 these are in red 1003 .gcolor 1004 and these words are in black. 1005 1006 1007 \m[red]these are in red\m[] and these words are in black. 1008 1009 The escape `\m[]' returns to the previous color, as does a call to 1010 `gcolor' without an argument. 1011 1012 The name of the current drawing color is available in the 1013 read-only, string-valued number register `.m'. 1014 1015 The drawing color is associated with the current environment 1016 (*note Environments::). 1017 1018 Note that `\m' doesn't produce an input token in `gtroff'. As a 1019 consequence, it can be used in requests like `mc' (which expects a 1020 single character as an argument) to change the color on the fly: 1021 1022 1023 .mc \m[red]x\m[] 1024 1025 1026 -- Request: .fcolor [color] 1027 -- Escape: \Mc 1028 -- Escape: \M(co 1029 -- Escape: \M[color] 1030 -- Register: \n[.M] 1031 Set fill (background) color for filled objects drawn with the 1032 `\D'...'' commands. 1033 1034 A red ellipse can be created with the following code: 1035 1036 1037 \M[red]\h'0.5i'\D'E 2i 1i'\M[] 1038 1039 The escape `\M[]' returns to the previous fill color, as does a 1040 call to `fcolor' without an argument. 1041 1042 The name of the current fill (background) color is available in the 1043 read-only, string-valued number register `.M'. 1044 1045 The fill color is associated with the current environment (*note 1046 Environments::). 1047 1048 Note that `\M' doesn't produce an input token in `gtroff'. 1049 1050 1051File: groff, Node: I/O, Next: Postprocessor Access, Prev: Colors, Up: gtroff Reference 1052 10535.29 I/O 1054======== 1055 1056`gtroff' has several requests for including files: 1057 1058 -- Request: .so file 1059 Read in the specified FILE and includes it in place of the `so' 1060 request. This is quite useful for large documents, e.g. keeping 1061 each chapter in a separate file. *Note gsoelim::, for more 1062 information. 1063 1064 Since `gtroff' replaces the `so' request with the contents of 1065 `file', it makes a difference whether the data is terminated with 1066 a newline or not: Assuming that file `xxx' contains the word `foo' 1067 without a final newline, this 1068 1069 1070 This is 1071 .so xxx 1072 bar 1073 1074 yields `This is foobar'. 1075 1076 The search path for FILE can be controlled with the `-I' command 1077 line option. 1078 1079 -- Request: .pso command 1080 Read the standard output from the specified COMMAND and includes 1081 it in place of the `pso' request. 1082 1083 This request causes an error if used in safer mode (which is the 1084 default). Use `groff''s or `troff''s `-U' option to activate 1085 unsafe mode. 1086 1087 The comment regarding a final newline for the `so' request is valid 1088 for `pso' also. 1089 1090 -- Request: .mso file 1091 Identical to the `so' request except that `gtroff' searches for 1092 the specified FILE in the same directories as macro files for the 1093 the `-m' command line option. If the file name to be included has 1094 the form `NAME.tmac' and it isn't found, `mso' tries to include 1095 `tmac.NAME' and vice versa. 1096 1097 -- Request: .trf file 1098 -- Request: .cf file 1099 Transparently output the contents of FILE. Each line is output as 1100 if it were preceded by `\!'; however, the lines are not subject to 1101 copy mode interpretation. If the file does not end with a newline, 1102 then a newline is added (`trf' only). For example, to define a 1103 macro `x' containing the contents of file `f', use 1104 1105 1106 .di x 1107 .trf f 1108 .di 1109 1110 Both `trf' and `cf', when used in a diversion, embeds an object in 1111 the diversion which, when reread, causes the contents of FILE to 1112 be transparently copied through to the output. In UNIX `troff', 1113 the contents of FILE is immediately copied through to the output 1114 regardless of whether there is a current diversion; this behaviour 1115 is so anomalous that it must be considered a bug. 1116 1117 While `cf' copies the contents of FILE completely unprocessed, 1118 `trf' disallows characters such as NUL that are not valid `gtroff' 1119 input characters (*note Identifiers::). 1120 1121 Both requests cause a line break. 1122 1123 -- Request: .nx [file] 1124 Force `gtroff' to continue processing of the file specified as an 1125 argument. If no argument is given, immediately jump to the end of 1126 file. 1127 1128 -- Request: .rd [prompt [arg1 arg2 ...]] 1129 Read from standard input, and include what is read as though it 1130 were part of the input file. Text is read until a blank line is 1131 encountered. 1132 1133 If standard input is a TTY input device (keyboard), write PROMPT 1134 to standard error, followed by a colon (or send BEL for a beep if 1135 no argument is given). 1136 1137 Arguments after PROMPT are available for the input. For example, 1138 the line 1139 1140 1141 .rd data foo bar 1142 1143 with the input `This is \$2.' prints 1144 1145 1146 This is bar. 1147 1148 1149 Using the `nx' and `rd' requests, it is easy to set up form letters. 1150The form letter template is constructed like this, putting the 1151following lines into a file called `repeat.let': 1152 1153 1154 .ce 1155 \*(td 1156 .sp 2 1157 .nf 1158 .rd 1159 .sp 1160 .rd 1161 .fi 1162 Body of letter. 1163 .bp 1164 .nx repeat.let 1165 1166When this is run, a file containing the following lines should be 1167redirected in. Note that requests included in this file are executed 1168as though they were part of the form letter. The last block of input 1169is the `ex' request which tells `groff' to stop processing. If this 1170was not there, `groff' would not know when to stop. 1171 1172 1173 Trent A. Fisher 1174 708 NW 19th Av., #202 1175 Portland, OR 97209 1176 1177 Dear Trent, 1178 1179 Len Adollar 1180 4315 Sierra Vista 1181 San Diego, CA 92103 1182 1183 Dear Mr. Adollar, 1184 1185 .ex 1186 1187 -- Request: .pi pipe 1188 Pipe the output of `gtroff' to the shell command(s) specified by 1189 PIPE. This request must occur before `gtroff' has a chance to 1190 print anything. 1191 1192 `pi' causes an error if used in safer mode (which is the default). 1193 Use `groff''s or `troff''s `-U' option to activate unsafe mode. 1194 1195 Multiple calls to `pi' are allowed, acting as a chain. For 1196 example, 1197 1198 1199 .pi foo 1200 .pi bar 1201 ... 1202 1203 is the same as `.pi foo | bar'. 1204 1205 Note that the intermediate output format of `gtroff' is piped to 1206 the specified commands. Consequently, calling `groff' without the 1207 `-Z' option normally causes a fatal error. 1208 1209 -- Request: .sy cmds 1210 -- Register: \n[systat] 1211 Execute the shell command(s) specified by CMDS. The output is not 1212 saved anyplace, so it is up to the user to do so. 1213 1214 This request causes an error if used in safer mode (which is the 1215 default). Use `groff''s or `troff''s `-U' option to activate 1216 unsafe mode. 1217 1218 For example, the following code fragment introduces the current 1219 time into a document: 1220 1221 1222 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 1223 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 1224 .so /tmp/x\n[$$] 1225 .sy rm /tmp/x\n[$$] 1226 \nH:\nM:\nS 1227 1228 Note that this works by having the `perl' script (run by `sy') 1229 print out the `nr' requests which set the number registers `H', 1230 `M', and `S', and then reads those commands in with the `so' 1231 request. 1232 1233 For most practical purposes, the number registers `seconds', 1234 `minutes', and `hours' which are initialized at start-up of 1235 `gtroff' should be sufficient. Use the `af' request to get a 1236 formatted output: 1237 1238 1239 .af hours 00 1240 .af minutes 00 1241 .af seconds 00 1242 \n[hours]:\n[minutes]:\n[seconds] 1243 1244 The `systat' read-write number register contains the return value 1245 of the `system()' function executed by the last `sy' request. 1246 1247 -- Request: .open stream file 1248 -- Request: .opena stream file 1249 Open the specified FILE for writing and associates the specified 1250 STREAM with it. 1251 1252 The `opena' request is like `open', but if the file exists, append 1253 to it instead of truncating it. 1254 1255 Both `open' and `opena' cause an error if used in safer mode 1256 (which is the default). Use `groff''s or `troff''s `-U' option to 1257 activate unsafe mode. 1258 1259 -- Request: .write stream data 1260 -- Request: .writec stream data 1261 Write to the file associated with the specified STREAM. The 1262 stream must previously have been the subject of an open request. 1263 The remainder of the line is interpreted as the `ds' request reads 1264 its second argument: A leading `"' is stripped, and it is read in 1265 copy-in mode. 1266 1267 The `writec' request is like `write', but only `write' appends a 1268 newline to the data. 1269 1270 -- Request: .writem stream xx 1271 Write the contents of the macro or string XX to the file 1272 associated with the specified STREAM. 1273 1274 XX is read in copy mode, i.e., already formatted elements are 1275 ignored. Consequently, diversions must be unformatted with the 1276 `asciify' request before calling `writem'. Usually, this means a 1277 loss of information. 1278 1279 -- Request: .close stream 1280 Close the specified STREAM; the stream is no longer an acceptable 1281 argument to the `write' request. 1282 1283 Here a simple macro to write an index entry. 1284 1285 1286 .open idx test.idx 1287 . 1288 .de IX 1289 . write idx \\n[%] \\$* 1290 .. 1291 . 1292 .IX test entry 1293 . 1294 .close idx 1295 1296 1297 -- Escape: \Ve 1298 -- Escape: \V(ev 1299 -- Escape: \V[env] 1300 Interpolate the contents of the specified environment variable ENV 1301 (one-character name E, two-character name EV) as returned by the 1302 function `getenv'. `\V' is interpreted in copy-in mode. 1303 1304 1305File: groff, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: gtroff Reference 1306 13075.30 Postprocessor Access 1308========================= 1309 1310There are two escapes which give information directly to the 1311postprocessor. This is particularly useful for embedding POSTSCRIPT 1312into the final document. 1313 1314 -- Escape: \X'xxx' 1315 Embeds its argument into the `gtroff' output preceded with `x X'. 1316 1317 The escapes `\&', `\)', `\%', and `\:' are ignored within `\X', 1318 `\ ' and `\~' are converted to single space characters. All other 1319 escapes (except `\\' which produces a backslash) cause an error. 1320 1321 If the `use_charnames_in_special' keyword is set in the `DESC' 1322 file, special characters no longer cause an error; the name XX is 1323 represented as `\(XX)' in the `x X' output command. Additionally, 1324 the backslash is represented as `\\'. 1325 1326 `use_charnames_in_special' is currently used by `grohtml' only. 1327 1328 -- Escape: \Yn 1329 -- Escape: \Y(nm 1330 -- Escape: \Y[name] 1331 This is approximately equivalent to `\X'\*[NAME]'' (one-character 1332 name N, two-character name NM). However, the contents of the 1333 string or macro NAME are not interpreted; also it is permitted for 1334 NAME to have been defined as a macro and thus contain newlines (it 1335 is not permitted for the argument to `\X' to contain newlines). 1336 The inclusion of newlines requires an extension to the UNIX `troff' 1337 output format, and confuses drivers that do not know about this 1338 extension (*note Device Control Commands::). 1339 1340 *Note Output Devices::. 1341 1342 1343File: groff, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: gtroff Reference 1344 13455.31 Miscellaneous 1346================== 1347 1348This section documents parts of `gtroff' which cannot (yet) be 1349categorized elsewhere in this manual. 1350 1351 -- Request: .nm [start [inc [space [indent]]]] 1352 Print line numbers. START is the line number of the _next_ output 1353 line. INC indicates which line numbers are printed. For example, 1354 the value 5 means to emit only line numbers which are multiples 1355 of 5; this defaults to 1. SPACE is the space to be left between 1356 the number and the text; this defaults to one digit space. The 1357 fourth argument is the indentation of the line numbers, defaulting 1358 to zero. Both SPACE and INDENT are given as multiples of digit 1359 spaces; they can be negative also. Without any arguments, line 1360 numbers are turned off. 1361 1362 `gtroff' reserves three digit spaces for the line number (which is 1363 printed right-justified) plus the amount given by INDENT; the 1364 output lines are concatenated to the line numbers, separated by 1365 SPACE, and _without_ reducing the line length. Depending on the 1366 value of the horizontal page offset (as set with the `po' 1367 request), line numbers which are longer than the reserved space 1368 stick out to the left, or the whole line is moved to the right. 1369 1370 Parameters corresponding to missing arguments are not changed; any 1371 non-digit argument (to be more precise, any argument starting with 1372 a character valid as a delimiter for identifiers) is also treated 1373 as missing. 1374 1375 If line numbering has been disabled with a call to `nm' without an 1376 argument, it can be reactivated with `.nm +0', using the 1377 previously active line numbering parameters. 1378 1379 The parameters of `nm' are associated with the current environment 1380 (*note Environments::). The current output line number is 1381 available in the number register `ln'. 1382 1383 1384 .po 1m 1385 .ll 2i 1386 This test shows how line numbering works with groff. 1387 .nm 999 1388 This test shows how line numbering works with groff. 1389 .br 1390 .nm xxx 3 2 1391 .ll -\w'0'u 1392 This test shows how line numbering works with groff. 1393 .nn 2 1394 This test shows how line numbering works with groff. 1395 1396 And here the result: 1397 1398 1399 This test shows how 1400 line numbering works 1401 999 with groff. This 1402 1000 test shows how line 1403 1001 numbering works with 1404 1002 groff. 1405 This test shows how 1406 line numbering 1407 works with groff. 1408 This test shows how 1409 1005 line numbering 1410 works with groff. 1411 1412 1413 -- Request: .nn [skip] 1414 Temporarily turn off line numbering. The argument is the number 1415 of lines not to be numbered; this defaults to 1. 1416 1417 -- Request: .mc glyph [dist] 1418 Print a "margin character" to the right of the text.(1) (*note 1419 Miscellaneous-Footnote-1::) The first argument is the glyph to be 1420 printed. The second argument is the distance away from the right 1421 margin. If missing, the previously set value is used; default is 1422 10pt). For text lines that are too long (that is, longer than the 1423 text length plus DIST), the margin character is directly appended 1424 to the lines. 1425 1426 With no arguments the margin character is turned off. If this 1427 occurs before a break, no margin character is printed. 1428 1429 For compatibility with AT&T `troff', a call to `mc' to set the 1430 margin character can't be undone immediately; at least one line 1431 gets a margin character. Thus 1432 1433 1434 .ll 1i 1435 .mc \[br] 1436 .mc 1437 xxx 1438 .br 1439 xxx 1440 1441 produces 1442 1443 1444 xxx | 1445 xxx 1446 1447 For empty lines and lines produced by the `tl' request no margin 1448 character is emitted. 1449 1450 The margin character is associated with the current environment 1451 (*note Environments::). 1452 1453 This is quite useful for indicating text that has changed, and, in 1454 fact, there are programs available for doing this (they are called 1455 `nrchbar' and `changebar' and can be found in any 1456 `comp.sources.unix' archive). 1457 1458 1459 …
Large files files are truncated, but you can click here to view the full file