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 in between 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, or gropdf(1) to  output  directly  to
599       PDF.
600
601       · Low-resolution device latin1
602
603         This  is  similar to the high-resolution device except that the posi‐
604         tioning is done at a minor scale.  Some comments (lines starting with
605         #)  were added for clarification; they were not generated by the for‐
606         matter.
607
608         shell> "hell world" | groff -Z -T latin1
609
610         # prologue
611         x T latin1
612         x res 240 24 40
613         x init
614         # begin a new page
615         p1
616         # font setup
617         x font 1 R
618         f1
619         s10
620         # initial positioning on the page
621         V40
622         H0
623         # write text `hell'
624         thell
625         # inform about a space, and do it by a horizontal jump
626         wh24
627         # write text `world'
628         tworld
629         # announce line break, but do nothing because ...
630         n40 0
631         # ... the end of the document has been reached
632         x trailer
633         V2640
634         x stop
635
636       This output can be fed into the postprocessor grotty(1) to get  a  for‐
637       matted text document.
638
639       · Classical style output
640
641         As  a  computer  monitor has a very low resolution compared to modern
642         printers the intermediate output for the X devices can use the  jump-
643         and-write command with its 2-digit displacements.
644
645         shell> "hell world" | groff -Z -T X100
646
647         x T X100
648         x res 100 1 1
649         x init
650         p1
651         x font 5 TR
652         f5
653         s10
654         V16
655         H100
656         # write text with old-style jump-and-write command
657         ch07e07l03lw06w11o07r05l03dh7
658         n16 0
659         x trailer
660         V1100
661         x stop
662
663       This   output  can  be  fed  into  the  postprocessor  xditview(1x)  or
664       gxditview(1) for displaying in X.
665
666       Due to the obsolete jump-and-write command, the text  clusters  in  the
667       classical output are almost unreadable.
668

COMPATIBILITY

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

FILES

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

SEE ALSO

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

AUTHORS

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