1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
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."
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."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference
30 `gtroff' has string variables, which are entirely for user
31 convenience (i.e. there are no built-in strings exept `.T', but even
32 this is a read-write string variable).
34 - Request: .ds name [string]
35 - Request: .ds1 name [string]
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
53 => This is a nice test.
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
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).
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.
72 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
74 Instead the comment should be put on another line or have the
75 comment escape adjacent with the end of the string.
78 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
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.
85 .ds sign " Yours in a white wine sauce,
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.
92 .ds foo lots and lots \
93 of text are on these \
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.
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.
107 .ds aa The value of xxx is \\n[xxx].
108 .ds1 bb The value of xxx ix \\n[xxx].
113 => warning: number register `[' not defined
114 => The value of xxx is 0xxx].
116 => The value of xxx ix 12345.
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.
128 => This is a funny test.
133 => This is a funny test.
135 Diversions and boxes can be also called with string syntax.
137 Another consequence is that you can copy one-line diversions or
145 .ds yyy This is \*[xxx]\c
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.
153 Copying diversions longer than a single output line produces
163 .ds yyy This is \*[xxx]\c
165 => test This is a funny.
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.
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
189 => This is a funny test.
191 *Note Gtroff Internals::, for more information.
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.
200 .as sign " with shallots, onions and garlic,
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.
208 Rudimentary string manipulation routines are given with the next two
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,
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.
233 .ds xxx abcd\h'3i'efgh
240 Rename the request, macro, diversion, or string XX to YY.
243 Remove the request, macro, diversion, or string XX. `gtroff'
244 treats subsequent invocations as if the object had never been
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.
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'.
261 *Note Identifiers::, and *Note Comments::.
264 File: groff, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference
266 Conditionals and Loops
267 ======================
271 * Operators in Conditionals::
276 File: groff, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops
278 Operators in Conditionals
279 -------------------------
281 In `if' and `while' requests, there are several more operators
286 True if the current page is even or odd numbered (respectively).
289 True if the document is being processed in nroff mode (i.e., the
290 `.nroff' command has been issued).
293 True if the document is being processed in troff mode (i.e., the
294 `.troff' command has been issued).
297 Always false. This condition is for compatibility with other
298 `troff' versions only.
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:
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.
323 True if there is a number register named XXX.
326 True if there is a string, macro, diversion, or request named XXX.
329 True if there is a color named XXX.
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.
337 Note that these operators can't be combined with other operators like
338 `:' or `&'; only a leading `!' (without whitespace between the
339 exclamation mark and the operator) can be used to negate the result.
349 A whitespace after `!' always evaluates to zero (this bizarre
350 behaviour is due to compatibility with UNIX `troff').
360 It is possible to omit the whitespace before the argument to the
361 `r', `d', and `c' operators.
366 File: groff, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals
368 (1) The created output nodes must be identical. *Note Gtroff
371 (2) The name of this conditional operator is a misnomer since it
372 tests names of output glyphs.
375 File: groff, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops
380 `gtroff' has if-then-else constructs like other languages, although
381 the formatting can be painful.
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.
392 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
396 - Request: .nop anything
397 Executes ANYTHING. This is similar to `.if 1'.
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.
405 .ie n .ls 2 \" double-spacing in nroff
406 .el .ls 1 \" single-spacing in troff
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
431 File: groff, Node: while, Prev: if-else, Up: Conditionals and Loops
436 `gtroff' provides a looping construct using the `while' request,
437 which is used much like the `if' (and related) requests.
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.
449 => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
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
464 . while (\\n[num] > 0) \{\
465 . \" many lines of code
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.
476 . if (\\n[num] > 0) \{\
477 . \" many lines of code
488 Note that the number of available recursion levels is set
489 to 1000 (this is a compile-time constant value of `gtroff').
491 * The closing brace of a `while' body must end a line.
496 . while (\n[a] < 10) \{\
503 Break out of a `while' loop. Be sure not to confuse this with the
504 `br' request (causing a line break).
507 Finish the current iteration of a `while' loop, immediately
508 restarting the next iteration.
513 File: groff, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference
518 A "macro" is a collection of text and embedded commands which can be
519 invoked multiple times. Use macros to define common operations.
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'.
529 There can be whitespace after the first dot in the line containing
530 the ending token (either `.' or macro `END').
532 Here a small example macro called `P' which causes a break and
533 inserts some vertical space. It could be used to separate
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.
547 \# a dummy macro to avoid a warning
553 . nop \f[B]Hallo \\\\$1!\f[]
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'.
565 The `de1' request turns off compatibility mode while executing the
566 macro. On entry, the current compatibility mode is saved and
573 The value of xxx is \\n[xxx].
576 The value of xxx ix \\n[xxx].
582 => warning: number register
\e' not defined
583 => The value of xxx is 0xxx].
585 => The value of xxx ix 12345.
587 The `dei' request defines a macro indirectly. That is, it expands
588 strings whose names are NAME or END before performing the append.
602 Using `trace.tmac', you can trace calls to `de' and `de1'.
604 Note that macro identifiers are shared with identifiers for
605 strings and diversions.
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:
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.
625 The `ami' request appends indirectly, meaning that `gtroff'
626 expands strings whose names are XX or YY before performing the
629 Using `trace.tmac', you can trace calls to `am' and `am1'.
631 *Note Strings::, for the `als' request to rename a macro.
633 The `de', `am', `di', `da', `ds', and `as' requests (together with
634 its variants) only create a new object if the name of the macro,
635 diversion or string diversion is currently undefined or if it is
636 defined to be a request; normally they modify the value of an existing
640 Exit a macro, immediately returning to the caller.
648 File: groff, Node: Copy-in Mode, Next: Parameters, Prev: Writing Macros, Up: Writing Macros
653 When `gtroff' reads in the text for a macro, string, or diversion,
654 it copies the text (including request lines, but excluding escapes) into
655 an internal buffer. Escapes are converted into an internal form,
656 except for `\n', `\$', `\*', `\\' and `\<RET>' which are evaluated and
657 inserted into the text where the escape was located. This is known as
658 "copy-in" mode or "copy" mode.
660 What this means is that you can specify when these escapes are to be
661 evaluated (either at copy-in time or at the time of use) by insulating
662 the escapes with an extra backslash. Compare this to the `\def' and
663 `\edef' commands in TeX.
665 The following example prints the numbers 20 and 10:
677 File: groff, Node: Parameters, Prev: Copy-in Mode, Up: Writing Macros
682 The arguments to a macro or string can be examined using a variety of
686 The number of arguments passed to a macro or string. This is a
687 read-only number register.
689 Any individual argument can be retrieved with one of the following
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.
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.
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::).
720 The name used to invoke the current macro. The `als' request can
721 make a macro have more than one name.
727 . tm \\$0: Houston, we have a problem.
732 .als foo generic-macro
733 .als bar generic-macro
736 *Note Request Arguments::.
739 File: groff, Node: Page Motions, Next: Drawing Requests, Prev: Writing Macros, Up: gtroff Reference
744 *Note Manipulating Spacing::, for a discussion of the main request
745 for vertical motion, `sp'.
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).
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
762 Here a primitive solution for a two-column macro.
765 .nr column-length 1.5i
774 . ll \\n[column-length]u
775 . wh -\\n[bottom-margin]u 2c-trap
782 . ie \\n[right-side] \{\
784 . po -(\\n[column-length]u + \\n[column-gap]u)
786 . wh -\\n[bottom-margin]u
789 . \" switch to right side
791 . po +(\\n[column-length]u + \\n[column-gap]u)
800 This is a small test which shows how the
801 rt request works in combination with mk.
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
812 This is a small test which shows how the
813 rt request works in combination with mk.
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.
822 The following escapes give fine control of movements about the page.
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.
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
838 There are some special-case escapes for vertical motion.
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'.
855 There are a number of special-case escapes for horizontal motion.
858 An unbreakable and unpaddable (i.e. not expanded during filling)
859 space. (Note: This is a backslash followed by a space.)
862 An unbreakable space that stretches like a normal inter-word space
863 when a line is adjusted.
866 A 1/6th em space. Ignored for TTY output devices (rounded to
870 A 1/12th em space. Ignored for TTY output devices (rounded to
874 A space the size of a digit.
876 The following string sets the TeX logo:
879 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
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).
894 The length of the string `abc' is \w'abc'u.
895 => The length of the string `abc' is 72u.
897 Font changes may occur in TEXT which don't affect current settings.
899 After use, `\w' sets several registers:
903 The highest and lowest point of the baseline, respectively,
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.
913 Defines the kinds of glyphs occurring in TEXT:
916 only short glyphs, no descenders or tall glyphs.
919 at least one descender.
922 at least one tall glyph.
925 at least one each of a descender and a tall glyph.
928 The amount of horizontal space (possibly negative) that
929 should be added to the last glyph before a subscript.
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.
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.
945 The current horizontal position at the input line.
948 A read-only number register containing the current horizontal
952 Overstrike glyphs A, B, C, ...; the glyphs are centered, and the
953 resulting spacing is the largest width of the affected glyphs.
956 Print glyph G with zero width, i.e., without spacing. Use this to
957 overstrike glyphs left-aligned.
959 - Escape: \Z'ANYTHING'
960 Print ANYTHING, then restore the horizontal and vertical position.
961 The argument may not contain tabs or leaders.
963 The following is an example of a strike-through macro:
968 \Z@\v'-.25m'\l'\\n[ww]u'@\\$1
977 File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference
982 `gtroff' provides a number of ways to draw lines and other figures
983 on 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
985 drawn. However, for complex drawings these operations can be quite
986 cumbersome, and it may be wise to use graphic preprocessors like `gpic'
987 or `ggrn'. *Note gpic::, and *Note ggrn::, for more information.
989 All drawing is done via escapes.
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
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
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]'.
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 `\&'.
1012 Here a small useful example:
1016 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
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.
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.
1035 This is a \L'3v'test.
1037 Here the result, produced with `grotty'.
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.
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.
1057 Draw a line from the current location to the relative point
1058 specified by (DX,DY).
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
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)'\
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
1085 Draw a circle with a diameter of D with the leftmost point at
1086 the current position.
1089 Draw a solid circle with the same parameters as an outlined
1090 circle. No outline is drawn.
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.
1097 Draw a solid ellipse with the same parameters as an outlined
1098 ellipse. No outline is drawn.
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.
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.
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.
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
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.
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.
1138 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
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)'\
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
1157 *Note Graphics Commands::.
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.
1163 Here an example how to create a large opening brace:
1166 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
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.
1176 *Note Manipulating Spacing::, how to adjust the vertical spacing
1177 with the `\x' escape.
1180 File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference
1185 "Traps" are locations, which, when reached, call a specified macro.
1186 These traps can occur at a given location on the page, at a given
1187 location in the current diversion, at a blank line, after a certain
1188 number of input lines, or at the end of input.
1190 Setting a trap is also called "planting". It is also said that a
1191 trap is "sprung" if the associated macro is executed.
1195 * Page Location Traps::
1197 * Input Line Traps::
1198 * Blank Line Traps::
1199 * End-of-input Traps::
1202 File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps
1207 "Page location traps" perform an action when `gtroff' reaches or
1208 passes a certain vertical location on the page. Page location traps
1209 have a variety of purposes, including:
1211 * setting headers and footers
1213 * setting body text in multiple columns
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.
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
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.
1236 The following is a simple example of how many macro packages set
1237 headers and footers.
1240 .de hd \" Page header
1246 .de fo \" Page footer
1252 .wh 0 hd \" trap at top of the page
1253 .wh -1i fo \" trap one inch from bottom
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.
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):
1296 A read-only number register holding the distance to the next trap.
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.
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.
1312 Default scaling indicator for DIST is `v'. If DIST is missing,
1313 the trap is removed.
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.
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.
1332 File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps
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.
1345 File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps
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.
1356 For example, one possible use is to have a macro which prints the
1357 next N lines in a bold font.
1369 The `itc' request is identical, except that a line interrupted
1370 with `\c' counts as one input line.
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.
1378 File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps
1383 - Request: .blm macro
1384 Set a blank line trap. `gtroff' executes MACRO when it encounters
1385 a blank line in the input file.
1388 File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps
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.
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
1404 . sp |(\\n[.t] - 6v)
nant's projects / dragonfly.git / blob