2 .\" The above line should force the use of eqn as a preprocessor
6 Last update: 15 Jul 2003
8 This file is part of groff, the GNU roff type-setting system.
10 Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
11 rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being this .ig-section and AUTHORS, with no
17 Front-Cover Texts, and with no Back-Cover Texts.
19 A copy of the Free Documentation License is included as a file called
20 FDL in the main directory of the groff source package.
23 .\" --------------------------------------------------------------------
25 .\" --------------------------------------------------------------------
27 .do nr groff_out_C \n[.C]
48 .\" ----------------- Document configuration
50 .\" Number register to decide whether the commands `{' and `}' are used
51 .\" 0: disable (actual default); 1: enable
55 Unfortunately, old versions of groff used an illogical position change
56 after some D\~commands (Dp, DP, Dt). If the number register
57 @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
58 after these commands, otherwise the position is not changed.
60 .nr @STUPID_DRAWING_POSITIONING 1
62 .\" ----------------- Syntactical definitions
64 .\" comments when escapes are switched off
67 .\" Begin of macro definitions
73 .c follow-up line for a .TP header
79 .c a bulleted paragraph
86 . IR "shell>" "\h'1m'\f[CB]\$*\f[]\/"
89 .\" End of macro definitions
91 .c ----------------- Semantical definitions
94 .ds @backslash \[rs]\"
95 .ds @linebreak \f[R]\[la]line_break\[ra]\f[]\"
97 .\" Begin of macro definitions
100 .c format: .unit <letter> <punctuation>
104 .c argument in italic with punctuation
110 .c comma separated list of indexed variables
115 . nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c
126 . ab `.offset' needs at least 2 arguments
130 . nop (\f[I]\,\*[@arg1]\/\f[],\ \f[I]\,\*[@arg2]\/\f[])\$*
136 . ab `.indexed_offset' needs at least 4 arguments
143 . ie \B'\*[@index1]' \{\
144 . nop ($\*[@arg1] sub roman \*[@index1]$,\ \c
147 . nop ($\*[@arg1] sub \*[@index1]$,\ \c
149 . ie \B'\*[@index2]' \{\
150 . nop $\*[@arg2] sub roman \*[@index2]$)\$* \c
153 . nop $\*[@arg2] sub \*[@index2]$)\$* \c
157 . nop (\f[I]\*[@arg1]\*[@index1]\f[],\ \c
158 . nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c
165 .c format: .command <name> "<arguments>" <punctuation>
170 . IP "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
174 .c format: .command+ <name> "<arguments>" <punctuation>
175 .c continue previous .command heading
181 . Text "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
185 .c format: .D-command <subcommand> "<arguments>"
189 . IP "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]"
192 .c format: .D-command+ <subcommand> "<arguments>"
193 .c continue previous .D-command heading
198 . Text "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\*[@linebreak]"
204 . ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\"
206 . ds @args \f[I]h1\~v1 h2\~v2\f[]\"
207 . IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]"
210 .c graphics command .D with a variable number of arguments
211 .c format: .D-multiarg <subcommand>
216 . ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \"
217 . as @args "$h sub n$\~$v sub n$\"
220 . ds @args \f[I]h1\~v1 h2\~v2\f[] ... \f[I]\,hn\~vn\f[]\"
221 . IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]"
225 .c format: .x-command <subname> "<arguments>"
231 . ds @args \ \f[I]\,\$*\/\f[]\"
232 . IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]"
237 . RI "(" "\$1" " control command)"
241 .\" End of macro definitions
244 .\" --------------------------------------------------------------------
246 .\" --------------------------------------------------------------------
248 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
251 groff_out \- groff intermediate output format
254 .\" --------------------------------------------------------------------
256 .\" --------------------------------------------------------------------
258 This manual page describes the intermediate output format of the GNU
260 text processing system.
262 This output is produced by a run of the GNU
263 .BR troff (@MAN1EXT@)
264 program before it is fed into a device postprocessor program.
267 As the GNU roff processor
268 .BR groff (@MAN1EXT@)
269 is a wrapper program around troff that automatically calls a
270 postprocessor, this output does not show up normally.
272 This is why it is called
280 program provides the option
282 to inhibit postprocessing, such that the produced intermediate output
283 is sent to standard output just like calling
288 In this document, the term
290 describes what is output by the GNU troff program, while
291 .I intermediate output
292 refers to the language that is accepted by the parser that prepares
293 this output for the postprocessors.
295 This parser is smarter on whitespace and implements obsolete elements
296 for compatibility, otherwise both formats are the same.
298 The pre-groff roff versions are denoted as
303 The main purpose of the intermediate output concept is to facilitate
304 the development of postprocessors by providing a common programming
305 interface for all devices.
307 It has a language of its own that is completely different from the
308 .BR groff (@MAN7EXT@)
313 language is a high-level programming language for text processing, the
314 intermediate output language is a kind of low-level assembler language
315 by specifying all positions on the page for writing and drawing.
318 The intermediate output produced by
320 is fairly readable, while
322 output was hard to understand because of strange habits that are
323 still supported, but not used any longer by
328 .\" --------------------------------------------------------------------
329 .SH "LANGUAGE CONCEPTS"
330 .\" --------------------------------------------------------------------
334 the roff input is cracked down to the information on what has to be
335 printed at what position on the intended device.
337 So the language of the intermediate output format can be quite small.
339 Its only elements are commands with or without arguments.
341 In this document, the term "command" always refers to the intermediate
342 output language, never to the roff language used for document
345 There are commands for positioning and text writing, for drawing, and
346 for device controlling.
349 .\" --------------------------------------------------------------------
351 .\" --------------------------------------------------------------------
353 .I Classical troff output
354 had strange requirements on whitespace.
358 output parser, however, is smart about whitespace by making it
361 The whitespace characters, i.e.\& the
366 characters, always have a syntactical meaning.
368 They are never printable because spacing within the output is always
369 done by positioning commands.
376 characters is treated as a single
380 It separates commands and arguments, but is only required when there
381 would occur a clashing between the command code and the arguments
384 Most often, this happens when variable length command names,
385 arguments, argument lists, or command clusters meet.
387 Commands and arguments with a known, fixed length need not be
388 separated by syntactical space.
391 A line break is a syntactical element, too.
393 Every command argument can be followed by whitespace, a comment, or a
397 .B syntactical line break
398 is defined to consist of optional syntactical space that is optionally
399 followed by a comment, and a newline character.
402 The normal commands, those for positioning and text, consist of a
403 single letter taking a fixed number of arguments.
405 For historical reasons, the parser allows to stack such commands on
406 the same line, but fortunately, in groff intermediate output, every
407 command with at least one argument is followed by a line break, thus
408 providing excellent readability.
411 The other commands \[em] those for drawing and device controlling \[em]
412 have a more complicated structure; some recognize long command names,
413 and some take a variable number of arguments.
419 commands were designed to request a
420 .I syntactical line break
421 after their last argument.
425 has an argument that can stretch over several lines, all other
426 commands must have all of their arguments on the same line as the
427 command, i.e.\& the arguments may not be splitted by a line break.
430 Empty lines, i.e.\& lines containing only space and/or a comment, can
433 They are just ignored.
436 .\" --------------------------------------------------------------------
438 .\" --------------------------------------------------------------------
440 Some commands take integer arguments that are assumed to represent
441 values in a measurement unit, but the letter for the corresponding
443 is not written with the output command arguments; see
444 .BR groff (@MAN7EXT@)
445 and the groff info file for more on this topic.
447 Most commands assume the scale indicator\~\c
449 the basic unit of the device, some use\~\c
453 of the device, while others, such as the color commands expect plain
456 Note that these scale indicators are relative to the chosen device.
458 They are defined by the parameters specified in the device's
461 .BR groff_font (@MAN5EXT@).
464 Note that single characters can have the eighth bit set, as can the
465 names of fonts and special characters.
467 The names of characters and fonts can be of arbitrary length.
469 A character that is to be printed will always be in the current font.
472 A string argument is always terminated by the next whitespace
473 character (space, tab, or newline); an embedded
475 character is regarded as part of the argument, not as the beginning of
478 An integer argument is already terminated by the next non-digit
479 character, which then is regarded as the first character of the next
483 .\" --------------------------------------------------------------------
485 .\" --------------------------------------------------------------------
486 A correct intermediate output document consists of two parts, the
487 prologue and the body.
492 is to set the general device parameters using three exactly specified
497 is guaranteed to consist of the following three lines (in that order):
509 with the arguments set as outlined in the section
510 .BR "Device Control Commands" .
512 But the parser for the intermediate output format is able to swallow
513 additional whitespace and comments as well.
518 is the main section for processing the document data.
520 Syntactically, it is a sequence of any commands different from the
521 ones used in the prologue.
523 Processing is terminated as soon as the first
525 command is encountered; the last line of any groff intermediate output
526 always contains such a command.
529 Semantically, the body is page oriented.
531 A new page is started by a
534 Positioning, writing, and drawing commands are always done within the
535 current page, so they cannot occur before the first
538 Absolute positioning (by the
542 is done relative to the current page, all other positioning
543 is done relative to the current location within this page.
546 .\" --------------------------------------------------------------------
547 .SH "COMMAND REFERENCE"
548 .\" --------------------------------------------------------------------
550 This section describes all intermediate output commands, the classical
551 commands as well as the
556 .\" --------------------------------------------------------------------
557 .SS "Comment Command"
558 .\" --------------------------------------------------------------------
561 .BI # anything \[la]end_of_line\[ra]
564 Ignore any characters from the
566 character up to the next newline character.
569 This command is the only possibility for commenting in the intermediate
572 Each comment can be preceded by arbitrary
575 every command can be terminated by a comment.
578 .\" --------------------------------------------------------------------
579 .SS "Simple Commands"
580 .\" --------------------------------------------------------------------
582 The commands in this subsection have a command code consisting of a
583 single character, taking a fixed number of arguments.
585 Most of them are commands for positioning and text writing.
587 These commands are smart about whitespace.
591 can be inserted before, after, and between the command letter and its
594 All of these commands are stackable, i.e., they can be preceded by
595 other simple commands or followed by arbitrary other commands on the
598 A separating syntactical space is only necessary when two integer
599 arguments would clash or if the preceding argument ends with a string
603 .if (\n[@USE_ENV_STACK] == 1) \{\
605 Open a new environment by copying the actual device configuration data
606 to the environment stack.
608 The current environment is setup by the device specification and
609 manipulated by the setting commands.
613 Close the actual environment (opened by a preceding
615 and restore the previous environment from the environment
616 stack as the actual device configuration data.
618 \} \" endif @USE_ENV_STACK
621 .command C xxx \[la]white_space\[ra]
622 Print a special groff character named
625 The trailing syntactical space or line break is necessary to allow
626 character names of arbitrary length.
628 The character is printed at the current print position;
629 the character's size is read from the font file.
631 The print position is not changed.
637 at the current print position;
638 the character's size is read from the font file.
640 The print position is not changed.
644 Set font to font number\~\c
646 (a non-negative integer).
650 Move right to the absolute vertical position\~\c
652 (a non-negative integer in basic units\~\c
654 relative to left edge of current page.
660 (a non-negative integer) basic units\~\c
662 horizontally to the right.
665 allows negative values for
672 .command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
673 Set the color for text (glyphs), line drawing, and the outline of
674 graphic objects using different color schemes; the analoguous command
675 for the filling color of graphic objects is
678 The color components are specified as integer arguments between 0 and
681 The number of color components and their meaning vary for the
682 different color schemes.
684 These commands are generated by the groff escape sequence
685 .BR \*[@backslash]m .
687 No position changing.
689 These commands are a groff extension.
694 .command mc "cyan magenta yellow"
695 Set color using the CMY color scheme, having the 3\~color components
696 cyan, magenta, and yellow.
700 Set color to the default color value
701 (black in most cases).
703 No component arguments.
707 Set color to the shade of gray given by the argument, an integer
708 between 0 (black) and \n[@maxcolor] (white).
711 .command mk "cyan magenta yellow black"
712 Set color using the CMYK color scheme, having the 4\~color components
713 cyan, magenta, yellow, and black.
715 .command mr "red green blue"
716 Set color using the RGB color scheme, having the 3\~color components
717 red, green, and blue.
723 Print character with index\~\c
725 (an integer, normally non-negative) of the current font.
727 The print position is not changed.
731 is used, negative values are emitted also to indicate an unbreakable space
736 represents an unbreakable space which has a width of 193u.
738 This command is a groff extension.
742 Inform the device about a line break, but no positioning is done by
745 In classical troff, the integer arguments
749 informed about the space before and after the current line to
750 make the intermediate output more human readable without performing
753 In groff, they are just ignored, but they must be provided for
754 compatibility reasons.
758 Begin a new page in the outprint.
760 The page number is set to\~\c
763 This page is completely independent of pages formerly processed even
764 if those have the same page number.
766 The vertical position on the outprint is automatically set to\~0.
768 All positioning, writing, and drawing is always done relative to a
771 must be issued before any of these commands.
783 Classical troff used the unit
791 .command t xxx \[la]white_space\[ra]
792 .command+ t "xxx dummy_arg" \[la]white_space\[ra]
793 Print a word, i.e.\& a sequence of characters
795 terminated by a space character or a line break; an optional second
796 integer argument is ignored (this allows the formatter to generate
797 an even number of arguments).
799 The first character should be printed at the current position, the
800 current horizontal position should then be increased by the width of
801 the first character, and so on for each character.
803 The widths of the characters are read from the font file, scaled for the
804 current point size, and rounded to a multiple of the horizontal
807 Special characters cannot be printed using this command (use the
809 command for named characters).
811 This command is a groff extension; it is only used for devices whose
816 .BR groff_font (@MAN5EXT@).
819 .command u "n xxx" \[la]white_space\[ra]
820 Print word with track kerning.
822 This is the same as the
824 command except that after printing each character, the current
825 horizontal position is increased by the sum of the width of that
831 This command is a groff extension; it is only used for devices whose
836 .BR groff_font (@MAN5EXT@).
840 Move down to the absolute vertical position\~\c
842 (a non-negative integer in basic units\~\c
844 relative to upper edge of current page.
854 is a non-negative integer).
857 allows negative values for
865 Informs about a paddable whitespace to increase readability.
867 The spacing itself must be performed explicitly by a move command.
870 .\" --------------------------------------------------------------------
871 .SS "Graphics Commands"
872 .\" --------------------------------------------------------------------
874 Each graphics or drawing command in the intermediate output starts
877 followed by one or two characters that specify a subcommand; this
878 is followed by a fixed or variable number of integer arguments that
879 are separated by a single space character.
883 may not be followed by another command on the same line
884 (apart from a comment), so each
886 is terminated by a syntactical line break.
890 output follows the classical spacing rules (no space between command
891 and subcommand, all arguments are preceded by a single space
892 character), but the parser allows optional space between the command
893 letters and makes the space before the first argument optional.
895 As usual, each space can be any sequence of tab and space characters.
898 Some graphics commands can take a variable number of arguments.
900 In this case, they are integers representing a size measured in basic
906 stand for horizontal distances where positive means right, negative
911 stand for vertical distances where positive means down, negative up.
913 All these distances are offsets relative to the current location.
916 Unless indicated otherwise, each graphics command directly corresponds
921 .BR groff (@MAN7EXT@).
924 Unknown D\~commands are assumed to be device-specific.
926 Its arguments are parsed as strings; the whole information is then
927 sent to the postprocessor.
930 In the following command reference, the syntax element
931 .I \[la]line_break\[ra]
933 .I syntactical line break
934 as defined in section
939 Draw B-spline from current position to offset
940 .indexed_offset h 1 v 1 ,
942 .indexed_offset h 2 v 2
943 if given, etc.\& up to
944 .indexed_offset h n v n .
945 This command takes a variable number of argument pairs;
946 the current position is moved to the terminal point of the drawn curve.
950 Draw arc from current position to
951 .indexed_offset h 1 v 1 \|+\|\c
952 .indexed_offset h 2 v 2
954 .indexed_offset h 1 v 1 ;
955 then move the current position to the final point of the arc.
959 .D-command+ C d dummy_arg
960 Draw a solid circle using the current fill color with diameter\~\c
962 (integer in basic units\~\c
964 with leftmost point at the current position; then move the current
965 position to the rightmost point of the circle.
967 An optional second integer argument is ignored (this allows to the
968 formatter to generate an even number of arguments).
970 This command is a groff extension.
974 Draw circle line with diameter\~\c
976 (integer in basic units\~\c
978 with leftmost point at the current position; then move the current
979 position to the rightmost point of the circle.
983 Draw a solid ellipse in the current fill color with a horizontal
986 and a vertical diameter of\~\c
988 (both integers in basic units\~\c
990 with the leftmost point at the current position; then move to the
991 rightmost point of the ellipse.
993 This command is a groff extension.
997 Draw an outlined ellipse with a horizontal diameter of\~\c
999 and a vertical diameter of\~\c
1001 (both integers in basic units\~\c
1003 with the leftmost point at current position; then move to the
1004 rightmost point of the ellipse.
1007 .D-command F "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
1008 Set fill color for solid drawing objects using different color
1009 schemes; the analoguous command for setting the color of text, line
1010 graphics, and the outline of graphic objects is
1013 The color components are specified as integer arguments between 0 and
1016 The number of color components and their meaning vary for the
1017 different color schemes.
1019 These commands are generated by the groff escape sequences
1020 .B \*[@backslash]D'F\ .\|.\|.'
1023 (with no other corresponding graphics commands).
1025 No position changing.
1027 This command is a groff extension.
1032 .D-command Fc "cyan magenta yellow"
1033 Set fill color for solid drawing objects using the CMY color scheme,
1034 having the 3\~color components cyan, magenta, and yellow.
1038 Set fill color for solid drawing objects to the default fill color value
1039 (black in most cases).
1041 No component arguments.
1044 .D-command Fg "gray"
1045 Set fill color for solid drawing objects to the shade of gray given by
1046 the argument, an integer between 0 (black) and \n[@maxcolor] (white).
1049 .D-command Fk "cyan magenta yellow black"
1050 Set fill color for solid drawing objects using the CMYK color scheme,
1051 having the 4\~color components cyan, magenta, yellow, and black.
1053 .D-command Fr "red green blue"
1054 Set fill color for solid drawing objects using the RGB color scheme,
1055 having the 3\~color components red, green, and blue.
1063 must be an integer in the range -32767 to 32767.
1067 .RI "0 \[<=] " n " \[<=] 1000"
1068 Set the color for filling solid drawing objects to a shade of gray,
1069 where 0 corresponds to solid white, 1000 (the default) to solid black,
1070 and values in between to intermediate shades of gray; this is
1071 obsoleted by command
1075 .IR n " < 0 or " n " > 1000"
1076 Set the filling color to the color that is currently being used for
1077 the text and the outline, see command
1079 For example, the command sequence
1085 mg 0 0 \n[@maxcolor]
1091 sets all colors to blue.
1095 No position changing.
1097 This command is a groff extension.
1103 Draw line from current position to offset
1105 (integers in basic units\~\c
1107 then set current position to the end of the drawn line.
1111 Draw a polygon line from current position to offset
1113 from there to offset
1117 and from there back to the starting position.
1119 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1120 For historical reasons, the position is changed by adding the sum of
1121 all arguments with odd index to the actual horizontal position and the
1122 even ones to the vertical position.
1124 Although this doesn't make sense it is kept for compatibility.
1128 As the polygon is closed, the end of drawing is the starting point, so
1129 the position doesn't change.
1132 This command is a groff extension.
1136 The same macro as the corresponding
1138 command with the same arguments, but draws a solid polygon in the
1139 current fill color rather than an outlined polygon.
1141 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1142 The position is changed in the same way as with
1146 No position changing.
1148 This command is a groff extension.
1152 Set the current line thickness to\~\c
1154 (an integer in basic units\~\c
1160 select the smallest available line thickness; if
1162 set the line thickness proportional to the point size (this is the
1163 default before the first
1165 command was specified).
1167 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1168 For historical reasons, the horizontal position is changed by adding
1169 the argument to the actual horizontal position, while the vertical
1170 position is not changed.
1172 Although this doesn't make sense it is kept for compatibility.
1176 No position changing.
1178 This command is a groff extension.
1181 .\" --------------------------------------------------------------------
1182 .SS "Device Control Commands"
1183 .\" --------------------------------------------------------------------
1185 Each device control command starts with the letter
1187 followed by a space character (optional or arbitrary space/\:tab in
1188 groff) and a subcommand letter or word; each argument (if any) must be
1189 preceded by a syntactical space.
1193 commands are terminated by a
1194 .IR "syntactical line break" ;
1195 no device control command can be followed by another command on the same
1196 line (except a comment).
1199 The subcommand is basically a single letter, but to increase
1200 readability, it can be written as a word, i.e.\& an arbitrary sequence
1201 of characters terminated by the next tab, space, or newline character.
1203 All characters of the subcommand word but the first are simply ignored.
1207 outputs the initialization command
1211 and the resolution command
1220 resp.\& are accepted as well to mean the same commands.
1223 In the following, the syntax element
1224 .I \[la]line_break\[ra]
1226 .I syntactical line break
1227 as defined in section
1234 as the intended name for the current file in error reports.
1236 This is useful for remembering the original file name when groff uses
1237 an internal piping mechanism.
1239 The input file is not changed by this command.
1241 This command is a groff extension.
1246 Mount font position\~\c
1248 (a non-negative integer) with font named\~\c
1252 .BR groff_font (@MAN5EXT@).
1257 Set character height to\~\c
1259 (a positive integer in scaled points\~\c
1262 Classical troff used the unit
1265 instead; see section
1273 This is the third command of the prologue.
1280 The classical documentation reads
1281 .I pause device, can be
1285 .x-command r "n\ h\ v"
1291 is the minimal horizontal motion, and
1293 the minimal vertical motion possible with this device; all arguments
1294 are positive integers in basic units\~\c
1298 This is the second command of the prologue.
1305 degrees (an integer in basic units\~\c
1311 Terminates the processing of the current file; issued as the last
1312 command of any intermediate troff output.
1317 Generate trailer information, if any.
1321 this is actually just ignored.
1326 Set name of device to word
1328 a sequence of characters ended by the next whitespace character.
1330 The possible device names coincide with those from the groff
1334 This is the first command of the prologue.
1339 Configure underlining of spaces.
1343 is\~1, start underlining of spaces;
1346 is\~0, stop underlining of spaces.
1348 This is needed for the
1352 mode and is ignored otherwise.
1354 This command is a groff extension.
1357 .x-command X anything
1361 uninterpreted to the device.
1363 If the line following this command starts with a
1365 character this line is interpreted as a continuation line in the
1370 is ignored, but a newline character is sent instead to the device, the
1371 rest of the line is sent uninterpreted.
1373 The same applies to all following lines until the first character of a
1378 This command is generated by the
1381 .BR \*[@backslash]X .
1383 The line-continuing feature is a groff extension.
1386 .\" --------------------------------------------------------------------
1387 .SS "Obsolete Command"
1388 .\" --------------------------------------------------------------------
1392 output, the writing of a single character was mostly done by a very
1393 strange command that combined a horizontal move and the printing of a
1396 It didn't have a command code, but is represented by a 3-character
1397 argument consisting of exactly 2\~digits and a character.
1403 (exactly two decimal digits) basic units\~\c
1405 then print character\~\c
1410 In groff, arbitrary syntactical space around and within this command
1411 is allowed to be added.
1413 Only when a preceding command on the same line ends with an argument
1414 of variable length a separating space is obligatory.
1419 large clusters of these and other commands were used, mostly without
1420 spaces; this made such output almost unreadable.
1425 For modern high-resolution devices, this command does not make sense
1426 because the width of the characters can become much larger than two
1429 In groff, this is only used for the devices
1441 provide a better functionality.
1444 .\" --------------------------------------------------------------------
1445 .SH "POSTPROCESSING"
1446 .\" --------------------------------------------------------------------
1450 postprocessors are programs that have the task to translate the
1451 intermediate output into actions that are sent to a device.
1453 A device can be some piece of hardware such as a printer, or a software
1454 file format suitable for graphical or text processing.
1458 system provides powerful means that make the programming of such
1459 postprocessors an easy task.
1461 There is a library function that parses the intermediate output and
1462 sends the information obtained to the device via methods of a class
1463 with a common interface for each device.
1467 postprocessor must only redefine the methods of this class.
1469 For details, see the reference in section
1473 .\" --------------------------------------------------------------------
1475 .\" --------------------------------------------------------------------
1477 This section presents the intermediate output generated from the same
1478 input for three different devices.
1480 The input is the sentence
1482 fed into groff on the command line.
1485 High-resolution device
1491 .ShellCommand echo "hell world" | groff -Z -T ps
1519 This output can be fed into the postprocessor
1520 .BR grops (@MAN1EXT@)
1521 to get its representation as a PostScript file.
1525 Low-resolution device
1531 This is similar to the high-resolution device except that the
1532 positioning is done at a minor scale.
1534 Some comments (lines starting with
1536 were added for clarification; they were not generated by the
1540 .ShellCommand echo "hell world" | groff -Z -T latin1
1549 .I # begin a new page
1557 .I # initial positioning on the page
1561 .I # write text `hell'
1564 .I # inform about a space, and do it by a horizontal jump
1567 .I # write text `world'
1570 .I # announce line break, but do nothing because ...
1573 .I # ... the end of the document has been reached
1583 This output can be fed into the postprocessor
1584 .BR grotty (@MAN1EXT@)
1585 to get a formatted text document.
1589 Classical style output
1594 As a computer monitor has a very low resolution compared to modern
1595 printers the intermediate output for the X\~devices can use the
1596 jump-and-write command with its 2-digit displacements.
1599 .ShellCommand echo "hell world" | groff -Z -T X100
1613 .I # write text with old-style jump-and-write command
1615 ch07e07l03lw06w11o07r05l03dh7
1625 This output can be fed into the postprocessor
1628 .BR gxditview (@MAN1EXT@)
1629 for displaying in\~X.
1632 Due to the obsolete jump-and-write command, the text clusters in the
1633 classical output are almost unreadable.
1636 .\" --------------------------------------------------------------------
1638 .\" --------------------------------------------------------------------
1640 The intermediate output language of the
1642 was first documented in
1647 intermediate output format is compatible with this specification
1648 except for the following features.
1650 The classical quasi device independence is not yet implemented.
1653 The old hardware was very different from what we use today.
1655 So the groff devices are also fundamentally different from the ones in
1658 For example, the classical PostScript device was called
1660 and had a resolution of 720 units per inch,
1663 device has a resolution of 72000 units per inch.
1665 Maybe, by implementing some rescaling mechanism similar to the
1666 classical quasi device independence, these could be integrated into
1670 The B-spline command
1672 is correctly handled by the intermediate output parser, but the
1673 drawing routines aren't implemented in some of the postprocessor
1676 The argument of the commands
1680 has the implicit unit scaled point\~\c
1682 in groff, while classical troff had point (\c
1685 This isn't an incompatibility, but a compatible extension,
1686 for both units coincide for all devices without a
1688 parameter, including all classical and the groff text devices.
1690 The few groff devices with a sizescale parameter either did
1691 not exist, had a different name, or seem to have had a different
1694 So conflicts with classical devices are very unlikely.
1696 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1698 The position changing after the commands
1703 is illogical, but as old versions of groff used this feature it is
1704 kept for compatibility reasons.
1705 .\} \" @STUPID_DRAWING_POSITIONING
1708 Temporarily, there existed some confusion on the positioning after the
1710 commands that are groff extensions.
1712 This has been clarified by establishing the classical rule for all
1713 groff drawing commands:
1717 .I The position after a graphic object has been drawn is at its end;
1718 .I for circles and ellipses, the "end" is at the right side.
1722 From this, the positionings specified for the drawing commands above
1723 follow quite naturally.
1724 .\} \" @STUPID_DRAWING_POSITIONING
1727 The differences between groff and classical troff are documented in
1728 .BR groff_diff (@MAN7EXT@).
1731 .\" --------------------------------------------------------------------
1733 .\" --------------------------------------------------------------------
1736 .BI @FONTDIR@/dev name /DESC
1737 Device description file for device
1741 .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
1742 Defines the parser and postprocessor for the intermediate output.
1744 It is located relative to the top directory of the
1749 This parser is the definitive specification of the
1751 intermediate output format.
1754 .\" --------------------------------------------------------------------
1756 .\" --------------------------------------------------------------------
1759 .BR groff (@MAN7EXT@)
1760 refers to a manual page; here
1764 of the man-page documentation system.
1766 To read the example, look up section\~@MAN7EXT@ in your desktop help
1767 system or call from the shell prompt
1771 .ShellCommand man @MAN7EXT@ groff
1775 For more details, see
1779 .BR groff (@MAN1EXT@)
1782 and further readings on groff.
1785 .BR groff (@MAN7EXT@)
1788 language such as numerical units and escape sequences.
1791 .BR groff_font (@MAN5EXT@)
1792 for details on the device scaling parameters of the
1797 .BR troff (@MAN1EXT@)
1798 generates the device-independent intermediate output.
1801 .BR roff (@MAN7EXT@)
1802 for historical aspects and the general structure of roff systems.
1805 .BR groff_diff (@MAN7EXT@)
1806 The differences between the intermediate output in groff and classical
1810 .BR \%grodvi (@MAN1EXT@),
1811 .BR \%grohtml (@MAN1EXT@),
1812 .BR \%grolbp (@MAN1EXT@),
1813 .BR \%grolj4 (@MAN1EXT@),
1814 .BR \%grops (@MAN1EXT@),
1815 .BR \%grotty (@MAN1EXT@)
1818 the groff postprocessor programs.
1822 For a treatment of all aspects of the groff system within a single
1827 It can be read within the integrated help systems, within
1829 or from the shell prompt by
1832 .ShellCommand info groff
1837 .I classical troff output language
1838 is described in two AT&T Bell Labs CSTR documents available on-line at
1839 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
1840 "Bell Labs CSTR site" .
1844 .I A Typesetter-independent TROFF
1847 is the original and most concise documentation on the output language;
1849 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
1853 The 1992 revision of the
1854 .I Nroff/\:Troff User's Manual
1861 regarding the output language;
1863 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
1866 .\" --------------------------------------------------------------------
1868 .\" --------------------------------------------------------------------
1870 Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
1872 This document is distributed under the terms of the FDL (GNU Free
1873 Documentation License) version 1.1 or later.
1875 You should have received a copy of the FDL with this package; it is also
1876 available on-line at the
1877 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1880 This document is part of
1882 the GNU roff distribution.
1884 It is based on a former version \- published under the GPL \- that
1885 described only parts of the
1887 extensions of the output language.
1889 It has been rewritten 2002 by
1890 .MTO bwarken@mayn.de "Bernd Warken"
1891 and is maintained by
1892 .MTO wl@gnu.org "Werner Lemberg" .
1896 .\" --------------------------------------------------------------------
1898 .\" --------------------------------------------------------------------
1900 .\" Local Variables: