1GROFF_OUT(5)                  File Formats Manual                 GROFF_OUT(5)
2
3
4

NAME

6       groff_out - groff intermediate output format
7

DESCRIPTION

9       This  manual  page  describes the intermediate output format of the GNU
10       roff(7) text processing system.  This output is produced by  a  run  of
11       the  GNU  troff(1) program before it is fed into a device postprocessor
12       program.
13
14       As the GNU roff processor groff(1) is a wrapper  program  around  troff
15       that  automatically calls a postprocessor, this output does not show up
16       normally.  This is why it is called intermediate within the groff  sys‐
17       tem.   The groff program provides the option -Z to inhibit postprocess‐
18       ing, such that the produced intermediate output  is  sent  to  standard
19       output just like calling troff manually.
20
21       In this document, the term troff output describes what is output by the
22       GNU troff program, while intermediate output  refers  to  the  language
23       that  is accepted by the parser that prepares this output for the post‐
24       processors.  This parser is smarter on whitespace and implements  obso‐
25       lete  elements  for compatibility, otherwise both formats are the same.
26       The pre-groff roff versions are denoted as classical troff.
27
28       The main purpose of the intermediate output concept  is  to  facilitate
29       the  development  of  postprocessors  by providing a common programming
30       interface for all devices.  It has a language of its own that  is  com‐
31       pletely different from the groff(7) language.  While the groff language
32       is a high-level programming language for text processing, the  interme‐
33       diate  output  language  is  a  kind of low-level assembler language by
34       specifying all positions on the page for writing and drawing.
35
36       The intermediate output produced by groff  is  fairly  readable,  while
37       classical troff output was hard to understand because of strange habits
38       that are still supported, but not used any longer by GNU troff.
39

LANGUAGE CONCEPTS

