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

LANGUAGE CONCEPTS

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

COMMAND REFERENCE

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

POSTPROCESSING

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

EXAMPLES

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

COMPATIBILITY

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

FILES

704       /usr/share/groff/1.20.1/font/devname/DESC
705              Device description file for device name.
706
707       ⟨groff-source-dir⟩/src/libs/libdriver/input.cpp
708              Defines the parser and postprocessor for the  intermediate  out‐
709              put.   It  is located relative to the top directory of the groff
710              source tree.  This parser is the definitive specification of the
711              groff intermediate output format.
712

SEE ALSO

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

AUTHORS

770       Copyright  (C)  1989,  2001,  2002, 2003, 2004, 2005, 2006, 2007, 2008,
771       2009 Free Software Foundation, Inc.
772
773       This document is distributed under the terms of the FDL (GNU Free Docu‐
774       mentation  License)  version  1.3 or later.  You should have received a
775       copy of the FDL with this package; it is also available on-line at  the
776       GNU copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
777
778       This document is part of groff, the GNU roff distribution.  It is based
779       on a former version - published under the GPL  -  that  described  only
780       parts of the groff extensions of the output language.  It was rewritten
781       in  2002  by  Bernd  Warken  and  is  maintained  by   Werner   Lemberg
782       ⟨wl@gnu.org⟩.
783
784
785
786Groff Version 1.20.1            9 January 2009                    GROFF_OUT(5)
Impressum