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 Section “See Also” below gives pointers to both the classical roff and
16 the 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 Groff: The GNU Implementa‐
35 tion of troff, the groff Texinfo manual, for details of how a
36 glyph name for a composite glyph is constructed, and
37 groff_char(7) for a list of glyph name components used in com‐
38 posite glyph names.
39 \f[xxx]
41 Set font xxx. Additionally, \f[] is a new syntax form equal to
42 \fP, i.e., to return to the previous font.
43 \*[xxx arg1 arg2 ...]
45 Interpolate string xxx, taking arg1, arg2, ..., as arguments.
46 \n[xxx]
48 Interpolate number register xxx.
49 Fractional point sizes
51 A scaled point is equal to 1/sizescale points, where sizescale is spec‐
52 ified in the DESC file (1 by default). There is a new scale indica‐
53 tor z that has the effect of multiplying by sizescale. Requests and
54 escape sequences in troff interpret arguments that represent a point
55 size as being in units of scaled points, but they evaluate each such
56 argument using a default scale indicator of z. Arguments treated in
57 this way are the argument to the ps request, the third argument to the
58 cs request, the second and fourth arguments to the tkf request, the ar‐
59 gument to the \H escape sequence, and those variants of the \s escape
60 sequence that take a numeric expression as their argument.
61 For example, suppose sizescale is 1000; then a scaled point is equiva‐
63 lent to a millipoint; the call .ps 10.25 is equivalent to .ps 10.25z
64 and so sets the point size to 10250 scaled points, which is equal to
65 10.25 points.
66 The number register \n[.s] returns the point size in points as decimal
68 fraction. There is also a new number register \n[.ps] that returns the
69 point size in scaled points.
70 It would make no sense to use the z scale indicator in a numeric ex‐
72 pression whose default scale indicator was neither u nor z, and so
73 troff disallows this. Similarly it would make no sense to use a scal‐
74 ing indicator other than z or u in a numeric expression whose default
75 scale indicator was z, and so troff disallows this as well.
76 There is also new scale indicator s which multiplies by the number of
78 units in a scaled point. So, for example, \n[.ps]s is equal to 1m. Be
79 sure not to confuse the s and z scale indicators.
80 Numeric expressions
82 Spaces are permitted in a number expression within parentheses.
83 M indicates a scale of 100ths of an em. f indicates a scale of 65536
85 units, providing fractions for color definitions with the defcolor re‐
86 quest. For example, 0.5f = 32768u.
87 e1>?e2 The maximum of e1 and e2.
89 e1<?e2 The minimum of e1 and e2.
91 (c;e) Evaluate e using c as the default scaling indicator. If c is
93 missing, ignore scaling indicators in the evaluation of e.
94 New escape sequences
96 \A'anything'
97 This expands to 1 or 0, depending on whether anything is or is
98 not acceptable as the name of a string, macro, diversion, number
99 register, environment, font, or color. It returns 0 if anything
100 is empty. This is useful if you want to look up user input in
101 some sort of associative table.
102 \B'anything'
104 This expands to 1 or 0, depending on whether anything is or is
105 not a valid numeric expression. It returns 0 if anything is
106 empty.
107 \C'xxx'
109 Typeset glyph named xxx. Normally it is more convenient to use
110 \[xxx]. But \C has the advantage that it is compatible with re‐
111 cent versions of Unix and is available in compatibility mode.
112 \E This is equivalent to an escape character, but it is not inter‐
114 preted in copy mode. For example, strings to start and end su‐
115 perscripting could be defined like this
116 .ds { \v'-.3m'\s'\En[.s]*6u/10u'
118 .ds } \s0\v'.3m'
119 The use of \E ensures that these definitions work even if \*{
121 gets interpreted in copy mode (for example, by being used in a
122 macro argument).
123 \Ff
125 \F(fm
126 \F[fam]
127 Change font family. This is the same as the fam request. \F[]
128 switches back to the previous font family (note that \FP won't
129 work; it selects font family ‘P’ instead).
130 \mx
132 \m(xx
133 \m[xxx]
134 Set drawing color. \m[] switches back to the previous color.
135 \Mx
137 \M(xx
138 \M[xxx]
139 Set background color for filled objects drawn with the \D'...'
140 commands. \M[] switches back to the previous color.
141 \N'n' Typeset the glyph with index n in the current font. n can be
143 any integer. Most devices only have glyphs with indices between
144 0 and 255. If the current font does not contain a glyph with
145 that code, special fonts are not searched. The \N escape se‐
146 quence can be conveniently used in conjunction with the char re‐
147 quest, for example
148 .char \[phone] \f(ZD\N'37'
150 The index of each glyph is given in the fourth column in the
152 font description file after the charset command. It is possible
153 to include unnamed glyphs in the font description file by using
154 a name of ---; the \N escape sequence is the only way to use
155 these.
156 \On
158 \O[n] Suppress troff output. The escapes \O2, \O3, \O4, and \O5 are
159 intended for internal use by grohtml.
160 \O0 Disable any ditroff glyphs from being emitted to the de‐
162 vice driver, provided that the escape occurs at the outer
163 level (see \O3 and \O4).
164 \O1 Enable output of glyphs, provided that the escape occurs
166 at the outer level.
167 \O0 and \O1 also reset the registers \n[opminx], \n[op‐
169 miny], \n[opmaxx], and \n[opmaxy] to -1. These four reg‐
170 isters mark the top left and bottom right hand corners of
171 a box which encompasses all written glyphs.
172 \O2 Provided that the escape occurs at the outer level, en‐
174 able output of glyphs and also write out to stderr the
175 page number and four registers encompassing the glyphs
176 previously written since the last call to \O.
177 \O3 Begin a nesting level. At start-up, troff is at outer
179 level. This is really an internal mechanism for grohtml
180 while producing images. They are generated by running
181 the troff source through troff to the PostScript device
182 and ghostscript to produce images in PNG format. The \O3
183 escape starts a new page if the device is not html (to
184 reduce the possibility of images crossing a page bound‐
185 ary).
186 \O4 End a nesting level.
188 \O5[Pfilename]
190 This escape is grohtml specific. Provided that this es‐
191 cape occurs at the outer nesting level, write filename to
192 stderr. The position of the image, P, must be specified
193 and must be one of l, r, c, or i (left, right, centered,
194 inline). filename is associated with the production of
195 the next inline image.
196 \R'name ±n'
198 This has the same effect as
199 .nr name ±n
201 \s(nn
203 \s±(nn Set the point size to nn points; nn must be exactly two digits.
204 \s[±n]
206 \s±[n]
207 \s'±n'
208 \s±'n' Set the point size to n scaled points; n is a numeric expression
209 with a default scale indicator of z.
210 \Vx
212 \V(xx
213 \V[xxx]
214 Interpolate the contents of the environment variable xxx, as re‐
215 turned by getenv(3). \V is interpreted in copy mode.
216 \Yx
218 \Y(xx
219 \Y[xxx]
220 This is approximately equivalent to \X'\*[xxx]'. However the
221 contents of the string or macro xxx are not interpreted; also it
222 is permitted for xxx to have been defined as a macro and thus
223 contain newlines (it is not permitted for the argument to \X to
224 contain newlines). The inclusion of newlines requires an exten‐
225 sion to the Unix troff output format, and confuses drivers that
226 do not know about this extension.
227 \Z'anything'
229 Print anything and then restore the horizontal and vertical po‐
230 sition; anything may not contain tabs or leaders.
231 \$0 The name by which the current macro was invoked. The als re‐
233 quest can make a macro have more than one name.
234 \$* In a macro or string, the concatenation of all the arguments
236 separated by spaces.
237 \$@ In a macro or string, the concatenation of all the arguments
239 with each surrounded by double quotes, and separated by spaces.
240 \$^ In a macro, the representation of all parameters as if they were
242 an argument to the ds request.
243 \$(nn
245 \$[nnn]
246 In a macro or string, this gives the nn-th or nnn-th argument.
247 Macros and strings can have an unlimited number of arguments.
248 \?anything\?
250 When used in a diversion, this transparently embeds anything in
251 the diversion. anything is read in copy mode. When the diver‐
252 sion is reread, anything is interpreted. anything may not con‐
253 tain newlines; use \! if you want to embed newlines in a diver‐
254 sion. The escape sequence \? is also recognized in copy mode
255 and turned into a single internal code; it is this code that
256 terminates anything. Thus
257 .nr x 1
259 .nf
260 .di d
261 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
262 .di
263 .nr x 2
264 .di e
265 .d
266 .di
267 .nr x 3
268 .di f
269 .e
270 .di
271 .nr x 4
272 .f
273 prints 4.
275 \/ This increases the width of the preceding glyph so that the
277 spacing between that glyph and the following glyph is correct if
278 the following glyph is a roman glyph. It is a good idea to use
279 this escape sequence whenever an italic glyph is immediately
280 followed by a roman glyph without any intervening space.
281 \, This modifies the spacing of the following glyph so that the
283 spacing between that glyph and the preceding glyph is correct if
284 the preceding glyph is a roman glyph. It is a good idea to use
285 this escape sequence whenever a roman glyph is immediately fol‐
286 lowed by an italic glyph without any intervening space.
287 \) Like \& except that it behaves like a character declared with
289 the cflags request to be transparent for the purposes of end-of-
290 sentence recognition.
291 \~ This produces an unbreakable space that stretches like a normal
293 inter-word space when a line is adjusted.
294 \: This causes the insertion of a zero-width break point. It is
296 equal to \% within a word but without insertion of a soft hyphen
297 glyph.
298 \# Everything up to and including the next newline is ignored.
300 This is interpreted in copy mode. It is like \" except that \"
301 does not ignore the terminating newline.
302 New requests
304 .aln xx yy
305 Create an alias xx for number register object named yy. The new
306 name and the old name are exactly equivalent. If yy is unde‐
307 fined, a warning of type reg is generated, and the request is
308 ignored.
309 .als xx yy
311 Create an alias xx for request, string, macro, or diversion ob‐
312 ject named yy. The new name and the old name are exactly equiv‐
313 alent (it is similar to a hard rather than a soft link). If yy
314 is undefined, a warning of type mac is generated, and the re‐
315 quest is ignored. The de, am, di, da, ds, and as requests only
316 create a new object if the name of the macro, diversion or
317 string is currently undefined or if it is defined to be a re‐
318 quest; normally they modify the value of an existing object.
319 .am1 xx yy
321 Similar to .am, but compatibility mode is switched off during
322 execution. To be more precise, a ‘compatibility save’ token is
323 inserted at the beginning of the macro addition, and a ‘compati‐
324 bility restore’ token at the end. As a consequence, the re‐
325 quests am, am1, de, and de1 can be intermixed freely since the
326 compatibility save/restore tokens only affect the macro parts
327 defined by .am1 and .ds1.
328 .ami xx yy
330 Append to macro indirectly. See the dei request below for more
331 information.
332 .ami1 xx yy
334 Same as the ami request but compatibility mode is switched off
335 during execution.
336 .as1 xx yy
338 Similar to .as, but compatibility mode is switched off during
339 expansion. To be more precise, a ‘compatibility save’ token is
340 inserted at the beginning of the string, and a ‘compatibility
341 restore’ token at the end. As a consequence, the requests as,
342 as1, ds, and ds1 can be intermixed freely since the compatibil‐
343 ity save/restore tokens only affect the (sub)strings defined by
344 as1 and ds1.
345 .asciify xx
347 This request ‘unformats’ the diversion xx in such a way that
348 ASCII and space characters (and some escape sequences) that were
349 formatted and diverted into xx are treated like ordinary input
350 characters when xx is reread. Useful for diversions in conjunc‐
351 tion with the writem request. It can be also used for gross
352 hacks; for example, this
353 .tr @.
355 .di x
356 @nr n 1
357 .br
358 .di
359 .tr @@
360 .asciify x
361 .x
362 sets register n to 1. Note that glyph information (font, font
364 size, etc.) is not preserved; use .unformat instead.
365 .backtrace
367 Print a backtrace of the input stack on stderr.
368 .blm xx
370 Set the blank line macro to xx. If there is a blank line macro,
371 it is invoked when a blank line is encountered instead of the
372 usual troff behaviour.
373 .box xx
375 .boxa xx
376 These requests are similar to the di and da requests with the
377 exception that a partially filled line does not become part of
378 the diversion (i.e., the diversion always starts with a new
379 line) but is restored after ending the diversion, discarding the
380 partially filled line which possibly comes from the diversion.
381 .break Break out of a while loop. See also the while and continue re‐
383 quests. Be sure not to confuse this with the br request.
384 .brp This is the same as \p.
386 .cflags n c1 c2 ...
388 Characters c1, c2, ..., have properties determined by n, which
389 is ORed from the following:
390 1 The character ends sentences (initially characters .?!
392 have this property).
393 2 Lines can be broken before the character (initially no
395 characters have this property); a line is not broken at a
396 character with this property unless the characters on
397 each side both have non-zero hyphenation codes. This can
398 be overridden with value 64.
399 4 Lines can be broken after the character (initially char‐
401 acters -\[hy]\[em] have this property); a line is not
402 broken at a character with this property unless the char‐
403 acters on each side both have non-zero hyphenation codes.
404 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]\[cq] 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 128 Prohibit a line break before the character, but allow a
426 line break after the character. This works only in com‐
427 bination with flags 256 and 512 and has no effect other‐
428 wise.
429 256 Prohibit a line break after the character, but allow a
431 line break before the character. This works only in com‐
432 bination with flags 128 and 512 and has no effect other‐
433 wise.
434 512 Allow line break before or after the character. This
436 works only in combination with flags 128 and 256 and has
437 no effect otherwise.
438 Contrary to flag values 2 and 4, the flags 128, 256, and 512
440 work pairwise. If, for example, the left character has value
441 512, and the right character 128, no line break gets inserted.
442 If we use value 6 instead for the left character, a line break
443 after the character can't be suppressed since the right neigh‐
444 bour character doesn't get examined.
445 .char c string
447 [This request can both define characters and glyphs.]
448 Define entity c to be string. To be more precise, define (or
450 even override) a groff entity which can be accessed with name c
451 on the input side, and which uses string on the output side.
452 Every time glyph c needs to be printed, string is processed in a
453 temporary environment and the result is wrapped up into a single
454 object. Compatibility mode is turned off and the escape charac‐
455 ter is set to \ while string is being processed. Any embolden‐
456 ing, constant spacing or track kerning is applied to this object
457 rather than to individual glyphs in string.
458 A groff object defined by this request can be used just like a
460 normal glyph provided by the output device. In particular other
461 characters can be translated to it with the tr request; it can
462 be made the leader glyph by the lc request; repeated patterns
463 can be drawn with the glyph using the \l and \L escape se‐
464 quences; words containing c can be hyphenated correctly, if the
465 hcode request is used to give the object a hyphenation code.
466 There is a special anti-recursion feature: Use of glyph within
468 the glyph's definition is handled like normal glyphs not defined
469 with char.
470 A glyph definition can be removed with the rchar request.
472 .chop xx
474 Chop the last element off macro, string, or diversion xx. This
475 is useful for removing the newline from the end of diversions
476 that are to be interpolated as strings.
477 .class name c1 c2 ...
479 Assign name to a set of characters c1, c2, ..., so that they can
480 be referred to from other requests easily (currently .cflags
481 only). Character ranges (indicated by an intermediate ‘-’) and
482 nested classes are possible also. This is useful to assign
483 properties to a large set of characters.
484 .close stream
486 Close the stream named stream; stream will no longer be an ac‐
487 ceptable argument to the write request. See the open request.
488 .composite glyph1 glyph2
490 Map glyph name glyph1 to glyph name glyph2 if it is used in
491 \[...] with more than one component.
492 .continue
494 Finish the current iteration of a while loop. See also the
495 while and break requests.
496 .color n
498 If n is non-zero or missing, enable colors (this is the de‐
499 fault), otherwise disable them.
500 .cp n If n is non-zero or missing, enable compatibility mode, other‐
502 wise disable it. In compatibility mode, long names are not rec‐
503 ognized, and the incompatibilities caused by long names do not
504 arise.
505 .defcolor xxx scheme color_components
507 Define color xxx. scheme can be one of the following values:
508 rgb (three components), cmy (three components), cmyk (four com‐
509 ponents), and gray or grey (one component). Color components
510 can be given either as a hexadecimal string or as positive deci‐
511 mal integers in the range 0–65535. A hexadecimal string con‐
512 tains all color components concatenated; it must start with ei‐
513 ther # or ##. The former specifies hex values in the range
514 0–255 (which are internally multiplied by 257), the latter in
515 the range 0–65535. Examples: #FFC0CB (pink), ##ffff0000ffff
516 (magenta). A new scaling indicator f has been introduced which
517 multiplies its value by 65536; this makes it convenient to spec‐
518 ify color components as fractions in the range 0 to 1. Example:
519 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
521 Note that f is the default scaling indicator for the defcolor
523 request, thus the above statement is equivalent to
524 .defcolor darkgreen rgb 0.1 0.5 0.2
526 The color named default (which is device-specific) can't be re‐
528 defined. It is possible that the default color for \M and \m is
529 not the same.
530 .de1 xx yy
532 Similar to .de, but compatibility mode is switched off during
533 execution. On entry, the current compatibility mode is saved
534 and restored at exit.
535 .dei xx yy
537 Define macro indirectly. The following example
538 .ds xx aa
540 .ds yy bb
541 .dei xx yy
542 is equivalent to
544 .de aa bb
546 .dei1 xx yy
548 Similar to the dei request but compatibility mode is switched
549 off during execution.
550 .device anything
552 This is (almost) the same as the \X escape. anything is read in
553 copy mode; a leading " is stripped.
554 .devicem xx
556 This is the same as the \Y escape (to embed the contents of a
557 macro into the intermediate output preceded with ‘x X’).
558 .do xxx
560 Interpret .xxx with compatibility mode disabled. For example,
561 .do fam T
563 would have the same effect as
565 .fam T
567 except that it would work even if compatibility mode had been
569 enabled. Note that the previous compatibility mode is restored
570 before any files sourced by xxx are interpreted.
571 .ds1 xx yy
573 Similar to .ds, but compatibility mode is switched off during
574 expansion. To be more precise, a ‘compatibility save’ token is
575 inserted at the beginning of the string, and a ‘compatibility
576 restore’ token at the end.
577 .ecs Save current escape character.
579 .ecr Restore escape character saved with ecs. Without a previous
581 call to ecs, ‘\’ will be the new escape character.
582 .evc xx
584 Copy the contents of environment xx to the current environment.
585 No pushing or popping of environments is done.
586 .fam xx
588 Set the current font family to xx. The current font family is
589 part of the current environment. If xx is missing, switch back
590 to previous font family. The value at start-up is ‘T’. See the
591 description of the sty request for more information on font fam‐
592 ilies.
593 .fchar c string
595 Define fallback character (or glyph) c to be string. The syntax
596 of this request is the same as the char request; the only dif‐
597 ference is that a glyph defined with char hides the glyph with
598 the same name in the current font, whereas a glyph defined with
599 fchar is checked only if the particular glyph isn't found in the
600 current font. This test happens before checking special fonts.
601 .fcolor c
603 Set the fill color to c. If c is missing, switch to the previ‐
604 ous fill color.
605 .fschar f c string
607 Define fallback character (or glyph) c for font f to be string.
608 The syntax of this request is the same as the char request (with
609 an additional argument to specify the font); a glyph defined
610 with fschar is searched after the list of fonts declared with
611 the fspecial request but before the list of fonts declared with
612 .special.
613 .fspecial f s1 s2 ...
615 When the current font is f, fonts s1, s2, ..., are special, that
616 is, they are searched for glyphs not in the current font. Any
617 fonts specified in the special request are searched after fonts
618 specified in the fspecial request. Without argument, reset the
619 list of global special fonts to be empty.
620 .ftr f g
622 Translate font f to g. Whenever a font named f is referred to
623 in an \f escape sequence, in the F and S conditional operators,
624 or in the ft, ul, bd, cs, tkf, special, fspecial, fp, or sty re‐
625 quests, font g is used. If g is missing, or equal to f then
626 font f is not translated.
627 .fzoom f zoom
629 Set zoom factor zoom for font f. zoom must a non-negative inte‐
630 ger multiple of 1/1000th. If it is missing or is equal to zero,
631 it means the same as 1000, namely no magnification. f must be a
632 real font name, not a style.
633 .gcolor c
635 Set the glyph color to c. If c is missing, switch to the previ‐
636 ous glyph color.
637 .hcode c1 code1 c2 code2 ...
639 Set the hyphenation code of character c1 to code1 and that of c2
640 to code2, and so on. A hyphenation code must be a single input
641 character (not a special character) other than a digit or a
642 space. Initially each lower-case letter a–z has a hyphenation
643 code, which is itself, and each upper-case letter A–Z has a hy‐
644 phenation code which is the lower-case version of itself. See
645 also the hpf request.
646 .hla lang
648 Set the current hyphenation language to lang. Hyphenation ex‐
649 ceptions specified with the hw request and hyphenation patterns
650 specified with the hpf request are both associated with the cur‐
651 rent hyphenation language. The hla request is usually invoked
652 by the troffrc file to set up a default language.
653 .hlm n Set the maximum number of consecutive hyphenated lines to n. If
655 n is negative, there is no maximum. The default value is -1.
656 This value is associated with the current environment. Only
657 lines output from an environment count towards the maximum asso‐
658 ciated with that environment. Hyphens resulting from \% are
659 counted; explicit hyphens are not.
660 .hpf file
662 Read hyphenation patterns from file; this is searched for in the
663 same way that name.tmac is searched for when the -mname option
664 is specified. It should have the same format as (simple) TeX
665 patterns files. More specifically, the following scanning rules
666 are implemented.
667 • A percent sign starts a comment (up to the end of the
669 line) even if preceded by a backslash.
670 • No support for ‘digraphs’ like \$.
672 • ^^xx (x is 0–9 or a–f) and ^^x (character code of x in
674 the range 0–127) are recognized; other use of ^ causes an
675 error.
676 • No macro expansion.
678 • hpf checks for the expression \patterns{...} (possibly
680 with whitespace before and after the braces). Everything
681 between the braces is taken as hyphenation patterns.
682 Consequently, { and } are not allowed in patterns.
683 • Similarly, \hyphenation{...} gives a list of hyphenation
685 exceptions.
686 • \endinput is recognized also.
688 • For backwards compatibility, if \patterns is missing, the
690 whole file is treated as a list of hyphenation patterns
691 (only recognizing the % character as the start of a com‐
692 ment).
693 Use the hpfcode request to map the encoding used in hyphenation
695 patterns files to groff's input encoding. By default, every‐
696 thing maps to itself except letters ‘A’ to ‘Z’ which map to ‘a’
697 to ‘z’.
698 The set of hyphenation patterns is associated with the current
700 language set by the hla request. The hpf request is usually in‐
701 voked by the troffrc file; a second call replaces the old pat‐
702 terns with the new ones.
703 .hpfa file
705 The same as hpf except that the hyphenation patterns from file
706 are appended to the patterns already loaded in the current lan‐
707 guage.
708 .hpfcode a b c d ...
710 After reading a hyphenation patterns file with the hpf or hpfa
711 request, convert all characters with character code a in the re‐
712 cently read patterns to character code b, character code c to d,
713 etc. Initially, all character codes map to themselves. The ar‐
714 guments of hpfcode must be integers in the range 0 to 255. Note
715 that it is even possible to use character codes which are in‐
716 valid in groff otherwise.
717 .hym n Set the hyphenation margin to n: when the current adjustment
719 mode is not b, the line is not hyphenated if the line is no more
720 than n short. The default hyphenation margin is 0. The default
721 scaling indicator for this request is m. The hyphenation margin
722 is associated with the current environment. The current hyphen‐
723 ation margin is available in the \n[.hym] register.
724 .hys n Set the hyphenation space to n: When the current adjustment mode
726 is b don't hyphenate the line if the line can be justified by
727 adding no more than n extra space to each word space. The de‐
728 fault hyphenation space is 0. The default scaling indicator for
729 this request is m. The hyphenation space is associated with the
730 current environment. The current hyphenation space is available
731 in the \n[.hys] register.
732 .itc n macro
734 Variant of .it for which a line interrupted with \c is not
735 counted as an input line.
736 .kern n
738 If n is non-zero or missing, enable pairwise kerning, otherwise
739 disable it.
740 .length xx string
742 Compute the length of string and return it in the number regis‐
743 ter xx (which is not necessarily defined before).
744 .linetabs n
746 If n is non-zero or missing, enable line-tabs mode, otherwise
747 disable it (which is the default). In line-tabs mode, tab dis‐
748 tances are computed relative to the (current) output line. Oth‐
749 erwise they are taken relative to the input line. For example,
750 the following
751 .ds x a\t\c
753 .ds y b\t\c
754 .ds z c
755 .ta 1i 3i
756 \*x
757 \*y
758 \*z
759 yields
761 a b c
763 In line-tabs mode, the same code gives
765 a b c
767 Line-tabs mode is associated with the current environment; the
769 read-only number register \n[.linetabs] is set to 1 if in line-
770 tabs mode, and 0 otherwise.
771 .lsm xx
773 Set the leading spaces macro to xx. If there are leading spaces
774 in an input line, it is invoked instead of the usual troff be‐
775 haviour; the leading spaces are removed. Registers \n[lsn] and
776 \n[lss] hold the number of removed leading spaces and the corre‐
777 sponding horizontal space, respectively.
778 .mso file
780 The same as the so request except that file is searched for in
781 the same directories as macro files for the -m command-line op‐
782 tion. If the file name to be included has the form name.tmac
783 and it isn't found, mso tries to include tmac.name instead and
784 vice versa. A warning of type file is generated if file can't
785 be loaded, and the request is ignored.
786 .nop anything
788 Execute anything. This is similar to ‘.if 1’.
789 .nroff Make the n built-in condition true and the t built-in condition
791 false. This can be reversed using the troff request.
792 .open stream filename
794 Open filename for writing and associate the stream named stream
795 with it. See also the close and write requests.
796 .opena stream filename
798 Like open, but if filename exists, append to it instead of trun‐
799 cating it.
800 .output string
802 Emit string directly to the intermediate output (subject to
803 copy-mode interpretation); this is similar to \! used at the top
804 level. An initial double quote in string is stripped off to al‐
805 low initial blanks.
806 .pev Print the current environment and each defined environment state
808 on stderr.
809 .pnr Print the names and contents of all currently defined number
811 registers on stderr.
812 .psbb filename
814 Get the bounding box of a PostScript image filename. This file
815 must conform to Adobe's Document Structuring Conventions; the
816 command looks for a %%BoundingBox comment to extract the bound‐
817 ing box values. After a successful call, the coordinates (in
818 PostScript units) of the lower left and upper right corner can
819 be found in the registers \n[llx], \n[lly], \n[urx], and
820 \n[ury], respectively. If some error has occurred, the four
821 registers are set to zero.
822 .pso command
824 This behaves like the so request except that input comes from
825 the standard output of command.
826 .ptr Print the names and positions of all traps (not including input
828 line traps and diversion traps) on stderr. Empty slots in the
829 page trap list are printed as well, because they can affect the
830 priority of subsequently planted traps.
831 .pvs ±n
833 Set the post-vertical line space to n; default scale indicator
834 is p. This value is added to each line after it has been out‐
835 put. With no argument, the post-vertical line space is set to
836 its previous value.
837 The total vertical line spacing consists of four components: .vs
839 and \x with a negative value which are applied before the line
840 is output, and .pvs and \x with a positive value which are ap‐
841 plied after the line is output.
842 .rchar c1 c2 ...
844 Remove the definitions of glyphs c1, c2, ... This undoes the
845 effect of a char request.
846 .return
848 Within a macro, return immediately. If called with an argument,
849 return twice, namely from the current macro and from the macro
850 one level higher. No effect otherwise.
851 .rfschar c1 c2 ...
853 Remove the font-specific definitions of glyphs c1, c2, ... This
854 undoes the effect of an fschar request.
855 .rj
857 .rj n Right justify the next n input lines. Without an argument right
858 justify the next input line. The number of lines to be right
859 justified is available in the \n[.rj] register. This implicitly
860 does .ce 0. The ce request implicitly does .rj 0.
861 .rnn xx yy
863 Rename number register xx to yy.
864 .schar c string
866 Define global fallback character (or glyph) c to be string. The
867 syntax of this request is the same as the char request; a glyph
868 defined with schar is searched after the list of fonts declared
869 with the special request but before the mounted special fonts.
870 .shc c Set the soft hyphen character to c. If c is omitted, the soft
872 hyphen character is set to the default \[hy]. The soft hyphen
873 character is the glyph which is inserted when a word is hyphen‐
874 ated at a line break. If the soft hyphen character does not ex‐
875 ist in the font of the glyph immediately preceding a potential
876 break point, then the line is not broken at that point. Neither
877 definitions (specified with the char request) nor translations
878 (specified with the tr request) are considered when finding the
879 soft hyphen character.
880 .shift n
882 In a macro, shift the arguments by n positions: argument i be‐
883 comes argument i-n; arguments 1 to n are no longer available.
884 If n is missing, arguments are shifted by 1. Shifting by nega‐
885 tive amounts is currently undefined.
886 .sizes s1 s2 ... sn [0]
888 This command is similar to the sizes command of a DESC file. It
889 sets the available font sizes for the current font to s1, s2,
890 ..., sn scaled points. The list of sizes can be terminated by
891 an optional 0. Each si can also be a range of sizes m–n. Con‐
892 trary to the font file command, the list can't extend over more
893 than a single line.
894 .special s1 s2 ...
896 Fonts s1, s2, ..., are special and are searched for glyphs not
897 in the current font. Without arguments, reset the list of spe‐
898 cial fonts to be empty.
899 .spreadwarn limit
901 Make troff emit a warning if the additional space inserted for
902 each space between words in an output line is larger or equal to
903 limit. A negative value is changed to zero; no argument toggles
904 the warning on and off without changing limit. The default
905 scaling indicator is m. At startup, spreadwarn is deactivated,
906 and limit is set to 3m. For example, .spreadwarn 0.2m causes a
907 warning if troff must add 0.2m or more for each interword space
908 in a line. This request is active only if text is justified to
909 both margins (using .ad b).
910 .sty n f
912 Associate style f with font position n. A font position can be
913 associated either with a font or with a style. The current font
914 is the index of a font position and so is also either a font or
915 a style. When it is a style, the font that is actually used is
916 the font the name of which is the concatenation of the name of
917 the current family and the name of the current style. For exam‐
918 ple, if the current font is 1 and font position 1 is associated
919 with style R and the current font family is T, then font TR is
920 used. If the current font is not a style, then the current fam‐
921 ily is ignored. When the requests cs, bd, tkf, uf, or fspecial
922 are applied to a style, then they are applied instead to the
923 member of the current family corresponding to that style. The
924 default family can be set with the -f command-line option. The
925 styles command in the DESC file controls which font positions
926 (if any) are initially associated with styles rather than fonts.
927 .substring xx n1 [n2]
929 Replace the string named xx with the substring defined by the
930 indices n1 and n2. The first character in the string has in‐
931 dex 0. If n2 is omitted, it is taken to be equal to the
932 string's length. If the index value n1 or n2 is negative, it is
933 counted from the end of the string, going backwards: The last
934 character has index -1, the character before the last character
935 has index -2, etc.
936 .tkf f s1 n1 s2 n2
938 Enable track kerning for font f. When the current font is f the
939 width of every glyph is increased by an amount between n1 and
940 n2; when the current point size is less than or equal to s1 the
941 width is increased by n1; when it is greater than or equal to s2
942 the width is increased by n2; when the point size is greater
943 than or equal to s1 and less than or equal to s2 the increase in
944 width is a linear function of the point size.
945 .tm1 string
947 Similar to the tm request, string is read in copy mode and writ‐
948 ten on the standard error, but an initial double quote in string
949 is stripped off to allow initial blanks.
950 .tmc string
952 Similar to tm1 but without writing a final newline.
953 .trf filename
955 Transparently output the contents of file filename. Each line
956 is output as if preceded by \!; however, the lines are not sub‐
957 ject to copy-mode interpretation. If the file does not end with
958 a newline, then a newline is added. For example, you can define
959 a macro x containing the contents of file f, using
960 .di x
962 .trf f
963 .di
964 Unlike with the cf request, the file cannot contain characters,
966 such as NUL, that are not valid troff input characters.
967 .trin abcd
969 This is the same as the tr request except that the asciify re‐
970 quest uses the character code (if any) before the character
971 translation. Example:
972 .trin ax
974 .di xxx
975 a
976 .br
977 .di
978 .xxx
979 .trin aa
980 .asciify xxx
981 .xxx
982 The result is x a. Using tr, the result would be x x.
984 .trnt abcd
986 This is the same as the tr request except that the translations
987 do not apply to text that is transparently throughput into a di‐
988 version with \!. For example,
989 .tr ab
991 .di x
992 \!.tm a
993 .di
994 .x
995 prints b; if trnt is used instead of tr it prints a.
997 .troff Make the n built-in condition false, and the t built-in condi‐
999 tion true. This undoes the effect of the nroff request.
1000 .unformat xx
1002 This request ‘unformats’ the diversion xx. Contrary to the
1003 asciify request, which tries to convert formatted elements of
1004 the diversion back to input tokens as much as possible, .unfor‐
1005 mat only handles tabs and spaces between words (usually caused
1006 by spaces or newlines in the input) specially. The former are
1007 treated as if they were input tokens, and the latter are
1008 stretchable again. Note that the vertical size of lines is not
1009 preserved. Glyph information (font, font size, space width,
1010 etc.) is retained. Useful in conjunction with the box and boxa
1011 requests.
1012 .vpt n Enable vertical position traps if n is non-zero, disable them
1014 otherwise. Vertical position traps are traps set by the wh or
1015 dt requests. Traps set by the it request are not vertical posi‐
1016 tion traps. The parameter that controls whether vertical posi‐
1017 tion traps are enabled is global. Initially vertical position
1018 traps are enabled.
1019 .warn n
1021 Control warnings. n is the sum of the numbers associated with
1022 each warning that is to be enabled; all other warnings are dis‐
1023 abled. The number associated with each warning is listed in
1024 troff(1). For example, .warn 0 disables all warnings, and
1025 .warn 1 disables all warnings except that about missing glyphs.
1026 If n is not given, all warnings are enabled.
1027 .warnscale si
1029 Set the scaling indicator used in warnings to si. Valid values
1030 for si are u, i, c, p, and P. At startup, it is set to i.
1031 .while c anything
1033 While condition c is true, accept anything as input; c can be
1034 any condition acceptable to an if request; anything can comprise
1035 multiple lines if the first line starts with \{ and the last
1036 line ends with \}. See also the break and continue requests.
1037 .write stream anything
1039 Write anything to the stream named stream. stream must previ‐
1040 ously have been the subject of an open request. anything is
1041 read in copy mode; a leading " is stripped.
1042 .writec stream anything
1044 Similar to write but without writing a final newline.
1045 .writem stream xx
1047 Write the contents of the macro or string xx to the stream named
1048 stream. stream must previously have been the subject of an open
1049 request. xx is read in copy mode.
1050 Extended escape sequences
1052 \D'...'
1053 All drawing commands of groff's intermediate output are ac‐
1054 cepted. See subsection “Drawing Commands” below.
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’ to‐
1072 ken at the end, with compatibility mode switched on during exe‐
1073 cution.
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 .hy n New additive values 16 and 32 are available; the former enables
1082 hyphenation before the last character, the latter enables hy‐
1083 phenation after the first character.
1084 .ss m n
1086 When two arguments are given to the ss request, the second argu‐
1087 ment gives the sentence space size. If the second argument is
1088 not given, the sentence space size is the same as the word space
1089 size. Like the word space size, the sentence space is in units
1090 of one twelfth of the spacewidth parameter for the current font.
1091 Initially both the word space size and the sentence space size
1092 are 12. Contrary to Unix troff, GNU troff handles this request
1093 in nroff mode also; a given value is then rounded down to the
1094 nearest multiple of 12. The sentence space size is used in two
1095 circumstances. If the end of a sentence occurs at the end of a
1096 line in fill mode, then both an inter-word space and a sentence
1097 space are added; if two spaces follow the end of a sentence in
1098 the middle of a line, then the second space is a sentence space.
1099 Note that the behaviour of Unix troff is exactly that exhibited
1100 by GNU troff if a second argument is never given to the ss re‐
1101 quest. In GNU troff, as in Unix troff, you should always follow
1102 a sentence with either a newline or two spaces.
1103 .ta n1 n2 ... nn T r1 r2 ... rn
1105 Set tabs at positions n1, n2, ..., nn and then set tabs at
1106 nn+r1, nn+r2, ..., nn+rn and then at nn+rn+r1, nn+rn+r2, ...,
1107 nn+rn+rn, and so on. For example,
1108 .ta T .5i
1110 sets tabs every half an inch.
1112 New number registers
1114 The following read-only registers are available:
1115 \n[.br]
1117 Within a macro call, it is set to 1 if the macro is called with
1118 the ‘normal’ control character (‘.’ by default), and set to 0
1119 otherwise. This allows the reliable modification of requests.
1120 .als bp*orig bp
1122 .de bp
1123 .tm before bp
1124 .ie \\n[.br] .bp*orig
1125 .el 'bp*orig
1126 .tm after bp
1127 ..
1128 Using this register outside of a macro makes no sense (it always
1130 returns zero in such cases).
1131 \n[.C] 1 if compatibility mode is in effect, 0 otherwise.
1133 \n[.cdp]
1135 The depth of the last glyph added to the current environment.
1136 It is positive if the glyph extends below the baseline.
1137 \n[.ce]
1139 The number of lines remaining to be centered, as set by the ce
1140 request.
1141 \n[.cht]
1143 The height of the last glyph added to the current environment.
1144 It is positive if the glyph extends above the baseline.
1145 \n[.color]
1147 1 if colors are enabled, 0 otherwise.
1148 \n[.csk]
1150 The skew of the last glyph added to the current environment.
1151 The skew of a glyph is how far to the right of the center of a
1152 glyph the center of an accent over that glyph should be placed.
1153 \n[.ev]
1155 The name or number of the current environment. This is a
1156 string-valued register.
1157 \n[.fam]
1159 The current font family. This is a string-valued register.
1160 \n[.fn]
1162 The current (internal) real font name. This is a string-valued
1163 register. If the current font is a style, the value of \n[.fn]
1164 is the proper concatenation of family and style name.
1165 \n[.fp]
1167 The number of the next free font position.
1168 \n[.g] Always 1. Macros should use this to determine whether they are
1170 running under GNU troff.
1171 \n[.height]
1173 The current height of the font as set with \H.
1174 \n[.hla]
1176 The current hyphenation language as set by the hla request.
1177 \n[.hlc]
1179 The number of immediately preceding consecutive hyphenated
1180 lines.
1181 \n[.hlm]
1183 The maximum allowed number of consecutive hyphenated lines, as
1184 set by the hlm request.
1185 \n[.hy]
1187 The current hyphenation flags (as set by the hy request).
1188 \n[.hym]
1190 The current hyphenation margin (as set by the hym request).
1191 \n[.hys]
1193 The current hyphenation space (as set by the hys request).
1194 \n[.in]
1196 The indentation that applies to the current output line.
1197 \n[.int]
1199 Set to a positive value if last output line is interrupted
1200 (i.e., if it contains \c).
1201 \n[.kern]
1203 1 if pairwise kerning is enabled, 0 otherwise.
1204 \n[.lg]
1206 The current ligature mode (as set by the lg request).
1207 \n[.linetabs]
1209 The current line-tabs mode (as set by the linetabs request).
1210 \n[.ll]
1212 The line length that applies to the current output line.
1213 \n[.lt]
1215 The title length as set by the lt request.
1216 \n[.m] The name of the current drawing color. This is a string-valued
1218 register.
1219 \n[.M] The name of the current background color. This is a string-val‐
1221 ued register.
1222 \n[.ne]
1224 The amount of space that was needed in the last ne request that
1225 caused a trap to be sprung. Useful in conjunction with the
1226 \n[.trunc] register.
1227 \n[.ns]
1229 1 if no-space mode is active, 0 otherwise.
1230 \n[.O] The current output level as set with \O.
1232 \n[.P] 1 if the current page is in the output list set with -o.
1234 \n[.pe]
1236 1 during a page ejection caused by the bp request, 0 otherwise.
1237 \n[.pn]
1239 The number of the next page, either the value set by a pn re‐
1240 quest, or the number of the current page plus 1.
1241 \n[.ps]
1243 The current point size in scaled points.
1244 \n[.psr]
1246 The last-requested point size in scaled points.
1247 \n[.pvs]
1249 The current post-vertical line space as set with the pvs re‐
1250 quest.
1251 \n[.rj]
1253 The number of lines to be right-justified as set by the rj re‐
1254 quest.
1255 \n[.slant]
1257 The slant of the current font as set with \S.
1258 \n[.sr]
1260 The last requested point size in points as a decimal fraction.
1261 This is a string-valued register.
1262 \n[.ss]
1264 \n[.sss]
1265 These give the values of the parameters set by the first and
1266 second arguments of the ss request.
1267 \n[.sty]
1269 The current font style. This is a string-valued register.
1270 \n[.tabs]
1272 A string representation of the current tab settings suitable for
1273 use as an argument to the ta request.
1274 \n[.trunc]
1276 The amount of vertical space truncated by the most recently
1277 sprung vertical position trap, or, if the trap was sprung by an
1278 ne request, minus the amount of vertical motion produced by the
1279 ne request. In other words, at the point a trap is sprung, it
1280 represents the difference of what the vertical position would
1281 have been but for the trap, and what the vertical position actu‐
1282 ally is. Useful in conjunction with the \n[.ne] register.
1283 \n[.U] Set to 1 if in safer mode and to 0 if in unsafe mode (as given
1285 with the -U command-line option).
1286 \n[.vpt]
1288 1 if vertical position traps are enabled, 0 otherwise.
1289 \n[.warn]
1291 The sum of the numbers associated with each of the currently en‐
1292 abled warnings. The number associated with each warning is
1293 listed in troff(1).
1294 \n[.x] The major version number. For example, if the version number is
1296 1.03, then \n[.x] contains 1.
1297 \n[.y] The minor version number. For example, if the version number is
1299 1.03, then \n[.y] contains 03.
1300 \n[.Y] The revision number of groff.
1302 \n[.zoom]
1304 The zoom value of the current font, in multiples of 1/1000th.
1305 Zero if no magnification.
1306 \n[llx]
1308 \n[lly]
1309 \n[urx]
1310 \n[ury]
1311 These four read/write registers are set by the psbb request and
1312 contain the bounding box values (in PostScript units) of a given
1313 PostScript image.
1314 The following read/write registers are set by the \w escape sequence:
1316 \n[rst]
1318 \n[rsb]
1319 Like the st and sb registers, but take account of the heights
1320 and depths of glyphs.
1321 \n[ssc]
1323 The amount of horizontal space (possibly negative) that should
1324 be added to the last glyph before a subscript.
1325 \n[skw]
1327 How far to right of the center of the last glyph in the \w argu‐
1328 ment, the center of an accent from a roman font should be placed
1329 over that glyph.
1330 Other available read/write number registers are:
1332 \n[c.] The current input line number. \n[.c] is a read-only alias to
1334 this register.
1335 \n[hours]
1337 The number of hours past midnight. Initialized at start-up.
1338 \n[hp] The current horizontal position at input line.
1340 \n[lsn]
1342 \n[lss]
1343 If there are leading spaces in an input line, these registers
1344 hold the number of leading spaces and the corresponding horizon‐
1345 tal space, respectively.
1346 \n[minutes]
1348 The number of minutes after the hour. Initialized at start-up.
1349 \n[seconds]
1351 The number of seconds after the minute. Initialized at start-
1352 up.
1353 \n[systat]
1355 The return value of the system() function executed by the last
1356 sy request.
1357 \n[slimit]
1359 If greater than 0, the maximum number of objects on the input
1360 stack. If less than or equal to 0, there is no limit on the
1361 number of objects on the input stack. With no limit, recursion
1362 can continue until virtual memory is exhausted.
1363 \n[year]
1365 The current year. Note that the traditional troff number regis‐
1366 ter \n[yr] is the current year minus 1900.
1367 Miscellaneous
1369 troff predefines a single (read/write) string-based register, \*[.T],
1370 which contains the argument given to the -T command-line option, namely
1371 the current output device (for example, latin1 or ascii). Note that
1372 this is not the same as the (read-only) number register \n[.T] which is
1373 defined to be 1 if troff is called with the -T command-line option, and
1374 zero otherwise. This behaviour is different from Unix troff.
1375 Fonts not listed in the DESC file are automatically mounted on the next
1377 available font position when they are referenced. If a font is to be
1378 mounted explicitly with the fp request on an unused font position, it
1379 should be mounted on the first unused font position, which can be found
1380 in the \n[.fp] register; although troff does not enforce this strictly,
1381 it does not allow a font to be mounted at a position whose number is
1382 much greater than that of any currently used position.
1383 Interpolating a string does not hide existing macro arguments. Thus in
1385 a macro, a more efficient way of doing
1386 .xx \\$@
1388 is
1390 \\*[xx]\\
1392 If the font description file contains pairwise kerning information,
1394 glyphs from that font are kerned. Kerning between two glyphs can be
1395 inhibited by placing a \& between them.
1396 In a string comparison in a condition, characters that appear at dif‐
1398 ferent input levels to the first delimiter character are not recognized
1399 as the second or third delimiters. This applies also to the tl re‐
1400 quest. In a \w escape sequence, a character that appears at a differ‐
1401 ent input level to the starting delimiter character is not recognized
1402 as the closing delimiter character. The same is true for \A, \b, \B,
1403 \C, \l, \L, \o, \X, and \Z. When decoding a macro or string argument
1404 that is delimited by double quotes, a character that appears at a dif‐
1405 ferent input level to the starting delimiter character is not recog‐
1406 nized as the closing delimiter character. The implementation of \$@
1407 ensures that the double quotes surrounding an argument appear at the
1408 same input level, which is different to the input level of the argument
1409 itself. In a long escape name ] is not recognized as a closing delim‐
1410 iter except when it occurs at the same input level as the opening [.
1411 In compatibility mode, no attention is paid to the input-level.
1412 There are some new types of condition:
1414 .if rxxx
1416 True if there is a number register named xxx.
1417 .if dxxx
1419 True if there is a string, macro, diversion, or request named
1420 xxx.
1421 .if mxxx
1423 True if there is a color named xxx.
1424 .if cch
1426 True if there is a character (or glyph) ch available; ch is ei‐
1427 ther an ASCII character or a glyph (special character) \N'xxx',
1428 \(xx or \[xxx]; the condition is also true if ch has been de‐
1429 fined by the char request.
1430 .if Ff True if font f exists. f is handled as if it was opened with
1432 the ft request (this is, font translation and styles are ap‐
1433 plied), without actually mounting it.
1434 .if Ss True if style s has been registered. Font translation is ap‐
1436 plied.
1437 The tr request can now map characters onto \~.
1439 The space width emitted by the \| and \^ escape sequences can be con‐
1441 trolled on a per-font basis. If there is a glyph named \| or \^, re‐
1442 spectively (note the leading backslash), defined in the current font
1443 file, use this glyph's width instead of the default value.
1444 It is now possible to have whitespace between the first and second dot
1446 (or the name of the ending macro) to end a macro definition. Example:
1447 .if t \{\
1449 . de bar
1450 . nop Hello, I'm ‘bar’.
1451 . .
1452 .\}
1453
1455 This section describes the format output by GNU troff. The output for‐
1456 mat used by GNU troff is very similar to that used by Unix device-inde‐
1457 pendent troff. Only the differences are documented here.
1458 Units
1460 The argument to the s command is in scaled points (units of points/n,
1461 where n is the argument to the sizescale command in the DESC file).
1462 The argument to the x Height command is also in scaled points.
1463 Text Commands
1465 Nn Print glyph with index n (a non-negative integer) of the current
1466 font.
1467 If the tcommand line is present in the DESC file, troff uses the fol‐
1469 lowing two commands.
1470 txxx xxx is any sequence of characters terminated by a space or a
1472 newline (to be more precise, it is a sequence of glyphs which
1473 are accessed with the corresponding characters); the first char‐
1474 acter should be printed at the current position, the current
1475 horizontal position should be increased by the width of the
1476 first character, and so on for each character. The width of the
1477 glyph is that given in the font file, appropriately scaled for
1478 the current point size, and rounded so that it is a multiple of
1479 the horizontal resolution. Special characters cannot be printed
1480 using this command.
1481 un xxx This is same as the t command except that after printing each
1483 character, the current horizontal position is increased by the
1484 sum of the width of that character and n.
1485 Note that single characters can have the eighth bit set, as can the
1487 names of fonts and special characters.
1488 The names of glyphs and fonts can be of arbitrary length; drivers
1490 should not assume that they are only two characters long.
1491 When a glyph is to be printed, that glyph is always in the current
1493 font. Unlike device-independent troff, it is not necessary for drivers
1494 to search special fonts to find a glyph.
1495 For color support, some new commands have been added:
1497 mc cyan magenta yellow
1499 md
1500 mg gray
1501 mk cyan magenta yellow black
1502 mr red green blue
1503 Set the color components of the current drawing color, using
1504 various color schemes. md resets the drawing color to the de‐
1505 fault value. The arguments are integers in the range 0 to
1506 65536.
1507 The x device control command has been extended.
1509 x u n If n is 1, start underlining of spaces. If n is 0, stop under‐
1511 lining of spaces. This is needed for the cu request in nroff
1512 mode and is ignored otherwise.
1513 Drawing Commands
1515 The D drawing command has been extended. These extensions are not used
1516 by GNU pic if the -n option is given.
1517 Df n\n Set the shade of gray to be used for filling solid objects to n;
1519 n must be an integer between 0 and 1000, where 0 corresponds
1520 solid white and 1000 to solid black, and values in between cor‐
1521 respond to intermediate shades of gray. This applies only to
1522 solid circles, solid ellipses and solid polygons. By default, a
1523 level of 1000 is used. Whatever color a solid object has, it
1524 should completely obscure everything beneath it. A value
1525 greater than 1000 or less than 0 can also be used: this means
1526 fill with the shade of gray that is currently being used for
1527 lines and text. Normally this is black, but some drivers may
1528 provide a way of changing this.
1529 The corresponding \D'f...' command shouldn't be used since its
1531 argument is always rounded to an integer multiple of the hori‐
1532 zontal resolution which can lead to surprising results.
1533 DC d\n Draw a solid circle with a diameter of d with the leftmost point
1535 at the current position.
1536 DE dx dy\n
1538 Draw a solid ellipse with a horizontal diameter of dx and a ver‐
1539 tical diameter of dy with the leftmost point at the current po‐
1540 sition.
1541 Dp dx1 dy1 dx2 dy2 ... .lf 3498
1543 dxn dyn\n Draw a polygon with, for i=1,...,n+1, the i-th vertex
1544 at the current position +ij−=Σ11(dxj,dyj). At the moment, GNU pic
1545 only uses this command to generate triangles and rectangles.
1546 DP dx1 dy1 dx2 dy2 ... .lf 3510
1548 dxn dyn\n Like Dp but draw a solid rather than outlined polygon.
1549 Dt n\n Set the current line thickness to n machine units. Tradition‐
1551 ally Unix troff drivers use a line thickness proportional to the
1552 current point size; drivers should continue to do this if no Dt
1553 command has been given, or if a Dt command has been given with a
1554 negative value of n. A zero value of n selects the smallest
1555 available line thickness.
1556 A difficulty arises in how the current position should be changed after
1558 the execution of these commands. This is not of great importance since
1559 the code generated by GNU pic does not depend on this. Given a drawing
1560 command of the form
1561 \D'c x1 y1 x2 y2 ... .lf 3543 xn yn'
1563 where c is not one of c, e, l, a, or ~, Unix troff treats each of the
1565 xi as a horizontal quantity, and each of the yi as a vertical quantity
1566 and assumes that the width of the drawn object is in=Σ1xi, and that the
1567 height is in=Σ1yi. (The assumption about the height can be seen by exam‐
1568 ining the st and sb registers after using such a D command in a \w es‐
1569 cape sequence). This rule also holds for all the original drawing com‐
1570 mands with the exception of De. For the sake of compatibility GNU
1571 troff also follows this rule, even though it produces an ugly result in
1572 the case of the Dt and Df, and, to a lesser extent, DE commands. Thus
1573 after executing a D command of the form
1574 Dc x1 y1 x2 y2 ... .lf 3587 xn yn\n
1576 the current position should be increased by (in=Σ1xi,in=Σ1yi).
1578 Another set of extensions is
1580 DFc cyan magenta yellow\n
1582 DFd\n
1583 DFg gray\n
1584 DFk cyan magenta yellow black\n
1585 DFr red green blue\n
1586 Set the color components of the filling color similar to the
1587 m commands above.
1588 The current position isn't changed by those colour commands (contrary
1590 to Df).
1591 Device Control Commands
1593 There is a continuation convention which permits the argument to the
1594 x X command to contain newlines: when outputting the argument to the
1595 x X command, GNU troff follows each newline in the argument with a +
1596 character (as usual, it terminates the entire argument with a newline);
1597 thus if the line after the line containing the x X command starts with
1598 +, then the newline ending the line containing the x X command should
1599 be treated as part of the argument to the x X command, the + should be
1600 ignored, and the part of the line following the + should be treated
1601 like the part of the line following the x X command.
1602 The first three output commands are guaranteed to be:
1604 x T device
1606 x res n h v
1607 x init
1608
1610 In spite of the many extensions, groff has retained compatibility to
1611 classical troff to a large degree. For the cases where the extensions
1612 lead to collisions, a special compatibility mode with the restricted,
1613 old functionality was created for groff.
1614 Groff Language
1616 groff provides a compatibility mode that allows the processing of roff
1617 code written for classical troff or for other implementations of roff
1618 in a consistent way.
1619 Compatibility mode can be turned on with the -C command-line option,
1621 and turned on or off with the .cp request. The number register \n(.C
1622 is 1 if compatibility mode is on, 0 otherwise.
1623 This became necessary because the GNU concept for long names causes
1625 some incompatibilities. Classical troff interprets
1626 .dsabcd
1628 as defining a string ab with contents cd. In groff mode, this is con‐
1630 sidered as a call of a macro named dsabcd.
1631 Also classical troff interprets \*[ or \n[ as references to a string or
1633 number register called [ while groff takes this as the start of a long
1634 name.
1635 In compatibility mode, groff interprets these things in the traditional
1637 way; so long names are not recognized.
1638 On the other hand, groff in GNU native mode does not allow to use the
1640 single-character escapes \\ (backslash), \| (vertical bar), \^ (caret),
1641 \& (ampersand), \{ (opening brace), \} (closing brace), ‘\ ’ (space),
1642 \' (single quote), \` (backquote), \- (minus), \_ (underline), \!
1643 (bang), \% (percent), and \c (character c) in names of strings, macros,
1644 diversions, number registers, fonts or environments, whereas classical
1645 troff does.
1646 The \A escape sequence can be helpful in avoiding these escape se‐
1648 quences in names.
1649 Fractional point sizes cause one noteworthy incompatibility. In clas‐
1651 sical troff, the ps request ignores scale indicators and so
1652 .ps 10u
1654 sets the point size to 10 points, whereas in groff native mode the
1656 point size is set to 10 scaled points.
1657 In groff, there is a fundamental difference between unformatted input
1659 characters, and formatted output characters (glyphs). Everything that
1660 affects how a glyph is output is stored with the glyph; once a glyph
1661 has been constructed it is unaffected by any subsequent requests that
1662 are executed, including the bd, cs, tkf, tr, or fp requests.
1663 Normally glyphs are constructed from input characters at the moment im‐
1665 mediately before the glyph is added to the current output line.
1666 Macros, diversions and strings are all, in fact, the same type of ob‐
1667 ject; they contain lists of input characters and glyphs in any combina‐
1668 tion.
1669 Special characters can be both; before being added to the output, they
1671 act as input entities, afterwards they denote glyphs.
1672 A glyph does not behave like an input character for the purposes of
1674 macro processing; it does not inherit any of the special properties
1675 that the input character from which it was constructed might have had.
1676 The following example makes things clearer.
1677 .di x
1679 \\\\
1680 .br
1681 .di
1682 .x
1683 With GNU troff this is printed as \\. So each pair of input back‐
1685 slashes ‘\\’ is turned into a single output backslash glyph ‘\’ and the
1686 resulting output backslashes are not interpreted as escape characters
1687 when they are reread.
1688 Classical troff would interpret them as escape characters when they
1690 were reread and would end up printing a single backslash ‘\’.
1691 In GNU, the correct way to get a printable version of the backslash
1693 character ’\’ is the \(rs escape sequence, but classical troff does not
1694 provide a clean feature for getting a non-syntactical backslash. A
1695 close method is the printable version of the current escape character
1696 using the \e escape sequence; this works if the current escape charac‐
1697 ter is not redefined. It works in both GNU mode and compatibility
1698 mode, while dirty tricks like specifying a sequence of multiple back‐
1699 slashes do not work reliably; for the different handling in diversions,
1700 macro definitions, or text mode quickly leads to a confusion about the
1701 necessary number of backslashes.
1702 To store an escape sequence in a diversion that is interpreted when the
1704 diversion is reread, either the traditional \! transparent output fa‐
1705 cility or the new \? escape sequence can be used.
1706 Intermediate Output
1708 The groff intermediate output format is in a state of evolution. So
1709 far it has some incompatibilities, but it is intended to establish a
1710 full compatibility to the classical troff output format. Actually the
1711 following incompatibilities exist:
1712 • The positioning after the drawing of the polygons conflicts with the
1714 classical definition.
1715 • The intermediate output cannot be rescaled to other devices as clas‐
1717 sical ‘device-independent’ troff did.
1718
1720 This document was written by James Clark ⟨jjc@jclark.com⟩ and modified
1721 by Werner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@
1722 web.de⟩.
1723
1725 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
1726 Lemberg, is the primary groff manual. You can browse it interactively
1727 with “info groff”.
1728 groff(1)
1730 A list of all documentation around groff.
1731 groff(7)
1733 A description of the groff language, including a short, but com‐
1734 plete reference of all predefined requests, registers, and es‐
1735 capes of plain groff. From the command line, this is called us‐
1736 ing
1737 man 7 groff
1739 roff(7)
1741 A survey of roff systems, including pointers to further histori‐
1742 cal documentation.
1743 [CSTR #54]
1745 The Nroff/Troff User's Manual by J. F. Ossanna of 1976 in the
1746 revision of Brian Kernighan of 1992, being the classical troff
1747 documentation ⟨http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.
1748groff 1.22.4 22 July 2021 GROFF_DIFF(7)