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       The  section SEE ALSO gives pointers to both the classical roff and the
16       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 the groff info file for
35              details how a glyph name for a composite glyph  is  constructed,
36              and  groff_char(7)  for  a list of glyph name components used in
37              composite glyph names.
38
39       \f[xxx]
40              Set font xxx.  Additionally, \f[] is a new syntax form equal  to
41              \fP, i.e., to return to the previous font.
42
43       \*[xxx arg1 arg2 ...]
44              Interpolate string xxx, taking arg1, arg2, ..., as arguments.
45
46       \n[xxx]
47              Interpolate number register xxx.
48
49   Fractional point sizes
50       A scaled point is equal to 1/sizescale points, where sizescale is spec‐
51       ified in the DESC file (1 by default).  There is a  new  scale  indica‐
52       tor  z  that  has the effect of multiplying by sizescale.  Requests and
53       escape sequences in troff interpret arguments that  represent  a  point
54       size  as  being  in units of scaled points, but they evaluate each such
55       argument using a default scale indicator of z.   Arguments  treated  in
56       this  way are the argument to the ps request, the third argument to the
57       cs request, the second and fourth arguments to  the  tkf  request,  the
58       argument to the \H escape sequence, and those variants of the \s escape
59       sequence that take a numeric expression as their argument.
60
61       For example, suppose sizescale is 1000; then a scaled point is  equiva‐
62       lent  to  a  millipoint; the call .ps 10.25 is equivalent to .ps 10.25z
63       and so sets the point size to 10250 scaled points, which  is  equal  to
64       10.25 points.
65
66       The  number register \n[.s] returns the point size in points as decimal
67       fraction.  There is also a new number register \n[.ps] that returns the
68       point size in scaled points.
69
70       It  would  make  no  sense  to  use  the z scale indicator in a numeric
71       expression whose default scale indicator was neither u nor  z,  and  so
72       troff  disallows this.  Similarly it would make no sense to use a scal‐
73       ing indicator other than z or u in a numeric expression  whose  default
74       scale indicator was z, and so troff disallows this as well.
75
76       There  is  also new scale indicator s which multiplies by the number of
77       units in a scaled point.  So, for example, \n[.ps]s is equal to 1m.  Be
78       sure not to confuse the s and z scale indicators.
79
80   Numeric expressions
81       Spaces are permitted in a number expression within parentheses.
82
83       M  indicates  a scale of 100ths of an em.  f indicates a scale of 65536
84       units, providing fractions for  color  definitions  with  the  defcolor
85       request.  For example, 0.5f = 32768u.
86
87       e1>?e2 The maximum of e1 and e2.
88
89       e1<?e2 The minimum of e1 and e2.
90
91       (c;e)  Evaluate  e  using  c as the default scaling indicator.  If c is
92              missing, ignore scaling indicators in the evaluation of e.
93
94   New escape sequences
95       \A'anything'
96              This expands to 1 or 0, depending on whether anything is  or  is
97              not acceptable as the name of a string, macro, diversion, number
98              register, environment, font, or color.  It returns 0 if anything
99              is  empty.   This is useful if you want to look up user input in
100              some sort of associative table.
101
102       \B'anything'
103              This expands to 1 or 0, depending on whether anything is  or  is
104              not  a  valid  numeric  expression.  It returns 0 if anything is
105              empty.
106
107       \C'xxx'
108              Typeset glyph named xxx.  Normally it is more convenient to  use
109              \[xxx].   But  \C  has  the advantage that it is compatible with
110              recent versions of UNIX and is available in compatibility mode.
111
112       \E     This is equivalent to an escape character, but it is not  inter‐
113              preted  in  copy  mode.   For  example, strings to start and end
114              superscripting could be defined like this
115
116                     .ds { \v'-.3m'\s'\En[.s]*6u/10u'
117                     .ds } \s0\v'.3m'
118
119              The use of \E ensures that these definitions work  even  if  \*{
120              gets  interpreted  in copy mode (for example, by being used in a
121              macro argument).
122
123       \Ff
124       \F(fm
125       \F[fam]
126              Change font family.  This is the same as the fam request.   \F[]
127              switches  back  to the previous font family (note that \FP won't
128              work; it selects font family ‘P’ instead).
129
130       \mx
131       \m(xx
132       \m[xxx]
133              Set drawing color.  \m[] switches back to the previous color.
134
135       \Mx
136       \M(xx
137       \M[xxx]
138              Set background color for filled objects drawn with  the  \D'...'
139              commands.  \M[] switches back to the previous color.
140
141       \N'n'  Typeset  the  glyph  with index n in the current font.  n can be
142              any integer.  Most devices only have glyphs with indices between
143              0  and  255.   If the current font does not contain a glyph with
144              that code, special  fonts  are  not  searched.   The  \N  escape
145              sequence  can  be conveniently used in conjunction with the char
146              request, for example
147
148                     .char \[phone] \f(ZD\N'37'
149
150              The index of each glyph is given in the  fourth  column  in  the
151              font description file after the charset command.  It is possible
152              to include unnamed glyphs in the font description file by  using
153              a  name  of  ---;  the \N escape sequence is the only way to use
154              these.
155
156       \On
157       \O[n]  Suppress troff output.  The escapes \O2, \O3, \O4, and  \O5  are
158              intended for internal use by grohtml.
159
160              \O0    Disable  any  ditroff  glyphs  from  being emitted to the
161                     device driver, provided that the  escape  occurs  at  the
162                     outer level (see \O3 and \O4).
163
164              \O1    Enable  output of glyphs, provided that the escape occurs
165                     at the outer level.
166
167                     \O0  and  \O1  also  reset  the   registers   \n[opminx],
168                     \n[opminy], \n[opmaxx], and \n[opmaxy] to -1.  These four
169                     registers mark the top left and bottom right hand corners
170                     of a box which encompasses all written glyphs.
171
172              \O2    Provided  that  the  escape  occurs  at  the outer level,
173                     enable output of glyphs and also write out to stderr  the
174                     page  number  and  four registers encompassing the glyphs
175                     previously written since the last call to \O.
176
177              \O3    Begin a nesting level.  At start-up, troff  is  at  outer
178                     level.   This is really an internal mechanism for grohtml
179                     while producing images.  They are  generated  by  running
180                     the  troff  source through troff to the postscript device
181                     and ghostscript to produce images in PNG format.  The \O3
182                     escape  starts  a  new page if the device is not html (to
183                     reduce the possibility of images crossing a  page  bound‐
184                     ary).
185
186              \O4    End a nesting level.
187
188              \O5[Pfilename]
189                     This  escape  is  grohtml  specific.   Provided that this
190                     escape occurs at the outer nesting level, write  filename
191                     to  stderr.  The position of the image, P, must be speci‐
192                     fied and must be one of l, r, c, or i (left, right,  cen‐
193                     tered,  inline).  filename is associated with the produc‐
194                     tion of the next inline image.
195
196       \R'name ±n'
197              This has the same effect as
198
199                     .nr name ±n
200
201       \s(nn
202       \s±(nn Set the point size to nn points; nn must be exactly two digits.
203
204       \s[±n]
205       \s±[n]
206       \s'±n'
207       \s±'n' Set the point size to n scaled points; n is a numeric expression
208              with a default scale indicator of z.
209
210       \Vx
211       \V(xx
212       \V[xxx]
213              Interpolate  the  contents  of  the environment variable xxx, as
214              returned by getenv(3).  \V is interpreted in copy mode.
215
216       \Yx
217       \Y(xx
218       \Y[xxx]
219              This is approximately equivalent to  \X'\*[xxx]'.   However  the
220              contents of the string or macro xxx are not interpreted; also it
221              is permitted for xxx to have been defined as a  macro  and  thus
222              contain  newlines (it is not permitted for the argument to \X to
223              contain newlines).  The inclusion of newlines requires an exten‐
224              sion  to the UNIX troff output format, and confuses drivers that
225              do not know about this extension.
226
227       \Z'anything'
228              Print anything and then  restore  the  horizontal  and  vertical
229              position; anything may not contain tabs or leaders.
230
231       \$0    The  name  by  which  the  current  macro  was invoked.  The als
232              request can make a macro have more than one name.
233
234       \$*    In a macro or string, the concatenation  of  all  the  arguments
235              separated by spaces.
236
237       \$@    In  a  macro  or  string, the concatenation of all the arguments
238              with each surrounded by double quotes, and separated by spaces.
239
240       \$^    In a macro, the representation of all parameters as if they were
241              an argument to the ds request.
242
243       \$(nn
244       \$[nnn]
245              In  a  macro or string, this gives the nn-th or nnn-th argument.
246              Macros and strings can have an unlimited number of arguments.
247
248       \?anything\?
249              When used in a diversion, this transparently embeds anything  in
250              the  diversion.  anything is read in copy mode.  When the diver‐
251              sion is reread, anything is interpreted.  anything may not  con‐
252              tain  newlines; use \! if you want to embed newlines in a diver‐
253              sion.  The escape sequence \? is also recognized  in  copy  mode
254              and  turned  into  a  single internal code; it is this code that
255              terminates anything.  Thus
256
257                     .nr x 1
258                     .nf
259                     .di d
260                     \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
261                     .di
262                     .nr x 2
263                     .di e
264                     .d
265                     .di
266                     .nr x 3
267                     .di f
268                     .e
269                     .di
270                     .nr x 4
271                     .f
272
273              prints 4.
274
275       \/     This increases the width of the  preceding  glyph  so  that  the
276              spacing between that glyph and the following glyph is correct if
277              the following glyph is a roman glyph.  It is a good idea to  use
278              this  escape  sequence  whenever  an italic glyph is immediately
279              followed by a roman glyph without any intervening space.
280
281       \,     This modifies the spacing of the following  glyph  so  that  the
282              spacing between that glyph and the preceding glyph is correct if
283              the preceding glyph is a roman glyph.  It is a good idea to  use
284              this  escape sequence whenever a roman glyph is immediately fol‐
285              lowed by an italic glyph without any intervening space.
286
287       \)     Like \& except that it behaves like a  character  declared  with
288              the cflags request to be transparent for the purposes of end-of-
289              sentence recognition.
290
291       \~     This produces an unbreakable space that stretches like a  normal
292              inter-word space when a line is adjusted.
293
294       \:     This  causes  the  insertion of a zero-width break point.  It is
295              equal to \% within a word but without insertion of a soft hyphen
296              glyph.
297
298       \#     Everything  up  to  and  including  the next newline is ignored.
299              This is interpreted in copy mode.  It is like \" except that  \"
300              does not ignore the terminating newline.
301
302   New requests
303       .aln xx yy
304              Create an alias xx for number register object named yy.  The new
305              name and the old name are exactly equivalent.  If  yy  is  unde‐
306              fined,  a  warning  of type reg is generated, and the request is
307              ignored.
308
309       .als xx yy
310              Create an alias xx for  request,  string,  macro,  or  diversion
311              object  named  yy.   The  new  name and the old name are exactly
312              equivalent (it is similar to a hard rather than  a  soft  link).
313              If  yy is undefined, a warning of type mac is generated, and the
314              request is ignored.  The de, am, di, da,  ds,  and  as  requests
315              only  create a new object if the name of the macro, diversion or
316              string is currently undefined or  if  it  is  defined  to  be  a
317              request; normally they modify the value of an existing object.
318
319       .am1 xx yy
320              Similar  to  .am,  but compatibility mode is switched off during
321              execution.  To be more precise, a ‘compatibility save’ token  is
322              inserted at the beginning of the macro addition, and a ‘compati‐
323              bility restore’  token  at  the  end.   As  a  consequence,  the
324              requests am, am1, de, and de1 can be intermixed freely since the
325              compatibility save/restore tokens only affect  the  macro  parts
326              defined by .am1 and .ds1.
327
328       .ami xx yy
329              Append  to macro indirectly.  See the dei request below for more
330              information.
331
332       .ami1 xx yy
333              Same as the ami request but compatibility mode is  switched  off
334              during execution.
335
336       .as1 xx yy
337              Similar  to  .as,  but compatibility mode is switched off during
338              expansion.  To be more precise, a ‘compatibility save’ token  is
339              inserted  at  the  beginning of the string, and a ‘compatibility
340              restore’ token at the end.  As a consequence, the  requests  as,
341              as1,  ds, and ds1 can be intermixed freely since the compatibil‐
342              ity save/restore tokens only affect the (sub)strings defined  by
343              as1 and ds1.
344
345       .asciify xx
346              This  request  ‘unformats’  the  diversion xx in such a way that
347              ASCII and space characters (and some escape sequences) that were
348              formatted  and  diverted into xx are treated like ordinary input
349              characters when xx is reread.  Useful for diversions in conjunc‐
350              tion  with  the  writem  request.  It can be also used for gross
351              hacks; for example, this
352
353                     .tr @.
354                     .di x
355                     @nr n 1
356                     .br
357                     .di
358                     .tr @@
359                     .asciify x
360                     .x
361
362              sets register n to 1.  Note that glyph information  (font,  font
363              size, etc.) is not preserved; use .unformat instead.
364
365       .backtrace
366              Print a backtrace of the input stack on stderr.
367
368       .blm xx
369              Set the blank line macro to xx.  If there is a blank line macro,
370              it is invoked when a blank line is encountered  instead  of  the
371              usual troff behaviour.
372
373       .box xx
374       .boxa xx
375              These  requests  are  similar to the di and da requests with the
376              exception that a partially filled line does not become  part  of
377              the  diversion  (i.e.,  the  diversion  always starts with a new
378              line) but is restored after ending the diversion, discarding the
379              partially filled line which possibly comes from the diversion.
380
381       .break Break  out  of  a  while  loop.  See also the while and continue
382              requests.  Be sure not to confuse this with the br request.
383
384       .brp   This is the same as \p.
385
386       .cflags n c1 c2 ...
387              Characters c1, c2, ..., have properties determined by  n,  which
388              is ORed from the following:
389
390              1      The  character  ends  sentences (initially characters .?!
391                     have this property).
392
393              2      Lines can be broken before the  character  (initially  no
394                     characters have this property); a line is not broken at a
395                     character with this property  unless  the  characters  on
396                     each side both have non-zero hyphenation codes.  This can
397                     be overridden with value 64.
398
399              4      Lines can be broken after the character (initially  char‐
400                     acters  -\[hy]\[em]  have  this  property); a line is not
401                     broken at a character with this property unless the char‐
402                     acters on each side both have non-zero hyphenation codes.
403                     This can be overridden with value 64.
404
405              8      The glyph associated with this character  overlaps  hori‐
406                     zontally   (initially  characters  \[ul]\[rn]\[ru]\[radi‐
407                     calex]\[sqrtex] have this property).
408
409              16     The glyph associated with this character overlaps  verti‐
410                     cally (initially glyph \[br] has this property).
411
412              32     An  end-of-sentence  character  followed by any number of
413                     characters with this property is treated as the end of  a
414                     sentence if followed by a newline or two spaces; in other
415                     words the character is transparent for  the  purposes  of
416                     end-of-sentence recognition; this is the same as having a
417                     zero  space   factor   in   TeX   (initially   characters
418                     "')]*\[dg]\[rq]\[cq] have this property).
419
420              64     Ignore hyphenation code values of the surrounding charac‐
421                     ters.  Use this in combination with values 2 and 4  (ini‐
422                     tially no characters have this property).
423
424              128    Prohibit  a  line break before the character, but allow a
425                     line break after the character.  This works only in  com‐
426                     bination  with flags 256 and 512 and has no effect other‐
427                     wise.
428
429              256    Prohibit a line break after the character,  but  allow  a
430                     line break before the character.  This works only in com‐
431                     bination with flags 128 and 512 and has no effect  other‐
432                     wise.
433
434              512    Allow  line  break  before  or after the character.  This
435                     works only in combination with flags 128 and 256 and  has
436                     no effect otherwise.
437
438              Contrary  to  flag  values  2 and 4, the flags 128, 256, and 512
439              work pairwise.  If, for example, the left  character  has  value
440              512,  and  the right character 128, no line break gets inserted.
441              If we use value 6 instead for the left character, a  line  break
442              after  the  character can't be suppressed since the right neigh‐
443              bour character doesn't get examined.
444
445       .char c string
446              [This request can both define characters and glyphs.]
447
448              Define entity c to be string.  To be more  precise,  define  (or
449              even  override) a groff entity which can be accessed with name c
450              on the input side, and which uses string  on  the  output  side.
451              Every time glyph c needs to be printed, string is processed in a
452              temporary environment and the result is wrapped up into a single
453              object.  Compatibility mode is turned off and the escape charac‐
454              ter is set to \ while string is being processed.  Any  embolden‐
455              ing, constant spacing or track kerning is applied to this object
456              rather than to individual glyphs in string.
457
458              A groff object defined by this request can be used just  like  a
459              normal glyph provided by the output device.  In particular other
460              characters can be translated to it with the tr request;  it  can
461              be  made  the  leader glyph by the lc request; repeated patterns
462              can be  drawn  with  the  glyph  using  the  \l  and  \L  escape
463              sequences;  words  containing  c can be hyphenated correctly, if
464              the hcode request is used to give the object a hyphenation code.
465
466              There is a special anti-recursion feature: Use of  glyph  within
467              the glyph's definition is handled like normal glyphs not defined
468              with char.
469
470              A glyph definition can be removed with the rchar request.
471
472       .chop xx
473              Chop the last element off macro, string, or diversion xx.   This
474              is  useful  for  removing the newline from the end of diversions
475              that are to be interpolated as strings.
476
477       .class name c1 c2 ...
478              Assign name to a set of characters c1, c2, ..., so that they can
479              be  referred  to  from  other requests easily (currently .cflags
480              only).  Character ranges (indicated by an intermediate ‘-’)  and
481              nested  classes  are  possible  also.   This is useful to assign
482              properties to a large set of characters.
483
484       .close stream
485              Close the stream named stream;  stream  will  no  longer  be  an
486              acceptable argument to the write request.  See the open request.
487
488       .composite glyph1 glyph2
489              Map  glyph  name  glyph1  to  glyph name glyph2 if it is used in
490              \[...] with more than one component.
491
492       .continue
493              Finish the current iteration of a  while  loop.   See  also  the
494              while and break requests.
495
496       .color n
497              If  n  is  non-zero  or  missing,  enable  colors  (this  is the
498              default), otherwise disable them.
499
500       .cp n  If n is non-zero or missing, enable compatibility  mode,  other‐
501              wise disable it.  In compatibility mode, long names are not rec‐
502              ognized, and the incompatibilities caused by long names  do  not
503              arise.
504
505       .defcolor xxx scheme color_components
506              Define  color  xxx.   scheme can be one of the following values:
507              rgb (three components), cmy (three components), cmyk (four  com‐
508              ponents),  and  gray  or grey (one component).  Color components
509              can be given either as a hexadecimal string or as positive deci‐
510              mal  integers  in  the range 0–65535.  A hexadecimal string con‐
511              tains all color components  concatenated;  it  must  start  with
512              either  #  or  ##.  The former specifies hex values in the range
513              0–255 (which are internally multiplied by 257),  the  latter  in
514              the  range  0–65535.   Examples:  #FFC0CB (pink), ##ffff0000ffff
515              (magenta).  A new scaling indicator f has been introduced  which
516              multiplies its value by 65536; this makes it convenient to spec‐
517              ify color components as fractions in the range 0 to 1.  Example:
518
519                     .defcolor darkgreen rgb 0.1f 0.5f 0.2f
520
521              Note that f is the default scaling indicator  for  the  defcolor
522              request, thus the above statement is equivalent to
523
524                     .defcolor darkgreen rgb 0.1 0.5 0.2
525
526              The  color  named  default  (which  is device-specific) can't be
527              redefined.  It is possible that the default color for \M and  \m
528              is not the same.
529
530       .de1 xx yy
531              Similar  to  .de,  but compatibility mode is switched off during
532              execution.  On entry, the current compatibility  mode  is  saved
533              and restored at exit.
534
535       .dei xx yy
536              Define macro indirectly.  The following example
537
538                     .ds xx aa
539                     .ds yy bb
540                     .dei xx yy
541
542              is equivalent to
543
544                     .de aa bb
545
546       .dei1 xx yy
547              Similar  to  the  dei request but compatibility mode is switched
548              off during execution.
549
550       .device anything
551              This is (almost) the same as the \X escape.  anything is read in
552              copy mode; a leading " is stripped.
553
554       .devicem xx
555              This  is  the  same as the \Y escape (to embed the contents of a
556              macro into the intermediate output preceded with ‘x X’).
557
558       .do xxx
559              Interpret .xxx with compatibility mode disabled.  For example,
560
561                     .do fam T
562
563              would have the same effect as
564
565                     .fam T
566
567              except that it would work even if compatibility  mode  had  been
568              enabled.   Note that the previous compatibility mode is restored
569              before any files sourced by xxx are interpreted.
570
571       .ds1 xx yy
572              Similar to .ds, but compatibility mode is  switched  off  during
573              expansion.   To be more precise, a ‘compatibility save’ token is
574              inserted at the beginning of the string,  and  a  ‘compatibility
575              restore’ token at the end.
576
577       .ecs   Save current escape character.
578
579       .ecr   Restore  escape  character  saved  with ecs.  Without a previous
580              call to ecs, ‘\’ will be the new escape character.
581
582       .evc xx
583              Copy the contents of environment xx to the current  environment.
584              No pushing or popping of environments is done.
585
586       .fam xx
587              Set  the  current font family to xx.  The current font family is
588              part of the current environment.  If xx is missing, switch  back
589              to previous font family.  The value at start-up is ‘T’.  See the
590              description of the sty request for more information on font fam‐
591              ilies.
592
593       .fchar c string
594              Define fallback character (or glyph) c to be string.  The syntax
595              of this request is the same as the char request; the  only  dif‐
596              ference  is  that a glyph defined with char hides the glyph with
597              the same name in the current font, whereas a glyph defined  with
598              fchar is checked only if the particular glyph isn't found in the
599              current font.  This test happens before checking special fonts.
600
601       .fcolor c
602              Set the fill color to c.  If c is missing, switch to the  previ‐
603              ous fill color.
604
605       .fschar f c string
606              Define  fallback character (or glyph) c for font f to be string.
607              The syntax of this request is the same as the char request (with
608              an  additional  argument  to  specify the font); a glyph defined
609              with fschar is searched after the list of  fonts  declared  with
610              the  fspecial request but before the list of fonts declared with
611              .special.
612
613       .fspecial f s1 s2 ...
614              When the current font is f, fonts s1, s2, ..., are special, that
615              is,  they  are searched for glyphs not in the current font.  Any
616              fonts specified in the special request are searched after  fonts
617              specified  in the fspecial request.  Without argument, reset the
618              list of global special fonts to be empty.
619
620       .ftr f g
621              Translate font f to g.  Whenever a font named f is  referred  to
622              in  an \f escape sequence, in the F and S conditional operators,
623              or in the ft, ul, bd, cs, tkf, special,  fspecial,  fp,  or  sty
624              requests,  font  g is used.  If g is missing, or equal to f then
625              font f is not translated.
626
627       .fzoom f zoom
628              Set zoom factor zoom for font f.  zoom must a non-negative inte‐
629              ger multiple of 1/1000th.  If it is missing or is equal to zero,
630              it means the same as 1000, namely no magnification.  f must be a
631              real font name, not a style.
632
633       .gcolor c
634              Set the glyph color to c.  If c is missing, switch to the previ‐
635              ous glyph color.
636
637       .hcode c1 code1 c2 code2 ...
638              Set the hyphenation code of character c1 to code1 and that of c2
639              to  code2, and so on.  A hyphenation code must be a single input
640              character (not a special character) other  than  a  digit  or  a
641              space.   Initially  each lower-case letter a–z has a hyphenation
642              code, which is itself, and each  upper-case  letter  A–Z  has  a
643              hyphenation code which is the lower-case version of itself.  See
644              also the hpf request.
645
646       .hla lang
647              Set the  current  hyphenation  language  to  lang.   Hyphenation
648              exceptions  specified  with  the hw request and hyphenation pat‐
649              terns specified with the hpf request are  both  associated  with
650              the  current  hyphenation  language.  The hla request is usually
651              invoked by the troffrc file to set up a default language.
652
653       .hlm n Set the maximum number of consecutive hyphenated lines to n.  If
654              n  is  negative,  there is no maximum.  The default value is -1.
655              This value is associated with  the  current  environment.   Only
656              lines output from an environment count towards the maximum asso‐
657              ciated with that environment.  Hyphens  resulting  from  \%  are
658              counted; explicit hyphens are not.
659
660       .hpf file
661              Read hyphenation patterns from file; this is searched for in the
662              same way that name.tmac is searched for when the  -mname  option
663              is  specified.   It  should have the same format as (simple) TeX
664              patterns files.  More specifically, the following scanning rules
665              are implemented.
666
667              ·      A  percent  sign  starts  a comment (up to the end of the
668                     line) even if preceded by a backslash.
669
670              ·      No support for ‘digraphs’ like \$.
671
672              ·      ^^xx (x is 0–9 or a–f) and ^^x (character code  of  x  in
673                     the range 0–127) are recognized; other use of ^ causes an
674                     error.
675
676              ·      No macro expansion.
677
678              ·      hpf checks for the  expression  \patterns{...}  (possibly
679                     with whitespace before and after the braces).  Everything
680                     between the braces  is  taken  as  hyphenation  patterns.
681                     Consequently, { and } are not allowed in patterns.
682
683              ·      Similarly,  \hyphenation{...} gives a list of hyphenation
684                     exceptions.
685
686              ·      \endinput is recognized also.
687
688              ·      For backwards compatibility, if \patterns is missing, the
689                     whole  file  is treated as a list of hyphenation patterns
690                     (only recognizing the % character as the start of a  com‐
691                     ment).
692
693              Use  the hpfcode request to map the encoding used in hyphenation
694              patterns files to groff's input encoding.   By  default,  every‐
695              thing  maps to itself except letters ‘A’ to ‘Z’ which map to ‘a’
696              to ‘z’.
697
698              The set of hyphenation patterns is associated with  the  current
699              language  set  by  the  hla request.  The hpf request is usually
700              invoked by the troffrc file; a second call replaces the old pat‐
701              terns with the new ones.
702
703       .hpfa file
704              The  same  as hpf except that the hyphenation patterns from file
705              are appended to the patterns already loaded in the current  lan‐
706              guage.
707
708       .hpfcode a b c d ...
709              After  reading  a hyphenation patterns file with the hpf or hpfa
710              request, convert all characters with character  code  a  in  the
711              recently  read  patterns  to  character code b, character code c
712              to d, etc.  Initially, all character codes  map  to  themselves.
713              The arguments of hpfcode must be integers in the range 0 to 255.
714              Note that it is even possible to use character codes  which  are
715              invalid in groff otherwise.
716
717       .hym n Set  the  hyphenation  margin  to n: when the current adjustment
718              mode is not b, the line is not hyphenated if the line is no more
719              than n short.  The default hyphenation margin is 0.  The default
720              scaling indicator for this request is m.  The hyphenation margin
721              is associated with the current environment.  The current hyphen‐
722              ation margin is available in the \n[.hym] register.
723
724       .hys n Set the hyphenation space to n: When the current adjustment mode
725              is  b  don't  hyphenate the line if the line can be justified by
726              adding no more than n extra  space  to  each  word  space.   The
727              default  hyphenation  space is 0.  The default scaling indicator
728              for this request is m.  The hyphenation space is associated with
729              the  current  environment.   The  current  hyphenation  space is
730              available in the \n[.hys] register.
731
732       .itc n macro
733              Variant of .it for which a line interrupted with  \c  counts  as
734              one input line.
735
736       .kern n
737              If  n is non-zero or missing, enable pairwise kerning, otherwise
738              disable it.
739
740       .length xx string
741              Compute the length of string and return it in the number  regis‐
742              ter xx (which is not necessarily defined before).
743
744       .linetabs n
745              If  n  is  non-zero or missing, enable line-tabs mode, otherwise
746              disable it (which is the default).  In line-tabs mode, tab  dis‐
747              tances are computed relative to the (current) output line.  Oth‐
748              erwise they are taken relative to the input line.  For  example,
749              the following
750
751                     .ds x a\t\c
752                     .ds y b\t\c
753                     .ds z c
754                     .ta 1i 3i
755                     \*x
756                     \*y
757                     \*z
758
759              yields
760
761                     a         b         c
762
763              In line-tabs mode, the same code gives
764
765                     a         b                   c
766
767              Line-tabs  mode  is associated with the current environment; the
768              read-only number register \n[.linetabs] is set to 1 if in  line-
769              tabs mode, and 0 otherwise.
770
771       .lsm xx
772              Set the leading spaces macro to xx.  If there are leading spaces
773              in an input line, it is invoked instead of the usual  troff  be‐
774              haviour;  the leading spaces are removed.  Registers \n[lsn] and
775              \n[lss] hold the number of removed leading spaces and the corre‐
776              sponding horizontal space, respectively.
777
778       .mso file
779              The  same  as the so request except that file is searched for in
780              the same directories as macro files for the the -m command  line
781              option.   If the file name to be included has the form name.tmac
782              and it isn't found, mso tries to include tmac.name  instead  and
783              vice  versa.   A warning of type file is generated if file can't
784              be loaded, and the request is ignored.
785
786       .nop anything
787              Execute anything.  This is similar to ‘.if 1’.
788
789       .nroff Make the n built-in condition true and the t built-in  condition
790              false.  This can be reversed using the troff request.
791
792       .open stream filename
793              Open  filename for writing and associate the stream named stream
794              with it.  See also the close and write requests.
795
796       .opena stream filename
797              Like open, but if filename exists, append to it instead of trun‐
798              cating it.
799
800       .output string
801              Emit  string  directly  to  the  intermediate output (subject to
802              copy-mode interpretation); this is similar to \! used at the top
803              level.   An  initial  double  quote in string is stripped off to
804              allow initial blanks.
805
806       .pev   Print the current environment and each defined environment state
807              on stderr.
808
809       .pnr   Print  the  names  and  contents of all currently defined number
810              registers on stderr.
811
812       .psbb filename
813              Get the bounding box of a PostScript image filename.  This  file
814              must  conform  to  Adobe's Document Structuring Conventions; the
815              command looks for a %%BoundingBox comment to extract the  bound‐
816              ing  box  values.   After a successful call, the coordinates (in
817              PostScript units) of the lower left and upper right  corner  can
818              be  found  in  the  registers  \n[llx],  \n[lly],  \n[urx],  and
819              \n[ury], respectively.  If some error  has  occurred,  the  four
820              registers are set to zero.
821
822       .pso command
823              This  behaves  like  the so request except that input comes from
824              the standard output of command.
825
826       .ptr   Print the names and positions of all traps (not including  input
827              line  traps  and diversion traps) on stderr.  Empty slots in the
828              page trap list are printed as well, because they can affect  the
829              priority of subsequently planted traps.
830
831       .pvs ±n
832              Set  the  post-vertical line space to n; default scale indicator
833              is p.  This value is added to each line after it has  been  out‐
834              put.   With  no argument, the post-vertical line space is set to
835              its previous value.
836
837              The total vertical line spacing consists of four components: .vs
838              and  \x  with a negative value which are applied before the line
839              is output, and .pvs and \x  with  a  positive  value  which  are
840              applied after the line is output.
841
842       .rchar c1 c2 ...
843              Remove  the  definitions  of  glyphs c1, c2, ... This undoes the
844              effect of a char request.
845
846       .return
847              Within a macro, return immediately.  If called with an argument,
848              return  twice,  namely from the current macro and from the macro
849              one level higher.  No effect otherwise.
850
851       .rfschar c1 c2 ...
852              Remove the font-specific definitions of glyphs c1, c2, ...  This
853              undoes the effect of a fschar request.
854
855       .rj
856       .rj n  Right justify the next n input lines.  Without an argument right
857              justify the next input line.  The number of lines  to  be  right
858              justified is available in the \n[.rj] register.  This implicitly
859              does .ce 0.  The ce request implicitly does .rj 0.
860
861       .rnn xx yy
862              Rename number register xx to yy.
863
864       .schar c string
865              Define global fallback character (or glyph) c to be string.  The
866              syntax  of this request is the same as the char request; a glyph
867              defined with schar is searched after the list of fonts  declared
868              with the special request but before the mounted special fonts.
869
870       .shc c Set  the  soft hyphen character to c.  If c is omitted, the soft
871              hyphen character is set to the default \[hy].  The  soft  hyphen
872              character  is the glyph which is inserted when a word is hyphen‐
873              ated at a line break.  If the soft  hyphen  character  does  not
874              exist in the font of the glyph immediately preceding a potential
875              break point, then the line is not broken at that point.  Neither
876              definitions  (specified  with the char request) nor translations
877              (specified with the tr request) are considered when finding  the
878              soft hyphen character.
879
880       .shift n
881              In  a  macro,  shift  the  arguments  by n positions: argument i
882              becomes argument i-n; arguments 1 to n are no longer  available.
883              If  n is missing, arguments are shifted by 1.  Shifting by nega‐
884              tive amounts is currently undefined.
885
886       .sizes s1 s2 ... sn [0]
887              This command is similar to the sizes command of a DESC file.  It
888              sets  the  available  font sizes for the current font to s1, s2,
889              ..., sn scaled points.  The list of sizes can be  terminated  by
890              an  optional 0.  Each si can also be a range of sizes mn.  Con‐
891              trary to the font file command, the list can't extend over  more
892              than a single line.
893
894       .special s1 s2 ...
895              Fonts  s1,  s2, ..., are special and are searched for glyphs not
896              in the current font.  Without arguments, reset the list of  spe‐
897              cial fonts to be empty.
898
899       .spreadwarn limit
900              Make  troff  emit a warning if the additional space inserted for
901              each space between words in an output line is larger or equal to
902              limit.  A negative value is changed to zero; no argument toggles
903              the warning on and off  without  changing  limit.   The  default
904              scaling  indicator is m.  At startup, spreadwarn is deactivated,
905              and limit is set to 3m.  For example, .spreadwarn 0.2m causes  a
906              warning  if troff must add 0.2m or more for each interword space
907              in a line.  This request is active only if text is justified  to
908              both margins (using .ad b).
909
910       .sty n f
911              Associate  style f with font position n.  A font position can be
912              associated either with a font or with a style.  The current font
913              is  the index of a font position and so is also either a font or
914              a style.  When it is a style, the font that is actually used  is
915              the  font  the name of which is the concatenation of the name of
916              the current family and the name of the current style.  For exam‐
917              ple,  if the current font is 1 and font position 1 is associated
918              with style R and the current font family is T, then font  TR  is
919              used.  If the current font is not a style, then the current fam‐
920              ily is ignored.  When the requests cs, bd, tkf, uf, or  fspecial
921              are  applied  to  a  style, then they are applied instead to the
922              member of the current family corresponding to that  style.   The
923              default  family can be set with the -f command line option.  The
924              styles command in the DESC file controls  which  font  positions
925              (if any) are initially associated with styles rather than fonts.
926
927       .substring xx n1 [n2]
928              Replace  the  string  named xx with the substring defined by the
929              indices n1 and n2.   The  first  character  in  the  string  has
930              index  0.   If  n2  is  omitted,  it is taken to be equal to the
931              string's length.  If the index value n1 or n2 is negative, it is
932              counted  from  the  end of the string, going backwards: The last
933              character has index -1, the character before the last  character
934              has index -2, etc.
935
936       .tkf f s1 n1 s2 n2
937              Enable track kerning for font f.  When the current font is f the
938              width of every glyph is increased by an amount  between  n1  and
939              n2;  when the current point size is less than or equal to s1 the
940              width is increased by n1; when it is greater than or equal to s2
941              the  width  is  increased  by n2; when the point size is greater
942              than or equal to s1 and less than or equal to s2 the increase in
943              width is a linear function of the point size.
944
945       .tm1 string
946              Similar to the tm request, string is read in copy mode and writ‐
947              ten on the standard error, but an initial double quote in string
948              is stripped off to allow initial blanks.
949
950       .tmc string
951              Similar to tm1 but without writing a final newline.
952
953       .trf filename
954              Transparently  output  the contents of file filename.  Each line
955              is output as if preceded by \!; however, the lines are not  sub‐
956              ject to copy-mode interpretation.  If the file does not end with
957              a newline, then a newline is added.  For example, you can define
958              a macro x containing the contents of file f, using
959
960                     .di x
961                     .trf f
962                     .di
963
964              Unlike  with  the cf request, the file cannot contain characters
965              such as NUL that are not valid troff input characters.
966
967       .trin abcd
968              This is the same as the  tr  request  except  that  the  asciify
969              request  uses  the  character code (if any) before the character
970              translation.  Example:
971
972                     .trin ax
973                     .di xxx
974                     a
975                     .br
976                     .di
977                     .xxx
978                     .trin aa
979                     .asciify xxx
980                     .xxx
981
982              The result is x a.  Using tr, the result would be x x.
983
984       .trnt abcd
985              This is the same as the tr request except that the  translations
986              do  not  apply  to  text that is transparently throughput into a
987              diversion with \!.  For example,
988
989                     .tr ab
990                     .di x
991                     \!.tm a
992                     .di
993                     .x
994
995              prints b; if trnt is used instead of tr it prints a.
996
997       .troff Make the n built-in condition false, and the t  built-in  condi‐
998              tion true.  This undoes the effect of the nroff request.
999
1000       .unformat xx
1001              This  request  ‘unformats’  the  diversion  xx.  Contrary to the
1002              asciify request, which tries to convert  formatted  elements  of
1003              the  diversion back to input tokens as much as possible, .unfor‐
1004              mat only handles tabs and spaces between words  (usually  caused
1005              by  spaces  or newlines in the input) specially.  The former are
1006              treated as if  they  were  input  tokens,  and  the  latter  are
1007              stretchable  again.  Note that the vertical size of lines is not
1008              preserved.  Glyph information (font,  font  size,  space  width,
1009              etc.)  is retained.  Useful in conjunction with the box and boxa
1010              requests.
1011
1012       .vpt n Enable vertical position traps if n is  non-zero,  disable  them
1013              otherwise.   Vertical  position traps are traps set by the wh or
1014              dt requests.  Traps set by the it request are not vertical posi‐
1015              tion  traps.  The parameter that controls whether vertical posi‐
1016              tion traps are enabled is global.  Initially  vertical  position
1017              traps are enabled.
1018
1019       .warn n
1020              Control  warnings.   n is the sum of the numbers associated with
1021              each warning that is to be enabled; all other warnings are  dis‐
1022              abled.   The  number  associated  with each warning is listed in
1023              troff(1).  For example,  .warn  0  disables  all  warnings,  and
1024              .warn  1 disables all warnings except that about missing glyphs.
1025              If n is not given, all warnings are enabled.
1026
1027       .warnscale si
1028              Set the scaling indicator used in warnings to si.  Valid  values
1029              for si are u, i, c, p, and P.  At startup, it is set to i.
1030
1031       .while c anything
1032              While  condition  c  is true, accept anything as input; c can be
1033              any condition acceptable to an if request; anything can comprise
1034              multiple  lines  if  the  first line starts with \{ and the last
1035              line ends with \}.  See also the break and continue requests.
1036
1037       .write stream anything
1038              Write anything to the stream named stream.  stream  must  previ‐
1039              ously  have  been  the  subject of an open request.  anything is
1040              read in copy mode; a leading " is stripped.
1041
1042       .writec stream anything
1043              Similar to write but without writing a final newline.
1044
1045       .writem stream xx
1046              Write the contents of the macro or string xx to the stream named
1047              stream.  stream must previously have been the subject of an open
1048              request.  xx is read in copy mode.
1049
1050   Extended escape sequences
1051       \D'...'
1052              All  drawing  commands  of  groff's  intermediate   output   are
1053              accepted.  See subsection Drawing Commands below for more infor‐
1054              mation.
1055
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’
1072              token at the end, with compatibility  mode  switched  on  during
1073              execution.
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       .ss m n
1082              When two arguments are given to the ss request, the second argu‐
1083              ment gives the sentence space size.  If the second  argument  is
1084              not given, the sentence space size is the same as the word space
1085              size.  Like the word space size, the sentence space is in  units
1086              of one twelfth of the spacewidth parameter for the current font.
1087              Initially both the word space size and the sentence  space  size
1088              are  12.  Contrary to UNIX troff, GNU troff handles this request
1089              in nroff mode also; a given value is then rounded  down  to  the
1090              nearest  multiple of 12.  The sentence space size is used in two
1091              circumstances.  If the end of a sentence occurs at the end of  a
1092              line  in fill mode, then both an inter-word space and a sentence
1093              space are added; if two spaces follow the end of a  sentence  in
1094              the middle of a line, then the second space is a sentence space.
1095              Note that the behaviour of UNIX troff are exactly that exhibited
1096              by  GNU  troff  if  a  second  argument is never given to the ss
1097              request.  In GNU troff, as in UNIX troff, you should always fol‐
1098              low a sentence with either a newline or two spaces.
1099
1100       .ta n1 n2 ... nn T r1 r2 ... rn
1101              Set  tabs  at  positions  n1,  n2,  ..., nn and then set tabs at
1102              nn+r1, nn+r2, ..., nn+rn and then at  nn+rn+r1,  nn+rn+r2,  ...,
1103              nn+rn+rn, and so on.  For example,
1104
1105                     .ta T .5i
1106
1107              sets tabs every half an inch.
1108
1109   New number registers
1110       The following read-only registers are available:
1111
1112       \n[.br]
1113              Within  a macro call, it is set to 1 if the macro is called with
1114              the ‘normal’ control character (‘.’ by default), and  set  to  0
1115              otherwise.  This allows to reliably modify requests.
1116
1117                     .als bp*orig bp
1118                     .de bp
1119                     .tm before bp
1120                     .ie \\n[.br] .bp*orig
1121                     .el 'bp*orig
1122                     .tm after bp
1123                     ..
1124
1125              Using this register outside of a macro makes no sense (it always
1126              returns zero in such cases).
1127
1128       \n[.C] 1 if compatibility mode is in effect, 0 otherwise.
1129
1130       \n[.cdp]
1131              The depth of the last glyph added to  the  current  environment.
1132              It is positive if the glyph extends below the baseline.
1133
1134       \n[.ce]
1135              The  number  of lines remaining to be centered, as set by the ce
1136              request.
1137
1138       \n[.cht]
1139              The height of the last glyph added to the  current  environment.
1140              It is positive if the glyph extends above the baseline.
1141
1142       \n[.color]
1143              1 if colors are enabled, 0 otherwise.
1144
1145       \n[.csk]
1146              The  skew  of  the  last glyph added to the current environment.
1147              The skew of a glyph is how far to the right of the center  of  a
1148              glyph the center of an accent over that glyph should be placed.
1149
1150       \n[.ev]
1151              The  name  or  number  of  the  current  environment.  This is a
1152              string-valued register.
1153
1154       \n[.fam]
1155              The current font family.  This is a string-valued register.
1156
1157       \n[.fn]
1158              The current (internal) real font name.  This is a  string-valued
1159              register.   If the current font is a style, the value of \n[.fn]
1160              is the proper concatenation of family and style name.
1161
1162       \n[.fp]
1163              The number of the next free font position.
1164
1165       \n[.g] Always 1.  Macros should use this to determine whether they  are
1166              running under GNU troff.
1167
1168       \n[.height]
1169              The current height of the font as set with \H.
1170
1171       \n[.hla]
1172              The current hyphenation language as set by the hla request.
1173
1174       \n[.hlc]
1175              The  number  of  immediately  preceding  consecutive  hyphenated
1176              lines.
1177
1178       \n[.hlm]
1179              The maximum allowed number of consecutive hyphenated  lines,  as
1180              set by the hlm request.
1181
1182       \n[.hy]
1183              The current hyphenation flags (as set by the hy request).
1184
1185       \n[.hym]
1186              The current hyphenation margin (as set by the hym request).
1187
1188       \n[.hys]
1189              The current hyphenation space (as set by the hys request).
1190
1191       \n[.in]
1192              The indentation that applies to the current output line.
1193
1194       \n[.int]
1195              Set  to  a  positive  value  if  last output line is interrupted
1196              (i.e., if it contains \c).
1197
1198       \n[.kern]
1199              1 if pairwise kerning is enabled, 0 otherwise.
1200
1201       \n[.lg]
1202              The current ligature mode (as set by the lg request).
1203
1204       \n[.linetabs]
1205              The current line-tabs mode (as set by the linetabs request).
1206
1207       \n[.ll]
1208              The line length that applies to the current output line.
1209
1210       \n[.lt]
1211              The title length as set by the lt request.
1212
1213       \n[.m] The name of the current drawing color.  This is a  string-valued
1214              register.
1215
1216       \n[.M] The name of the current background color.  This is a string-val‐
1217              ued register.
1218
1219       \n[.ne]
1220              The amount of space that was needed in the last ne request  that
1221              caused  a  trap  to  be  sprung.  Useful in conjunction with the
1222              \n[.trunc] register.
1223
1224       \n[.ns]
1225              1 if no-space mode is active, 0 otherwise.
1226
1227       \n[.O] The current output level as set with \O.
1228
1229       \n[.P] 1 if the current page is in the output list set with -o.
1230
1231       \n[.pe]
1232              1 during a page ejection caused by the bp request, 0 otherwise.
1233
1234       \n[.pn]
1235              The number of the next page,  either  the  value  set  by  a  pn
1236              request, or the number of the current page plus 1.
1237
1238       \n[.ps]
1239              The current point size in scaled points.
1240
1241       \n[.psr]
1242              The last-requested point size in scaled points.
1243
1244       \n[.pvs]
1245              The  current  post-vertical  line  space  as  set  with  the pvs
1246              request.
1247
1248       \n[.rj]
1249              The number of lines to be  right-justified  as  set  by  the  rj
1250              request.
1251
1252       \n[.slant]
1253              The slant of the current font as set with \S.
1254
1255       \n[.sr]
1256              The  last  requested point size in points as a decimal fraction.
1257              This is a string-valued register.
1258
1259       \n[.ss]
1260       \n[.sss]
1261              These give the values of the parameters set  by  the  first  and
1262              second arguments of the ss request.
1263
1264       \n[.sty]
1265              The current font style.  This is a string-valued register.
1266
1267       \n[.tabs]
1268              A string representation of the current tab settings suitable for
1269              use as an argument to the ta request.
1270
1271       \n[.trunc]
1272              The amount of vertical space  truncated  by  the  most  recently
1273              sprung  vertical  position trap, or, if the trap was sprung by a
1274              ne request, minus the amount of vertical motion produced by  the
1275              ne  request.   In other words, at the point a trap is sprung, it
1276              represents the difference of what the  vertical  position  would
1277              have been but for the trap, and what the vertical position actu‐
1278              ally is.  Useful in conjunction with the \n[.ne] register.
1279
1280       \n[.U] Set to 1 if in safer mode and to 0 if in unsafe mode  (as  given
1281              with the -U command line option).
1282
1283       \n[.vpt]
1284              1 if vertical position traps are enabled, 0 otherwise.
1285
1286       \n[.warn]
1287              The  sum  of  the  numbers associated with each of the currently
1288              enabled warnings.  The number associated with  each  warning  is
1289              listed in troff(1).
1290
1291       \n[.x] The major version number.  For example, if the version number is
1292              1.03, then \n[.x] contains 1.
1293
1294       \n[.y] The minor version number.  For example, if the version number is
1295              1.03, then \n[.y] contains 03.
1296
1297       \n[.Y] The revision number of groff.
1298
1299       \n[.zoom]
1300              The  zoom  value  of the current font, in multiples of 1/1000th.
1301              Zero if no magnification.
1302
1303       \n[llx]
1304       \n[lly]
1305       \n[urx]
1306       \n[ury]
1307              These four read/write registers are set by the psbb request  and
1308              contain the bounding box values (in PostScript units) of a given
1309              PostScript image.
1310
1311       The following read/write registers are set by the \w escape sequence:
1312
1313       \n[rst]
1314       \n[rsb]
1315              Like the st and sb registers, but take account  of  the  heights
1316              and depths of glyphs.
1317
1318       \n[ssc]
1319              The  amount  of horizontal space (possibly negative) that should
1320              be added to the last glyph before a subscript.
1321
1322       \n[skw]
1323              How far to right of the center of the last glyph in the \w argu‐
1324              ment, the center of an accent from a roman font should be placed
1325              over that glyph.
1326
1327       Other available read/write number registers are:
1328
1329       \n[c.] The current input line number.  \n[.c] is a read-only  alias  to
1330              this register.
1331
1332       \n[hours]
1333              The number of hours past midnight.  Initialized at start-up.
1334
1335       \n[hp] The current horizontal position at input line.
1336
1337       \n[lsn]
1338       \n[lss]
1339              If  there  are  leading spaces in an input line, these registers
1340              hold the number of leading spaces and the corresponding horizon‐
1341              tal space, respectively.
1342
1343       \n[minutes]
1344              The number of minutes after the hour.  Initialized at start-up.
1345
1346       \n[seconds]
1347              The  number  of seconds after the minute.  Initialized at start-
1348              up.
1349
1350       \n[systat]
1351              The return value of the system() function executed by  the  last
1352              sy request.
1353
1354       \n[slimit]
1355              If  greater  than  0, the maximum number of objects on the input
1356              stack.  If less than or equal to 0, there is  no  limit  on  the
1357              number  of objects on the input stack.  With no limit, recursion
1358              can continue until virtual memory is exhausted.
1359
1360       \n[year]
1361              The current year.  Note that the traditional troff number regis‐
1362              ter \n[yr] is the current year minus 1900.
1363
1364   Miscellaneous
1365       troff  predefines  a single (read/write) string-based register, \*[.T],
1366       which contains the argument given to the -T command line option, namely
1367       the  current  output  device (for example, latin1 or ascii).  Note that
1368       this is not the same as the (read-only) number register \n[.T] which is
1369       defined to be 1 if troff is called with the -T command line option, and
1370       zero otherwise.  This behaviour is different to UNIX troff.
1371
1372       Fonts not listed in the DESC file are automatically mounted on the next
1373       available  font  position when they are referenced.  If a font is to be
1374       mounted explicitly with the fp request on an unused font  position,  it
1375       should be mounted on the first unused font position, which can be found
1376       in the \n[.fp] register; although troff does not enforce this strictly,
1377       it  does  not  allow a font to be mounted at a position whose number is
1378       much greater than that of any currently used position.
1379
1380       Interpolating a string does not hide existing macro arguments.  Thus in
1381       a macro, a more efficient way of doing
1382
1383              .xx \\$@
1384
1385       is
1386
1387              \\*[xx]\\
1388
1389       If  the  font  description  file contains pairwise kerning information,
1390       glyphs from that font are kerned.  Kerning between two  glyphs  can  be
1391       inhibited by placing a \& between them.
1392
1393       In  a  string comparison in a condition, characters that appear at dif‐
1394       ferent input levels to the first delimiter character are not recognized
1395       as  the  second  or  third  delimiters.   This  applies  also to the tl
1396       request.  In a \w escape sequence, a character that appears at  a  dif‐
1397       ferent  input  level  to the starting delimiter character is not recog‐
1398       nized as the closing delimiter character.  The same is true for \A, \b,
1399       \B,  \C, \l, \L, \o, \X, and \Z.  When decoding a macro or string argu‐
1400       ment that is delimited by double quotes, a character that appears at  a
1401       different input level to the starting delimiter character is not recog‐
1402       nized as the closing delimiter character.  The  implementation  of  \$@
1403       ensures  that  the  double quotes surrounding an argument appear at the
1404       same input level, which is different to the input level of the argument
1405       itself.   In a long escape name ] is not recognized as a closing delim‐
1406       iter except when it occurs at the same input level as  the  opening  [.
1407       In compatibility mode, no attention is paid to the input-level.
1408
1409       There are some new types of condition:
1410
1411       .if rxxx
1412              True if there is a number register named xxx.
1413
1414       .if dxxx
1415              True  if  there  is a string, macro, diversion, or request named
1416              xxx.
1417
1418       .if mxxx
1419              True if there is a color named xxx.
1420
1421       .if cch
1422              True if there is a character (or  glyph)  ch  available;  ch  is
1423              either  an  ASCII  character  or  a  glyph  (special  character)
1424              \N'xxx', \(xx or \[xxx]; the condition is also true  if  ch  has
1425              been defined by the char request.
1426
1427       .if Ff True  if  font  f exists.  f is handled as if it was opened with
1428              the ft  request  (this  is,  font  translation  and  styles  are
1429              applied), without actually mounting it.
1430
1431       .if Ss True  if  style  s  has  been  registered.   Font translation is
1432              applied.
1433
1434       The tr request can now map characters onto \~.
1435
1436       The space width emitted by the \| and \^ escape sequences can  be  con‐
1437       trolled  on  a  per-font  basis.   If  there is a glyph named \| or \^,
1438       respectively (note the leading backslash), defined in the current  font
1439       file, use this glyph's width instead of the default value.
1440
1441       It  is now possible to have whitespace between the first and second dot
1442       (or the name of the ending macro) to end a macro definition.  Example:
1443
1444              .if t \{\
1445              .  de bar
1446              .    nop Hello, I'm ‘bar’.
1447              .  .
1448              .\}
1449

INTERMEDIATE OUTPUT FORMAT

1451       This section describes the format output by GNU troff.  The output for‐
1452       mat used by GNU troff is very similar to that used by Unix device-inde‐
1453       pendent troff.  Only the differences are documented here.
1454
1455   Units
1456       The argument to the s command is in scaled points (units  of  points/n,
1457       where  n  is  the argument to the sizescale command  in the DESC file).
1458       The argument to the x Height command is also in scaled points.
1459
1460   Text Commands
1461       Nn     Print glyph with index n (a non-negative integer) of the current
1462              font.
1463
1464       If  the  tcommand line is present in the DESC file, troff uses the fol‐
1465       lowing two commands.
1466
1467       txxx   xxx is any sequence of characters terminated by  a  space  or  a
1468              newline  (to  be  more precise, it is a sequence of glyphs which
1469              are accessed with the corresponding characters); the first char‐
1470              acter  should  be  printed  at the current position, the current
1471              horizontal position should be increased  by  the  width  of  the
1472              first character, and so on for each character.  The width of the
1473              glyph is that given in the font file, appropriately  scaled  for
1474              the  current point size, and rounded so that it is a multiple of
1475              the horizontal resolution.  Special characters cannot be printed
1476              using this command.
1477
1478       un xxx This  is  same  as the t command except that after printing each
1479              character, the current horizontal position is increased  by  the
1480              sum of the width of that character and n.
1481
1482       Note  that  single  characters  can have the eighth bit set, as can the
1483       names of fonts and special characters.
1484
1485       The names of glyphs and fonts  can  be  of  arbitrary  length;  drivers
1486       should not assume that they are only two characters long.
1487
1488       When  a  glyph  is  to  be printed, that glyph is always in the current
1489       font.  Unlike device-independent troff, it is not necessary for drivers
1490       to search special fonts to find a glyph.
1491
1492       For color support, some new commands have been added:
1493
1494       mc cyan magenta yellow
1495       md
1496       mg gray
1497       mk cyan magenta yellow black
1498       mr red green blue
1499              Set  the  color  components  of the current drawing color, using
1500              various color schemes.  md  resets  the  drawing  color  to  the
1501              default  value.   The  arguments  are integers in the range 0 to
1502              65536.
1503
1504       The x device control command has been extended.
1505
1506       x u n  If n is 1, start underlining of spaces.  If n is 0, stop  under‐
1507              lining  of  spaces.   This is needed for the cu request in nroff
1508              mode and is ignored otherwise.
1509
1510   Drawing Commands
1511       The D drawing command has been extended.  These extensions are not used
1512       by GNU pic if the -n option is given.
1513
1514       Df n\n Set the shade of gray to be used for filling solid objects to n;
1515              n must be an integer between 0 and  1000,  where  0  corresponds
1516              solid  white and 1000 to solid black, and values in between cor‐
1517              respond to intermediate shades of gray.  This  applies  only  to
1518              solid circles, solid ellipses and solid polygons.  By default, a
1519              level of 1000 is used.  Whatever color a solid  object  has,  it
1520              should  completely  obscure  everything  beneath  it.   A  value
1521              greater than 1000 or less than 0 can also be  used:  this  means
1522              fill  with  the  shade  of gray that is currently being used for
1523              lines and text.  Normally this is black, but  some  drivers  may
1524              provide a way of changing this.
1525
1526              The  corresponding  \D'f...' command shouldn't be used since its
1527              argument is always rounded to an integer multiple of  the  hori‐
1528              zontal resolution which can lead to surprising results.
1529
1530       DC d\n Draw a solid circle with a diameter of d with the leftmost point
1531              at the current position.
1532
1533       DE dx dy\n
1534              Draw a solid ellipse with a horizontal diameter of dx and a ver‐
1535              tical  diameter  of  dy  with  the leftmost point at the current
1536              position.
1537
1538       Dp dx1 dy1 dx2 dy2 ... dxn dyn\n
1539              Draw a polygon with, for i=1,...,n+1, the  i-th  vertex  at  the
1540              current  position  +ij−=Σ11(dxj,dyj).   At  the moment, GNU pic only
1541              uses this command to generate triangles and rectangles.
1542
1543       DP dx1 dy1 dx2 dy2 ... dxn dyn\n
1544              Like Dp but draw a solid rather than outlined polygon.
1545
1546       Dt n\n Set the current line thickness to n machine  units.   Tradition‐
1547              ally Unix troff drivers use a line thickness proportional to the
1548              current point size; drivers should continue to do this if no  Dt
1549              command has been given, or if a Dt command has been given with a
1550              negative value of n.  A zero value of  n  selects  the  smallest
1551              available line thickness.
1552
1553       A difficulty arises in how the current position should be changed after
1554       the execution of these commands.  This is not of great importance since
1555       the code generated by GNU pic does not depend on this.  Given a drawing
1556       command of the form
1557
1558              \D'c x1 y1 x2 y2 ... xn yn'
1559
1560       where c is not one of c, e, l, a, or ~, Unix troff treats each  of  the
1561       xi  as a horizontal quantity, and each of the yi as a vertical quantity
1562       and assumes that the width of the drawn object is in=Σ1xi, and  that  the
1563       height is in=Σ1yi.  (The assumption about the height can be seen by exam‐
1564       ining the st and sb registers after using such a  D  command  in  a  \w
1565       escape  sequence).   This  rule also holds for all the original drawing
1566       commands with the exception of De.  For the sake of  compatibility  GNU
1567       troff also follows this rule, even though it produces an ugly result in
1568       the case of the Dt and Df, and, to a lesser extent, DE commands.   Thus
1569       after executing a D command of the form
1570
1571              Dc x1 y1 x2 y2 ... xn yn\n
1572
1573       the current position should be increased by (in=Σ1xi,in=Σ1yi).
1574
1575       Another set of extensions is
1576
1577       DFc cyan magenta yellow\n
1578       DFd\n
1579       DFg gray\n
1580       DFk cyan magenta yellow black\n
1581       DFr red green blue\n
1582              Set  the  color  components  of the filling color similar to the
1583              m commands above.
1584
1585       The current position isn't changed by those colour  commands  (contrary
1586       to Df).
1587
1588   Device Control Commands
1589       There  is  a  continuation convention which permits the argument to the
1590       x X command to contain newlines: when outputting the  argument  to  the
1591       x X  command,  GNU  troff follows each newline in the argument with a +
1592       character (as usual, it terminates the entire argument with a newline);
1593       thus  if the line after the line containing the x X command starts with
1594       +, then the newline ending the line containing the x X  command  should
1595       be  treated as part of the argument to the x X command, the + should be
1596       ignored, and the part of the line following the  +  should  be  treated
1597       like the part of the line following the x X command.
1598
1599       The first three output commands are guaranteed to be:
1600
1601              x T device
1602              x res n h v
1603              x init
1604

INCOMPATIBILITIES

1606       In  spite  of  the many extensions, groff has retained compatibility to
1607       classical troff to a large degree.  For the cases where the  extensions
1608       lead  to  collisions, a special compatibility mode with the restricted,
1609       old functionality was created for groff.
1610
1611   Groff Language
1612       groff provides a compatibility mode that allows to  process  roff  code
1613       written  for  classical troff or for other implementations of roff in a
1614       consistent way.
1615
1616       Compatibility mode can be turned on with the -C  command  line  option,
1617       and  turned  on or off with the .cp request.  The number register \n(.C
1618       is 1 if compatibility mode is on, 0 otherwise.
1619
1620       This became necessary because the GNU concept  for  long  names  causes
1621       some incompatibilities.  Classical troff interprets
1622
1623              .dsabcd
1624
1625       as  defining a string ab with contents cd.  In groff mode, this is con‐
1626       sidered as a call of a macro named dsabcd.
1627
1628       Also classical troff interprets \*[ or \n[ as references to a string or
1629       number  register called [ while groff takes this as the start of a long
1630       name.
1631
1632       In compatibility mode, groff interprets these things in the traditional
1633       way; so long names are not recognized.
1634
1635       On  the  other hand, groff in GNU native mode does not allow to use the
1636       single-character escapes \\ (backslash), \| (vertical bar), \^ (caret),
1637       \&  (ampersand),  \{ (opening brace), \} (closing brace), ‘\ ’ (space),
1638       \' (single quote), \`  (backquote),  \-  (minus),  \_  (underline),  \!
1639       (bang), \% (percent), and \c (character c) in names of strings, macros,
1640       diversions, number registers, fonts or environments, whereas  classical
1641       troff does.
1642
1643       The  \A  escape  sequence  can  be  helpful  in  avoiding  these escape
1644       sequences in names.
1645
1646       Fractional point sizes cause one noteworthy incompatibility.  In  clas‐
1647       sical troff, the ps request ignores scale indicators and so
1648
1649              .ps 10u
1650
1651       sets  the  point  size  to  10 points, whereas in groff native mode the
1652       point size is set to 10 scaled points.
1653
1654       In groff, there is a fundamental difference between  unformatted  input
1655       characters,  and formatted output characters (glyphs).  Everything that
1656       affects how a glyph is output is stored with the glyph;  once  a  glyph
1657       has  been  constructed it is unaffected by any subsequent requests that
1658       are executed, including the bd, cs, tkf, tr, or fp requests.
1659
1660       Normally glyphs are constructed from input  characters  at  the  moment
1661       immediately  before  the  glyph  is  added  to the current output line.
1662       Macros, diversions and strings are all,  in  fact,  the  same  type  of
1663       object; they contain lists of input characters and glyphs in any combi‐
1664       nation.
1665
1666       Special characters can be both; before being added to the output,  they
1667       act as input entities, afterwards they denote glyphs.
1668
1669       A  glyph  does  not  behave like an input character for the purposes of
1670       macro processing; it does not inherit any  of  the  special  properties
1671       that  the input character from which it was constructed might have had.
1672       The following example makes things clearer.
1673
1674              .di x
1675              \\\\
1676              .br
1677              .di
1678              .x
1679
1680       With GNU troff this is printed as \\.  So  each  pair  of  input  back‐
1681       slashes ‘\\’ is turned into a single output backslash glyph ‘\’ and the
1682       resulting output backslashes are not interpreted as  escape  characters
1683       when they are reread.
1684
1685       Classical  troff  would  interpret  them as escape characters when they
1686       were reread and would end up printing a single backslash ‘\’.
1687
1688       In GNU, the correct way to get a printable  version  of  the  backslash
1689       character ’\’ is the \(rs escape sequence, but classical troff does not
1690       provide a clean feature for getting  a  non-syntactical  backslash.   A
1691       close  method  is the printable version of the current escape character
1692       using the \e escape sequence; this works if the current escape  charac‐
1693       ter  is  not  redefined.   It  works in both GNU mode and compatibility
1694       mode, while dirty tricks like specifying a sequence of  multiple  back‐
1695       slashes do not work reliably; for the different handling in diversions,
1696       macro definitions, or text mode quickly leads to a confusion about  the
1697       necessary number of backslashes.
1698
1699       To store an escape sequence in a diversion that is interpreted when the
1700       diversion is reread,  either  the  traditional  \!  transparent  output
1701       facility or the new \? escape sequence can be used.
1702
1703   Intermediate Output
1704       The  groff  intermediate  output format is in a state of evolution.  So
1705       far it has some incompatibilities, but it is intended  to  establish  a
1706       full  compatibility to the classical troff output format.  Actually the
1707       following incompatibilities exist:
1708
1709       · The positioning after the drawing of the polygons conflicts with  the
1710         classical definition.
1711
1712       · The  intermediate output cannot be rescaled to other devices as clas‐
1713         sical ‘device-independent’ troff did.
1714

SEE ALSO

1716       The groff info file,  cf.  info(1)  presents  all  groff  documentation
1717       within a single document.
1718
1719       groff(1)
1720              A list of all documentation around groff.
1721
1722       groff(7)
1723              A description of the groff language, including a short, but com‐
1724              plete reference  of  all  predefined  requests,  registers,  and
1725              escapes  of  plain groff.  From the command line, this is called
1726              using
1727
1728                     man 7 groff
1729
1730       roff(7)
1731              A survey of roff systems, including pointers to further histori‐
1732              cal documentation.
1733
1734       [CSTR #54]
1735              The  Nroff/Troff  User's  Manual by J. F. Ossanna of 1976 in the
1736              revision of Brian Kernighan of 1992, being the  classical  troff
1737              documentation ⟨http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.
1738

COPYING

1740       Copyright © 1989-2014 Free Software Foundation, Inc.
1741
1742       This  file  is  part of groff, the GNU roff type-setting system.  It is
1743       the source of the man-page groff_diff(7).
1744
1745       Permission is granted to copy, distribute and/or modify  this  document
1746       under  the  terms of the GNU Free Documentation License, Version 1.3 or
1747       any later version published by the Free Software  Foundation;  with  no
1748       Front-Cover Texts, and with no Back-Cover Texts.
1749
1750       A  copy  of the Free Documentation License is included as a file called
1751       FDL in the main directory of the  groff  source  package,  it  is  also
1752       available  in  the  internet  at  GNU  FDL license ⟨http://www.gnu.org/
1753       copyleft/fdl.html⟩.
1754

AUTHORS

1756       This document was written by James Clark ⟨jjc@jclark.com⟩, was modified
1757       by    Werner    Lemberg   ⟨wl@gnu.org⟩   and   Bernd   Warken   ⟨groff-
1758       bernd.warken-72@web.de⟩.
1759
1760
1761
1762Groff Version 1.22.3            4 November 2014                  GROFF_DIFF(7)
Impressum