41       During the run of troff, the roff input is cracked down to the informa‐
42       tion on what has to be printed at what position on the intended device.
43       So the language of the intermediate output format can be  quite  small.
44       Its only elements are commands with or without arguments.  In this doc‐
45       ument, the term "command" always refers to the intermediate output lan‐
46       guage,  never to the roff language used for document formatting.  There
47       are commands for positioning and text writing,  for  drawing,  and  for
48       device controlling.
49
50   Separation
51       Classical  troff  output  had  strange requirements on whitespace.  The
52       groff output parser, however, is smart about whitespace  by  making  it
53       maximally  optional.   The  whitespace characters, i.e. the tab, space,
54       and newline characters, always have a syntactical  meaning.   They  are
55       never  printable  because  spacing  within the output is always done by
56       positioning commands.
57
58       Any sequence of space or tab characters is treated as a single  syntac‐
59       tical space.  It separates commands and arguments, but is only required
60       when there would occur a clashing between  the  command  code  and  the
61       arguments  without  the  space.  Most often, this happens when variable
62       length command names, arguments, argument lists,  or  command  clusters
63       meet.   Commands  and  arguments with a known, fixed length need not be
64       separated by syntactical space.
65
66       A line break is a syntactical element, too.  Every command argument can
67       be  followed  by whitespace, a comment, or a newline character.  Thus a
68       syntactical line break is defined to consist  of  optional  syntactical
69       space  that  is optionally followed by a comment, and a newline charac‐
70       ter.
71
72       The normal commands, those for positioning and text, consist of a  sin‐
73       gle letter taking a fixed number of arguments.  For historical reasons,
74       the parser allows to stack such commands on the same line,  but  fortu‐
75       nately,  in  groff intermediate output, every command with at least one
76       argument is followed by a line break, thus  providing  excellent  read‐
77       ability.
78
79       The  other commands — those for drawing and device controlling — have a
80       more complicated structure; some recognize long command names, and some
81       take  a  variable  number  of  arguments.  So all D and x commands were
82       designed to request a syntactical line break after their last argument.
83       Only  one  command, `x X' has an argument that can stretch over several
84       lines, all other commands must have all of their arguments on the  same
85       line  as  the command, i.e. the arguments may not be splitted by a line
86       break.
87
88       Empty lines, i.e. lines containing only space  and/or  a  comment,  can
89       occur everywhere.  They are just ignored.
90
91   Argument Units
92       Some commands take integer arguments that are assumed to represent val‐
93       ues in a measurement unit, but the letter for the  corresponding  scale
94       indicator  is  not  written  with  the  output  command  arguments; see
95       groff(7) and the groff info file for more on this topic.  Most commands
96       assume the scale indicator u, the basic unit of the device, some use z,
97       the scaled point unit of the device, while others, such  as  the  color
98       commands  expect  plain integers.  Note that these scale indicators are
99       relative to the chosen device.  They  are  defined  by  the  parameters
100       specified in the device's DESC file; see groff_font(5).
101
102       Note  that  single  characters  can have the eighth bit set, as can the
103       names of fonts and special characters.  The  names  of  characters  and
104       fonts  can  be  of arbitrary length.  A character that is to be printed
105       will always be in the current font.
106
107       A string argument is always terminated by the next whitespace character
108       (space,  tab,  or newline); an embedded # character is regarded as part
109       of the argument, not as the beginning of a comment command.  An integer
110       argument  is  already terminated by the next non-digit character, which
111       then is regarded as the first character of the next  argument  or  com‐
112       mand.
113
114   Document Parts
115       A  correct intermediate output document consists of two parts, the pro‐
116       logue and the body.
117
118       The task of the prologue is to set the general device parameters  using
119       three  exactly specified commands.  The groff prologue is guaranteed to
120       consist of the following three lines (in that order):
121
122              x T device
123              x res n h v
124              x init
125
126       with the arguments set as outlined in the section Device  Control  Com‐
127       mands.   But  the  parser for the intermediate output format is able to
128       swallow additional whitespace and comments as well.
129
130       The body is the main section for processing the document data.  Syntac‐
131       tically,  it is a sequence of any commands different from the ones used
132       in the prologue.  Processing is terminated as soon as the first  x stop
133       command  is encountered; the last line of any groff intermediate output
134       always contains such a command.
135
136       Semantically, the body is page oriented.  A new page is  started  by  a
137       p  command.  Positioning, writing, and drawing commands are always done
138       within the current page, so they cannot occur before the first  p  com‐
139       mand.   Absolute positioning (by the H and V commands) is done relative
140       to the current page, all other positioning is done relative to the cur‐
141       rent location within this page.
142

COMMAND REFERENCE

144       This  section describes all intermediate output commands, the classical
145       commands as well as the groff extensions.
146
147   Comment Command
148       #anything⟨end_of_line⟩
149              A comment.  Ignore any characters from the # character up to the
150              next newline character.
151
152       This command is the only possibility for commenting in the intermediate
153       output.  Each comment can be preceded by arbitrary  syntactical  space;
154       every command can be terminated by a comment.
155
156   Simple Commands
157       The  commands  in  this  subsection have a command code consisting of a
158       single character, taking a fixed number of arguments.  Most of them are
159       commands  for  positioning  and text writing.  These commands are smart
160       about  whitespace.   Optionally,  syntactical  space  can  be  inserted
161       before,  after,  and between the command letter and its arguments.  All
162       of these commands are stackable, i.e., they can be  preceded  by  other
163       simple  commands  or  followed  by arbitrary other commands on the same
164       line.  A separating syntactical space is only necessary when two  inte‐
165       ger  arguments  would  clash  or  if the preceding argument ends with a
166       string argument.
167
168       C xxx⟨white_space⟩
169              Print a special groff character named xxx.  The trailing syntac‐
170              tical  space or line break is necessary to allow character names
171              of arbitrary length.  The character is printed  at  the  current
172              print position; the character's size is read from the font file.
173              The print position is not changed.
174
175       c c    Print character c at the current print position; the character's
176              size  is  read  from  the  font file.  The print position is not
177              changed.
178
179       f n    Set font to font number n (a non-negative integer).
180
181       H n    Move right to the absolute vertical position n  (a  non-negative
182              integer in basic units u) relative to left edge of current page.
183
184       h n    Move  n  (a  non-negative integer) basic units u horizontally to
185              the right.  [54] allows negative values for n  also,  but  groff
186              doesn't use this.
187
188       m color_scheme [component ...]
189              Set  the  color for text (glyphs), line drawing, and the outline
190              of graphic objects using different color schemes; the analoguous
191              command  for  the  filling  color of graphic objects is DF.  The
192              color components are specified as integer  arguments  between  0
193              and  65536.   The  number  of color components and their meaning
194              vary for the different color schemes.  These commands are gener‐
195              ated  by  the  groff  escape sequence \m.  No position changing.
196              These commands are a groff extension.
197
198              mc cyan magenta yellow
199                     Set color using the CMY color scheme, having the 3  color
200                     components cyan, magenta, and yellow.
201
202              md     Set  color  to  the  default  color  value (black in most
203                     cases).  No component arguments.
204
205              mg gray
206                     Set color to the shade of gray given by the argument,  an
207                     integer between 0 (black) and 65536 (white).
208
209              mk cyan magenta yellow black
210                     Set color using the CMYK color scheme, having the 4 color
211                     components cyan, magenta, yellow, and black.
212
213              mr red green blue
214                     Set color using the RGB color scheme, having the 3  color
215                     components red, green, and blue.
216
217       N n    Print  character  with  index  n (a non-negative integer) of the
218              current font.  The print position is not changed.  This  command
219              is a groff extension.
220
221       n b a  Inform the device about a line break, but no positioning is done
222              by this command.  In classical troff, the  integer  arguments  b
223              and a informed about the space before and after the current line
224              to make the intermediate output more human readable without per‐
225              forming  any  action.  In groff, they are just ignored, but they
226              must be provided for compatibility reasons.
227
228       p n    Begin a new page in the outprint.  The page number is set to  n.
229              This  page is completely independent of pages formerly processed
230              even if those have the same page number.  The vertical  position
231              on  the  outprint  is  automatically set to 0.  All positioning,
232              writing, and drawing is always done relative to  a  page,  so  a
233              p command must be issued before any of these commands.
234
235       s n    Set point size to n scaled points (this is unit z in GNU troff).
236              Classical troff used the unit points (p)  instead;  see  section
237              COMPATIBILITY.
238
239       t xxx⟨white_space⟩
240       t xxx dummy_arg⟨white_space⟩
241              Print  a word, i.e. a sequence of characters xxx terminated by a
242              space character or a line  break;  an  optional  second  integer
243              argument  is  ignored  (this allows the formatter to generate an
244              even number  of  arguments).   The  first  character  should  be
245              printed at the current position, the current horizontal position
246              should then be increased by the width of  the  first  character,
247              and  so on for each character.  The widths of the characters are
248              read from the font file, scaled for the current point size,  and
249              rounded  to  a  multiple  of the horizontal resolution.  Special
250              characters cannot be printed using this command (use the C  com‐
251              mand  for named characters).  This command is a groff extension;
252              it is only used for devices whose DESC file contains  the  tcom‐
253              mand keyword; see groff_font(5).
254
255       u n xxx⟨white_space⟩
256              Print  word  with track kerning.  This is the same as the t com‐
257              mand except that after printing each character, the current hor‐
258              izontal  position  is  increased by the sum of the width of that
259              character and n (an integer in basic units u).  This command  is
260              a  groff  extension; it is only used for devices whose DESC file
261              contains the tcommand keyword; see groff_font(5).
262
263       V n    Move down to the absolute vertical position  n  (a  non-negative
264              integer  in  basic  units  u)  relative to upper edge of current
265              page.
266
267       v n    Move n basic units u down (n is a non-negative  integer).   [54]
268              allows negative values for n also, but groff doesn't use this.
269
270       w      Informs  about  a  paddable  whitespace to increase readability.
271              The spacing itself must be performed explicitly by a  move  com‐
272              mand.
273
274   Graphics Commands
275       Each graphics or drawing command in the intermediate output starts with
276       the letter D followed by one or two characters that specify  a  subcom‐
277       mand;  this  is followed by a fixed or variable number of integer argu‐
278       ments that are separated by a single space character.  A D command  may
279       not  be followed by another command on the same line (apart from a com‐
280       ment), so each D command is terminated by a syntactical line break.
281
282       troff output follows the classical spacing rules (no space between com‐
283       mand and subcommand, all arguments are preceded by a single space char‐
284       acter), but the parser allows optional space between the  command  let‐
285       ters and makes the space before the first argument optional.  As usual,
286       each space can be any sequence of tab and space characters.
287
288       Some graphics commands can take a variable  number  of  arguments.   In
289       this  case,  they  are  integers  representing a size measured in basic
290       units u.  The arguments called h1, h2, ..., hn h1, h2,  ...,  hn  stand
291       for  horizontal  distances  where  positive means right, negative left.
292       The arguments called v1, v2, ..., vn v1, v2, ..., vn stand for vertical
293       distances  where positive means down, negative up.  All these distances
294       are offsets relative to the current location.
295
296       Unless indicated otherwise, each graphics command directly  corresponds
297       to a similar groff \D escape sequence; see groff(7).
298
299       Unknown  D  commands  are assumed to be device-specific.  Its arguments
300       are parsed as strings; the whole information is then sent to the  post‐
301       processor.
302
303       In  the  following  command  reference, the syntax element ⟨line_break⟩
304       means a syntactical line break as defined in section Separation.
305
306       D~ h1 v1 h2 v2 ... hn vn⟨line_break⟩
307              Draw B-spline from current position to offset (h1, v1), then  to
308              offset  (h2, v2)  if  given,  etc.  up to (hn, vn). This command
309              takes a variable number of argument pairs; the current  position
310              is moved to the terminal point of the drawn curve.
311
312       Da h1 v1 h2 v2⟨line_break⟩
313              Draw  arc from current position to (h1, v1)+(h2, v2) with center
314              at (h1, v1); then move the current position to the  final  point
315              of the arc.
316
317       DC d⟨line_break⟩
318       DC d dummy_arg⟨line_break⟩
319              Draw a solid circle using the current fill color with diameter d
320              (integer in basic units u) with leftmost point  at  the  current
321              position;  then move the current position to the rightmost point
322              of the circle.  An optional second integer argument  is  ignored
323              (this  allows  to  the  formatter  to generate an even number of
324              arguments).  This command is a groff extension.
325
326       Dc d⟨line_break⟩
327              Draw circle line with diameter d (integer in basic units u) with
328              leftmost  point  at  the current position; then move the current
329              position to the rightmost point of the circle.
330
331       DE h v⟨line_break⟩
332              Draw a solid ellipse in the current fill color with a horizontal
333              diameter  of  h  and  a vertical diameter of v (both integers in
334              basic units u) with the leftmost point at the current  position;
335              then  move  to the rightmost point of the ellipse.  This command
336              is a groff extension.
337
338       De h v⟨line_break⟩
339              Draw an outlined ellipse with a horizontal diameter of h  and  a
340              vertical diameter of v (both integers in basic units u) with the
341              leftmost point at current position; then move to  the  rightmost
342              point of the ellipse.
343
344       DF color_scheme [component ...]⟨line_break⟩
345              Set  fill  color for solid drawing objects using different color
346              schemes; the analoguous command for setting the color  of  text,
347              line  graphics,  and  the  outline of graphic objects is m.  The
348              color components are specified as integer  arguments  between  0
349              and  65536.   The  number  of color components and their meaning
350              vary for the different color schemes.  These commands are gener‐
351              ated  by  the  groff escape sequences \D'F ...'  and \M (with no
352              other corresponding graphics commands).  No  position  changing.
353              This command is a groff extension.
354
355              DFc cyan magenta yellow⟨line_break⟩
356                     Set  fill  color  for solid drawing objects using the CMY
357                     color  scheme,  having  the  3  color  components   cyan,
358                     magenta, and yellow.
359
360              DFd ⟨line_break⟩
361                     Set  fill  color for solid drawing objects to the default
362                     fill color value (black in  most  cases).   No  component
363                     arguments.
364
365              DFg gray⟨line_break⟩
366                     Set  fill color for solid drawing objects to the shade of
367                     gray given by the argument, an integer between 0  (black)
368                     and 65536 (white).
369
370              DFk cyan magenta yellow black⟨line_break⟩
371                     Set  fill  color for solid drawing objects using the CMYK
372                     color  scheme,  having  the  4  color  components   cyan,
373                     magenta, yellow, and black.
374
375              DFr red green blue⟨line_break⟩
376                     Set  fill  color  for solid drawing objects using the RGB
377                     color scheme, having the 3 color components  red,  green,
378                     and blue.
379
380       Df n⟨line_break⟩
381              The argument n must be an integer in the range -32767 to 32767.
382
383              0 ≤ n ≤ 1000
384                     Set  the  color  for  filling  solid drawing objects to a
385                     shade of gray, where 0 corresponds to solid  white,  1000
386                     (the  default)  to  solid black, and values in between to
387                     intermediate shades of gray; this is obsoleted by command
388                     DFg.
389
390              n < 0 or n > 1000
391                     Set  the  filling  color  to  the color that is currently
392                     being used for the text and the outline, see  command  m.
393                     For example, the command sequence
394                            mg 0 0 65536
395                            Df -1
396                     sets all colors to blue.
397
398              No position changing.  This command is a groff extension.
399
400       Dl h v⟨line_break⟩
401              Draw  line  from  current position to offset (h, v) (integers in
402              basic units u); then set current position  to  the  end  of  the
403              drawn line.
404
405       Dp h1 v1 h2 v2 ... hn vn⟨line_break⟩
406              Draw  a  polygon  line from current position to offset (h1, v1),
407              from there to offset (h2, v2), etc. up to offset  (hn, vn),  and
408              from  there  back to the starting position.  For historical rea‐
409              sons, the position is changed by adding the sum of all arguments
410              with  odd  index  to the actual horizontal position and the even
411              ones to the vertical position.  Although this doesn't make sense
412              it  is  kept  for compatibility.  This command is a groff exten‐
413              sion.
414
415       DP h1 v1 h2 v2 ... hn vn⟨line_break⟩
416              The same macro as the corresponding Dp  command  with  the  same
417              arguments,  but  draws a solid polygon in the current fill color
418              rather than an outlined polygon.  The position is changed in the
419              same way as with Dp.  This command is a groff extension.
420
421       Dt n⟨line_break⟩
422              Set  the  current  line  thickness  to  n  (an  integer in basic
423              units u) if n>0; if  n=0  select  the  smallest  available  line
424              thickness;  if  n<0  set  the line thickness proportional to the
425              point size (this is the default before the first Dt command  was
426              specified).   For historical reasons, the horizontal position is
427              changed by adding the argument to the  actual  horizontal  posi‐
428              tion, while the vertical position is not changed.  Although this
429              doesn't make sense it is kept for compatibility.   This  command
430              is a groff extension.
431
432   Device Control Commands
433       Each  device  control  command  starts  with the letter x followed by a
434       space character (optional or arbitrary space/tab in groff) and  a  sub‐
435       command  letter  or  word; each argument (if any) must be preceded by a
436       syntactical space.  All x commands are terminated by a syntactical line
437       break;  no device control command can be followed by another command on
438       the same line (except a comment).
439
440       The subcommand is basically a single letter, but to increase  readabil‐
441       ity, it can be written as a word, i.e. an arbitrary sequence of charac‐
442       ters terminated by the next tab,  space,  or  newline  character.   All
443       characters  of  the  subcommand  word but the first are simply ignored.
444       For example, troff outputs the initialization command x i as x init and
445       the  resolution command x r as x res.  But writings like x i_like_groff
446       and x roff_is_groff resp. are accepted as well to mean  the  same  com‐
447       mands.
448
449       In  the  following, the syntax element ⟨line_break⟩ means a syntactical
450       line break as defined in section Separation.
451
452       xF name⟨line_break⟩
453              (Filename control command)
454              Use name as the intended name for  the  current  file  in  error
455              reports.   This is useful for remembering the original file name
456              when groff uses an internal piping mechanism.  The input file is
457              not changed by this command.  This command is a groff extension.
458
459       xf n s⟨line_break⟩
460              (font control command)
461              Mount font position n (a non-negative integer) with font named s
462              (a text word), cf.  groff_font(5).
463
464       xH n⟨line_break⟩
465              (Height control command)
466              Set  character  height  to  n  (a  positive  integer  in  scaled
467              points  z).   Classical  troff used the unit points (p) instead;
468              see section COMPATIBILITY.
469
470       xi⟨line_break⟩
471              (init control command)
472              Initialize device.  This is the third command of the prologue.
473
474       xp⟨line_break⟩
475              (pause control command)
476              Parsed but ignored.  The  classical  documentation  reads  pause
477              device, can be restarted.
478
479       xr n h v⟨line_break⟩
480              (resolution control command)
481              Resolution is n, while h is the minimal horizontal motion, and v
482              the minimal vertical motion possible with this device; all argu‐
483              ments  are positive integers in basic units u per inch.  This is
484              the second command of the prologue.
485
486       xS n⟨line_break⟩
487              (Slant control command)
488              Set slant to n (an integer in basic units u).
489
490       xs⟨line_break⟩
491              (stop control command)
492              Terminates the processing of the current  file;  issued  as  the
493              last command of any intermediate troff output.
494
495       xt⟨line_break⟩
496              (trailer control command)
497              Generate  trailer  information, if any.  In groff, this is actu‐
498              ally just ignored.
499
500       xT xxx⟨line_break⟩
501              (Typesetter control command)
502              Set name of device to word xxx, a sequence of  characters  ended
503              by  the  next  whitespace  character.  The possible device names
504              coincide with those from the groff -T option.  This is the first
505              command of the prologue.
506
507       xu n⟨line_break⟩
508              (underline control command)
509              Configure  underlining  of spaces.  If n is 1, start underlining
510              of spaces; if n is 0,  stop  underlining  of  spaces.   This  is
511              needed  for  the  cu request in nroff mode and is ignored other‐
512              wise.  This command is a groff extension.
513
514       xX anything⟨line_break⟩
515              (X-escape control command)
516              Send string anything uninterpreted to the device.  If  the  line
517              following  this  command  starts with a + character this line is
518              interpreted as a continuation line in the following sense.   The
519              +  is  ignored,  but  a newline character is sent instead to the
520              device, the rest of the line is sent  uninterpreted.   The  same
521              applies  to  all  following lines until the first character of a
522              line is not a + character.  This command  is  generated  by  the
523              groff  escape  sequence  \X.   The  line-continuing feature is a
524              groff extension.
525
526   Obsolete Command
527       In classical troff output, the writing of a single character was mostly
528       done  by a very strange command that combined a horizontal move and the
529       printing of a character.  It didn't have a command code, but is  repre‐
530       sented  by  a 3-character argument consisting of exactly 2 digits and a
531       character.
532
533       ddc    Move right dd (exactly two decimal digits) basic units  u,  then
534              print character c.
535
536              In  groff,  arbitrary  syntactical  space around and within this
537              command is allowed to be added.  Only when a  preceding  command
538              on the same line ends with an argument of variable length a sep‐
539              arating space is obligatory.  In classical troff, large clusters
540              of  these  and  other commands were used, mostly without spaces;
541              this made such output almost unreadable.
542
543       For modern high-resolution devices, this command does  not  make  sense
544       because  the  width  of  the characters can become much larger than two
545       decimal digits.  In groff, this is  only  used  for  the  devices  X75,
546       X75-12,  X100,  and  X100-12.   For other devices, the commands t and u
547       provide a better functionality.
548

POSTPROCESSING

550       The roff postprocessors are programs that have the  task  to  translate
551       the  intermediate  output  into  actions  that are sent to a device.  A
552       device can be some piece of hardware such as a printer, or  a  software
553       file  format suitable for graphical or text processing.  The groff sys‐
554       tem provides powerful means that make the programming of such  postpro‐
555       cessors an easy task.
556
557       There  is  a  library  function that parses the intermediate output and
558       sends the information obtained to the device via  methods  of  a  class
559       with a common interface for each device.  So a groff postprocessor must
560       only redefine the methods of this class.  For details, see  the  refer‐
561       ence in section FILES.
562

EXAMPLES

564       This  section  presents the intermediate output generated from the same
565       input for three different devices.  The  input  is  the  sentence  hell
566       world fed into groff on the command line.
567
568       · High-resolution device ps
569
570         shell> echo hell world | groff -Z -T ps
571
572         x T ps
573         x res 72000 1 1
574         x init
575         p1
576         x font 5 TR
577         f5
578         s10000
579         V12000
580         H72000
581         thell
582         wh2500
583         tw
584         H96620
585         torld
586         n12000 0
587         x trailer
588         V792000
589         x stop
590
591       This  output can be fed into the postprocessor grops(1) to get its rep‐
592       resentation as a PostScript file.
593
594       · Low-resolution device latin1
595
596         This is similar to the high-resolution device except that  the  posi‐
597         tioning is done at a minor scale.  Some comments (lines starting with
598         #) were added for clarification; they were not generated by the  for‐
599         matter.
600
601         shell> echo hell world | groff -Z -T latin1
602
603         # prologue
604         x T latin1
605         x res 240 24 40
606         x init
607         # begin a new page
608         p1
609         # font setup
610         x font 1 R
611         f1
612         s10
613         # initial positioning on the page
614         V40
615         H0
616         # write text `hell'
617         thell
618         # inform about a space, and do it by a horizontal jump
619         wh24
620         # write text `world'
621         tworld
622         # announce line break, but do nothing because ...
623         n40 0
624         # ... the end of the document has been reached
625         x trailer
626         V2640
627         x stop
628
629       This  output  can be fed into the postprocessor grotty(1) to get a for‐
630       matted text document.
631
632       · Classical style output
633
634         As a computer monitor has a very low resolution  compared  to  modern
635         printers  the intermediate output for the X devices can use the jump-
636         and-write command with its 2-digit displacements.
637
638         shell> echo hell world | groff -Z -T X100
639
640         x T X100
641         x res 100 1 1
642         x init
643         p1
644         x font 5 TR
645         f5
646         s10
647         V16
648         H100
649         # write text with old-style jump-and-write command
650         ch07e07l03lw06w11o07r05l03dh7
651         n16 0
652         x trailer
653         V1100
654         x stop
655
656       This  output  can  be  fed  into  the  postprocessor  xditview(1x)   or
657       gxditview(1) for displaying in X.
658
659       Due  to  the  obsolete jump-and-write command, the text clusters in the
660       classical output are almost unreadable.
661

