1GROFF_DIFF(7) Miscellaneous Information Manual GROFF_DIFF(7)
2
6 groff_diff - differences between GNU troff and classical troff
7
9 This manual page describes the language differences between groff, the
10 GNU roff text processing system, and the classical roff formatter of
11 the freely available Unix 7 of the 1970s, documented in the Troff
12 User's Manual by Ossanna and Kernighan. This inludes the roff language
13 as well as the intermediate output format (troff output).
14 The section SEE ALSO gives pointers to both the classical roff and the
16 modern groff documentation.
17
19 In this section, all additional features of groff compared to the clas‐
20 sical Unix 7 troff are described in detail.
21 Long names
23 The names of number registers, fonts, strings/macros/diversions, spe‐
24 cial characters (glyphs), and colors can be of any length. In escape
25 sequences, additionally to the classical `(xx' construction for a two-
26 character glyph name, you can use `[xxx]' for a name of arbitrary
27 length.
28 \[xxx] Print the special character (glyph) called xxx.
30 \[comp1 comp2 ...]
32 Print composite glyph consisting of multiple components. Exam‐
33 ple: `\[A ho]' is capital letter A with ogonek which finally
34 maps to glyph name `u0041_0328'. See the groff info file for
35 details how a glyph name for a composite glyph is constructed,
36 and groff_char(7) for a list of glyph name components used in
37 composite glyph names.
38 \f[xxx]
40 Set font xxx. Additionally, \f[] is a new syntax form equal to
41 \fP, i.e., to return to the previous font.
42 \*[xxx arg1 arg2 ...]
44 Interpolate string xxx, taking arg1, arg2, ... as arguments.
45 \n[xxx]
47 Interpolate number register xxx.
48 Fractional point sizes
50 A scaled point is equal to 1/sizescale points, where sizescale is spec‐
51 ified in the DESC file (1 by default). There is a new scale indica‐
52 tor z that has the effect of multiplying by sizescale. Requests and
53 escape sequences in troff interpret arguments that represent a point
54 size as being in units of scaled points, but they evaluate each such
55 argument using a default scale indicator of z. Arguments treated in
56 this way are the argument to the ps request, the third argument to the
57 cs request, the second and fourth arguments to the tkf request, the
58 argument to the \H escape sequence, and those variants of the \s escape
59 sequence that take a numeric expression as their argument.
60 For example, suppose sizescale is 1000; then a scaled point is equiva‐
62 lent to a millipoint; the call .ps 10.25 is equivalent to .ps 10.25z
63 and so sets the point size to 10250 scaled points, which is equal to
64 10.25 points.
65 The number register \n[.s] returns the point size in points as decimal
67 fraction. There is also a new number register \n[.ps] that returns the
68 point size in scaled points.
69 It would make no sense to use the z scale indicator in a numeric
71 expression whose default scale indicator was neither u nor z, and so
72 troff disallows this. Similarly it would make no sense to use a scal‐
73 ing indicator other than z or u in a numeric expression whose default
74 scale indicator was z, and so troff disallows this as well.
75 There is also new scale indicator s which multiplies by the number of
77 units in a scaled point. So, for example, \n[.ps]s is equal to 1m. Be
78 sure not to confuse the s and z scale indicators.
79 Numeric expressions
81 Spaces are permitted in a number expression within parentheses.
82 M indicates a scale of 100ths of an em. f indicates a scale of 65536
84 units, providing fractions for color definitions with the defcolor
85 request. For example, 0.5f = 32768u.
86 e1>?e2 The maximum of e1 and e2.
88 e1<?e2 The minimum of e1 and e2.
90 (c;e) Evaluate e using c as the default scaling indicator. If c is
92 missing, ignore scaling indicators in the evaluation of e.
93 New escape sequences
95 \A'anything'
96 This expands to 1 or 0, depending on whether anything is or is
97 not acceptable as the name of a string, macro, diversion, number
98 register, environment, font, or color. It returns 0 if anything
99 is empty. This is useful if you want to look up user input in
100 some sort of associative table.
101 \B'anything'
103 This expands to 1 or 0, depending on whether anything is or is
104 not a valid numeric expression. It returns 0 if anything is
105 empty.
106 \C'xxx'
108 Typeset glyph named xxx. Normally it is more convenient to use
109 \[xxx]. But \C has the advantage that it is compatible with
110 recent versions of UNIX and is available in compatibility mode.
111 \E This is equivalent to an escape character, but it is not inter‐
113 preted in copy mode. For example, strings to start and end
114 superscripting could be defined like this
115 .ds { \v'-.3m'\s'\En[.s]*6u/10u'
117 .ds } \s0\v'.3m'
118 The use of \E ensures that these definitions work even if \*{
120 gets interpreted in copy mode (for example, by being used in a
121 macro argument).
122 \Ff
124 \F(fm
125 \F[fam]
126 Change font family. This is the same as the fam request. \F[]
127 switches back to the previous color (note that \FP won't work;
128 it selects font family `P' instead).
129 \mx
131 \m(xx
132 \m[xxx]
133 Set drawing color. \m[] switches back to the previous color.
134 \Mx
136 \M(xx
137 \M[xxx]
138 Set background color for filled objects drawn with the \D'...'
139 commands. \M[] switches back to the previous color.
140 \N'n' Typeset the glyph with index n in the current font. n can be
142 any integer. Most devices only have glyphs with indices between
143 0 and 255. If the current font does not contain a glyph with
144 that code, special fonts are not searched. The \N escape
145 sequence can be conveniently used in conjunction with the char
146 request, for example
147 .char \[phone] \f(ZD\N'37'
149 The index of each glyph is given in the fourth column in the
151 font description file after the charset command. It is possible
152 to include unnamed glyphs in the font description file by using
153 a name of ---; the \N escape sequence is the only way to use
154 these.
155 \On
157 \O[n] Suppress troff output. The escapes \O2, \O3, \O4, and \O5 are
158 intended for internal use by grohtml.
159 \O0 Disable any ditroff glyphs from being emitted to the
161 device driver, provided that the escape occurs at the
162 outer level (see \O3 and \O4).
163 \O1 Enable output of glyphs, provided that the escape occurs
165 at the outer level.
166 \O0 and \O1 also reset the registers \n[opminx],
168 \n[opminy], \n[opmaxx], and \n[opmaxy] to -1. These four
169 registers mark the top left and bottom right hand corners
170 of a box which encompasses all written glyphs.
171 \O2 Provided that the escape occurs at the outer level,
173 enable output of glyphs and also write out to stderr the
174 page number and four registers encompassing the glyphs
175 previously written since the last call to \O.
176 \O3 Begin a nesting level. At start-up, troff is at outer
178 level. This is really an internal mechanism for grohtml
179 while producing images. They are generated by running
180 the troff source through troff to the postscript device
181 and ghostscript to produce images in PNG format. The \O3
182 escape starts a new page if the device is not html (to
183 reduce the possibility of images crossing a page bound‐
184 ary).
185 \O4 End a nesting level.
187 \O5[Pfilename]
189 This escape is grohtml specific. Provided that this
190 escape occurs at the outer nesting level, write filename
191 to stderr. The position of the image, P, must be speci‐
192 fied and must be one of l, r, c, or i (left, right, cen‐
193 tered, inline). filename is associated with the produc‐
194 tion of the next inline image.
195 \R'name ±n'
197 This has the same effect as
198 .nr name ±n
200 \s(nn
202 \s±(nn Set the point size to nn points; nn must be exactly two digits.
203 \s[±n]
205 \s±[n]
206 \s'±n'
207 \s±'n' Set the point size to n scaled points; n is a numeric expression
208 with a default scale indicator of z.
209 \Vx
211 \V(xx
212 \V[xxx]
213 Interpolate the contents of the environment variable xxx, as
214 returned by getenv(3). \V is interpreted in copy mode.
215 \Yx
217 \Y(xx
218 \Y[xxx]
219 This is approximately equivalent to \X'\*[xxx]'. However the
220 contents of the string or macro xxx are not interpreted; also it
221 is permitted for xxx to have been defined as a macro and thus
222 contain newlines (it is not permitted for the argument to \X to
223 contain newlines). The inclusion of newlines requires an exten‐
224 sion to the UNIX troff output format, and confuses drivers that
225 do not know about this extension.
226 \Z'anything'
228 Print anything and then restore the horizontal and vertical
229 position; anything may not contain tabs or leaders.
230 \$0 The name by which the current macro was invoked. The als
232 request can make a macro have more than one name.
233 \$* In a macro or string, the concatenation of all the arguments
235 separated by spaces.
236 \$@ In a macro or string, the concatenation of all the arguments
238 with each surrounded by double quotes, and separated by spaces.
239 \$^ In a macro, the representation of all parameters as if they were
241 an argument to the ds request.
242 \$(nn
244 \$[nnn]
245 In a macro or string, this gives the nn-th or nnn-th argument.
246 Macros and strings can have an unlimited number of arguments.
247 \?anything\?
249 When used in a diversion, this transparently embeds anything in
250 the diversion. anything is read in copy mode. When the diver‐
251 sion is reread, anything is interpreted. anything may not con‐
252 tain newlines; use \! if you want to embed newlines in a diver‐
253 sion. The escape sequence \? is also recognized in copy mode
254 and turned into a single internal code; it is this code that
255 terminates anything. Thus
256 .nr x 1
258 .nf
259 .di d
260 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
261 .di
262 .nr x 2
263 .di e
264 .d
265 .di
266 .nr x 3
267 .di f
268 .e
269 .di
270 .nr x 4
271 .f
272 prints 4.
274 \/ This increases the width of the preceding glyph so that the
276 spacing between that glyph and the following glyph is correct if
277 the following glyph is a roman glyph. It is a good idea to use
278 this escape sequence whenever an italic glyph is immediately
279 followed by a roman glyph without any intervening space.
280 \, This modifies the spacing of the following glyph so that the
282 spacing between that glyph and the preceding glyph is correct if
283 the preceding glyph is a roman glyph. It is a good idea to use
284 this escape sequence whenever a roman glyph is immediately fol‐
285 lowed by an italic glyph without any intervening space.
286 \) Like \& except that it behaves like a character declared with
288 the cflags request to be transparent for the purposes of end-of-
289 sentence recognition.
290 \~ This produces an unbreakable space that stretches like a normal
292 inter-word space when a line is adjusted.
293 \: This causes the insertion of a zero-width break point. It is
295 equal to \% within a word but without insertion of a soft hyphen
296 glyph.
297 \# Everything up to and including the next newline is ignored.
299 This is interpreted in copy mode. It is like \" except that \"
300 does not ignore the terminating newline.
301 New requests
303 .aln xx yy
304 Create an alias xx for number register object named yy. The new
305 name and the old name are exactly equivalent. If yy is unde‐
306 fined, a warning of type reg is generated, and the request is
307 ignored.
308 .als xx yy
310 Create an alias xx for request, string, macro, or diversion
311 object named yy. The new name and the old name are exactly
312 equivalent (it is similar to a hard rather than a soft link).
313 If yy is undefined, a warning of type mac is generated, and the
314 request is ignored. The de, am, di, da, ds, and as requests
315 only create a new object if the name of the macro, diversion or
316 string is currently undefined or if it is defined to be a
317 request; normally they modify the value of an existing object.
318 .am1 xx yy
320 Similar to .am, but compatibility mode is switched off during
321 execution. To be more precise, a `compatibility save' token is
322 inserted at the beginning of the macro addition, and a `compati‐
323 bility restore' token at the end. As a consequence, the
324 requests am, am1, de, and de1 can be intermixed freely since the
325 compatibility save/restore tokens only affect the macro parts
326 defined by .am1 and .ds1.
327 .ami xx yy
329 Append to macro indirectly. See the dei request below for more
330 information.
331 .ami1 xx yy
333 Same as the ami request but compatibility mode is switched off
334 during execution.
335 .as1 xx yy
337 Similar to .as, but compatibility mode is switched off during
338 expansion. To be more precise, a `compatibility save' token is
339 inserted at the beginning of the string, and a `compatibility
340 restore' token at the end. As a consequence, the requests as,
341 as1, ds, and ds1 can be intermixed freely since the compatibil‐
342 ity save/restore tokens only affect the (sub)strings defined by
343 as1 and ds1.
344 .asciify xx
346 This request `unformats' the diversion xx in such a way that
347 ASCII and space characters (and some escape sequences) that were
348 formatted and diverted into xx are treated like ordinary input
349 characters when xx is reread. Useful for diversions in conjunc‐
350 tion with the writem request. It can be also used for gross
351 hacks; for example, this
352 .tr @.
354 .di x
355 @nr n 1
356 .br
357 .di
358 .tr @@
359 .asciify x
360 .x
361 sets register n to 1. Note that glyph information (font, font
363 size, etc.) is not preserved; use .unformat instead.
364 .backtrace
366 Print a backtrace of the input stack on stderr.
367 .blm xx
369 Set the blank line macro to xx. If there is a blank line macro,
370 it is invoked when a blank line is encountered instead of the
371 usual troff behaviour.
372 .box xx
374 .boxa xx
375 These requests are similar to the di and da requests with the
376 exception that a partially filled line does not become part of
377 the diversion (i.e., the diversion always starts with a new
378 line) but is restored after ending the diversion, discarding the
379 partially filled line which possibly comes from the diversion.
380 .break Break out of a while loop. See also the while and continue
382 requests. Be sure not to confuse this with the br request.
383 .brp This is the same as \p.
385 .cflags n c1 c2...
387 Characters c1, c2,... have properties determined by n, which is
388 ORed from the following:
389 1 The character ends sentences (initially characters .?!
391 have this property).
392 2 Lines can be broken before the character (initially no
394 characters have this property); a line is not broken at a
395 character with this property unless the characters on
396 each side both have non-zero hyphenation codes. This can
397 be overridden with value 64.
398 4 Lines can be broken after the character (initially char‐
400 acters -\[hy]\[em] have this property); a line is not
401 broken at a character with this property unless the char‐
402 acters on each side both have non-zero hyphenation codes.
403 This can be overridden with value 64.
405 8 The glyph associated with this character overlaps hori‐
407 zontally (initially characters \[ul]\[rn]\[ru]\[radi‐
408 calex]\[sqrtex] have this property).
409 16 The glyph associated with this character overlaps verti‐
411 cally (initially glyph \[br] has this property).
412 32 An end-of-sentence character followed by any number of
414 characters with this property is treated as the end of a
415 sentence if followed by a newline or two spaces; in other
416 words the character is transparent for the purposes of
417 end-of-sentence recognition; this is the same as having a
418 zero space factor in TeX (initially characters
419 "')]*\[dg]\[rq] have this property).
420 64 Ignore hyphenation code values of the surrounding charac‐
422 ters. Use this in combination with values 2 and 4 (ini‐
423 tially no characters have this property).
424 .char c string
426 [This request can both define characters and glyphs.]
427 Define entity c to be string. To be more precise, define (or
429 even override) a groff entity which can be accessed with name c
430 on the input side, and which uses string on the output side.
431 Every time glyph c needs to be printed, string is processed in a
432 temporary environment and the result is wrapped up into a single
433 object. Compatibility mode is turned off and the escape charac‐
434 ter is set to \ while string is being processed. Any embolden‐
435 ing, constant spacing or track kerning is applied to this object
436 rather than to individual glyphs in string.
437 A groff object defined by this request can be used just like a
439 normal glyph provided by the output device. In particular other
440 characters can be translated to it with the tr request; it can
441 be made the leader glyph by the lc request; repeated patterns
442 can be drawn with the glyph using the \l and \L escape
443 sequences; words containing c can be hyphenated correctly, if
444 the hcode request is used to give the object a hyphenation code.
445 There is a special anti-recursion feature: Use of glyph within
447 the glyph's definition is handled like normal glyphs not defined
448 with char.
449 A glyph definition can be removed with the rchar request.
451 .chop xx
453 Chop the last element off macro, string, or diversion xx. This
454 is useful for removing the newline from the end of diversions
455 that are to be interpolated as strings.
456 .close stream
458 Close the stream named stream; stream will no longer be an
459 acceptable argument to the write request. See the open request.
460 .composite glyph1 glyph2
462 Map glyph name glyph1 to glyph name glyph2 if it is used in
463 \[...] with more than one component.
464 .continue
466 Finish the current iteration of a while loop. See also the
467 while and break requests.
468 .color n
470 If n is non-zero or missing, enable colors (this is the
471 default), otherwise disable them.
472 .cp n If n is non-zero or missing, enable compatibility mode, other‐
474 wise disable it. In compatibility mode, long names are not rec‐
475 ognized, and the incompatibilities caused by long names do not
476 arise.
477 .defcolor xxx scheme color_components
479 Define color xxx. scheme can be one of the following values:
480 rgb (three components), cmy (three components), cmyk (four com‐
481 ponents), and gray or grey (one component). Color components
482 can be given either as a hexadecimal string or as positive deci‐
483 mal integers in the range 0-65535. A hexadecimal string con‐
484 tains all color components concatenated; it must start with
485 either # or ##. The former specifies hex values in the range
486 0-255 (which are internally multiplied by 257), the latter in
487 the range 0-65535. Examples: #FFC0CB (pink), ##ffff0000ffff
488 (magenta). A new scaling indicator f has been introduced which
489 multiplies its value by 65536; this makes it convenient to spec‐
490 ify color components as fractions in the range 0 to 1. Example:
491 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
493 Note that f is the default scaling indicator for the defcolor
495 request, thus the above statement is equivalent to
496 .defcolor darkgreen rgb 0.1 0.5 0.2
498 The color named default (which is device-specific) can't be
500 redefined. It is possible that the default color for \M and \m
501 is not the same.
502 .de1 xx yy
504 Similar to .de, but compatibility mode is switched off during
505 execution. On entry, the current compatibility mode is saved
506 and restored at exit.
507 .dei xx yy
509 Define macro indirectly. The following example
510 .ds xx aa
512 .ds yy bb
513 .dei xx yy
514 is equivalent to
516 .de aa bb
518 .dei1 xx yy
520 Similar to the dei request but compatibility mode is switched
521 off during execution.
522 .device anything
524 This is (almost) the same as the \X escape. anything is read in
525 copy mode; a leading " is stripped.
526 .devicem xx
528 This is the same as the \Y escape (to embed the contents of a
529 macro into the intermediate output preceded with `x X').
530 .do xxx
532 Interpret .xxx with compatibility mode disabled. For example,
533 .do fam T
535 would have the same effect as
537 .fam T
539 except that it would work even if compatibility mode had been
541 enabled. Note that the previous compatibility mode is restored
542 before any files sourced by xxx are interpreted.
543 .ds1 xx yy
545 Similar to .ds, but compatibility mode is switched off during
546 expansion. To be more precise, a `compatibility save' token is
547 inserted at the beginning of the string, and a `compatibility
548 restore' token at the end.
549 .ecs Save current escape character.
551 .ecr Restore escape character saved with ecs. Without a previous
553 call to ecs, `\' will be the new escape character.
554 .evc xx
556 Copy the contents of environment xx to the current environment.
557 No pushing or popping of environments is done.
558 .fam xx
560 Set the current font family to xx. The current font family is
561 part of the current environment. If xx is missing, switch back
562 to previous font family. The value at start-up is `T'. See the
563 description of the sty request for more information on font fam‐
564 ilies.
565 .fchar c string
567 Define fallback character (or glyph) c to be string. The syntax
568 of this request is the same as the char request; the only dif‐
569 ference is that a glyph defined with char hides the glyph with
570 the same name in the current font, whereas a glyph defined with
571 fchar is checked only if the particular glyph isn't found in the
572 current font. This test happens before checking special fonts.
573 .fcolor c
575 Set the fill color to c. If c is missing, switch to the previ‐
576 ous fill color.
577 .fschar f c string
579 Define fallback character (or glyph) c for font f to be string.
580 The syntax of this request is the same as the char request (with
581 an additional argument to specify the font); a glyph defined
582 with fschar is searched after the list of fonts declared with
583 the fspecial request but before the list of fonts declared with
584 .special.
585 .fspecial f s1 s2...
587 When the current font is f, fonts s1, s2,... are special, that
588 is, they are searched for glyphs not in the current font. Any
589 fonts specified in the special request are searched after fonts
590 specified in the fspecial request. Without argument, reset the
591 list of global special fonts to be empty.
592 .ftr f g
594 Translate font f to g. Whenever a font named f is referred to
595 in an \f escape sequence, in the F and S conditional operators,
596 or in the ft, ul, bd, cs, tkf, special, fspecial, fp, or sty
597 requests, font g is used. If g is missing, or equal to f then
598 font f is not translated.
599 .fzoom f zoom
601 Set zoom factor zoom for font f. zoom must a non-negative inte‐
602 ger multiple of 1/1000th. If it is missing or is equal to zero,
603 it means the same as 1000, namely no magnification. f must be a
604 real font name, not a style.
605 .gcolor c
607 Set the glyph color to c. If c is missing, switch to the previ‐
608 ous glyph color.
609 .hcode c1 code1 c2 code2...
611 Set the hyphenation code of character c1 to code1 and that of c2
612 to code2. A hyphenation code must be a single input character
613 (not a special character) other than a digit or a space. Ini‐
614 tially each lower-case letter a-z has a hyphenation code, which
615 is itself, and each upper-case letter A-Z has a hyphenation code
616 which is the lower-case version of itself. See also the hpf
617 request.
618 .hla lang
620 Set the current hyphenation language to lang. Hyphenation
621 exceptions specified with the hw request and hyphenation pat‐
622 terns specified with the hpf request are both associated with
623 the current hyphenation language. The hla request is usually
624 invoked by the troffrc file to set up a default language.
625 .hlm n Set the maximum number of consecutive hyphenated lines to n. If
627 n is negative, there is no maximum. The default value is -1.
628 This value is associated with the current environment. Only
629 lines output from an environment count towards the maximum asso‐
630 ciated with that environment. Hyphens resulting from \% are
631 counted; explicit hyphens are not.
632 .hpf file
634 Read hyphenation patterns from file; this is searched for in the
635 same way that name.tmac is searched for when the -mname option
636 is specified. It should have the same format as (simple) TeX
637 patterns files. More specifically, the following scanning rules
638 are implemented.
639 · A percent sign starts a comment (up to the end of the
641 line) even if preceded by a backslash.
642 · No support for `digraphs' like \$.
644 · ^^xx (x is 0-9 or a-f) and ^^x (character code of x in
646 the range 0-127) are recognized; other use of ^ causes an
647 error.
648 · No macro expansion.
650 · hpf checks for the expression \patterns{...} (possibly
652 with whitespace before and after the braces). Everything
653 between the braces is taken as hyphenation patterns.
654 Consequently, { and } are not allowed in patterns.
655 · Similarly, \hyphenation{...} gives a list of hyphenation
657 exceptions.
658 · \endinput is recognized also.
660 · For backwards compatibility, if \patterns is missing, the
662 whole file is treated as a list of hyphenation patterns
663 (only recognizing the % character as the start of a com‐
664 ment).
665 Use the hpfcode request to map the encoding used in hyphenation
667 patterns files to groff's input encoding.
668 The set of hyphenation patterns is associated with the current
670 language set by the hla request. The hpf request is usually
671 invoked by the troffrc file; a second call replaces the old pat‐
672 terns with the new ones.
673 .hpfa file
675 The same as hpf except that the hyphenation patterns from file
676 are appended to the patterns already loaded in the current lan‐
677 guage.
678 .hpfcode a b c d ...
680 After reading a hyphenation patterns file with the hpf or hpfa
681 request, convert all characters with character code a in the
682 recently read patterns to character code b, character code c
683 to d, etc. Initially, all character codes map to themselves.
684 The arguments of hpfcode must be integers in the range 0 to 255.
685 Note that it is even possible to use character codes which are
686 invalid in groff otherwise.
687 .hym n Set the hyphenation margin to n: when the current adjustment
689 mode is not b, the line is not hyphenated if the line is no more
690 than n short. The default hyphenation margin is 0. The default
691 scaling indicator for this request is m. The hyphenation margin
692 is associated with the current environment. The current hyphen‐
693 ation margin is available in the \n[.hym] register.
694 .hys n Set the hyphenation space to n: When the current adjustment mode
696 is b don't hyphenate the line if the line can be justified by
697 adding no more than n extra space to each word space. The
698 default hyphenation space is 0. The default scaling indicator
699 for this request is m. The hyphenation space is associated with
700 the current environment. The current hyphenation space is
701 available in the \n[.hys] register.
702 .itc n macro
704 Variant of .it for which a line interrupted with \c counts as
705 one input line.
706 .kern n
708 If n is non-zero or missing, enable pairwise kerning, otherwise
709 disable it.
710 .length xx string
712 Compute the length of string and return it in the number regis‐
713 ter xx (which is not necessarily defined before).
714 .linetabs n
716 If n is non-zero or missing, enable line-tabs mode, otherwise
717 disable it (which is the default). In line-tabs mode, tab dis‐
718 tances are computed relative to the (current) output line. Oth‐
719 erwise they are taken relative to the input line. For example,
720 the following
721 .ds x a\t\c
723 .ds y b\t\c
724 .ds z c
725 .ta 1i 3i
726 \*x
727 \*y
728 \*z
729 yields
731 a b c
733 In line-tabs mode, the same code gives
735 a b c
737 Line-tabs mode is associated with the current environment; the
739 read-only number register \n[.linetabs] is set to 1 if in line-
740 tabs mode, and 0 otherwise.
741 .mso file
743 The same as the so request except that file is searched for in
744 the same directories as macro files for the the -m command line
745 option. If the file name to be included has the form name.tmac
746 and it isn't found, mso tries to include tmac.name instead and
747 vice versa.
748 .nop anything
750 Execute anything. This is similar to `.if 1'.
751 .nroff Make the n built-in condition true and the t built-in condition
753 false. This can be reversed using the troff request.
754 .open stream filename
756 Open filename for writing and associate the stream named stream
757 with it. See also the close and write requests.
758 .opena stream filename
760 Like open, but if filename exists, append to it instead of trun‐
761 cating it.
762 .output string
764 Emit string directly to the intermediate output (subject to
765 copy-mode interpretation); this is similar to \! used at the top
766 level. An initial double quote in string is stripped off to
767 allow initial blanks.
768 .pev Print the current environment and each defined environment state
770 on stderr.
771 .pnr Print the names and contents of all currently defined number
773 registers on stderr.
774 .psbb filename
776 Get the bounding box of a PostScript image filename. This file
777 must conform to Adobe's Document Structuring Conventions; the
778 command looks for a %%BoundingBox comment to extract the bound‐
779 ing box values. After a successful call, the coordinates (in
780 PostScript units) of the lower left and upper right corner can
781 be found in the registers \n[llx], \n[lly], \n[urx], and
782 \n[ury], respectively. If some error has occurred, the four
783 registers are set to zero.
784 .pso command
786 This behaves like the so request except that input comes from
787 the standard output of command.
788 .ptr Print the names and positions of all traps (not including input
790 line traps and diversion traps) on stderr. Empty slots in the
791 page trap list are printed as well, because they can affect the
792 priority of subsequently planted traps.
793 .pvs ±n
795 Set the post-vertical line space to n; default scale indicator
796 is p. This value is added to each line after it has been out‐
797 put. With no argument, the post-vertical line space is set to
798 its previous value.
799 The total vertical line spacing consists of four components: .vs
801 and \x with a negative value which are applied before the line
802 is output, and .pvs and \x with a positive value which are
803 applied after the line is output.
804 .rchar c1 c2...
806 Remove the definitions of glyphs c1, c2,... This undoes the
807 effect of a char request.
808 .return
810 Within a macro, return immediately. If called with an argument,
811 return twice, namely from the current macro and from the macro
812 one level higher. No effect otherwise.
813 .rfschar c1 c2...
815 Remove the font-specific definitions of glyphs c1, c2,... This
816 undoes the effect of a fschar request.
817 .rj
819 .rj n Right justify the next n input lines. Without an argument right
820 justify the next input line. The number of lines to be right
821 justified is available in the \n[.rj] register. This implicitly
822 does .ce 0. The ce request implicitly does .rj 0.
823 .rnn xx yy
825 Rename number register xx to yy.
826 .schar c string
828 Define global fallback character (or glyph) c to be string. The
829 syntax of this request is the same as the char request; a glyph
830 defined with schar is searched after the list of fonts declared
831 with the special request but before the mounted special fonts.
832 .shc c Set the soft hyphen character to c. If c is omitted, the soft
834 hyphen character is set to the default \[hy]. The soft hyphen
835 character is the glyph which is inserted when a word is hyphen‐
836 ated at a line break. If the soft hyphen character does not
837 exist in the font of the glyph immediately preceding a potential
838 break point, then the line is not broken at that point. Neither
839 definitions (specified with the char request) nor translations
840 (specified with the tr request) are considered when finding the
841 soft hyphen character.
842 .shift n
844 In a macro, shift the arguments by n positions: argument i
845 becomes argument i-n; arguments 1 to n are no longer available.
846 If n is missing, arguments are shifted by 1. Shifting by nega‐
847 tive amounts is currently undefined.
848 .sizes s1 s2...sn [0]
850 This command is similar to the sizes command of a DESC file. It
851 sets the available font sizes for the current font to s1,
852 s2,..., sn scaled points. The list of sizes can be terminated
853 by an optional 0. Each si can also be a range of sizes m-n.
854 Contrary to the font file command, the list can't extend over
855 more than a single line.
856 .special s1 s2...
858 Fonts s1, s2,... are special and are searched for glyphs not in
859 the current font. Without arguments, reset the list of special
860 fonts to be empty.
861 .spreadwarn limit
863 Make troff emit a warning if the additional space inserted for
864 each space between words in an output line is larger or equal to
865 limit. A negative value is changed to zero; no argument toggles
866 the warning on and off without changing limit. The default
867 scaling indicator is m. At startup, spreadwarn is deactivated,
868 and limit is set to 3m. For example, .spreadwarn 0.2m causes a
869 warning if troff must add 0.2m or more for each interword space
870 in a line. This request is active only if text is justified to
871 both margins (using .ad b).
872 .sty n f
874 Associate style f with font position n. A font position can be
875 associated either with a font or with a style. The current font
876 is the index of a font position and so is also either a font or
877 a style. When it is a style, the font that is actually used is
878 the font the name of which is the concatenation of the name of
879 the current family and the name of the current style. For exam‐
880 ple, if the current font is 1 and font position 1 is associated
881 with style R and the current font family is T, then font TR is
882 used. If the current font is not a style, then the current fam‐
883 ily is ignored. When the requests cs, bd, tkf, uf, or fspecial
884 are applied to a style, then they are applied instead to the
885 member of the current family corresponding to that style. The
886 default family can be set with the -f command line option. The
887 styles command in the DESC file controls which font positions
888 (if any) are initially associated with styles rather than fonts.
889 .substring xx n1 [n2]
891 Replace the string named xx with the substring defined by the
892 indices n1 and n2. The first character in the string has
893 index 0. If n2 is omitted, it is taken to be equal to the
894 string's length. If the index value n1 or n2 is negative, it is
895 counted from the end of the string, going backwards: The last
896 character has index -1, the character before the last character
897 has index -2, etc.
898 .tkf f s1 n1 s2 n2
900 Enable track kerning for font f. When the current font is f the
901 width of every glyph is increased by an amount between n1 and
902 n2; when the current point size is less than or equal to s1 the
903 width is increased by n1; when it is greater than or equal to s2
904 the width is increased by n2; when the point size is greater
905 than or equal to s1 and less than or equal to s2 the increase in
906 width is a linear function of the point size.
907 .tm1 string
909 Similar to the tm request, string is read in copy mode and writ‐
910 ten on the standard error, but an initial double quote in string
911 is stripped off to allow initial blanks.
912 .tmc string
914 Similar to tm1 but without writing a final newline.
915 .trf filename
917 Transparently output the contents of file filename. Each line
918 is output as if preceded by \!; however, the lines are not sub‐
919 ject to copy-mode interpretation. If the file does not end with
920 a newline, then a newline is added. For example, you can define
921 a macro x containing the contents of file f, using
922 .di x
924 .trf f
925 .di
926 Unlike with the cf request, the file cannot contain characters
928 such as NUL that are not valid troff input characters.
929 .trin abcd
931 This is the same as the tr request except that the asciify
932 request uses the character code (if any) before the character
933 translation. Example:
934 .trin ax
936 .di xxx
937 a
938 .br
939 .di
940 .xxx
941 .trin aa
942 .asciify xxx
943 .xxx
944 The result is x a. Using tr, the result would be x x.
946 .trnt abcd
948 This is the same as the tr request except that the translations
949 do not apply to text that is transparently throughput into a
950 diversion with \!. For example,
951 .tr ab
953 .di x
954 \!.tm a
955 .di
956 .x
957 prints b; if trnt is used instead of tr it prints a.
959 .troff Make the n built-in condition false, and the t built-in condi‐
961 tion true. This undoes the effect of the nroff request.
962 .unformat xx
964 This request `unformats' the diversion xx. Contrary to the
965 asciify request, which tries to convert formatted elements of
966 the diversion back to input tokens as much as possible, .unfor‐
967 mat only handles tabs and spaces between words (usually caused
968 by spaces or newlines in the input) specially. The former are
969 treated as if they were input tokens, and the latter are
970 stretchable again. Note that the vertical size of lines is not
971 preserved. Glyph information (font, font size, space width,
972 etc.) is retained. Useful in conjunction with the box and boxa
973 requests.
974 .vpt n Enable vertical position traps if n is non-zero, disable them
976 otherwise. Vertical position traps are traps set by the wh or
977 dt requests. Traps set by the it request are not vertical posi‐
978 tion traps. The parameter that controls whether vertical posi‐
979 tion traps are enabled is global. Initially vertical position
980 traps are enabled.
981 .warn n
983 Control warnings. n is the sum of the numbers associated with
984 each warning that is to be enabled; all other warnings are dis‐
985 abled. The number associated with each warning is listed in
986 troff(1). For example, .warn 0 disables all warnings, and
987 .warn 1 disables all warnings except that about missing glyphs.
988 If n is not given, all warnings are enabled.
989 .warnscale si
991 Set the scaling indicator used in warnings to si. Valid values
992 for si are u, i, c, p, and P. At startup, it is set to i.
993 .while c anything
995 While condition c is true, accept anything as input; c can be
996 any condition acceptable to an if request; anything can comprise
997 multiple lines if the first line starts with \{ and the last
998 line ends with \}. See also the break and continue requests.
999 .write stream anything
1001 Write anything to the stream named stream. stream must previ‐
1002 ously have been the subject of an open request. anything is
1003 read in copy mode; a leading " is stripped.
1004 .writec stream anything
1006 Similar to write but without writing a final newline.
1007 .writem stream xx
1009 Write the contents of the macro or string xx to the stream named
1010 stream. stream must previously have been the subject of an open
1011 request. xx is read in copy mode.
1012 Extended escape sequences
1014 \D'...'
1015 All drawing commands of groff's intermediate output are
1016 accepted. See subsection Drawing Commands below for more infor‐
1017 mation.
1018 Extended requests
1020 .cf filename
1021 When used in a diversion, this embeds in the diversion an object
1022 which, when reread, will cause the contents of filename to be
1023 transparently copied through to the output. In UNIX troff, the
1024 contents of filename is immediately copied through to the output
1025 regardless of whether there is a current diversion; this behav‐
1026 iour is so anomalous that it must be considered a bug.
1027 .de xx yy
1029 .am xx yy
1030 .ds xx yy
1031 .as xx yy
1032 In compatibility mode, these requests behaves similar to .de1,
1033 .am1, .ds1, and .as1, respectively: A `compatibility save' token
1034 is inserted at the beginning, and a `compatibility restore'
1035 token at the end, with compatibility mode switched on during
1036 execution.
1037 .ev xx If xx is not a number, this switches to a named environment
1039 called xx. The environment should be popped with a matching ev
1040 request without any arguments, just as for numbered environ‐
1041 ments. There is no limit on the number of named environments;
1042 they are created the first time that they are referenced.
1043 .ss m n
1045 When two arguments are given to the ss request, the second argu‐
1046 ment gives the sentence space size. If the second argument is
1047 not given, the sentence space size is the same as the word space
1048 size. Like the word space size, the sentence space is in units
1049 of one twelfth of the spacewidth parameter for the current font.
1050 Initially both the word space size and the sentence space size
1051 are 12. Contrary to UNIX troff, GNU troff handles this request
1052 in nroff mode also; a given value is then rounded down to the
1053 nearest multiple of 12. The sentence space size is used in two
1054 circumstances. If the end of a sentence occurs at the end of a
1055 line in fill mode, then both an inter-word space and a sentence
1056 space are added; if two spaces follow the end of a sentence in
1057 the middle of a line, then the second space is a sentence space.
1058 Note that the behaviour of UNIX troff are exactly that exhibited
1059 by GNU troff if a second argument is never given to the ss
1060 request. In GNU troff, as in UNIX troff, you should always fol‐
1061 low a sentence with either a newline or two spaces.
1062 .ta n1 n2...nn T r1 r2...rn
1064 Set tabs at positions n1, n2,..., nn and then set tabs at nn+r1,
1065 nn+r2,..., nn+rn and then at nn+rn+r1, nn+rn+r2,..., nn+rn+rn,
1066 and so on. For example,
1067 .ta T .5i
1069 sets tabs every half an inch.
1071 New number registers
1073 The following read-only registers are available:
1074 \n[.br]
1076 Within a macro call, it is set to 1 if the macro is called with
1077 the `normal' control character (`.' by default), and set to 0
1078 otherwise. This allows to reliably modify requests.
1079 .als bp*orig bp
1081 .de bp
1082 .tm before bp
1083 .ie \\n[.br] .bp*orig
1084 .el 'bp*orig
1085 .tm after bp
1086 ..
1087 Using this register outside of a macro makes no sense (it always
1089 returns zero in such cases).
1090 \n[.C] 1 if compatibility mode is in effect, 0 otherwise.
1092 \n[.cdp]
1094 The depth of the last glyph added to the current environment.
1095 It is positive if the glyph extends below the baseline.
1096 \n[.ce]
1098 The number of lines remaining to be centered, as set by the ce
1099 request.
1100 \n[.cht]
1102 The height of the last glyph added to the current environment.
1103 It is positive if the glyph extends above the baseline.
1104 \n[.color]
1106 1 if colors are enabled, 0 otherwise.
1107 \n[.csk]
1109 The skew of the last glyph added to the current environment.
1110 The skew of a glyph is how far to the right of the center of a
1111 glyph the center of an accent over that glyph should be placed.
1112 \n[.ev]
1114 The name or number of the current environment. This is a
1115 string-valued register.
1116 \n[.fam]
1118 The current font family. This is a string-valued register.
1119 \n[.fn]
1121 The current (internal) real font name. This is a string-valued
1122 register. If the current font is a style, the value of \n[.fn]
1123 is the proper concatenation of family and style name.
1124 \n[.fp]
1126 The number of the next free font position.
1127 \n[.g] Always 1. Macros should use this to determine whether they are
1129 running under GNU troff.
1130 \n[.height]
1132 The current height of the font as set with \H.
1133 \n[.hla]
1135 The current hyphenation language as set by the hla request.
1136 \n[.hlc]
1138 The number of immediately preceding consecutive hyphenated
1139 lines.
1140 \n[.hlm]
1142 The maximum allowed number of consecutive hyphenated lines, as
1143 set by the hlm request.
1144 \n[.hy]
1146 The current hyphenation flags (as set by the hy request).
1147 \n[.hym]
1149 The current hyphenation margin (as set by the hym request).
1150 \n[.hys]
1152 The current hyphenation space (as set by the hys request).
1153 \n[.in]
1155 The indentation that applies to the current output line.
1156 \n[.int]
1158 Set to a positive value if last output line is interrupted
1159 (i.e., if it contains \c).
1160 \n[.kern]
1162 1 if pairwise kerning is enabled, 0 otherwise.
1163 \n[.lg]
1165 The current ligature mode (as set by the lg request).
1166 \n[.linetabs]
1168 The current line-tabs mode (as set by the linetabs request).
1169 \n[.ll]
1171 The line length that applies to the current output line.
1172 \n[.lt]
1174 The title length as set by the lt request.
1175 \n[.m] The name of the current drawing color. This is a string-valued
1177 register.
1178 \n[.M] The name of the current background color. This is a string-val‐
1180 ued register.
1181 \n[.ne]
1183 The amount of space that was needed in the last ne request that
1184 caused a trap to be sprung. Useful in conjunction with the
1185 \n[.trunc] register.
1186 \n[.ns]
1188 1 if no-space mode is active, 0 otherwise.
1189 \n[.pe]
1191 1 during a page ejection caused by the bp request, 0 otherwise.
1192 \n[.pn]
1194 The number of the next page, either the value set by a pn
1195 request, or the number of the current page plus 1.
1196 \n[.ps]
1198 The current point size in scaled points.
1199 \n[.psr]
1201 The last-requested point size in scaled points.
1202 \n[.pvs]
1204 The current post-vertical line space as set with the pvs
1205 request.
1206 \n[.rj]
1208 The number of lines to be right-justified as set by the rj
1209 request.
1210 \n[.slant]
1212 The slant of the current font as set with \S.
1213 \n[.sr]
1215 The last requested point size in points as a decimal fraction.
1216 This is a string-valued register.
1217 \n[.ss]
1219 \n[.sss]
1220 These give the values of the parameters set by the first and
1221 second arguments of the ss request.
1222 \n[.sty]
1224 The current font style. This is a string-valued register.
1225 \n[.tabs]
1227 A string representation of the current tab settings suitable for
1228 use as an argument to the ta request.
1229 \n[.trunc]
1231 The amount of vertical space truncated by the most recently
1232 sprung vertical position trap, or, if the trap was sprung by a
1233 ne request, minus the amount of vertical motion produced by the
1234 ne request. In other words, at the point a trap is sprung,
1235 it represents the difference of what the vertical position
1236 would have been but for the trap, and what the vertical position
1237 actually is. Useful in conjunction with the \n[.ne] register.
1238 \n[.U] Set to 1 if in safer mode and to 0 if in unsafe mode (as given
1240 with the -U command line option).
1241 \n[.vpt]
1243 1 if vertical position traps are enabled, 0 otherwise.
1244 \n[.warn]
1246 The sum of the numbers associated with each of the currently
1247 enabled warnings. The number associated with each warning is
1248 listed in troff(1).
1249 \n[.x] The major version number. For example, if the version number is
1251 1.03, then \n[.x] contains 1.
1252 \n[.y] The minor version number. For example, if the version number is
1254 1.03, then \n[.y] contains 03.
1255 \n[.Y] The revision number of groff.
1257 \n[.zoom]
1259 The zoom value of the current font, in multiples of 1/1000th.
1260 Zero if no magnification.
1261 \n[llx]
1263 \n[lly]
1264 \n[urx]
1265 \n[ury]
1266 These four registers are set by the psbb request and contain the
1267 bounding box values (in PostScript units) of a given PostScript
1268 image.
1269 The following read/write registers are set by the \w escape sequence:
1271 \n[rst]
1273 \n[rsb]
1274 Like the st and sb registers, but take account of the heights
1275 and depths of glyphs.
1276 \n[ssc]
1278 The amount of horizontal space (possibly negative) that should
1279 be added to the last glyph before a subscript.
1280 \n[skw]
1282 How far to right of the center of the last glyph in the \w argu‐
1283 ment, the center of an accent from a roman font should be placed
1284 over that glyph.
1285 Other available read/write number registers are:
1287 \n[c.] The current input line number. \n[.c] is a read-only alias to
1289 this register.
1290 \n[hours]
1292 The number of hours past midnight. Initialized at start-up.
1293 \n[hp] The current horizontal position at input line.
1295 \n[minutes]
1297 The number of minutes after the hour. Initialized at start-up.
1298 \n[seconds]
1300 The number of seconds after the minute. Initialized at start-
1301 up.
1302 \n[systat]
1304 The return value of the system() function executed by the last
1305 sy request.
1306 \n[slimit]
1308 If greater than 0, the maximum number of objects on the input
1309 stack. If less than or equal to 0, there is no limit on the
1310 number of objects on the input stack. With no limit, recursion
1311 can continue until virtual memory is exhausted.
1312 \n[year]
1314 The current year. Note that the traditional troff number regis‐
1315 ter \n[yr] is the current year minus 1900.
1316 Miscellaneous
1318 troff predefines a single (read/write) string-based register, \*[.T],
1319 which contains the argument given to the -T command line option, namely
1320 the current output device (for example, latin1 or ascii). Note that
1321 this is not the same as the (read-only) number register \n[.T] which is
1322 defined to be 1 if troff is called with the -T command line option, and
1323 zero otherwise. This behaviour is different to UNIX troff.
1324 Fonts not listed in the DESC file are automatically mounted on the next
1326 available font position when they are referenced. If a font is to be
1327 mounted explicitly with the fp request on an unused font position, it
1328 should be mounted on the first unused font position, which can be found
1329 in the \n[.fp] register; although troff does not enforce this strictly,
1330 it does not allow a font to be mounted at a position whose number is
1331 much greater than that of any currently used position.
1332 Interpolating a string does not hide existing macro arguments. Thus in
1334 a macro, a more efficient way of doing
1335 .xx \\$@
1337 is
1339 \\*[xx]\\
1341 If the font description file contains pairwise kerning information,
1343 glyphs from that font are kerned. Kerning between two glyphs can be
1344 inhibited by placing a \& between them.
1345 In a string comparison in a condition, characters that appear at dif‐
1347 ferent input levels to the first delimiter character are not recognized
1348 as the second or third delimiters. This applies also to the tl
1349 request. In a \w escape sequence, a character that appears at a dif‐
1350 ferent input level to the starting delimiter character is not recog‐
1351 nized as the closing delimiter character. The same is true for \A, \b,
1352 \B, \C, \l, \L, \o, \X, and \Z. When decoding a macro or string argu‐
1353 ment that is delimited by double quotes, a character that appears at a
1354 different input level to the starting delimiter character is not recog‐
1355 nized as the closing delimiter character. The implementation of \$@
1356 ensures that the double quotes surrounding an argument appear at the
1357 same input level, which is different to the input level of the argument
1358 itself. In a long escape name ] is not recognized as a closing delim‐
1359 iter except when it occurs at the same input level as the opening ].
1360 In compatibility mode, no attention is paid to the input-level.
1361 There are some new types of condition:
1363 .if rxxx
1365 True if there is a number register named xxx.
1366 .if dxxx
1368 True if there is a string, macro, diversion, or request named
1369 xxx.
1370 .if mxxx
1372 True if there is a color named xxx.
1373 .if cch
1375 True if there is a character (or glyph) ch available; ch is
1376 either an ASCII character or a glyph (special character)
1377 \N'xxx', \(xx or \[xxx]; the condition is also true if ch has
1378 been defined by the char request.
1379 .if Ff True if font f exists. f is handled as if it was opened with
1381 the ft request (this is, font translation and styles are
1382 applied), without actually mounting it.
1383 .if Ss True if style s has been registered. Font translation is
1385 applied.
1386 The tr request can now map characters onto \~.
1388 The space width emitted by the \| and \^ escape sequences can be con‐
1390 trolled on a per-font basis. If there is a glyph named \| or \^,
1391 respectively (note the leading backslash), defined in the current font
1392 file, use this glyph's width instead of the default value.
1393 It is now possible to have whitespace between the first and second dot
1395 (or the name of the ending macro) to end a macro definition. Example:
1396 .if t \{\
1398 . de bar
1399 . nop Hello, I'm `bar'.
1400 . .
1401 .\}
1402
1404 This section describes the format output by GNU troff. The output for‐
1405 mat used by GNU troff is very similar to that used by Unix device-inde‐
1406 pendent troff. Only the differences are documented here.
1407 Units
1409 The argument to the s command is in scaled points (units of points/n,
1410 where n is the argument to the sizescale command in the DESC file).
1411 The argument to the x Height command is also in scaled points.
1412 Text Commands
1414 Nn Print glyph with index n (a non-negative integer) of the current
1415 font.
1416 If the tcommand line is present in the DESC file, troff uses the fol‐
1418 lowing two commands.
1419 txxx xxx is any sequence of characters terminated by a space or a
1421 newline (to be more precise, it is a sequence of glyphs which
1422 are accessed with the corresponding characters); the first char‐
1423 acter should be printed at the current position, the current
1424 horizontal position should be increased by the width of the
1425 first character, and so on for each character. The width of the
1426 glyph is that given in the font file, appropriately scaled for
1427 the current point size, and rounded so that it is a multiple of
1428 the horizontal resolution. Special characters cannot be printed
1429 using this command.
1430 un xxx This is same as the t command except that after printing each
1432 character, the current horizontal position is increased by the
1433 sum of the width of that character and n.
1434 Note that single characters can have the eighth bit set, as can the
1436 names of fonts and special characters.
1437 The names of glyphs and fonts can be of arbitrary length; drivers
1439 should not assume that they are only two characters long.
1440 When a glyph is to be printed, that glyph is always in the current
1442 font. Unlike device-independent troff, it is not necessary for drivers
1443 to search special fonts to find a glyph.
1444 For color support, some new commands have been added:
1446 mc cyan magenta yellow
1448 md
1449 mg gray
1450 mk cyan magenta yellow black
1451 mr red green blue
1452 Set the color components of the current drawing color, using
1453 various color schemes. md resets the drawing color to the
1454 default value. The arguments are integers in the range 0 to
1455 65536.
1456 The x device control command has been extended.
1458 x u n If n is 1, start underlining of spaces. If n is 0, stop under‐
1460 lining of spaces. This is needed for the cu request in nroff
1461 mode and is ignored otherwise.
1462 Drawing Commands
1464 The D drawing command has been extended. These extensions are not used
1465 by GNU pic if the -n option is given.
1466 Df n\n Set the shade of gray to be used for filling solid objects to n;
1468 n must be an integer between 0 and 1000, where 0 corresponds
1469 solid white and 1000 to solid black, and values in between cor‐
1470 respond to intermediate shades of gray. This applies only to
1471 solid circles, solid ellipses and solid polygons. By default, a
1472 level of 1000 is used. Whatever color a solid object has, it
1473 should completely obscure everything beneath it. A value
1474 greater than 1000 or less than 0 can also be used: this means
1475 fill with the shade of gray that is currently being used for
1476 lines and text. Normally this is black, but some drivers may
1477 provide a way of changing this.
1478 The corresponding \D'f...' command shouldn't be used since its
1480 argument is always rounded to an integer multiple of the hori‐
1481 zontal resolution which can lead to surprising results.
1482 DC d\n Draw a solid circle with a diameter of d with the leftmost point
1484 at the current position.
1485 DE dx dy\n
1487 Draw a solid ellipse with a horizontal diameter of dx and a ver‐
1488 tical diameter of dy with the leftmost point at the current
1489 position.
1490 Dp dx1 dy1 dx2 dy2 ... dxn dyn\n
1492 Draw a polygon with, for i=1,...,n+1, the i-th vertex at the
1493 current position +ij−=Σ11(dxj,dyj). At the moment, GNU pic only
1494 uses this command to generate triangles and rectangles.
1495 DP dx1 dy1 dx2 dy2 ... dxn dyn\n
1497 Like Dp but draw a solid rather than outlined polygon.
1498 Dt n\n Set the current line thickness to n machine units. Tradition‐
1500 ally Unix troff drivers use a line thickness proportional to the
1501 current point size; drivers should continue to do this if no Dt
1502 command has been given, or if a Dt command has been given with a
1503 negative value of n. A zero value of n selects the smallest
1504 available line thickness.
1505 A difficulty arises in how the current position should be changed after
1507 the execution of these commands. This is not of great importance since
1508 the code generated by GNU pic does not depend on this. Given a drawing
1509 command of the form
1510 \D'c x1 y1 x2 y2 ... xn yn'
1512 where c is not one of c, e, l, a, or ~, Unix troff treats each of the
1514 xi as a horizontal quantity, and each of the yi as a vertical quantity
1515 and assumes that the width of the drawn object is in=Σ1xi, and that the
1516 height is in=Σ1yi. (The assumption about the height can be seen by exam‐
1517 ining the st and sb registers after using such a D command in a \w
1518 escape sequence). This rule also holds for all the original drawing
1519 commands with the exception of De. For the sake of compatibility GNU
1520 troff also follows this rule, even though it produces an ugly result in
1521 the case of the Dt and Df, and, to a lesser extent, DE commands. Thus
1522 after executing a D command of the form
1523 Dc x1 y1 x2 y2 ... xn yn\n
1525 the current position should be increased by (in=Σ1xi,in=Σ1yi).
1527 Another set of extensions is
1529 DFc cyan magenta yellow\n
1531 DFd\n
1532 DFg gray\n
1533 DFk cyan magenta yellow black\n
1534 DFr red green blue\n
1535 Set the color components of the filling color similar to the
1536 m commands above.
1537 The current position isn't changed by those colour commands (contrary
1539 to Df).
1540 Device Control Commands
1542 There is a continuation convention which permits the argument to the
1543 x X command to contain newlines: when outputting the argument to the
1544 x X command, GNU troff follows each newline in the argument with a +
1545 character (as usual, it terminates the entire argument with a newline);
1546 thus if the line after the line containing the x X command starts with
1547 +, then the newline ending the line containing the x X command should
1548 be treated as part of the argument to the x X command, the + should be
1549 ignored, and the part of the line following the + should be treated
1550 like the part of the line following the x X command.
1551 The first three output commands are guaranteed to be:
1553 x T device
1555 x res n h v
1556 x init
1557
1559 In spite of the many extensions, groff has retained compatibility to
1560 classical troff to a large degree. For the cases where the extensions
1561 lead to collisions, a special compatibility mode with the restricted,
1562 old functionality was created for groff.
1563 Groff Language
1565 groff provides a compatibility mode that allows to process roff code
1566 written for classical troff or for other implementations of roff in a
1567 consistent way.
1568 Compatibility mode can be turned on with the -C command line option,
1570 and turned on or off with the .cp request. The number register \n(.C
1571 is 1 if compatibility mode is on, 0 otherwise.
1572 This became necessary because the GNU concept for long names causes
1574 some incompatibilities. Classical troff interprets
1575 .dsabcd
1577 as defining a string ab with contents cd. In groff mode, this is con‐
1579 sidered as a call of a macro named dsabcd.
1580 Also classical troff interprets \*[ or \n[ as references to a string or
1582 number register called [ while groff takes this as the start of a long
1583 name.
1584 In compatibility mode, groff interprets these things in the traditional
1586 way; so long names are not recognized.
1587 On the other hand, groff in GNU native mode does not allow to use the
1589 single-character escapes \\ (backslash), \| (vertical bar), \^ (caret),
1590 \& (ampersand), \{ (opening brace), \} (closing brace), `\ ' (space),
1591 \' (single quote), \` (backquote), \- (minus), \_ (underline), \!
1592 (bang), \% (percent), and \c (character c) in names of strings, macros,
1593 diversions, number registers, fonts or environments, whereas classical
1594 troff does.
1595 The \A escape sequence can be helpful in avoiding these escape
1597 sequences in names.
1598 Fractional point sizes cause one noteworthy incompatibility. In clas‐
1600 sical troff, the ps request ignores scale indicators and so
1601 .ps 10u
1603 sets the point size to 10 points, whereas in groff native mode the
1605 point size is set to 10 scaled points.
1606 In groff, there is a fundamental difference between unformatted input
1608 characters, and formatted output characters (glyphs). Everything that
1609 affects how a glyph is output is stored with the glyph; once a glyph
1610 has been constructed it is unaffected by any subsequent requests that
1611 are executed, including the bd, cs, tkf, tr, or fp requests.
1612 Normally glyphs are constructed from input characters at the moment
1614 immediately before the glyph is added to the current output line.
1615 Macros, diversions and strings are all, in fact, the same type of
1616 object; they contain lists of input characters and glyphs in any combi‐
1617 nation.
1618 Special characters can be both; before being added to the output, they
1620 act as input entities, afterwards they denote glyphs.
1621 A glyph does not behave like an input character for the purposes of
1623 macro processing; it does not inherit any of the special properties
1624 that the input character from which it was constructed might have had.
1625 The following example makes things clearer.
1626 .di x
1628 \\\\
1629 .br
1630 .di
1631 .x
1632 With GNU troff this is printed as \\. So each pair of input back‐
1634 slashes `\\' is turned into a single output backslash glyph `\' and the
1635 resulting output backslashes are not interpreted as escape characters
1636 when they are reread.
1637 Classical troff would interpret them as escape characters when they
1639 were reread and would end up printing a single backslash `\'.
1640 In GNU, the correct way to get a printable version of the backslash
1642 character `\' is the \(rs escape sequence, but classical troff does not
1643 provide a clean feature for getting a non-syntactical backslash. A
1644 close method is the printable version of the current escape character
1645 using the \e escape sequence; this works if the current escape charac‐
1646 ter is not redefined. It works in both GNU mode and compatibility
1647 mode, while dirty tricks like specifying a sequence of multiple back‐
1648 slashes do not work reliably; for the different handling in diversions,
1649 macro definitions, or text mode quickly leads to a confusion about the
1650 necessary number of backslashes.
1651 To store an escape sequence in a diversion that is interpreted when the
1653 diversion is reread, either the traditional \! transparent output
1654 facility or the new \? escape sequence can be used.
1655 Intermediate Output
1657 The groff intermediate output format is in a state of evolution. So
1658 far it has some incompatibilities, but it is intended to establish a
1659 full compatibility to the classical troff output format. Actually the
1660 following incompatibilities exist:
1661 · The positioning after the drawing of the polygons conflicts with the
1663 classical definition.
1664 · The intermediate output cannot be rescaled to other devices as clas‐
1666 sical `device-independent' troff did.
1667
1669 Copyright (C) 1989, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free
1670 Software Foundation, Inc.
1671 This document is distributed under the terms of the FDL (GNU Free Docu‐
1673 mentation License) version 1.3 or later. You should have received a
1674 copy of the FDL on your system, it is also available on-line at the GNU
1675 copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩. This document
1676 was written by James Clark, with modifications by Werner Lemberg
1677 ⟨wl@gnu.org⟩ and Bernd Warken ⟨bwarken@mayn.de⟩.
1678 This document is part of groff, the GNU roff distribution. Formerly,
1680 the contents of this document was kept in the manual page troff(1).
1681 Only the parts dealing with the language aspects of the different roff
1682 systems were carried over into this document. The troff command line
1683 options and warnings are still documented in troff(1).
1684
1686 The groff info file, cf. info(1) presents all groff documentation
1687 within a single document.
1688 groff(1)
1690 A list of all documentation around groff.
1691 groff(7)
1693 A description of the groff language, including a short, but com‐
1694 plete reference of all predefined requests, registers, and
1695 escapes of plain groff. From the command line, this is called
1696 using
1697 man 7 groff
1699 roff(7)
1701 A survey of roff systems, including pointers to further histori‐
1702 cal documentation.
1703 [CSTR #54]
1705 The Nroff/Troff User's Manual by J. F. Ossanna of 1976 in the
1706 revision of Brian Kernighan of 1992, being the classical troff
1707 documentation ⟨http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.
1708Groff Version 1.20.1 9 January 2009 GROFF_DIFF(7)