1 This is groff, produced by makeinfo version 4.3d from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.19.
5 Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation,
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."
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."
20 INFO-DIR-SECTION Typesetting
22 * Groff: (groff). The GNU troff document formatting system.
26 File: groff, Node: Changing Type Sizes, Next: Fractional Type Sizes, Prev: Sizes, Up: Sizes
36 Use the `ps' request or the `\s' escape to change (increase,
37 decrease) the type size (in points). Specify SIZE as either an
38 absolute point size, or as a relative change from the current size.
39 The size 0, or no argument, goes back to the previous size.
41 Default scaling indicator of `size' is `z'. If `size' is zero or
42 negative, it is set to 1u.
44 The read-only number register `.s' returns the point size in
45 points as a decimal fraction. This is a string. To get the point
46 size in scaled points, use the `.ps' register instead.
48 `.s' is associated with the current environment (*note
56 wink, wink, \s+2nudge, nudge,\s+8 say no more!
59 The `\s' escape may be called in a variety of ways. Much like
60 other escapes there must be a way to determine where the argument
61 ends and the text begins. Any of the following forms are valid:
64 Set the point size to N points. N must be either 0 or in the
69 Increase or decrease the point size by N points. N must be
73 Set the point size to NN points. NN must be exactly two
80 Increase or decrease the point size by NN points. NN must be
83 Note that `\s' doesn't produce an input token in `gtroff'. As a
84 consequence, it can be used in requests like `mc' (which expects a
85 single character as an argument) to change the font on the fly:
90 *Note Fractional Type Sizes::, for yet another syntactical form of
91 using the `\s' escape.
93 - Request: .sizes s1 s2 ... sn [0]
94 Some devices may only have certain permissible sizes, in which case
95 `gtroff' rounds to the nearest permissible size. The `DESC' file
96 specifies which sizes are permissible for the device.
98 Use the `sizes' request to change the permissible sizes for the
99 current output device. Arguments are in scaled points; the
100 `sizescale' line in the `DESC' file for the output device provides
101 the scaling factor. For example, if the scaling factor is 1000,
102 then the value 12000 is 12 points.
104 Each argument can be a single point size (such as `12000'), or a
105 range of sizes (such as `4000-72000'). You can optionally end the
108 - Request: .vs [space]
109 - Request: .vs +space
110 - Request: .vs -space
112 Change (increase, decrease) the vertical spacing by SPACE. The
113 default scaling indicator is `p'.
115 If `vs' is called without an argument, the vertical spacing is
116 reset to the previous value before the last call to `vs'.
118 `gtroff' creates a warning of type `range' if SPACE is negative;
119 the vertical spacing is then set to the vertical resolution (as
120 given in the `.V' register).
122 The read-only number register `.v' contains the current vertical
123 spacing; it is associated with the current environment (*note
126 The effective vertical line spacing consists of four components.
128 * The vertical line spacing as set with the `vs' request.
130 * The "post-vertical line spacing" as set with the `pvs' request.
131 This is vertical space which will be added after a line has been
134 * The "extra pre-vertical line space" as set with the `\x' request,
135 using a negative value. This is vertical space which will be
136 added once before the current line has been output.
138 * The "extra post-vertical line space" as set with the `\x' request,
139 using a positive value. This is vertical space which will be
140 added once after the current line has been output.
142 It is usually better to use `vs' or `pvs' instead of `ls' to produce
143 double-spaced documents: `vs' and `pvs' have a finer granularity for
144 the inserted vertical space compared to `ls'; furthermore, certain
145 preprocessors assume single-spacing.
147 *Note Manipulating Spacing::, for more details on the `\x' escape
148 and the `ls' request.
150 - Request: .pvs [space]
151 - Request: .pvs +space
152 - Request: .pvs -space
154 Change (increase, decrease) the post-vertical spacing by SPACE.
155 The default scaling indicator is `p'.
157 If `pvs' is called without an argument, the post-vertical spacing
158 is reset to the previous value before the last call to `pvs'.
160 `gtroff' creates a warning of type `range' if SPACE is zero or
161 negative; the vertical spacing is then set to zero.
163 The read-only number register `.pvs' contains the current
164 post-vertical spacing; it is associated with the current
165 environment (*note Environments::).
168 File: groff, Node: Fractional Type Sizes, Prev: Changing Type Sizes, Up: Sizes
170 Fractional Type Sizes
171 ---------------------
173 A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is
174 specified in the `DESC' file (1 by default). There is a new scale
175 indicator `z' which has the effect of multiplying by SIZESCALE.
176 Requests and escape sequences in `gtroff' interpret arguments that
177 represent a point size as being in units of scaled points, but they
178 evaluate each such argument using a default scale indicator of `z'.
179 Arguments treated in this way are the argument to the `ps' request, the
180 third argument to the `cs' request, the second and fourth arguments to
181 the `tkf' request, the argument to the `\H' escape sequence, and those
182 variants of the `\s' escape sequence that take a numeric expression as
183 their argument (see below).
185 For example, suppose SIZESCALE is 1000; then a scaled point is
186 equivalent to a millipoint; the request `.ps 10.25' is equivalent to
187 `.ps 10.25z' and thus sets the point size to 10250 scaled points, which
188 is equal to 10.25 points.
190 `gtroff' disallows the use of the `z' scale indicator in instances
191 where it would make no sense, such as a numeric expression whose
192 default scale indicator was neither `u' nor `z'. Similarly it would
193 make no sense to use a scaling indicator other than `z' or `u' in a
194 numeric expression whose default scale indicator was `z', and so
195 `gtroff' disallows this as well.
197 There is also new scale indicator `s' which multiplies by the number
198 of units in a scaled point. So, for example, `\n[.ps]s' is equal to
199 `1m'. Be sure not to confuse the `s' and `z' scale indicators.
202 A read-only number register returning the point size in scaled
205 `.ps' is associated with the current environment (*note
210 The last-requested point size in scaled points is contained in the
211 `.psr' read-only number register. The last requested point size
212 in points as a decimal fraction can be found in `.sr'. This is a
213 string-valued read-only number register.
215 Note that the requested point sizes are device-independent, whereas
216 the values returned by the `.ps' and `.s' registers are not. For
217 example, if a point size of 11pt is requested, and a `sizes'
218 request (or a `sizescale' line in a `DESC' file) specifies 10.95pt
219 instead, this value is actually used.
221 Both registers are associated with the current environment (*note
224 The `\s' escape has the following syntax for working with fractional
229 Set the point size to N scaled points; N is a numeric expression
230 with a default scale indicator of `z'.
240 Increase or or decrease the point size by N scaled points; N is a
241 numeric expression with a default scale indicator of `z'.
246 File: groff, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference
251 `gtroff' has string variables, which are entirely for user
252 convenience (i.e. there are no built-in strings exept `.T', but even
253 this is a read-write string variable).
255 - Request: .ds name [string]
256 - Request: .ds1 name [string]
259 - Escape: \*[name arg1 arg2 ...]
260 Define and access a string variable NAME (one-character name N,
261 two-character name NM). If NAME already exists, `ds' overwrites
262 the previous definition. Only the syntax form using brackets can
263 take arguments which are handled identically to macro arguments;
264 the single exception is that a closing bracket as an argument must
265 be enclosed in double quotes. *Note Request and Macro
266 Arguments::, and *Note Parameters::.
273 This is \*[foo nice].
274 => This is a nice test.
276 The `\*' escape "interpolates" (expands in-place) a
277 previously-defined string variable. To be more precise, the stored
278 string is pushed onto the input stack which is then parsed by
279 `gtroff'. Similar to number registers, it is possible to nest
280 strings, i.e. string variables can be called within string
283 If the string named by the `\*' escape does not exist, it is
284 defined as empty, and a warning of type `mac' is emitted (see
285 *Note Debugging::, for more details).
287 *Caution:* Unlike other requests, the second argument to the `ds'
288 request takes up the entire line including trailing spaces. This
289 means that comments on a line with such a request can introduce
290 unwanted space into a string.
293 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
295 Instead the comment should be put on another line or have the
296 comment escape adjacent with the end of the string.
299 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
301 To produce leading space the string can be started with a double
302 quote. No trailing quote is needed; in fact, any trailing quote is
303 included in your string.
306 .ds sign " Yours in a white wine sauce,
308 Strings are not limited to a single line of text. A string can
309 span several lines by escaping the newlines with a backslash. The
310 resulting string is stored _without_ the newlines.
313 .ds foo lots and lots \
314 of text are on these \
317 It is not possible to have real newlines in a string. To put a
318 single double quote character into a string, use two consecutive
319 double quote characters.
321 The `ds1' request turns off compatibility mode while interpreting
322 a string. To be more precise, a "compatibility save" input token
323 is inserted at the beginning of the string, and a "compatibility
324 restore" input token at the end.
328 .ds aa The value of xxx is \\n[xxx].
329 .ds1 bb The value of xxx ix \\n[xxx].
334 => warning: number register `[' not defined
335 => The value of xxx is 0xxx].
337 => The value of xxx ix 12345.
339 Strings, macros, and diversions (and boxes) share the same name
340 space. Internally, even the same mechanism is used to store them.
341 This has some interesting consequences. For example, it is
342 possible to call a macro with string syntax and vice versa.
349 => This is a funny test.
354 => This is a funny test.
356 Diversions and boxes can be also called with string syntax.
358 Another consequence is that you can copy one-line diversions or
366 .ds yyy This is \*[xxx]\c
370 As the previous example shows, it is possible to store formatted
371 output in strings. The `\c' escape prevents the insertion of an
372 additional blank line in the output.
374 Copying diversions longer than a single output line produces
384 .ds yyy This is \*[xxx]\c
386 => test This is a funny.
388 Usually, it is not predictable whether a diversion contains one or
389 more output lines, so this mechanism should be avoided. With UNIX
390 `troff', this was the only solution to strip off a final newline
391 from a diversion. Another disadvantage is that the spaces in the
392 copied string are already formatted, making them unstretchable.
393 This can cause ugly results.
395 A clean solution to this problem is available in GNU `troff',
396 using the requests `chop' to remove the final newline of a
397 diversion, and `unformat' to make the horizontal spaces
410 => This is a funny test.
412 *Note Gtroff Internals::, for more information.
414 - Request: .as name [string]
415 - Request: .as1 name [string]
416 The `as' request is similar to `ds' but appends STRING to the
417 string stored as NAME instead of redefining it. If NAME doesn't
418 exist yet, it is created.
421 .as sign " with shallots, onions and garlic,
423 The `as1' request is similar to `as', but compatibility mode is
424 switched off while the appended string is interpreted. To be more
425 precise, a "compatibility save" input token is inserted at the
426 beginning of the appended string, and a "compatibility restore"
427 input token at the end.
429 Rudimentary string manipulation routines are given with the next two
432 - Request: .substring str n1 [n2]
433 Replace the string named STR with the substring defined by the
434 indices N1 and N2. The first character in the string has index 0.
435 If N2 is omitted, it is taken to be equal to the string's length.
436 If the index value N1 or N2 is negative, it is counted from the
437 end of the string, going backwards: The last character has
438 index -1, the character before the last character has index -2,
448 - Request: .length reg str
449 Compute the number of characters of STR and return it in the
450 number register REG. If REG doesn't exist, it is created. `str'
451 is read in copy mode.
454 .ds xxx abcd\h'3i'efgh
461 Rename the request, macro, diversion, or string XX to YY.
464 Remove the request, macro, diversion, or string XX. `gtroff'
465 treats subsequent invocations as if the object had never been
468 - Request: .als new old
469 Create an alias named NEW for the request, string, macro, or
470 diversion object named OLD. The new name and the old name are
471 exactly equivalent (it is similar to a hard rather than a soft
472 link). If OLD is undefined, `gtroff' generates a warning of type
473 `mac' and ignores the request.
476 Remove (chop) the last character from the macro, string, or
477 diversion named XX. This is useful for removing the newline from
478 the end of diversions that are to be interpolated as strings.
479 This command can be used repeatedly; see *Note Gtroff Internals::,
480 for details on nodes inserted additionally by `gtroff'.
482 *Note Identifiers::, and *Note Comments::.
485 File: groff, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference
487 Conditionals and Loops
488 ======================
492 * Operators in Conditionals::
497 File: groff, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops
499 Operators in Conditionals
500 -------------------------
502 In `if' and `while' requests, there are several more operators
507 True if the current page is even or odd numbered (respectively).
510 True if the document is being processed in nroff mode (i.e., the
511 `.nroff' command has been issued).
514 True if the document is being processed in troff mode (i.e., the
515 `.troff' command has been issued).
518 Always false. This condition is for compatibility with other
519 `troff' versions only.
522 True if the string XXX is equal to the string YYY. Other
523 characters can be used in place of the single quotes; the same set
524 of delimiters as for the `\D' escape is used (*note Escapes::).
525 `gtroff' formats the strings before being compared:
534 The resulting motions, glyph sizes, and fonts have to match,(1)
535 (*note Operators in Conditionals-Footnote-1::) and not the
536 individual motion, size, and font requests. In the previous
537 example, `|' and `\fR|\fP' both result in a roman `|' glyph with
538 the same point size and at the same location on the page, so the
539 strings are equal. If `.ft I' had been added before the `.ie',
540 the result would be "false" because (the first) `|' produces an
541 italic `|' rather than a roman one.
544 True if there is a number register named XXX.
547 True if there is a string, macro, diversion, or request named XXX.
550 True if there is a color named XXX.
553 True if there is a glyph G available(2) (*note Operators in
554 Conditionals-Footnote-2::); G is either an ASCII character or a
555 special character (`\(GG' or `\[GGG]'); the condition is also true
556 if G has been defined by the `char' request.
558 Note that these operators can't be combined with other operators like
559 `:' or `&'; only a leading `!' (without whitespace between the
560 exclamation mark and the operator) can be used to negate the result.
570 A whitespace after `!' always evaluates to zero (this bizarre
571 behaviour is due to compatibility with UNIX `troff').
581 It is possible to omit the whitespace before the argument to the
582 `r', `d', and `c' operators.
587 File: groff, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals
589 (1) The created output nodes must be identical. *Note Gtroff
592 (2) The name of this conditional operator is a misnomer since it
593 tests names of output glyphs.
596 File: groff, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops
601 `gtroff' has if-then-else constructs like other languages, although
602 the formatting can be painful.
604 - Request: .if expr anything
605 Evaluate the expression EXPR, and executes ANYTHING (the remainder
606 of the line) if EXPR evaluates to non-zero (true). ANYTHING is
607 interpreted as though it was on a line by itself (except that
608 leading spaces are swallowed). *Note Expressions::, for more info.
613 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
617 - Request: .nop anything
618 Executes ANYTHING. This is similar to `.if 1'.
620 - Request: .ie expr anything
621 - Request: .el anything
622 Use the `ie' and `el' requests to write an if-then-else. The
623 first request is the `if' part and the latter is the `else' part.
626 .ie n .ls 2 \" double-spacing in nroff
627 .el .ls 1 \" single-spacing in troff
632 In many cases, an if (or if-else) construct needs to execute more
633 than one request. This can be done using the `\{' and `\}'
634 escapes. The following example shows the possible ways to use
635 these escapes (note the position of the opening and closing
652 File: groff, Node: while, Prev: if-else, Up: Conditionals and Loops
657 `gtroff' provides a looping construct using the `while' request,
658 which is used much like the `if' (and related) requests.
660 - Request: .while expr anything
661 Evaluate the expression EXPR, and repeatedly execute ANYTHING (the
662 remainder of the line) until EXPR evaluates to 0.
670 => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
674 * The body of a `while' request is treated like the body of a
675 `de' request: `gtroff' temporarily stores it in a macro which
676 is deleted after the loop has been exited. It can
677 considerably slow down a macro if the body of the `while'
678 request (within the macro) is large. Each time the macro is
679 executed, the `while' body is parsed and stored again as a
685 . while (\\n[num] > 0) \{\
686 . \" many lines of code
691 The traditional and ofter better solution (UNIX `troff'
692 doesn't have the `while' request) is to use a recursive macro
693 instead which is parsed only once during its definition.
697 . if (\\n[num] > 0) \{\
698 . \" many lines of code
709 Note that the number of available recursion levels is set
710 to 1000 (this is a compile-time constant value of `gtroff').
712 * The closing brace of a `while' body must end a line.
717 . while (\n[a] < 10) \{\
724 Break out of a `while' loop. Be sure not to confuse this with the
725 `br' request (causing a line break).
728 Finish the current iteration of a `while' loop, immediately
729 restarting the next iteration.
734 File: groff, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference
739 A "macro" is a collection of text and embedded commands which can be
740 invoked multiple times. Use macros to define common operations.
742 - Request: .de name [end]
743 - Request: .de1 name [end]
744 - Request: .dei name [end]
745 Define a new macro named NAME. `gtroff' copies subsequent lines
746 (starting with the next one) into an internal buffer until it
747 encounters the line `..' (two dots). The optional second argument
748 to `de' changes this to a macro to `.END'.
750 There can be whitespace after the first dot in the line containing
751 the ending token (either `.' or macro `END').
753 Here a small example macro called `P' which causes a break and
754 inserts some vertical space. It could be used to separate
763 The following example defines a macro within another. Remember
764 that expansion must be protected twice; once for reading the macro
765 and once for executing.
768 \# a dummy macro to avoid a warning
774 . nop \f[B]Hallo \\\\$1!\f[]
782 Since `\f' has no expansion, it isn't necessary to protect its
783 backslash. Had we defined another macro within `bar' which takes
784 a parameter, eight backslashes would be necessary before `$1'.
786 The `de1' request turns off compatibility mode while executing the
787 macro. On entry, the current compatibility mode is saved and
794 The value of xxx is \\n[xxx].
797 The value of xxx ix \\n[xxx].
803 => warning: number register
\e' not defined
804 => The value of xxx is 0xxx].
806 => The value of xxx ix 12345.
808 The `dei' request defines a macro indirectly. That is, it expands
809 strings whose names are NAME or END before performing the append.
823 Using `trace.tmac', you can trace calls to `de' and `de1'.
825 Note that macro identifiers are shared with identifiers for
826 strings and diversions.
828 - Request: .am name [end]
829 - Request: .am1 name [end]
830 - Request: .ami name [end]
831 Works similarly to `de' except it appends onto the macro named
832 NAME. So, to make the previously defined `P' macro actually do
833 indented instead of block paragraphs, add the necessary code to the
834 existing macro like this:
841 The `am1' request turns off compatibility mode while executing the
842 appended macro piece. To be more precise, a "compatibility save"
843 input token is inserted at the beginning of the appended code, and
844 a "compatibility restore" input token at the end.
846 The `ami' request appends indirectly, meaning that `gtroff'
847 expands strings whose names are NAME or END before performing the
850 Using `trace.tmac', you can trace calls to `am' and `am1'.
852 *Note Strings::, for the `als' request to rename a macro.
854 The `de', `am', `di', `da', `ds', and `as' requests (together with
855 its variants) only create a new object if the name of the macro,
856 diversion or string diversion is currently undefined or if it is
857 defined to be a request; normally they modify the value of an existing
861 Exit a macro, immediately returning to the caller.
869 File: groff, Node: Copy-in Mode, Next: Parameters, Prev: Writing Macros, Up: Writing Macros
874 When `gtroff' reads in the text for a macro, string, or diversion,
875 it copies the text (including request lines, but excluding escapes) into
876 an internal buffer. Escapes are converted into an internal form,
877 except for `\n', `\$', `\*', `\\' and `\<RET>' which are evaluated and
878 inserted into the text where the escape was located. This is known as
879 "copy-in" mode or "copy" mode.
881 What this means is that you can specify when these escapes are to be
882 evaluated (either at copy-in time or at the time of use) by insulating
883 the escapes with an extra backslash. Compare this to the `\def' and
884 `\edef' commands in TeX.
886 The following example prints the numbers 20 and 10:
898 File: groff, Node: Parameters, Prev: Copy-in Mode, Up: Writing Macros
903 The arguments to a macro or string can be examined using a variety of
907 The number of arguments passed to a macro or string. This is a
908 read-only number register.
910 Any individual argument can be retrieved with one of the following
916 Retrieve the Nth, NNth or NNNth argument. As usual, the first
917 form only accepts a single number (larger than zero), the second a
918 two-digit number (larger or equal to 10), and the third any
919 positive integer value (larger than zero). Macros and strings can
920 have an unlimited number of arguments. Note that due to copy-in
921 mode, use two backslashes on these in actual use to prevent
922 interpolation until the macro is actually invoked.
924 - Request: .shift [n]
925 Shift the arguments 1 position, or as many positions as specified
926 by its argument. After executing this request, argument I becomes
927 argument I-N; arguments 1 to N are no longer available. Shifting
928 by negative amounts is currently undefined.
932 In some cases it is convenient to use all of the arguments at once
933 (for example, to pass the arguments along to another macro). The
934 `\$*' escape concatenates all the arguments separated by spaces. A
935 similar escape is `\$@', which concatenates all the arguments with
936 each surrounded by double quotes, and separated by spaces. If not
937 in compatibility mode, the input level of double quotes is
938 preserved (see *Note Request and Macro Arguments::).
941 The name used to invoke the current macro. The `als' request can
942 make a macro have more than one name.
948 . tm \\$0: Houston, we have a problem.
953 .als foo generic-macro
954 .als bar generic-macro
957 *Note Request and Macro Arguments::.
960 File: groff, Node: Page Motions, Next: Drawing Requests, Prev: Writing Macros, Up: gtroff Reference
965 *Note Manipulating Spacing::, for a discussion of the main request
966 for vertical motion, `sp'.
969 - Request: .rt [dist]
970 The request `mk' can be used to mark a location on a page, for
971 movement to later. This request takes a register name as an
972 argument in which to store the current page location. With no
973 argument it stores the location in an internal register. The
974 results of this can be used later by the `rt' or the `sp' request
975 (or the `\v' escape).
977 The `rt' request returns _upwards_ to the location marked with the
978 last `mk' request. If used with an argument, return to a position
979 which distance from the top of the page is DIST (no previous call
980 to `mk' is necessary in this case). Default scaling indicator is
983 Here a primitive solution for a two-column macro.
986 .nr column-length 1.5i
995 . ll \\n[column-length]u
996 . wh -\\n[bottom-margin]u 2c-trap
1003 . ie \\n[right-side] \{\
1005 . po -(\\n[column-length]u + \\n[column-gap]u)
1007 . wh -\\n[bottom-margin]u
1010 . \" switch to right side
1012 . po +(\\n[column-length]u + \\n[column-gap]u)
1021 This is a small test which shows how the
1022 rt request works in combination with mk.
1025 Starting here, text is typeset in two columns.
1026 Note that this implementation isn't robust
1027 and thus not suited for a real two-column
1033 This is a small test which shows how the
1034 rt request works in combination with mk.
1036 Starting here, isn't robust
1037 text is typeset and thus not
1038 in two columns. suited for a
1039 Note that this real two-column
1040 implementation macro.
1043 The following escapes give fine control of movements about the page.
1046 Move vertically, usually from the current location on the page (if
1047 no absolute position operator `|' is used). The argument E
1048 specifies the distance to move; positive is downwards and negative
1049 upwards. The default scaling indicator for this escape is `v'.
1050 Beware, however, that `gtroff' continues text processing at the
1051 point where the motion ends, so you should always balance motions
1052 to avoid interference with text processing.
1054 `\v' doesn't trigger a trap. This can be quite useful; for
1055 example, consider a page bottom trap macro which prints a marker
1056 in the margin to indicate continuation of a footnote or something
1059 There are some special-case escapes for vertical motion.
1071 Move horizontally, usually from the current location (if no
1072 absolute position operator `|' is used). The expression E
1073 indicates how far to move: positive is rightwards and negative
1074 leftwards. The default scaling indicator for this escape is `m'.
1076 This horizontal space is not discarded at the end of a line. To
1077 insert discardable space of a certain length use the `ss' request.
1079 There are a number of special-case escapes for horizontal motion.
1082 An unbreakable and unpaddable (i.e. not expanded during filling)
1083 space. (Note: This is a backslash followed by a space.)
1086 An unbreakable space that stretches like a normal inter-word space
1087 when a line is adjusted.
1090 A 1/6th em space. Ignored for TTY output devices (rounded to
1094 A 1/12th em space. Ignored for TTY output devices (rounded to
1098 A space the size of a digit.
1100 The following string sets the TeX logo:
1103 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
1113 Return the width of the specified TEXT in basic units. This
1114 allows horizontal movement based on the width of some arbitrary
1115 text (e.g. given as an argument to a macro).
1118 The length of the string `abc' is \w'abc'u.
1119 => The length of the string `abc' is 72u.
1121 Font changes may occur in TEXT which don't affect current settings.
1123 After use, `\w' sets several registers:
1127 The highest and lowest point of the baseline, respectively,
1132 Like the `st' and `sb' registers, but takes account of the
1133 heights and depths of glyphs. With other words, this gives
1134 the highest and lowest point of TEXT. Values below the
1135 baseline are negative.
1138 Defines the kinds of glyphs occurring in TEXT:
1141 only short glyphs, no descenders or tall glyphs.
1144 at least one descender.
1147 at least one tall glyph.
1150 at least one each of a descender and a tall glyph.
1153 The amount of horizontal space (possibly negative) that
1154 should be added to the last glyph before a subscript.
1157 How far to right of the center of the last glyph in the `\w'
1158 argument, the center of an accent from a roman font should be
1159 placed over that glyph.
1163 - Escape: \k[position]
1164 Store the current horizontal position in the _input_ line in
1165 number register with name POSITION (one-character name P,
1166 two-character name PS). Use this, for example, to return to the
1167 beginning of a string for highlighting or other decoration.
1170 The current horizontal position at the input line.
1173 A read-only number register containing the current horizontal
1177 Overstrike glyphs A, B, C, ...; the glyphs are centered, and the
1178 resulting spacing is the largest width of the affected glyphs.
1181 Print glyph G with zero width, i.e., without spacing. Use this to
1182 overstrike glyphs left-aligned.
1184 - Escape: \Z'anything'
1185 Print ANYTHING, then restore the horizontal and vertical position.
1186 The argument may not contain tabs or leaders.
1188 The following is an example of a strike-through macro:
1193 \Z@\v'-.25m'\l'\\n[ww]u'@\\$1
1198 an actual emergency!
1202 File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference
1207 `gtroff' provides a number of ways to draw lines and other figures
1208 on the page. Used in combination with the page motion commands (see
1209 *Note Page Motions::, for more info), a wide variety of figures can be
1210 drawn. However, for complex drawings these operations can be quite
1211 cumbersome, and it may be wise to use graphic preprocessors like `gpic'
1212 or `ggrn'. *Note gpic::, and *Note ggrn::, for more information.
1214 All drawing is done via escapes.
1218 Draw a line horizontally. L is the length of the line to be
1219 drawn. If it is positive, start the line at the current location
1220 and draw to the right; its end point is the new current location.
1221 Negative values are handled differently: The line starts at the
1222 current location and draws to the left, but the current location
1225 L can also be specified absolutely (i.e. with a leading `|') which
1226 draws back to the beginning of the input line. Default scaling
1229 The optional second parameter G is a glyph to draw the line with.
1230 If this second argument is not specified, `gtroff' uses the
1231 underscore glyph, `\[ru]'.
1233 To separate the two arguments (to prevent `gtroff' from
1234 interpreting a drawing glyph as a scaling indicator if the glyph is
1235 represented by a single character) use `\&'.
1237 Here a small useful example:
1241 \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
1244 Note that this works by outputting a box rule (a vertical line),
1245 then the text given as an argument and then another box rule.
1246 Finally, the line drawing escapes both draw from the current
1247 location to the beginning of the _input_ line - this works because
1248 the line length is negative, not moving the current point.
1252 Draw vertical lines. Its parameters are similar to the `\l'
1253 escape, except that the default scaling indicator is `v'. The
1254 movement is downwards for positive values, and upwards for
1255 negative values. The default glyph is the box rule glyph,
1256 `\[br]'. As with the vertical motion escapes, text processing
1257 blindly continues where the line ends.
1260 This is a \L'3v'test.
1262 Here the result, produced with `grotty'.
1271 - Escape: \D'command arg ...'
1272 The `\D' escape provides a variety of drawing functions. Note
1273 that on character devices, only vertical and horizontal lines are
1274 supported within `grotty'; other devices may only support a subset
1275 of the available drawing functions.
1277 The default scaling indicator for all subcommands of `\D' is `m'
1278 for horizontal distances and `v' for vertical ones. Exceptions
1279 are `\D'f ...'' and `\D't ...'' which use `u' as the default, and
1280 `\D'FX ...'' which arguments are treated similar to the `defcolor'
1284 Draw a line from the current location to the relative point
1285 specified by (DX,DY).
1287 The following example is a macro for creating a box around a
1288 text string; for simplicity, the box margin is taken as a
1295 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
1296 \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
1297 \D'l (\\n[@wd]u + .4m) 0'\
1298 \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
1299 \D'l -(\\n[@wd]u + .4m) 0'\
1300 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
1305 First, the width of the string is stored in register `@wd'.
1306 Then, four lines are drawn to form a box, properly offset by
1307 the box margin. The registers `rst' and `rsb' are set by the
1308 `\w' escape, containing the largest height and depth of the
1312 Draw a circle with a diameter of D with the leftmost point at
1313 the current position. After drawing, the current location is
1314 positioned at the rightmost point of the circle.
1317 Draw a solid circle with the same parameters and behaviour as
1318 an outlined circle. No outline is drawn.
1321 Draw an ellipse with a horizontal diameter of X and a vertical
1322 diameter of Y with the leftmost point at the current position.
1323 After drawing, the current location is positioned at the
1324 rightmost point of the ellipse.
1327 Draw a solid ellipse with the same parameters and behaviour
1328 as an outlined ellipse. No outline is drawn.
1330 `\D'a DX1 DY1 DX2 DY2''
1331 Draw an arc clockwise from the current location through the
1332 two specified relative locations (DX1,DY1) and (DX2,DY2).
1333 The coordinates of the first point are relative to the
1334 current position, and the coordinates of the second point are
1335 relative to the first point. After drawing, the current
1336 position is moved to the final point of the arc.
1338 `\D'~ DX1 DY1 DX2 DY2 ...''
1339 Draw a spline from the current location to the relative point
1340 (DX1,DY1) and then to (DX2,DY2), and so on. The current
1341 position is moved to the terminal point of the drawn curve.
1344 Set the shade of gray to be used for filling solid objects
1345 to N; N must be an integer between 0 and 1000, where 0
1346 corresponds solid white and 1000 to solid black, and values
1347 in between correspond to intermediate shades of gray. This
1348 applies only to solid circles, solid ellipses, and solid
1349 polygons. By default, a level of 1000 is used.
1351 Despite of being silly, the current point is moved
1352 horizontally to the right by N.
1354 Don't use this command! It has the serious drawback that it
1355 will be always rounded to the next integer multiple of the
1356 horizontal resolution (the value of the `hor' keyword in the
1357 `DESC' file). Use `\M' (*note Colors::) or `\D'Fg ...''
1360 `\D'p DX1 DY1 DX2 DY2 ...''
1361 Draw a polygon from the current location to the relative
1362 position (DX1,DY1) and then to (DX2,DY2) and so on. When the
1363 specified data points are exhausted, a line is drawn back to
1364 the starting point. The current position is changed by
1365 adding the sum of all arguments with odd index to the actual
1366 horizontal position and the even ones to the vertical
1369 `\D'P DX1 DY1 DX2 DY2 ...''
1370 Draw a solid polygon with the same parameters and behaviour
1371 as an outlined polygon. No outline is drawn.
1373 Here a better variant of the box macro to fill the box with
1374 some color. Note that the box must be drawn before the text
1375 since colors in `gtroff' are not transparent; the filled
1376 polygon would hide the text completely.
1382 \h'-.2m'\v'(.2m - \\n[rsb]u)'\
1384 \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
1385 (\\n[@wd]u + .4m) 0 \
1386 0 (\\n[rst]u - \\n[rsb]u + .4m) \
1387 -(\\n[@wd]u + .4m) 0'\
1388 \h'.2m'\v'-(.2m - \\n[rsb]u)'\
1395 Set the current line thickness to N machine units. A value of
1396 zero selects the smallest available line thickness. A
1397 negative value makes the line thickness proportional to the
1398 current point size (this is the default behaviour of AT&T
1401 Despite of being silly, the current point is moved
1402 horizontally to the right by N.
1404 `\D'FSCHEME COLOR_COMPONENTS''
1405 Change current fill color. SCHEME is a single letter
1406 denoting the color scheme: `r' (rgb), `c' (cmy), `k' (cmyk),
1407 `g' (gray), or `d' (default color). The color components use
1408 exactly the same syntax as in the `defcolor' request (*note
1409 Colors::); the command `\D'Fd'' doesn't take an argument.
1411 _No_ position changing!
1416 \D'Fg .3' \" same gray as \D'f 700' \D'Fr #0000ff' \"
1419 *Note Graphics Commands::.
1421 - Escape: \b'string'
1422 "Pile" a sequence of glyphs vertically, and center it vertically
1423 on the current line. Use it to build large brackets and braces.
1425 Here an example how to create a large opening brace:
1428 \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
1430 The first glyph is on the top, the last glyph in STRING is at the
1431 bottom. Note that `gtroff' separates the glyphs vertically by 1m,
1432 and the whole object is centered 0.5m above the current baseline;
1433 the largest glyph width is used as the width for the whole object.
1434 This rather unflexible positioning algorithm doesn't work with
1435 `-Tdvi' since the bracket pieces vary in height for this device.
1436 Instead, use the `eqn' preprocessor.
1438 *Note Manipulating Spacing::, how to adjust the vertical spacing
1439 with the `\x' escape.
1442 File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference
1447 "Traps" are locations, which, when reached, call a specified macro.
1448 These traps can occur at a given location on the page, at a given
1449 location in the current diversion, at a blank line, after a certain
1450 number of input lines, or at the end of input.
1452 Setting a trap is also called "planting". It is also said that a
1453 trap is "sprung" if the associated macro is executed.
1457 * Page Location Traps::
1459 * Input Line Traps::
1460 * Blank Line Traps::
1461 * End-of-input Traps::