COMPATIBILITY

663       The intermediate output language of the classical troff was first docu‐
664       mented  in  [97].   The  groff intermediate output format is compatible
665       with this specification except for the following features.
666
667       · The classical quasi device independence is not yet implemented.
668
669       · The old hardware was very different from what we use today.   So  the
670         groff devices are also fundamentally different from the ones in clas‐
671         sical troff.  For example, the classical PostScript device was called
672         post  and  had  a  resolution of 720 units per inch, while groff's ps
673         device has a resolution of 72000 units per inch.   Maybe,  by  imple‐
674         menting  some  rescaling  mechanism  similar  to  the classical quasi
675         device independence, these could be integrated into modern groff.
676
677       · The B-spline command D~ is correctly handled by the intermediate out‐
678         put  parser,  but  the drawing routines aren't implemented in some of
679         the postprocessor programs.
680
681       · The argument of the commands s and x H has the implicit  unit  scaled
682         point z in groff, while classical troff had point (p).  This isn't an
683         incompatibility, but a compatible extension, for both units  coincide
684         for  all devices without a sizescale parameter, including all classi‐
685         cal and the groff  text  devices.   The  few  groff  devices  with  a
686         sizescale  parameter  either  did not exist, had a different name, or
687         seem to have had a different resolution.  So conflicts with classical
688         devices are very unlikely.
689
690       · The position changing after the commands Dp, DP, and Dt is illogical,
691         but as old versions of groff used this feature it is kept for compat‐
692         ibility reasons.
693
694       The  differences  between  groff  and classical troff are documented in
695       groff_diff(7).
696

