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 includes the roff lan‐
13 guage 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 font family (note that \FP won't
128 work; 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
388 is 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.
404 8 The glyph associated with this character overlaps hori‐
406 zontally (initially characters \[ul]\[rn]\[ru]\[radi‐
407 calex]\[sqrtex] have this property).
408 16 The glyph associated with this character overlaps verti‐
410 cally (initially glyph \[br] has this property).
411 32 An end-of-sentence character followed by any number of
413 characters with this property is treated as the end of a
414 sentence if followed by a newline or two spaces; in other
415 words the character is transparent for the purposes of
416 end-of-sentence recognition; this is the same as having a
417 zero space factor in TeX (initially characters
418 "')]*\[dg]\[rq] have this property).
419 64 Ignore hyphenation code values of the surrounding charac‐
421 ters. Use this in combination with values 2 and 4 (ini‐
422 tially no characters have this property).
423 128 Prohibit a line break before the character, but allow a
425 line break after the character. This works only in com‐
426 bination with flags 256 and 512 and has no effect other‐
427 wise.
428 256 Prohibit a line break after the character, but allow a
430 line break before the character. This works only in com‐
431 bination with flags 128 and 512 and has no effect other‐
432 wise.
433 512 Allow line break before or after the character. This
435 works only in combination with flags 128 and 256 and has
436 no effect otherwise.
437 Contrary to flag values 2 and 4, the flags 128, 256, and 512
439 work pairwise. If, for example, the left character has value
440 512, and the right character 128, no line break gets inserted.
441 If we use value 6 instead for the left character, a line break
442 after the character can't be suppressed since the right neigh‐
443 bour character doesn't get examined.
444 .char c string
446 [This request can both define characters and glyphs.]
447 Define entity c to be string. To be more precise, define (or
449 even override) a groff entity which can be accessed with name c
450 on the input side, and which uses string on the output side.
451 Every time glyph c needs to be printed, string is processed in a
452 temporary environment and the result is wrapped up into a single
453 object. Compatibility mode is turned off and the escape charac‐
454 ter is set to \ while string is being processed. Any embolden‐
455 ing, constant spacing or track kerning is applied to this object
456 rather than to individual glyphs in string.
457 A groff object defined by this request can be used just like a
459 normal glyph provided by the output device. In particular other
460 characters can be translated to it with the tr request; it can
461 be made the leader glyph by the lc request; repeated patterns
462 can be drawn with the glyph using the \l and \L escape
463 sequences; words containing c can be hyphenated correctly, if
464 the hcode request is used to give the object a hyphenation code.
465 There is a special anti-recursion feature: Use of glyph within
467 the glyph's definition is handled like normal glyphs not defined
468 with char.
469 A glyph definition can be removed with the rchar request.
471 .chop xx
473 Chop the last element off macro, string, or diversion xx. This
474 is useful for removing the newline from the end of diversions
475 that are to be interpolated as strings.
476 .class name c1 c2 ...
478 Assign name to a set of characters c1, c2, ..., so that they can
479 be referred to from other requests easily (currently .cflags
480 only). Character ranges (indicated by an intermediate `-') and
481 nested classes are possible also. This is useful to assign
482 properties to a large set of characters.
483 .close stream
485 Close the stream named stream; stream will no longer be an
486 acceptable argument to the write request. See the open request.
487 .composite glyph1 glyph2
489 Map glyph name glyph1 to glyph name glyph2 if it is used in
490 \[...] with more than one component.
491 .continue
493 Finish the current iteration of a while loop. See also the
494 while and break requests.
495 .color n
497 If n is non-zero or missing, enable colors (this is the
498 default), otherwise disable them.
499 .cp n If n is non-zero or missing, enable compatibility mode, other‐
501 wise disable it. In compatibility mode, long names are not rec‐
502 ognized, and the incompatibilities caused by long names do not
503 arise.
504 .defcolor xxx scheme color_components
506 Define color xxx. scheme can be one of the following values:
507 rgb (three components), cmy (three components), cmyk (four com‐
508 ponents), and gray or grey (one component). Color components
509 can be given either as a hexadecimal string or as positive deci‐
510 mal integers in the range 0–65535. A hexadecimal string con‐
511 tains all color components concatenated; it must start with
512 either # or ##. The former specifies hex values in the range
513 0–255 (which are internally multiplied by 257), the latter in
514 the range 0–65535. Examples: #FFC0CB (pink), ##ffff0000ffff
515 (magenta). A new scaling indicator f has been introduced which
516 multiplies its value by 65536; this makes it convenient to spec‐
517 ify color components as fractions in the range 0 to 1. Example:
518 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
520 Note that f is the default scaling indicator for the defcolor
522 request, thus the above statement is equivalent to
523 .defcolor darkgreen rgb 0.1 0.5 0.2
525 The color named default (which is device-specific) can't be
527 redefined. It is possible that the default color for \M and \m
528 is not the same.
529 .de1 xx yy
531 Similar to .de, but compatibility mode is switched off during
532 execution. On entry, the current compatibility mode is saved
533 and restored at exit.
534 .dei xx yy
536 Define macro indirectly. The following example
537 .ds xx aa
539 .ds yy bb
540 .dei xx yy
541 is equivalent to
543 .de aa bb
545 .dei1 xx yy
547 Similar to the dei request but compatibility mode is switched
548 off during execution.
549 .device anything
551 This is (almost) the same as the \X escape. anything is read in
552 copy mode; a leading " is stripped.
553 .devicem xx
555 This is the same as the \Y escape (to embed the contents of a
556 macro into the intermediate output preceded with `x X').
557 .do xxx
559 Interpret .xxx with compatibility mode disabled. For example,
560 .do fam T
562 would have the same effect as
564 .fam T
566 except that it would work even if compatibility mode had been
568 enabled. Note that the previous compatibility mode is restored
569 before any files sourced by xxx are interpreted.
570 .ds1 xx yy
572 Similar to .ds, but compatibility mode is switched off during
573 expansion. To be more precise, a `compatibility save' token is
574 inserted at the beginning of the string, and a `compatibility
575 restore' token at the end.
576 .ecs Save current escape character.
578 .ecr Restore escape character saved with ecs. Without a previous
580 call to ecs, `\' will be the new escape character.
581 .evc xx
583 Copy the contents of environment xx to the current environment.
584 No pushing or popping of environments is done.
585 .fam xx
587 Set the current font family to xx. The current font family is
588 part of the current environment. If xx is missing, switch back
589 to previous font family. The value at start-up is `T'. See the
590 description of the sty request for more information on font fam‐
591 ilies.
592 .fchar c string
594 Define fallback character (or glyph) c to be string. The syntax
595 of this request is the same as the char request; the only dif‐
596 ference is that a glyph defined with char hides the glyph with
597 the same name in the current font, whereas a glyph defined with
598 fchar is checked only if the particular glyph isn't found in the
599 current font. This test happens before checking special fonts.
600 .fcolor c
602 Set the fill color to c. If c is missing, switch to the previ‐
603 ous fill color.
604 .fschar f c string
606 Define fallback character (or glyph) c for font f to be string.
607 The syntax of this request is the same as the char request (with
608 an additional argument to specify the font); a glyph defined
609 with fschar is searched after the list of fonts declared with
610 the fspecial request but before the list of fonts declared with
611 .special.
612 .fspecial f s1 s2 ...
614 When the current font is f, fonts s1, s2, ..., are special, that
615 is, they are searched for glyphs not in the current font. Any
616 fonts specified in the special request are searched after fonts
617 specified in the fspecial request. Without argument, reset the
618 list of global special fonts to be empty.
619 .ftr f g
621 Translate font f to g. Whenever a font named f is referred to
622 in an \f escape sequence, in the F and S conditional operators,
623 or in the ft, ul, bd, cs, tkf, special, fspecial, fp, or sty
624 requests, font g is used. If g is missing, or equal to f then
625 font f is not translated.
626 .fzoom f zoom
628 Set zoom factor zoom for font f. zoom must a non-negative inte‐
629 ger multiple of 1/1000th. If it is missing or is equal to zero,
630 it means the same as 1000, namely no magnification. f must be a
631 real font name, not a style.
632 .gcolor c
634 Set the glyph color to c. If c is missing, switch to the previ‐
635 ous glyph color.
636 .hcode c1 code1 c2 code2 ...
638 Set the hyphenation code of character c1 to code1 and that of c2
639 to code2, and so on. A hyphenation code must be a single input
640 character (not a special character) other than a digit or a
641 space. Initially each lower-case letter a-z has a hyphenation
642 code, which is itself, and each upper-case letter A-Z has a
643 hyphenation code which is the lower-case version of itself. See
644 also the hpf request.
645 .hla lang
647 Set the current hyphenation language to lang. Hyphenation
648 exceptions specified with the hw request and hyphenation pat‐
649 terns specified with the hpf request are both associated with
650 the current hyphenation language. The hla request is usually
651 invoked by the troffrc file to set up a default language.
652 .hlm n Set the maximum number of consecutive hyphenated lines to n. If
654 n is negative, there is no maximum. The default value is -1.
655 This value is associated with the current environment. Only
656 lines output from an environment count towards the maximum asso‐
657 ciated with that environment. Hyphens resulting from \% are
658 counted; explicit hyphens are not.
659 .hpf file
661 Read hyphenation patterns from file; this is searched for in the
662 same way that name.tmac is searched for when the -mname option
663 is specified. It should have the same format as (simple) TeX
664 patterns files. More specifically, the following scanning rules
665 are implemented.
666 · A percent sign starts a comment (up to the end of the
668 line) even if preceded by a backslash.
669 · No support for `digraphs' like \$.
671 · ^^xx (x is 0–9 or a–f) and ^^x (character code of x in
673 the range 0–127) are recognized; other use of ^ causes an
674 error.
675 · No macro expansion.
677 · hpf checks for the expression \patterns{...} (possibly
679 with whitespace before and after the braces). Everything
680 between the braces is taken as hyphenation patterns.
681 Consequently, { and } are not allowed in patterns.
682 · Similarly, \hyphenation{...} gives a list of hyphenation
684 exceptions.
685 · \endinput is recognized also.
687 · For backwards compatibility, if \patterns is missing, the
689 whole file is treated as a list of hyphenation patterns
690 (only recognizing the % character as the start of a com‐
691 ment).
692 Use the hpfcode request to map the encoding used in hyphenation
694 patterns files to groff's input encoding. By default, every‐
695 thing maps to itself except letters `A' to `Z' which map to `a'
696 to `z'.
697 The set of hyphenation patterns is associated with the current
699 language set by the hla request. The hpf request is usually
700 invoked by the troffrc file; a second call replaces the old pat‐
701 terns with the new ones.
702 .hpfa file
704 The same as hpf except that the hyphenation patterns from file
705 are appended to the patterns already loaded in the current lan‐
706 guage.
707 .hpfcode a b c d ...
709 After reading a hyphenation patterns file with the hpf or hpfa
710 request, convert all characters with character code a in the
711 recently read patterns to character code b, character code c
712 to d, etc. Initially, all character codes map to themselves.
713 The arguments of hpfcode must be integers in the range 0 to 255.
714 Note that it is even possible to use character codes which are
715 invalid in groff otherwise.
716 .hym n Set the hyphenation margin to n: when the current adjustment
718 mode is not b, the line is not hyphenated if the line is no more
719 than n short. The default hyphenation margin is 0. The default
720 scaling indicator for this request is m. The hyphenation margin
721 is associated with the current environment. The current hyphen‐
722 ation margin is available in the \n[.hym] register.
723 .hys n Set the hyphenation space to n: When the current adjustment mode
725 is b don't hyphenate the line if the line can be justified by
726 adding no more than n extra space to each word space. The
727 default hyphenation space is 0. The default scaling indicator
728 for this request is m. The hyphenation space is associated with
729 the current environment. The current hyphenation space is
730 available in the \n[.hys] register.
731 .itc n macro
733 Variant of .it for which a line interrupted with \c counts as
734 one input line.
735 .kern n
737 If n is non-zero or missing, enable pairwise kerning, otherwise
738 disable it.
739 .length xx string
741 Compute the length of string and return it in the number regis‐
742 ter xx (which is not necessarily defined before).
743 .linetabs n
745 If n is non-zero or missing, enable line-tabs mode, otherwise
746 disable it (which is the default). In line-tabs mode, tab dis‐
747 tances are computed relative to the (current) output line. Oth‐
748 erwise they are taken relative to the input line. For example,
749 the following
750 .ds x a\t\c
752 .ds y b\t\c
753 .ds z c
754 .ta 1i 3i
755 \*x
756 \*y
757 \*z
758 yields
760 a b c
762 In line-tabs mode, the same code gives
764 a b c
766 Line-tabs mode is associated with the current environment; the
768 read-only number register \n[.linetabs] is set to 1 if in line-
769 tabs mode, and 0 otherwise.
770 .lsm xx
772 Set the leading spaces macro to xx. If there are leading spaces
773 in an input line, it is invoked instead of the usual troff be‐
774 haviour; the leading spaces are removed. Registers \n[lsn] and
775 \n[lss] hold the number of removed leading spaces and the corre‐
776 sponding horizontal space, respectively.
777 .mso file
779 The same as the so request except that file is searched for in
780 the same directories as macro files for the the -m command line
781 option. If the file name to be included has the form name.tmac
782 and it isn't found, mso tries to include tmac.name instead and
783 vice versa. A warning of type file is generated if file can't
784 be loaded, and the request is ignored.
785 .nop anything
787 Execute anything. This is similar to `.if 1'.
788 .nroff Make the n built-in condition true and the t built-in condition
790 false. This can be reversed using the troff request.
791 .open stream filename
793 Open filename for writing and associate the stream named stream
794 with it. See also the close and write requests.
795 .opena stream filename
797 Like open, but if filename exists, append to it instead of trun‐
798 cating it.
799 .output string
801 Emit string directly to the intermediate output (subject to
802 copy-mode interpretation); this is similar to \! used at the top
803 level. An initial double quote in string is stripped off to
804 allow initial blanks.
805 .pev Print the current environment and each defined environment state
807 on stderr.
808 .pnr Print the names and contents of all currently defined number
810 registers on stderr.
811 .psbb filename
813 Get the bounding box of a PostScript image filename. This file
814 must conform to Adobe's Document Structuring Conventions; the
815 command looks for a %%BoundingBox comment to extract the bound‐
816 ing box values. After a successful call, the coordinates (in
817 PostScript units) of the lower left and upper right corner can
818 be found in the registers \n[llx], \n[lly], \n[urx], and
819 \n[ury], respectively. If some error has occurred, the four
820 registers are set to zero.
821 .pso command
823 This behaves like the so request except that input comes from
824 the standard output of command.
825 .ptr Print the names and positions of all traps (not including input
827 line traps and diversion traps) on stderr. Empty slots in the
828 page trap list are printed as well, because they can affect the
829 priority of subsequently planted traps.
830 .pvs ±n
832 Set the post-vertical line space to n; default scale indicator
833 is p. This value is added to each line after it has been out‐
834 put. With no argument, the post-vertical line space is set to
835 its previous value.
836 The total vertical line spacing consists of four components: .vs
838 and \x with a negative value which are applied before the line
839 is output, and .pvs and \x with a positive value which are
840 applied after the line is output.
841 .rchar c1 c2 ...
843 Remove the definitions of glyphs c1, c2, ... This undoes the
844 effect of a char request.
845 .return
847 Within a macro, return immediately. If called with an argument,
848 return twice, namely from the current macro and from the macro
849 one level higher. No effect otherwise.
850 .rfschar c1 c2 ...
852 Remove the font-specific definitions of glyphs c1, c2, ... This
853 undoes the effect of a fschar request.
854 .rj
856 .rj n Right justify the next n input lines. Without an argument right
857 justify the next input line. The number of lines to be right
858 justified is available in the \n[.rj] register. This implicitly
859 does .ce 0. The ce request implicitly does .rj 0.
860 .rnn xx yy
862 Rename number register xx to yy.
863 .schar c string
865 Define global fallback character (or glyph) c to be string. The
866 syntax of this request is the same as the char request; a glyph
867 defined with schar is searched after the list of fonts declared
868 with the special request but before the mounted special fonts.
869 .shc c Set the soft hyphen character to c. If c is omitted, the soft
871 hyphen character is set to the default \[hy]. The soft hyphen
872 character is the glyph which is inserted when a word is hyphen‐
873 ated at a line break. If the soft hyphen character does not
874 exist in the font of the glyph immediately preceding a potential
875 break point, then the line is not broken at that point. Neither
876 definitions (specified with the char request) nor translations
877 (specified with the tr request) are considered when finding the
878 soft hyphen character.
879 .shift n
881 In a macro, shift the arguments by n positions: argument i
882 becomes argument i-n; arguments 1 to n are no longer available.
883 If n is missing, arguments are shifted by 1. Shifting by nega‐
884 tive amounts is currently undefined.
885 .sizes s1 s2 ... sn [0]
887 This command is similar to the sizes command of a DESC file. It
888 sets the available font sizes for the current font to s1, s2,
889 ..., sn scaled points. The list of sizes can be terminated by
890 an optional 0. Each si can also be a range of sizes m–n. Con‐
891 trary to the font file command, the list can't extend over more
892 than a single line.
893 .special s1 s2 ...
895 Fonts s1, s2, ..., are special and are searched for glyphs not
896 in the current font. Without arguments, reset the list of spe‐
897 cial fonts to be empty.
898 .spreadwarn limit
900 Make troff emit a warning if the additional space inserted for
901 each space between words in an output line is larger or equal to
902 limit. A negative value is changed to zero; no argument toggles
903 the warning on and off without changing limit. The default
904 scaling indicator is m. At startup, spreadwarn is deactivated,
905 and limit is set to 3m. For example, .spreadwarn 0.2m causes a
906 warning if troff must add 0.2m or more for each interword space
907 in a line. This request is active only if text is justified to
908 both margins (using .ad b).
909 .sty n f
911 Associate style f with font position n. A font position can be
912 associated either with a font or with a style. The current font
913 is the index of a font position and so is also either a font or
914 a style. When it is a style, the font that is actually used is
915 the font the name of which is the concatenation of the name of
916 the current family and the name of the current style. For exam‐
917 ple, if the current font is 1 and font position 1 is associated
918 with style R and the current font family is T, then font TR is
919 used. If the current font is not a style, then the current fam‐
920 ily is ignored. When the requests cs, bd, tkf, uf, or fspecial
921 are applied to a style, then they are applied instead to the
922 member of the current family corresponding to that style. The
923 default family can be set with the -f command line option. The
924 styles command in the DESC file controls which font positions
925 (if any) are initially associated with styles rather than fonts.
926 .substring xx n1 [n2]
928 Replace the string named xx with the substring defined by the
929 indices n1 and n2. The first character in the string has
930 index 0. If n2 is omitted, it is taken to be equal to the
931 string's length. If the index value n1 or n2 is negative, it is
932 counted from the end of the string, going backwards: The last
933 character has index -1, the character before the last character
934 has index -2, etc.
935 .tkf f s1 n1 s2 n2
937 Enable track kerning for font f. When the current font is f the
938 width of every glyph is increased by an amount between n1 and
939 n2; when the current point size is less than or equal to s1 the
940 width is increased by n1; when it is greater than or equal to s2
941 the width is increased by n2; when the point size is greater
942 than or equal to s1 and less than or equal to s2 the increase in
943 width is a linear function of the point size.
944 .tm1 string
946 Similar to the tm request, string is read in copy mode and writ‐
947 ten on the standard error, but an initial double quote in string
948 is stripped off to allow initial blanks.
949 .tmc string
951 Similar to tm1 but without writing a final newline.
952 .trf filename
954 Transparently output the contents of file filename. Each line
955 is output as if preceded by \!; however, the lines are not sub‐
956 ject to copy-mode interpretation. If the file does not end with
957 a newline, then a newline is added. For example, you can define
958 a macro x containing the contents of file f, using
959 .di x
961 .trf f
962 .di
963 Unlike with the cf request, the file cannot contain characters
965 such as NUL that are not valid troff input characters.
966 .trin abcd
968 This is the same as the tr request except that the asciify
969 request uses the character code (if any) before the character
970 translation. Example:
971 .trin ax
973 .di xxx
974 a
975 .br
976 .di
977 .xxx
978 .trin aa
979 .asciify xxx
980 .xxx
981 The result is x a. Using tr, the result would be x x.
983 .trnt abcd
985 This is the same as the tr request except that the translations
986 do not apply to text that is transparently throughput into a
987 diversion with \!. For example,
988 .tr ab
990 .di x
991 \!.tm a
992 .di
993 .x
994 prints b; if trnt is used instead of tr it prints a.
996 .troff Make the n built-in condition false, and the t built-in condi‐
998 tion true. This undoes the effect of the nroff request.
999 .unformat xx
1001 This request `unformats' the diversion xx. Contrary to the
1002 asciify request, which tries to convert formatted elements of
1003 the diversion back to input tokens as much as possible, .unfor‐
1004 mat only handles tabs and spaces between words (usually caused
1005 by spaces or newlines in the input) specially. The former are
1006 treated as if they were input tokens, and the latter are
1007 stretchable again. Note that the vertical size of lines is not
1008 preserved. Glyph information (font, font size, space width,
1009 etc.) is retained. Useful in conjunction with the box and boxa
1010 requests.
1011 .vpt n Enable vertical position traps if n is non-zero, disable them
1013 otherwise. Vertical position traps are traps set by the wh or
1014 dt requests. Traps set by the it request are not vertical posi‐
1015 tion traps. The parameter that controls whether vertical posi‐
1016 tion traps are enabled is global. Initially vertical position
1017 traps are enabled.
1018 .warn n
1020 Control warnings. n is the sum of the numbers associated with
1021 each warning that is to be enabled; all other warnings are dis‐
1022 abled. The number associated with each warning is listed in
1023 troff(1). For example, .warn 0 disables all warnings, and
1024 .warn 1 disables all warnings except that about missing glyphs.
1025 If n is not given, all warnings are enabled.
1026 .warnscale si
1028 Set the scaling indicator used in warnings to si. Valid values
1029 for si are u, i, c, p, and P. At startup, it is set to i.
1030 .while c anything
1032 While condition c is true, accept anything as input; c can be
1033 any condition acceptable to an if request; anything can comprise
1034 multiple lines if the first line starts with \{ and the last
1035 line ends with \}. See also the break and continue requests.
1036 .write stream anything
1038 Write anything to the stream named stream. stream must previ‐
1039 ously have been the subject of an open request. anything is
1040 read in copy mode; a leading " is stripped.
1041 .writec stream anything
1043 Similar to write but without writing a final newline.
1044 .writem stream xx
1046 Write the contents of the macro or string xx to the stream named
1047 stream. stream must previously have been the subject of an open
1048 request. xx is read in copy mode.
1049 Extended escape sequences
1051 \D'...'
1052 All drawing commands of groff's intermediate output are
1053 accepted. See subsection Drawing Commands below for more infor‐
1054 mation.
1055 Extended requests
1057 .cf filename
1058 When used in a diversion, this embeds in the diversion an object
1059 which, when reread, will cause the contents of filename to be
1060 transparently copied through to the output. In UNIX troff, the
1061 contents of filename is immediately copied through to the output
1062 regardless of whether there is a current diversion; this behav‐
1063 iour is so anomalous that it must be considered a bug.
1064 .de xx yy
1066 .am xx yy
1067 .ds xx yy
1068 .as xx yy
1069 In compatibility mode, these requests behaves similar to .de1,
1070 .am1, .ds1, and .as1, respectively: A `compatibility save' token
1071 is inserted at the beginning, and a `compatibility restore'
1072 token at the end, with compatibility mode switched on during
1073 execution.
1074 .ev xx If xx is not a number, this switches to a named environment
1076 called xx. The environment should be popped with a matching ev
1077 request without any arguments, just as for numbered environ‐
1078 ments. There is no limit on the number of named environments;
1079 they are created the first time that they are referenced.
1080 .ss m n
1082 When two arguments are given to the ss request, the second argu‐
1083 ment gives the sentence space size. If the second argument is
1084 not given, the sentence space size is the same as the word space
1085 size. Like the word space size, the sentence space is in units
1086 of one twelfth of the spacewidth parameter for the current font.
1087 Initially both the word space size and the sentence space size
1088 are 12. Contrary to UNIX troff, GNU troff handles this request
1089 in nroff mode also; a given value is then rounded down to the
1090 nearest multiple of 12. The sentence space size is used in two
1091 circumstances. If the end of a sentence occurs at the end of a
1092 line in fill mode, then both an inter-word space and a sentence
1093 space are added; if two spaces follow the end of a sentence in
1094 the middle of a line, then the second space is a sentence space.
1095 Note that the behaviour of UNIX troff are exactly that exhibited
1096 by GNU troff if a second argument is never given to the ss
1097 request. In GNU troff, as in UNIX troff, you should always fol‐
1098 low a sentence with either a newline or two spaces.
1099 .ta n1 n2 ... nn T r1 r2 ... rn
1101 Set tabs at positions n1, n2, ..., nn and then set tabs at
1102 nn+r1, nn+r2, ..., nn+rn and then at nn+rn+r1, nn+rn+r2, ...,
1103 nn+rn+rn, and so on. For example,
1104 .ta T .5i
1106 sets tabs every half an inch.
1108 New number registers
1110 The following read-only registers are available:
1111 \n[.br]
1113 Within a macro call, it is set to 1 if the macro is called with
1114 the `normal' control character (`.' by default), and set to 0
1115 otherwise. This allows to reliably modify requests.
1116 .als bp*orig bp
1118 .de bp
1119 .tm before bp
1120 .ie \\n[.br] .bp*orig
1121 .el 'bp*orig
1122 .tm after bp
1123 ..
1124 Using this register outside of a macro makes no sense (it always
1126 returns zero in such cases).
1127 \n[.C] 1 if compatibility mode is in effect, 0 otherwise.
1129 \n[.cdp]
1131 The depth of the last glyph added to the current environment.
1132 It is positive if the glyph extends below the baseline.
1133 \n[.ce]
1135 The number of lines remaining to be centered, as set by the ce
1136 request.
1137 \n[.cht]
1139 The height of the last glyph added to the current environment.
1140 It is positive if the glyph extends above the baseline.
1141 \n[.color]
1143 1 if colors are enabled, 0 otherwise.
1144 \n[.csk]
1146 The skew of the last glyph added to the current environment.
1147 The skew of a glyph is how far to the right of the center of a
1148 glyph the center of an accent over that glyph should be placed.
1149 \n[.ev]
1151 The name or number of the current environment. This is a
1152 string-valued register.
1153 \n[.fam]
1155 The current font family. This is a string-valued register.
1156 \n[.fn]
1158 The current (internal) real font name. This is a string-valued
1159 register. If the current font is a style, the value of \n[.fn]
1160 is the proper concatenation of family and style name.
1161 \n[.fp]
1163 The number of the next free font position.
1164 \n[.g] Always 1. Macros should use this to determine whether they are
1166 running under GNU troff.
1167 \n[.height]
1169 The current height of the font as set with \H.
1170 \n[.hla]
1172 The current hyphenation language as set by the hla request.
1173 \n[.hlc]
1175 The number of immediately preceding consecutive hyphenated
1176 lines.
1177 \n[.hlm]
1179 The maximum allowed number of consecutive hyphenated lines, as
1180 set by the hlm request.
1181 \n[.hy]
1183 The current hyphenation flags (as set by the hy request).
1184 \n[.hym]
1186 The current hyphenation margin (as set by the hym request).
1187 \n[.hys]
1189 The current hyphenation space (as set by the hys request).
1190 \n[.in]
1192 The indentation that applies to the current output line.
1193 \n[.int]
1195 Set to a positive value if last output line is interrupted
1196 (i.e., if it contains \c).
1197 \n[.kern]
1199 1 if pairwise kerning is enabled, 0 otherwise.
1200 \n[.lg]
1202 The current ligature mode (as set by the lg request).
1203 \n[.linetabs]
1205 The current line-tabs mode (as set by the linetabs request).
1206 \n[.ll]
1208 The line length that applies to the current output line.
1209 \n[.lt]
1211 The title length as set by the lt request.
1212 \n[.m] The name of the current drawing color. This is a string-valued
1214 register.
1215 \n[.M] The name of the current background color. This is a string-val‐
1217 ued register.
1218 \n[.ne]
1220 The amount of space that was needed in the last ne request that
1221 caused a trap to be sprung. Useful in conjunction with the
1222 \n[.trunc] register.
1223 \n[.ns]
1225 1 if no-space mode is active, 0 otherwise.
1226 \n[.O] The current output level as set with \O.
1228 \n[.P] 1 if the current page is in the output list set with -o.
1230 \n[.pe]
1232 1 during a page ejection caused by the bp request, 0 otherwise.
1233 \n[.pn]
1235 The number of the next page, either the value set by a pn
1236 request, or the number of the current page plus 1.
1237 \n[.ps]
1239 The current point size in scaled points.
1240 \n[.psr]
1242 The last-requested point size in scaled points.
1243 \n[.pvs]
1245 The current post-vertical line space as set with the pvs
1246 request.
1247 \n[.rj]
1249 The number of lines to be right-justified as set by the rj
1250 request.
1251 \n[.slant]
1253 The slant of the current font as set with \S.
1254 \n[.sr]
1256 The last requested point size in points as a decimal fraction.
1257 This is a string-valued register.
1258 \n[.ss]
1260 \n[.sss]
1261 These give the values of the parameters set by the first and
1262 second arguments of the ss request.
1263 \n[.sty]
1265 The current font style. This is a string-valued register.
1266 \n[.tabs]
1268 A string representation of the current tab settings suitable for
1269 use as an argument to the ta request.
1270 \n[.trunc]
1272 The amount of vertical space truncated by the most recently
1273 sprung vertical position trap, or, if the trap was sprung by a
1274 ne request, minus the amount of vertical motion produced by the
1275 ne request. In other words, at the point a trap is sprung, it
1276 represents the difference of what the vertical position would
1277 have been but for the trap, and what the vertical position actu‐
1278 ally is. Useful in conjunction with the \n[.ne] register.
1279 \n[.U] Set to 1 if in safer mode and to 0 if in unsafe mode (as given
1281 with the -U command line option).
1282 \n[.vpt]
1284 1 if vertical position traps are enabled, 0 otherwise.
1285 \n[.warn]
1287 The sum of the numbers associated with each of the currently
1288 enabled warnings. The number associated with each warning is
1289 listed in troff(1).
1290 \n[.x] The major version number. For example, if the version number is
1292 1.03, then \n[.x] contains 1.
1293 \n[.y] The minor version number. For example, if the version number is
1295 1.03, then \n[.y] contains 03.
1296 \n[.Y] The revision number of groff.
1298 \n[.zoom]
1300 The zoom value of the current font, in multiples of 1/1000th.
1301 Zero if no magnification.
1302 \n[llx]
1304 \n[lly]
1305 \n[urx]
1306 \n[ury]
1307 These four read/write registers are set by the psbb request and
1308 contain the bounding box values (in PostScript units) of a given
1309 PostScript image.
1310 The following read/write registers are set by the \w escape sequence:
1312 \n[rst]
1314 \n[rsb]
1315 Like the st and sb registers, but take account of the heights
1316 and depths of glyphs.
1317 \n[ssc]
1319 The amount of horizontal space (possibly negative) that should
1320 be added to the last glyph before a subscript.
1321 \n[skw]
1323 How far to right of the center of the last glyph in the \w argu‐
1324 ment, the center of an accent from a roman font should be placed
1325 over that glyph.
1326 Other available read/write number registers are:
1328 \n[c.] The current input line number. \n[.c] is a read-only alias to
1330 this register.
1331 \n[hours]
1333 The number of hours past midnight. Initialized at start-up.
1334 \n[hp] The current horizontal position at input line.
1336 \n[lsn]
1338 \n[lss]
1339 If there are leading spaces in an input line, these registers
1340 hold the number of leading spaces and the corresponding horizon‐
1341 tal space, respectively.
1342 \n[minutes]
1344 The number of minutes after the hour. Initialized at start-up.
1345 \n[seconds]
1347 The number of seconds after the minute. Initialized at start-
1348 up.
1349 \n[systat]
1351 The return value of the system() function executed by the last
1352 sy request.
1353 \n[slimit]
1355 If greater than 0, the maximum number of objects on the input
1356 stack. If less than or equal to 0, there is no limit on the
1357 number of objects on the input stack. With no limit, recursion
1358 can continue until virtual memory is exhausted.
1359 \n[year]
1361 The current year. Note that the traditional troff number regis‐
1362 ter \n[yr] is the current year minus 1900.
1363 Miscellaneous
1365 troff predefines a single (read/write) string-based register, \*[.T],
1366 which contains the argument given to the -T command line option, namely
1367 the current output device (for example, latin1 or ascii). Note that
1368 this is not the same as the (read-only) number register \n[.T] which is
1369 defined to be 1 if troff is called with the -T command line option, and
1370 zero otherwise. This behaviour is different to UNIX troff.
1371 Fonts not listed in the DESC file are automatically mounted on the next
1373 available font position when they are referenced. If a font is to be
1374 mounted explicitly with the fp request on an unused font position, it
1375 should be mounted on the first unused font position, which can be found
1376 in the \n[.fp] register; although troff does not enforce this strictly,
1377 it does not allow a font to be mounted at a position whose number is
1378 much greater than that of any currently used position.
1379 Interpolating a string does not hide existing macro arguments. Thus in
1381 a macro, a more efficient way of doing
1382 .xx \\$@
1384 is
1386 \\*[xx]\\
1388 If the font description file contains pairwise kerning information,
1390 glyphs from that font are kerned. Kerning between two glyphs can be
1391 inhibited by placing a \& between them.
1392 In a string comparison in a condition, characters that appear at dif‐
1394 ferent input levels to the first delimiter character are not recognized
1395 as the second or third delimiters. This applies also to the tl
1396 request. In a \w escape sequence, a character that appears at a dif‐
1397 ferent input level to the starting delimiter character is not recog‐
1398 nized as the closing delimiter character. The same is true for \A, \b,
1399 \B, \C, \l, \L, \o, \X, and \Z. When decoding a macro or string argu‐
1400 ment that is delimited by double quotes, a character that appears at a
1401 different input level to the starting delimiter character is not recog‐
1402 nized as the closing delimiter character. The implementation of \$@
1403 ensures that the double quotes surrounding an argument appear at the
1404 same input level, which is different to the input level of the argument
1405 itself. In a long escape name ] is not recognized as a closing delim‐
1406 iter except when it occurs at the same input level as the opening [.
1407 In compatibility mode, no attention is paid to the input-level.
1408 There are some new types of condition:
1410 .if rxxx
1412 True if there is a number register named xxx.
1413 .if dxxx
1415 True if there is a string, macro, diversion, or request named
1416 xxx.
1417 .if mxxx
1419 True if there is a color named xxx.
1420 .if cch
1422 True if there is a character (or glyph) ch available; ch is
1423 either an ASCII character or a glyph (special character)
1424 \N'xxx', \(xx or \[xxx]; the condition is also true if ch has
1425 been defined by the char request.
1426 .if Ff True if font f exists. f is handled as if it was opened with
1428 the ft request (this is, font translation and styles are
1429 applied), without actually mounting it.
1430 .if Ss True if style s has been registered. Font translation is
1432 applied.
1433 The tr request can now map characters onto \~.
1435 The space width emitted by the \| and \^ escape sequences can be con‐
1437 trolled on a per-font basis. If there is a glyph named \| or \^,
1438 respectively (note the leading backslash), defined in the current font
1439 file, use this glyph's width instead of the default value.
1440 It is now possible to have whitespace between the first and second dot
1442 (or the name of the ending macro) to end a macro definition. Example:
1443 .if t \{\
1445 . de bar
1446 . nop Hello, I'm `bar'.
1447 . .
1448 .\}
1449
1451 This section describes the format output by GNU troff. The output for‐
1452 mat used by GNU troff is very similar to that used by Unix device-inde‐
1453 pendent troff. Only the differences are documented here.
1454 Units
1456 The argument to the s command is in scaled points (units of points/n,
1457 where n is the argument to the sizescale command in the DESC file).
1458 The argument to the x Height command is also in scaled points.
1459 Text Commands
1461 Nn Print glyph with index n (a non-negative integer) of the current
1462 font.
1463 If the tcommand line is present in the DESC file, troff uses the fol‐
1465 lowing two commands.
1466 txxx xxx is any sequence of characters terminated by a space or a
1468 newline (to be more precise, it is a sequence of glyphs which
1469 are accessed with the corresponding characters); the first char‐
1470 acter should be printed at the current position, the current
1471 horizontal position should be increased by the width of the
1472 first character, and so on for each character. The width of the
1473 glyph is that given in the font file, appropriately scaled for
1474 the current point size, and rounded so that it is a multiple of
1475 the horizontal resolution. Special characters cannot be printed
1476 using this command.
1477 un xxx This is same as the t command except that after printing each
1479 character, the current horizontal position is increased by the
1480 sum of the width of that character and n.
1481 Note that single characters can have the eighth bit set, as can the
1483 names of fonts and special characters.
1484 The names of glyphs and fonts can be of arbitrary length; drivers
1486 should not assume that they are only two characters long.
1487 When a glyph is to be printed, that glyph is always in the current
1489 font. Unlike device-independent troff, it is not necessary for drivers
1490 to search special fonts to find a glyph.
1491 For color support, some new commands have been added:
1493 mc cyan magenta yellow
1495 md
1496 mg gray
1497 mk cyan magenta yellow black
1498 mr red green blue
1499 Set the color components of the current drawing color, using
1500 various color schemes. md resets the drawing color to the
1501 default value. The arguments are integers in the range 0 to
1502 65536.
1503 The x device control command has been extended.
1505 x u n If n is 1, start underlining of spaces. If n is 0, stop under‐
1507 lining of spaces. This is needed for the cu request in nroff
1508 mode and is ignored otherwise.
1509 Drawing Commands
1511 The D drawing command has been extended. These extensions are not used
1512 by GNU pic if the -n option is given.
1513 Df n\n Set the shade of gray to be used for filling solid objects to n;
1515 n must be an integer between 0 and 1000, where 0 corresponds
1516 solid white and 1000 to solid black, and values in between cor‐
1517 respond to intermediate shades of gray. This applies only to
1518 solid circles, solid ellipses and solid polygons. By default, a
1519 level of 1000 is used. Whatever color a solid object has, it
1520 should completely obscure everything beneath it. A value
1521 greater than 1000 or less than 0 can also be used: this means
1522 fill with the shade of gray that is currently being used for
1523 lines and text. Normally this is black, but some drivers may
1524 provide a way of changing this.
1525 The corresponding \D'f...' command shouldn't be used since its
1527 argument is always rounded to an integer multiple of the hori‐
1528 zontal resolution which can lead to surprising results.
1529 DC d\n Draw a solid circle with a diameter of d with the leftmost point
1531 at the current position.
1532 DE dx dy\n
1534 Draw a solid ellipse with a horizontal diameter of dx and a ver‐
1535 tical diameter of dy with the leftmost point at the current
1536 position.
1537 Dp dx1 dy1 dx2 dy2 ... dxn dyn\n
1539 Draw a polygon with, for i=1,...,n+1, the i-th vertex at the
1540 current position +ij−=Σ11(dxj,dyj). At the moment, GNU pic only
1541 uses this command to generate triangles and rectangles.
1542 DP dx1 dy1 dx2 dy2 ... dxn dyn\n
1544 Like Dp but draw a solid rather than outlined polygon.
1545 Dt n\n Set the current line thickness to n machine units. Tradition‐
1547 ally Unix troff drivers use a line thickness proportional to the
1548 current point size; drivers should continue to do this if no Dt
1549 command has been given, or if a Dt command has been given with a
1550 negative value of n. A zero value of n selects the smallest
1551 available line thickness.
1552 A difficulty arises in how the current position should be changed after
1554 the execution of these commands. This is not of great importance since
1555 the code generated by GNU pic does not depend on this. Given a drawing
1556 command of the form
1557 \D'c x1 y1 x2 y2 ... xn yn'
1559 where c is not one of c, e, l, a, or ~, Unix troff treats each of the
1561 xi as a horizontal quantity, and each of the yi as a vertical quantity
1562 and assumes that the width of the drawn object is in=Σ1xi, and that the
1563 height is in=Σ1yi. (The assumption about the height can be seen by exam‐
1564 ining the st and sb registers after using such a D command in a \w
1565 escape sequence). This rule also holds for all the original drawing
1566 commands with the exception of De. For the sake of compatibility GNU
1567 troff also follows this rule, even though it produces an ugly result in
1568 the case of the Dt and Df, and, to a lesser extent, DE commands. Thus
1569 after executing a D command of the form
1570 Dc x1 y1 x2 y2 ... xn yn\n
1572 the current position should be increased by (in=Σ1xi,in=Σ1yi).
1574 Another set of extensions is
1576 DFc cyan magenta yellow\n
1578 DFd\n
1579 DFg gray\n
1580 DFk cyan magenta yellow black\n
1581 DFr red green blue\n
1582 Set the color components of the filling color similar to the
1583 m commands above.
1584 The current position isn't changed by those colour commands (contrary
1586 to Df).
1587 Device Control Commands
1589 There is a continuation convention which permits the argument to the
1590 x X command to contain newlines: when outputting the argument to the
1591 x X command, GNU troff follows each newline in the argument with a +
1592 character (as usual, it terminates the entire argument with a newline);
1593 thus if the line after the line containing the x X command starts with
1594 +, then the newline ending the line containing the x X command should
1595 be treated as part of the argument to the x X command, the + should be
1596 ignored, and the part of the line following the + should be treated
1597 like the part of the line following the x X command.
1598 The first three output commands are guaranteed to be:
1600 x T device
1602 x res n h v
1603 x init
1604
1606 In spite of the many extensions, groff has retained compatibility to
1607 classical troff to a large degree. For the cases where the extensions
1608 lead to collisions, a special compatibility mode with the restricted,
1609 old functionality was created for groff.
1610 Groff Language
1612 groff provides a compatibility mode that allows to process roff code
1613 written for classical troff or for other implementations of roff in a
1614 consistent way.
1615 Compatibility mode can be turned on with the -C command line option,
1617 and turned on or off with the .cp request. The number register \n(.C
1618 is 1 if compatibility mode is on, 0 otherwise.
1619 This became necessary because the GNU concept for long names causes
1621 some incompatibilities. Classical troff interprets
1622 .dsabcd
1624 as defining a string ab with contents cd. In groff mode, this is con‐
1626 sidered as a call of a macro named dsabcd.
1627 Also classical troff interprets \*[ or \n[ as references to a string or
1629 number register called [ while groff takes this as the start of a long
1630 name.
1631 In compatibility mode, groff interprets these things in the traditional
1633 way; so long names are not recognized.
1634 On the other hand, groff in GNU native mode does not allow to use the
1636 single-character escapes \\ (backslash), \| (vertical bar), \^ (caret),
1637 \& (ampersand), \{ (opening brace), \} (closing brace), `\ ' (space),
1638 \' (single quote), \` (backquote), \- (minus), \_ (underline), \!
1639 (bang), \% (percent), and \c (character c) in names of strings, macros,
1640 diversions, number registers, fonts or environments, whereas classical
1641 troff does.
1642 The \A escape sequence can be helpful in avoiding these escape
1644 sequences in names.
1645 Fractional point sizes cause one noteworthy incompatibility. In clas‐
1647 sical troff, the ps request ignores scale indicators and so
1648 .ps 10u
1650 sets the point size to 10 points, whereas in groff native mode the
1652 point size is set to 10 scaled points.
1653 In groff, there is a fundamental difference between unformatted input
1655 characters, and formatted output characters (glyphs). Everything that
1656 affects how a glyph is output is stored with the glyph; once a glyph
1657 has been constructed it is unaffected by any subsequent requests that
1658 are executed, including the bd, cs, tkf, tr, or fp requests.
1659 Normally glyphs are constructed from input characters at the moment
1661 immediately before the glyph is added to the current output line.
1662 Macros, diversions and strings are all, in fact, the same type of
1663 object; they contain lists of input characters and glyphs in any combi‐
1664 nation.
1665 Special characters can be both; before being added to the output, they
1667 act as input entities, afterwards they denote glyphs.
1668 A glyph does not behave like an input character for the purposes of
1670 macro processing; it does not inherit any of the special properties
1671 that the input character from which it was constructed might have had.
1672 The following example makes things clearer.
1673 .di x
1675 \\\\
1676 .br
1677 .di
1678 .x
1679 With GNU troff this is printed as \\. So each pair of input back‐
1681 slashes `\\' is turned into a single output backslash glyph `\' and the
1682 resulting output backslashes are not interpreted as escape characters
1683 when they are reread.
1684 Classical troff would interpret them as escape characters when they
1686 were reread and would end up printing a single backslash `\'.
1687 In GNU, the correct way to get a printable version of the backslash
1689 character `\' is the \(rs escape sequence, but classical troff does not
1690 provide a clean feature for getting a non-syntactical backslash. A
1691 close method is the printable version of the current escape character
1692 using the \e escape sequence; this works if the current escape charac‐
1693 ter is not redefined. It works in both GNU mode and compatibility
1694 mode, while dirty tricks like specifying a sequence of multiple back‐
1695 slashes do not work reliably; for the different handling in diversions,
1696 macro definitions, or text mode quickly leads to a confusion about the
1697 necessary number of backslashes.
1698 To store an escape sequence in a diversion that is interpreted when the
1700 diversion is reread, either the traditional \! transparent output
1701 facility or the new \? escape sequence can be used.
1702 Intermediate Output
1704 The groff intermediate output format is in a state of evolution. So
1705 far it has some incompatibilities, but it is intended to establish a
1706 full compatibility to the classical troff output format. Actually the
1707 following incompatibilities exist:
1708 · The positioning after the drawing of the polygons conflicts with the
1710 classical definition.
1711 · The intermediate output cannot be rescaled to other devices as clas‐
1713 sical `device-independent' troff did.
1714
1716 Copyright (C) 1989, 2001-2004, 2006-2010, 2012 Free Software Founda‐
1717 tion, Inc.
1718 This document is distributed under the terms of the FDL (GNU Free Docu‐
1720 mentation License) version 1.3 or later. You should have received a
1721 copy of the FDL on your system, it is also available on-line at the GNU
1722 copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩. This document
1723 was written by James Clark, with modifications by Werner Lemberg
1724 ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
1725 This document is part of groff, the GNU roff distribution. Formerly,
1727 the contents of this document was kept in the manual page troff(1).
1728 Only the parts dealing with the language aspects of the different roff
1729 systems were carried over into this document. The troff command line
1730 options and warnings are still documented in troff(1).
1731
1733 The groff info file, cf. info(1) presents all groff documentation
1734 within a single document.
1735 groff(1)
1737 A list of all documentation around groff.
1738 groff(7)
1740 A description of the groff language, including a short, but com‐
1741 plete reference of all predefined requests, registers, and
1742 escapes of plain groff. From the command line, this is called
1743 using
1744 man 7 groff
1746 roff(7)
1748 A survey of roff systems, including pointers to further histori‐
1749 cal documentation.
1750 [CSTR #54]
1752 The Nroff/Troff User's Manual by J. F. Ossanna of 1976 in the
1753 revision of Brian Kernighan of 1992, being the classical troff
1754 documentation ⟨http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.
1755Groff Version 1.22.2 7 February 2013 GROFF_DIFF(7)