1GROFF_DIFF(7)          Miscellaneous Information Manual          GROFF_DIFF(7)
2
3
4

NAME

6       groff_diff - differences between GNU troff and classical troff
7

DESCRIPTION

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
15       Section  “See Also” below gives pointers to both the classical roff and
16       the modern groff documentation.
17

GROFF LANGUAGE

19       In this section, all additional features of groff compared to the clas‐
20       sical Unix 7 troff are described in detail.
21
22   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
29       \[xxx] Print the special character (glyph) called xxx.
30
31       \[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
40       \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
44       \*[xxx arg1 arg2 ...]
45              Interpolate string xxx, taking arg1, arg2, ..., as arguments.
46
47       \n[xxx]
48              Interpolate number register xxx.
49
50   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
62       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
67       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
71       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
77       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
81   Numeric expressions
82       Spaces are permitted in a number expression within parentheses.
83
84       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
88       e1>?e2 The maximum of e1 and e2.
89
90       e1<?e2 The minimum of e1 and e2.
91
92       (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
95   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
103       \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
108       \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
113       \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
117                     .ds { \v'-.3m'\s'\En[.s]*6u/10u'
118                     .ds } \s0\v'.3m'
119
120              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
124       \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
131       \mx
132       \m(xx
133       \m[xxx]
134              Set drawing color.  \m[] switches back to the previous color.
135
136       \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
142       \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
149                     .char \[phone] \f(ZD\N'37'
150
151              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
157       \On
158       \O[n]  Suppress  troff  output.  The escapes \O2, \O3, \O4, and \O5 are
159              intended for internal use by grohtml.
160
161              \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
165              \O1    Enable output of glyphs, provided that the escape  occurs
166                     at the outer level.
167
168                     \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
173              \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
178              \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
187              \O4    End a nesting level.
188
189              \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
197       \R'name ±n'
198              This has the same effect as
199
200                     .nr name ±n
201
202       \s(nn
203       \s±(nn Set the point size to nn points; nn must be exactly two digits.
204
205       \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
211       \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
217       \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
228       \Z'anything'
229              Print  anything and then restore the horizontal and vertical po‐
230              sition; anything may not contain tabs or leaders.
231
232       \$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
235       \$*    In  a  macro  or  string, the concatenation of all the arguments
236              separated by spaces.
237
238       \$@    In a macro or string, the concatenation  of  all  the  arguments
239              with each surrounded by double quotes, and separated by spaces.
240
241       \$^    In a macro, the representation of all parameters as if they were
242              an argument to the ds request.
243
244       \$(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
249       \?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
258                     .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
274              prints 4.
275
276       \/     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
282       \,     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
288       \)     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
292       \~     This  produces an unbreakable space that stretches like a normal
293              inter-word space when a line is adjusted.
294
295       \:     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
299       \#     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
303   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
310       .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
320       .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
329       .ami xx yy
330              Append to macro indirectly.  See the dei request below for  more
331              information.
332
333       .ami1 xx yy
334              Same  as  the ami request but compatibility mode is switched off
335              during execution.
336
337       .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
346       .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
354                     .tr @.
355                     .di x
356                     @nr n 1
357                     .br
358                     .di
359                     .tr @@
360                     .asciify x
361                     .x
362
363              sets  register  n to 1.  Note that glyph information (font, font
364              size, etc.) is not preserved; use .unformat instead.
365
366       .backtrace
367              Print a backtrace of the input stack on stderr.
368
369       .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
374       .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
382       .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
385       .brp   This is the same as \p.
386
387       .cflags n c1 c2 ...
388              Characters  c1,  c2, ..., have properties determined by n, which
389              is ORed from the following:
390
391              1      The character ends sentences  (initially  characters  .?!
392                     have this property).
393
394              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
400              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
406              8      The  glyph  associated with this character overlaps hori‐
407                     zontally  (initially  characters   \[ul]\[rn]\[ru]\[radi‐
408                     calex]\[sqrtex] have this property).
409
410              16     The  glyph associated with this character overlaps verti‐
411                     cally (initially glyph \[br] has this property).
412
413              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
421              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
425              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
430              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
435              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
439              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
446       .char c string
447              [This request can both define characters and glyphs.]
448
449              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
459              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
467              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
471              A glyph definition can be removed with the rchar request.
472
473       .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
478       .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
485       .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
489       .composite glyph1 glyph2
490              Map glyph name glyph1 to glyph name glyph2  if  it  is  used  in
491              \[...] with more than one component.
492
493       .continue
494              Finish  the  current  iteration  of  a while loop.  See also the
495              while and break requests.
496
497       .color n
498              If n is non-zero or missing, enable  colors  (this  is  the  de‐
499              fault), otherwise disable them.
500
501       .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
506       .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
520                     .defcolor darkgreen rgb 0.1f 0.5f 0.2f
521
522              Note  that  f  is the default scaling indicator for the defcolor
523              request, thus the above statement is equivalent to
524
525                     .defcolor darkgreen rgb 0.1 0.5 0.2
526
527              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
531       .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
536       .dei xx yy
537              Define macro indirectly.  The following example
538
539                     .ds xx aa
540                     .ds yy bb
541                     .dei xx yy
542
543              is equivalent to
544
545                     .de aa bb
546
547       .dei1 xx yy
548              Similar to the dei request but compatibility  mode  is  switched
549              off during execution.
550
551       .device anything
552              This is (almost) the same as the \X escape.  anything is read in
553              copy mode; a leading " is stripped.
554
555       .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
559       .do xxx
560              Interpret .xxx with compatibility mode disabled.  For example,
561
562                     .do fam T
563
564              would have the same effect as
565
566                     .fam T
567
568              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
572       .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
578       .ecs   Save current escape character.
579
580       .ecr   Restore escape character saved with  ecs.   Without  a  previous
581              call to ecs, ‘\’ will be the new escape character.
582
583       .evc xx
584              Copy  the contents of environment xx to the current environment.
585              No pushing or popping of environments is done.
586
587       .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
594       .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
602       .fcolor c
603              Set  the fill color to c.  If c is missing, switch to the previ‐
604              ous fill color.
605
606       .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
614       .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
621       .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
628       .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
634       .gcolor c
635              Set the glyph color to c.  If c is missing, switch to the previ‐
636              ous glyph color.
637
638       .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
647       .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
654       .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
661       .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
668              •      A percent sign starts a comment (up to  the  end  of  the
669                     line) even if preceded by a backslash.
670
671              •      No support for ‘digraphs’ like \$.
672
673^^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
677              •      No macro expansion.
678
679hpf  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
684              •      Similarly, \hyphenation{...} gives a list of  hyphenation
685                     exceptions.
686
687\endinput is recognized also.
688
689              •      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
694              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
699              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
704       .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
709       .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
718       .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
725       .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
733       .itc n macro
734              Variant  of  .it  for  which  a  line interrupted with \c is not
735              counted as an input line.
736
737       .kern n
738              If n is non-zero or missing, enable pairwise kerning,  otherwise
739              disable it.
740
741       .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
745       .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
752                     .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
760              yields
761
762                     a         b         c
763
764              In line-tabs mode, the same code gives
765
766                     a         b                   c
767
768              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
772       .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
779       .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
787       .nop anything
788              Execute anything.  This is similar to ‘.if 1’.
789
790       .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
793       .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
797       .opena stream filename
798              Like open, but if filename exists, append to it instead of trun‐
799              cating it.
800
801       .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
807       .pev   Print the current environment and each defined environment state
808              on stderr.
809
810       .pnr   Print the names and contents of  all  currently  defined  number
811              registers on stderr.
812
813       .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
823       .pso command
824              This behaves like the so request except that  input  comes  from
825              the standard output of command.
826
827       .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
832       .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
838              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
843       .rchar c1 c2 ...
844              Remove the definitions of glyphs c1, c2, ...   This  undoes  the
845              effect of a char request.
846
847       .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
852       .rfschar c1 c2 ...
853              Remove the font-specific definitions of glyphs c1, c2, ...  This
854              undoes the effect of an fschar request.
855
856       .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
862       .rnn xx yy
863              Rename number register xx to yy.
864
865       .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
871       .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
881       .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
887       .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 mn.   Con‐
892              trary  to the font file command, the list can't extend over more
893              than a single line.
894
895       .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
900       .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
911       .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
928       .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
937       .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
946       .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
951       .tmc string
952              Similar to tm1 but without writing a final newline.
953
954       .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
961                     .di x
962                     .trf f
963                     .di
964
965              Unlike with the cf request, the file cannot contain  characters,
966              such as NUL, that are not valid troff input characters.
967
968       .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
973                     .trin ax
974                     .di xxx
975                     a
976                     .br
977                     .di
978                     .xxx
979                     .trin aa
980                     .asciify xxx
981                     .xxx
982
983              The result is x a.  Using tr, the result would be x x.
984
985       .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
990                     .tr ab
991                     .di x
992                     \!.tm a
993                     .di
994                     .x
995
996              prints b; if trnt is used instead of tr it prints a.
997
998       .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
1001       .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
1013       .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
1020       .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
1028       .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
1032       .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
1038       .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
1043       .writec stream anything
1044              Similar to write but without writing a final newline.
1045
1046       .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
1051   Extended escape sequences
1052       \D'...'
1053              All  drawing  commands  of  groff's  intermediate output are ac‐
1054              cepted.  See subsection “Drawing Commands” below.
1055
1056   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
1065       .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
1075       .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
1081       .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
1085       .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
1104       .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
1109                     .ta T .5i
1110
1111              sets tabs every half an inch.
1112
1113   New number registers
1114       The following read-only registers are available:
1115
1116       \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
1121                     .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
1129              Using this register outside of a macro makes no sense (it always
1130              returns zero in such cases).
1131
1132       \n[.C] 1 if compatibility mode is in effect, 0 otherwise.
1133
1134       \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
1138       \n[.ce]
1139              The  number  of lines remaining to be centered, as set by the ce
1140              request.
1141
1142       \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
1146       \n[.color]
1147              1 if colors are enabled, 0 otherwise.
1148
1149       \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
1154       \n[.ev]
1155              The  name  or  number  of  the  current  environment.  This is a
1156              string-valued register.
1157
1158       \n[.fam]
1159              The current font family.  This is a string-valued register.
1160
1161       \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
1166       \n[.fp]
1167              The number of the next free font position.
1168
1169       \n[.g] Always 1.  Macros should use this to determine whether they  are
1170              running under GNU troff.
1171
1172       \n[.height]
1173              The current height of the font as set with \H.
1174
1175       \n[.hla]
1176              The current hyphenation language as set by the hla request.
1177
1178       \n[.hlc]
1179              The  number  of  immediately  preceding  consecutive  hyphenated
1180              lines.
1181
1182       \n[.hlm]
1183              The maximum allowed number of consecutive hyphenated  lines,  as
1184              set by the hlm request.
1185
1186       \n[.hy]
1187              The current hyphenation flags (as set by the hy request).
1188
1189       \n[.hym]
1190              The current hyphenation margin (as set by the hym request).
1191
1192       \n[.hys]
1193              The current hyphenation space (as set by the hys request).
1194
1195       \n[.in]
1196              The indentation that applies to the current output line.
1197
1198       \n[.int]
1199              Set  to  a  positive  value  if  last output line is interrupted
1200              (i.e., if it contains \c).
1201
1202       \n[.kern]
1203              1 if pairwise kerning is enabled, 0 otherwise.
1204
1205       \n[.lg]
1206              The current ligature mode (as set by the lg request).
1207
1208       \n[.linetabs]
1209              The current line-tabs mode (as set by the linetabs request).
1210
1211       \n[.ll]
1212              The line length that applies to the current output line.
1213
1214       \n[.lt]
1215              The title length as set by the lt request.
1216
1217       \n[.m] The name of the current drawing color.  This is a  string-valued
1218              register.
1219
1220       \n[.M] The name of the current background color.  This is a string-val‐
1221              ued register.
1222
1223       \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
1228       \n[.ns]
1229              1 if no-space mode is active, 0 otherwise.
1230
1231       \n[.O] The current output level as set with \O.
1232
1233       \n[.P] 1 if the current page is in the output list set with -o.
1234
1235       \n[.pe]
1236              1 during a page ejection caused by the bp request, 0 otherwise.
1237
1238       \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
1242       \n[.ps]
1243              The current point size in scaled points.
1244
1245       \n[.psr]
1246              The last-requested point size in scaled points.
1247
1248       \n[.pvs]
1249              The  current  post-vertical  line  space as set with the pvs re‐
1250              quest.
1251
1252       \n[.rj]
1253              The number of lines to be right-justified as set by the  rj  re‐
1254              quest.
1255
1256       \n[.slant]
1257              The slant of the current font as set with \S.
1258
1259       \n[.sr]
1260              The  last  requested point size in points as a decimal fraction.
1261              This is a string-valued register.
1262
1263       \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
1268       \n[.sty]
1269              The current font style.  This is a string-valued register.
1270
1271       \n[.tabs]
1272              A string representation of the current tab settings suitable for
1273              use as an argument to the ta request.
1274
1275       \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
1284       \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
1287       \n[.vpt]
1288              1 if vertical position traps are enabled, 0 otherwise.
1289
1290       \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
1295       \n[.x] The major version number.  For example, if the version number is
1296              1.03, then \n[.x] contains 1.
1297
1298       \n[.y] The minor version number.  For example, if the version number is
1299              1.03, then \n[.y] contains 03.
1300
1301       \n[.Y] The revision number of groff.
1302
1303       \n[.zoom]
1304              The  zoom  value  of the current font, in multiples of 1/1000th.
1305              Zero if no magnification.
1306
1307       \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
1315       The following read/write registers are set by the \w escape sequence:
1316
1317       \n[rst]
1318       \n[rsb]
1319              Like the st and sb registers, but take account  of  the  heights
1320              and depths of glyphs.
1321
1322       \n[ssc]
1323              The  amount  of horizontal space (possibly negative) that should
1324              be added to the last glyph before a subscript.
1325
1326       \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
1331       Other available read/write number registers are:
1332
1333       \n[c.] The current input line number.  \n[.c] is a read-only  alias  to
1334              this register.
1335
1336       \n[hours]
1337              The number of hours past midnight.  Initialized at start-up.
1338
1339       \n[hp] The current horizontal position at input line.
1340
1341       \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
1347       \n[minutes]
1348              The number of minutes after the hour.  Initialized at start-up.
1349
1350       \n[seconds]
1351              The  number  of seconds after the minute.  Initialized at start-
1352              up.
1353
1354       \n[systat]
1355              The return value of the system() function executed by  the  last
1356              sy request.
1357
1358       \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
1364       \n[year]
1365              The current year.  Note that the traditional troff number regis‐
1366              ter \n[yr] is the current year minus 1900.
1367
1368   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
1376       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
1384       Interpolating a string does not hide existing macro arguments.  Thus in
1385       a macro, a more efficient way of doing
1386
1387              .xx \\$@
1388
1389       is
1390
1391              \\*[xx]\\
1392
1393       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
1397       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
1413       There are some new types of condition:
1414
1415       .if rxxx
1416              True if there is a number register named xxx.
1417
1418       .if dxxx
1419              True  if  there  is a string, macro, diversion, or request named
1420              xxx.
1421
1422       .if mxxx
1423              True if there is a color named xxx.
1424
1425       .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
1431       .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
1435       .if Ss True  if  style  s has been registered.  Font translation is ap‐
1436              plied.
1437
1438       The tr request can now map characters onto \~.
1439
1440       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
1445       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
1448              .if t \{\
1449              .  de bar
1450              .    nop Hello, I'm ‘bar’.
1451              .  .
1452              .\}
1453

INTERMEDIATE OUTPUT FORMAT

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
1459   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
1464   Text Commands
1465       Nn     Print glyph with index n (a non-negative integer) of the current
1466              font.
1467
1468       If  the  tcommand line is present in the DESC file, troff uses the fol‐
1469       lowing two commands.
1470
1471       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
1482       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
1486       Note  that  single  characters  can have the eighth bit set, as can the
1487       names of fonts and special characters.
1488
1489       The names of glyphs and fonts  can  be  of  arbitrary  length;  drivers
1490       should not assume that they are only two characters long.
1491
1492       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
1496       For color support, some new commands have been added:
1497
1498       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
1508       The x device control command has been extended.
1509
1510       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
1514   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
1518       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
1530              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
1534       DC d\n Draw a solid circle with a diameter of d with the leftmost point
1535              at the current position.
1536
1537       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
1542       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
1547       DP dx1 dy1 dx2 dy2 ... .lf 3510
1548              dxn dyn\n Like Dp but draw a solid rather than outlined polygon.
1549
1550       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
1557       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
1562              \D'c x1 y1 x2 y2 ... .lf 3543 xn yn'
1563
1564       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
1575              Dc x1 y1 x2 y2 ... .lf 3587 xn yn\n
1576
1577       the current position should be increased by (in=Σ1xi,in=Σ1yi).
1578
1579       Another set of extensions is
1580
1581       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
1589       The current position isn't changed by those colour  commands  (contrary
1590       to Df).
1591
1592   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
1603       The first three output commands are guaranteed to be:
1604
1605              x T device
1606              x res n h v
1607              x init
1608

INCOMPATIBILITIES

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
1615   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
1620       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
1624       This became necessary because the GNU concept  for  long  names  causes
1625       some incompatibilities.  Classical troff interprets
1626
1627              .dsabcd
1628
1629       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
1632       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
1636       In compatibility mode, groff interprets these things in the traditional
1637       way; so long names are not recognized.
1638
1639       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
1647       The  \A  escape  sequence  can  be helpful in avoiding these escape se‐
1648       quences in names.
1649
1650       Fractional point sizes cause one noteworthy incompatibility.  In  clas‐
1651       sical troff, the ps request ignores scale indicators and so
1652
1653              .ps 10u
1654
1655       sets  the  point  size  to  10 points, whereas in groff native mode the
1656       point size is set to 10 scaled points.
1657
1658       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
1664       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
1670       Special characters can be both; before being added to the output,  they
1671       act as input entities, afterwards they denote glyphs.
1672
1673       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
1678              .di x
1679              \\\\
1680              .br
1681              .di
1682              .x
1683
1684       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
1689       Classical  troff  would  interpret  them as escape characters when they
1690       were reread and would end up printing a single backslash ‘\’.
1691
1692       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
1703       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
1707   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
1713       • The positioning after the drawing of the polygons conflicts with  the
1714         classical definition.
1715
1716       • The  intermediate output cannot be rescaled to other devices as clas‐
1717         sical ‘device-independent’ troff did.
1718

AUTHORS

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

SEE ALSO

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
1729       groff(1)
1730              A list of all documentation around groff.
1731
1732       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
1738                     man 7 groff
1739
1740       roff(7)
1741              A survey of roff systems, including pointers to further histori‐
1742              cal documentation.
1743
1744       [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⟩.
1748
1749
1750
1751groff 1.22.4                     21 July 2022                    GROFF_DIFF(7)
Impressum