FILES

698       /usr/share/groff/1.18.1.4/font/devname/DESC
699              Device description file for device name.
700
701       ⟨groff_source_dir⟩/src/libs/libdriver/input.cc
702              Defines the parser and postprocessor for the  intermediate  out‐
703              put.   It  is located relative to the top directory of the groff
704              source tree, e.g.  @GROFFSRCDIR@.  This parser is the definitive
705              specification of the groff intermediate output format.
706

SEE ALSO

708       A  reference  like groff(7) refers to a manual page; here groff in sec‐
709       tion 7 of the man-page documentation system.  To read the example, look
710       up section 7 in your desktop help system or call from the shell prompt
711
712              shell> man 7 groff
713
714       For more details, see man(1).
715
716       groff(1)
717              option -Z and further readings on groff.
718
719       groff(7)
720              for  details  of  the groff language such as numerical units and
721              escape sequences.
722
723       groff_font(5)
724              for details on the device scaling parameters of the DESC file.
725
726       troff(1)
727              generates the device-independent intermediate output.
728
729       roff(7)
730              for historical aspects and the general structure  of  roff  sys‐
731              tems.
732
733       groff_diff(7)
734              The  differences  between  the  intermediate output in groff and
735              classical troff.
736
737       grodvi(1), grohtml(1), grolbp(1), grolj4(1), grops(1), grotty(1)
738              the groff postprocessor programs.
739
740       For a treatment of all aspects of the groff system within a single doc‐
741       ument,  see  the groff info file.  It can be read within the integrated
742       help systems, within emacs(1) or from the shell prompt by
743              shell> info groff
744
745       The classical troff output language is described in two AT&T Bell  Labs
746       CSTR documents available on-line at Bell Labs CSTR site ⟨http://
747       cm.bell-labs.com/cm/cs/cstr.html⟩.
748
749       [CSTR #97]
750              A Typesetter-independent TROFF by Brian Kernighan is the  origi‐
751              nal and most concise documentation on the output language; see
752              CSTR #97 ⟨http://cm.bell-labs.com/cm/cs/cstr/97.ps.gz⟩.
753
754       [CSTR #54]
755              The 1992 revision of the Nroff/Troff  User's  Manual  by  J.  F.
756              Osanna  and  Brian  Kernighan  isn't  as  concise  as [CSTR #97]
757              regarding the output language; see CSTR #54 ⟨http://
758              cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.
759

AUTHORS

761       Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
762
763       This document is distributed under the terms of the FDL (GNU Free Docu‐
764       mentation License) version 1.1 or later.  You should  have  received  a
765       copy of the FDL with this package; it is also available on-line at the
766       GNU copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
767
768       This document is part of groff, the GNU roff distribution.  It is based
769       on  a  former  version  - published under the GPL - that described only
770       parts of the groff extensions of the  output  language.   It  has  been
771       rewritten  2002  by Bernd Warken ⟨bwarken@mayn.de⟩ and is maintained by
772       Werner Lemberg ⟨wl@gnu.org⟩.
773
774
775
776Groff Version 1.18.1.4         12 September 2002                  GROFF_OUT(5)
Impressum