GROFF_OUT(5)							  GROFF_OUT(5)

NAME
       groff_out - groff intermediate output format

DESCRIPTION
       This  manual  page  describes the intermediate output format of the GNU
       roff(7) text processing system.	This output is produced by  a  run  of
       the  GNU	 troff(1) program before it is fed into a device postprocessor
       program.

       As the GNU roff processor groff(1) is a wrapper	program	 around	 troff
       that  automatically calls a postprocessor, this output does not show up
       normally.  This is why it is called intermediate within the groff  sys-
       tem.   The groff program provides the option -Z to inhibit postprocess-
       ing, such that the produced intermediate output	is  sent  to  standard
       output just like calling troff manually.

       In this document, the term troff output describes what is output by the
       GNU troff program, while intermediate output  refers  to	 the  language
       that  is accepted by the parser that prepares this output for the post-
       processors.  This parser is smarter on whitespace and implements	 obso-
       lete  elements  for compatibility, otherwise both formats are the same.
       The pre-groff roff versions are denoted as classical troff.

       The main purpose of the intermediate output concept  is	to  facilitate
       the  development	 of  postprocessors  by providing a common programming
       interface for all devices.  It has a language of its own that  is  com-
       pletely different from the groff(7) language.  While the groff language
       is a high-level programming language for text processing, the  interme-
       diate  output  language	is  a  kind of low-level assembler language by
       specifying all positions on the page for writing and drawing.

       The intermediate output produced by groff  is  fairly  readable,	 while
       classical troff output was hard to understand because of strange habits
       that are still supported, but not used any longer by GNU troff.

LANGUAGE CONCEPTS
       During the run of troff, the roff input is cracked down to the informa-
       tion on what has to be printed at what position on the intended device.
       So the language of the intermediate output format can be	 quite	small.
       Its only elements are commands with or without arguments.  In this doc-
       ument, the term "command" always refers to the intermediate output lan-
       guage,  never to the roff language used for document formatting.	 There
       are commands for positioning and text writing,  for  drawing,  and  for
       device controlling.

  Separation
       Classical  troff	 output	 had  strange requirements on whitespace.  The
       groff output parser, however, is smart about whitespace	by  making  it
       maximally  optional.   The  whitespace characters, i.e. the tab, space,
       and newline characters, always have a syntactical  meaning.   They  are
       never  printable	 because  spacing  within the output is always done by
       positioning commands.

       Any sequence of space or tab characters is treated as a single  syntac-
       tical space.  It separates commands and arguments, but is only required
       when there would occur a clashing between  the  command	code  and  the
       arguments  without  the	space.	Most often, this happens when variable
       length command names, arguments, argument lists,	 or  command  clusters
       meet.   Commands	 and  arguments with a known, fixed length need not be
       separated by syntactical space.

       A line break is a syntactical element, too.  Every command argument can
       be  followed  by whitespace, a comment, or a newline character.	Thus a
       syntactical line break is defined to consist  of	 optional  syntactical
       space  that  is optionally followed by a comment, and a newline charac-
       ter.

       The normal commands, those for positioning and text, consist of a  sin-
       gle letter taking a fixed number of arguments.  For historical reasons,
       the parser allows to stack such commands on the same line,  but	fortu-
       nately,	in  groff intermediate output, every command with at least one
       argument is followed by a line break, thus  providing  excellent	 read-
       ability.

       The  other commands