2 .\" The above line should force the use of eqn as a preprocessor
6 Last update: 2 Jul 2005
8 This file is part of groff, the GNU roff type-setting system.
10 Copyright (C) 1989, 2001, 2002, 2003, 2004, 2005
11 Free Software Foundation, Inc.
12 rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with the
17 Invariant Sections being this .ig-section and AUTHORS, with no
18 Front-Cover Texts, and with no Back-Cover Texts.
20 A copy of the Free Documentation License is included as a file called
21 FDL in the main directory of the groff source package.
24 .\" --------------------------------------------------------------------
26 .\" --------------------------------------------------------------------
28 .do nr groff_out_C \n[.C]
49 .\" ----------------- Document configuration
51 .\" Number register to decide whether the commands `{' and `}' are used
52 .\" 0: disable (actual default); 1: enable
56 Unfortunately, old versions of groff used an illogical position change
57 after some D\~commands (Dp, DP, Dt). If the number register
58 @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
59 after these commands, otherwise the position is not changed.
61 .nr @STUPID_DRAWING_POSITIONING 1
63 .\" ----------------- Syntactical definitions
65 .\" comments when escapes are switched off
68 .\" Begin of macro definitions
74 .c follow-up line for a .TP header
80 .c a bulleted paragraph
87 . IR "shell>" "\h'1m'\f[CB]\$*\f[]\/"
90 .\" End of macro definitions
92 .c ----------------- Semantical definitions
95 .ds @backslash \[rs]\"
96 .ds @linebreak \f[R]\[la]line_break\[ra]\f[]\"
98 .\" Begin of macro definitions
101 .c format: .unit <letter> <punctuation>
105 .c argument in italic with punctuation
111 .c comma separated list of indexed variables
116 . nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c
127 . ab `.offset' needs at least 2 arguments
131 . nop (\f[I]\,\*[@arg1]\/\f[],\ \f[I]\,\*[@arg2]\/\f[])\$*
137 . ab `.indexed_offset' needs at least 4 arguments
144 . ie \B'\*[@index1]' \{\
145 . nop ($\*[@arg1] sub roman \*[@index1]$,\ \c
148 . nop ($\*[@arg1] sub \*[@index1]$,\ \c
150 . ie \B'\*[@index2]' \{\
151 . nop $\*[@arg2] sub roman \*[@index2]$)\$* \c
154 . nop $\*[@arg2] sub \*[@index2]$)\$* \c
158 . nop (\f[I]\*[@arg1]\*[@index1]\f[],\ \c
159 . nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c
166 .c format: .command <name> "<arguments>" <punctuation>
171 . IP "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
175 .c format: .command+ <name> "<arguments>" <punctuation>
176 .c continue previous .command heading
182 . Text "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
186 .c format: .D-command <subcommand> "<arguments>"
190 . IP "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]"
193 .c format: .D-command+ <subcommand> "<arguments>"
194 .c continue previous .D-command heading
199 . Text "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\*[@linebreak]"
205 . ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\"
207 . ds @args \f[I]h1\~v1 h2\~v2\f[]\"
208 . IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]"
211 .c graphics command .D with a variable number of arguments
212 .c format: .D-multiarg <subcommand>
217 . ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \"
218 . as @args "$h sub n$\~$v sub n$\"
221 . ds @args \f[I]h1\~v1 h2\~v2\f[] ... \f[I]\,hn\~vn\f[]\"
222 . IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]"
226 .c format: .x-command <subname> "<arguments>"
232 . ds @args \ \f[I]\,\$*\/\f[]\"
233 . IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]"
238 . RI "(" "\$1" " control command)"
242 .\" End of macro definitions
245 .\" --------------------------------------------------------------------
247 .\" --------------------------------------------------------------------
249 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
252 groff_out \- groff intermediate output format
255 .\" --------------------------------------------------------------------
257 .\" --------------------------------------------------------------------
259 This manual page describes the
260 .I intermediate output
263 text processing system
264 .BR groff (@MAN1EXT@).
266 This output is produced by a run of the GNU
267 .BR @g@troff (@MAN1EXT@)
270 It contains already all device-specific information, but it is not yet
271 fed into a device postprocessor program.
278 .BR groff (@MAN1EXT@)
279 is a wrapper program around
281 that automatically calls a
282 postprocessor, this output does not show up normally.
284 This is why it is called
292 program provides the option
294 to inhibit postprocessing, such that the produced
295 .I intermediate output
296 is sent to standard output just like calling
302 In this document, the term
304 describes what is output by the GNU
307 .I intermediate output
308 refers to the language that is accepted by the parser that prepares
309 this output for the postprocessors.
311 This parser is smarter on whitespace and implements obsolete elements
312 for compatibility, otherwise both formats are the same.
314 Both formats can be viewed directly with
315 .BR \%gxditview (@MAN1EXT@).
319 The main purpose of the
320 .I intermediate output
321 concept is to facilitate the development of postprocessors by
322 providing a common programming interface for all devices.
324 It has a language of its own that is completely different from the
325 .BR groff (@MAN7EXT@)
330 language is a high-level programming language for text processing, the
331 .I intermediate output
332 language is a kind of low-level assembler language by specifying all
333 positions on the page for writing and drawing.
340 versions are denoted as
344 .I intermediate output
347 is fairly readable, while
349 output was hard to understand because of strange habits that are
350 still supported, but not used any longer by
355 .\" --------------------------------------------------------------------
356 .SH "LANGUAGE CONCEPTS"
357 .\" --------------------------------------------------------------------
363 input is cracked down to the information on what has to be printed at
364 what position on the intended device.
366 So the language of the
367 .I intermediate output
368 format can be quite small.
370 Its only elements are commands with or without arguments.
372 In this document, the term "command" always refers to the
373 .I intermediate output
374 language, never to the
376 language used for document formatting.
378 There are commands for positioning and text writing, for drawing, and
379 for device controlling.
382 .\" --------------------------------------------------------------------
384 .\" --------------------------------------------------------------------
386 .I Classical troff output
387 had strange requirements on whitespace.
391 output parser, however, is smart about whitespace by making it
394 The whitespace characters, i.e., the
399 characters, always have a syntactical meaning.
401 They are never printable because spacing within the output is always
402 done by positioning commands.
410 characters is treated as a single
414 It separates commands and arguments, but is only required when there
415 would occur a clashing between the command code and the arguments
418 Most often, this happens when variable length command names,
419 arguments, argument lists, or command clusters meet.
421 Commands and arguments with a known, fixed length need not be
428 A line break is a syntactical element, too.
430 Every command argument can be followed by whitespace, a comment, or a
434 .I syntactical line break
435 is defined to consist of optional
437 that is optionally followed by a comment, and a newline character.
441 The normal commands, those for positioning and text, consist of a
442 single letter taking a fixed number of arguments.
444 For historical reasons, the parser allows to stack such commands on
445 the same line, but fortunately, in
446 .I groff intermediate
448 every command with at least one argument is followed by a line break,
449 thus providing excellent readability.
452 The other commands \[em] those for drawing and device controlling \[em]
453 have a more complicated structure; some recognize long command names,
454 and some take a variable number of arguments.
460 commands were designed to request a
461 .I syntactical line break
462 after their last argument.
466 has an argument that can stretch over several lines, all other
467 commands must have all of their arguments on the same line as the
468 command, i.e., the arguments may not be splitted by a line break.
471 Empty lines, i.e., lines containing only space and/or a comment, can
474 They are just ignored.
477 .\" --------------------------------------------------------------------
479 .\" --------------------------------------------------------------------
481 Some commands take integer arguments that are assumed to represent
482 values in a measurement unit, but the letter for the corresponding
484 is not written with the output command arguments; see
485 .BR groff (@MAN7EXT@)
488 for more on this topic.
490 Most commands assume the scale indicator\~\c
492 the basic unit of the device, some use\~\c
496 of the device, while others, such as the color commands expect plain
499 Note that these scale indicators are relative to the chosen device.
501 They are defined by the parameters specified in the device's
504 .BR groff_font (@MAN5EXT@).
508 Note that single characters can have the eighth bit set, as can the
509 names of fonts and special characters.
511 The names of characters and fonts can be of arbitrary length.
513 A character that is to be printed will always be in the current font.
517 A string argument is always terminated by the next whitespace
518 character (space, tab, or newline); an embedded
520 character is regarded as part of the argument, not as the beginning of
523 An integer argument is already terminated by the next non-digit
524 character, which then is regarded as the first character of the next
528 .\" --------------------------------------------------------------------
530 .\" --------------------------------------------------------------------
532 .I intermediate output
533 document consists of two parts, the
541 is to set the general device parameters using three exactly specified
546 is guaranteed to consist of the following three lines (in that order):
558 with the arguments set as outlined in the section
559 .BR "Device Control Commands" .
561 But the parser for the
562 .I intermediate output
563 format is able to swallow additional whitespace and comments as well.
569 is the main section for processing the document data.
571 Syntactically, it is a sequence of any commands different from the
575 Processing is terminated as soon as the first
577 command is encountered; the last line of any
578 .I groff intermediate output
579 always contains such a command.
587 A new page is started by a
590 Positioning, writing, and drawing commands are always done within the
591 current page, so they cannot occur before the first
594 Absolute positioning (by the
598 is done relative to the current page, all other positioning
599 is done relative to the current location within this page.
602 .\" --------------------------------------------------------------------
603 .SH "COMMAND REFERENCE"
604 .\" --------------------------------------------------------------------
606 This section describes all
607 .I intermediate output
608 commands, the classical commands as well as the
613 .\" --------------------------------------------------------------------
614 .SS "Comment Command"
615 .\" --------------------------------------------------------------------
618 .BI # anything \[la]end_of_line\[ra]
621 Ignore any characters from the
623 character up to the next newline character.
626 This command is the only possibility for commenting in the
630 Each comment can be preceded by arbitrary
633 every command can be terminated by a comment.
636 .\" --------------------------------------------------------------------
637 .SS "Simple Commands"
638 .\" --------------------------------------------------------------------
640 The commands in this subsection have a command code consisting of a
641 single character, taking a fixed number of arguments.
643 Most of them are commands for positioning and text writing.
645 These commands are smart about whitespace.
649 can be inserted before, after, and between the command letter and its
652 All of these commands are stackable, i.e., they can be preceded by
653 other simple commands or followed by arbitrary other commands on the
658 is only necessary when two integer arguments would clash or if the
659 preceding argument ends with a string argument.
662 .if (\n[@USE_ENV_STACK] == 1) \{\
664 Open a new environment by copying the actual device configuration data
665 to the environment stack.
667 The current environment is setup by the device specification and
668 manipulated by the setting commands.
672 Close the actual environment (opened by a preceding
674 and restore the previous environment from the environment
675 stack as the actual device configuration data.
677 \} \" endif @USE_ENV_STACK
680 .command C xxx \[la]white_space\[ra]
681 Print a special groff character named
688 is necessary to allow character names of arbitrary length.
690 The character is printed at the current print position; the
691 character's size is read from the font file.
693 The print position is not changed.
699 at the current print position;
700 the character's size is read from the font file.
702 The print position is not changed.
706 Set font to font number\~\c
708 (a non-negative integer).
712 Move right to the absolute vertical position\~\c
714 (a non-negative integer in basic units\~\c
716 relative to left edge of current page.
722 (a non-negative integer) basic units\~\c
724 horizontally to the right.
727 allows negative values for
734 .command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
735 Set the color for text (glyphs), line drawing, and the outline of
736 graphic objects using different color schemes; the analoguous command
737 for the filling color of graphic objects is
740 The color components are specified as integer arguments between 0 and
743 The number of color components and their meaning vary for the
744 different color schemes.
746 These commands are generated by the
749 .BR \*[@backslash]m .
751 No position changing.
760 .command mc "cyan magenta yellow"
761 Set color using the CMY color scheme, having the 3\~color components
762 cyan, magenta, and yellow.
766 Set color to the default color value
767 (black in most cases).
769 No component arguments.
773 Set color to the shade of gray given by the argument, an integer
774 between 0 (black) and \n[@maxcolor] (white).
777 .command mk "cyan magenta yellow black"
778 Set color using the CMYK color scheme, having the 4\~color components
779 cyan, magenta, yellow, and black.
781 .command mr "red green blue"
782 Set color using the RGB color scheme, having the 3\~color components
783 red, green, and blue.
789 Print character with index\~\c
791 (an integer, normally non-negative) of the current font.
793 The print position is not changed.
797 is used, negative values are emitted also to indicate an unbreakable space
802 represents an unbreakable space which has a width of 193u.
810 Inform the device about a line break, but no positioning is done by
816 the integer arguments
820 informed about the space before and after the current line to
822 .I intermediate output
823 more human readable without performing any action.
827 they are just ignored, but they must be provided for compatibility
832 Begin a new page in the outprint.
834 The page number is set to\~\c
837 This page is completely independent of pages formerly processed even
838 if those have the same page number.
840 The vertical position on the outprint is automatically set to\~0.
842 All positioning, writing, and drawing is always done relative to a
845 must be issued before any of these commands.
866 .command t xxx \[la]white_space\[ra]
867 .command+ t "xxx dummy_arg" \[la]white_space\[ra]
868 Print a word, i.e., a sequence of characters
870 terminated by a space character or a line break; an optional second
871 integer argument is ignored (this allows the formatter to generate
872 an even number of arguments).
874 The first character should be printed at the current position, the
875 current horizontal position should then be increased by the width of
876 the first character, and so on for each character.
878 The widths of the characters are read from the font file, scaled for the
879 current point size, and rounded to a multiple of the horizontal
882 Special characters cannot be printed using this command (use the
884 command for named characters).
888 extension; it is only used for devices whose
893 .BR groff_font (@MAN5EXT@).
896 .command u "n xxx" \[la]white_space\[ra]
897 Print word with track kerning.
899 This is the same as the
901 command except that after printing each character, the current
902 horizontal position is increased by the sum of the width of that
910 extension; it is only used for devices whose
915 .BR groff_font (@MAN5EXT@).
919 Move down to the absolute vertical position\~\c
921 (a non-negative integer in basic units\~\c
923 relative to upper edge of current page.
933 is a non-negative integer).
936 allows negative values for
944 Informs about a paddable whitespace to increase readability.
946 The spacing itself must be performed explicitly by a move command.
949 .\" --------------------------------------------------------------------
950 .SS "Graphics Commands"
951 .\" --------------------------------------------------------------------
953 Each graphics or drawing command in the
954 .I intermediate output
955 starts with the letter\~\c
957 followed by one or two characters that specify a subcommand; this
958 is followed by a fixed or variable number of integer arguments that
959 are separated by a single space character.
964 may not be followed by another command on the same line (apart from a
975 output follows the classical spacing rules (no space between command
976 and subcommand, all arguments are preceded by a single space
977 character), but the parser allows optional space between the command
978 letters and makes the space before the first argument optional.
980 As usual, each space can be any sequence of tab and space characters.
984 Some graphics commands can take a variable number of arguments.
986 In this case, they are integers representing a size measured in basic
992 stand for horizontal distances where positive means right, negative
997 stand for vertical distances where positive means down, negative up.
999 All these distances are offsets relative to the current location.
1003 Unless indicated otherwise, each graphics command directly corresponds
1007 escape sequence; see
1008 .BR groff (@MAN7EXT@).
1014 \~commands are assumed to be device-specific.
1016 Its arguments are parsed as strings; the whole information is then
1017 sent to the postprocessor.
1021 In the following command reference, the syntax element
1022 .I \[la]line_break\[ra]
1024 .I syntactical line break
1025 as defined in section
1030 Draw B-spline from current position to offset
1031 .indexed_offset h 1 v 1 ,
1033 .indexed_offset h 2 v 2
1034 if given, etc.\& up to
1035 .indexed_offset h n v n .
1036 This command takes a variable number of argument pairs; the current
1037 position is moved to the terminal point of the drawn curve.
1041 Draw arc from current position to
1042 .indexed_offset h 1 v 1 \|+\|\c
1043 .indexed_offset h 2 v 2
1045 .indexed_offset h 1 v 1 ;
1046 then move the current position to the final point of the arc.
1050 .D-command+ C d dummy_arg
1051 Draw a solid circle using the current fill color with diameter\~\c
1053 (integer in basic units\~\c
1055 with leftmost point at the current position; then move the current
1056 position to the rightmost point of the circle.
1058 An optional second integer argument is ignored (this allows to the
1059 formatter to generate an even number of arguments).
1067 Draw circle line with diameter\~\c
1069 (integer in basic units\~\c
1071 with leftmost point at the current position; then move the current
1072 position to the rightmost point of the circle.
1076 Draw a solid ellipse in the current fill color with a horizontal
1079 and a vertical diameter of\~\c
1081 (both integers in basic units\~\c
1083 with the leftmost point at the current position; then move to the
1084 rightmost point of the ellipse.
1092 Draw an outlined ellipse with a horizontal diameter of\~\c
1094 and a vertical diameter of\~\c
1096 (both integers in basic units\~\c
1098 with the leftmost point at current position; then move to the
1099 rightmost point of the ellipse.
1102 .D-command F "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
1103 Set fill color for solid drawing objects using different color
1104 schemes; the analoguous command for setting the color of text, line
1105 graphics, and the outline of graphic objects is
1108 The color components are specified as integer arguments between 0 and
1111 The number of color components and their meaning vary for the
1112 different color schemes.
1114 These commands are generated by the
1117 .B \*[@backslash]D'F\ .\|.\|.'
1120 (with no other corresponding graphics commands).
1122 No position changing.
1131 .D-command Fc "cyan magenta yellow"
1132 Set fill color for solid drawing objects using the CMY color scheme,
1133 having the 3\~color components cyan, magenta, and yellow.
1137 Set fill color for solid drawing objects to the default fill color value
1138 (black in most cases).
1140 No component arguments.
1143 .D-command Fg "gray"
1144 Set fill color for solid drawing objects to the shade of gray given by
1145 the argument, an integer between 0 (black) and \n[@maxcolor] (white).
1148 .D-command Fk "cyan magenta yellow black"
1149 Set fill color for solid drawing objects using the CMYK color scheme,
1150 having the 4\~color components cyan, magenta, yellow, and black.
1152 .D-command Fr "red green blue"
1153 Set fill color for solid drawing objects using the RGB color scheme,
1154 having the 3\~color components red, green, and blue.
1162 must be an integer in the range -32767 to 32767.
1166 .RI "0 \[<=] " n " \[<=] 1000"
1167 Set the color for filling solid drawing objects to a shade of gray,
1168 where 0 corresponds to solid white, 1000 (the default) to solid black,
1169 and values in between to intermediate shades of gray; this is
1170 obsoleted by command
1174 .IR n " < 0 or " n " > 1000"
1175 Set the filling color to the color that is currently being used for
1176 the text and the outline, see command
1178 For example, the command sequence
1184 mg 0 0 \n[@maxcolor]
1190 sets all colors to blue.
1195 No position changing.
1205 Draw line from current position to offset
1207 (integers in basic units\~\c
1209 then set current position to the end of the drawn line.
1213 Draw a polygon line from current position to offset
1215 from there to offset
1219 and from there back to the starting position.
1221 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1222 For historical reasons, the position is changed by adding the sum of
1223 all arguments with odd index to the actual horizontal position and the
1224 even ones to the vertical position.
1226 Although this doesn't make sense it is kept for compatibility.
1230 As the polygon is closed, the end of drawing is the starting point, so
1231 the position doesn't change.
1240 The same macro as the corresponding
1242 command with the same arguments, but draws a solid polygon in the
1243 current fill color rather than an outlined polygon.
1245 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1246 The position is changed in the same way as with
1250 No position changing.
1258 Set the current line thickness to\~\c
1260 (an integer in basic units\~\c
1266 select the smallest available line thickness; if
1268 set the line thickness proportional to the point size (this is the
1269 default before the first
1271 command was specified).
1273 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1274 For historical reasons, the horizontal position is changed by adding
1275 the argument to the actual horizontal position, while the vertical
1276 position is not changed.
1278 Although this doesn't make sense it is kept for compatibility.
1282 No position changing.
1289 .\" --------------------------------------------------------------------
1290 .SS "Device Control Commands"
1291 .\" --------------------------------------------------------------------
1293 Each device control command starts with the letter
1295 followed by a space character (optional or arbitrary space/\:tab in
1297 and a subcommand letter or word; each argument (if any) must be
1304 commands are terminated by a
1305 .IR "syntactical line break" ;
1306 no device control command can be followed by another command on the same
1307 line (except a comment).
1310 The subcommand is basically a single letter, but to increase
1311 readability, it can be written as a word, i.e., an arbitrary sequence
1312 of characters terminated by the next tab, space, or newline character.
1314 All characters of the subcommand word but the first are simply ignored.
1318 outputs the initialization command
1322 and the resolution command
1331 resp.\& are accepted as well to mean the same commands.
1334 In the following, the syntax element
1335 .I \[la]line_break\[ra]
1337 .I syntactical line break
1338 as defined in section
1345 as the intended name for the current file in error reports.
1347 This is useful for remembering the original file name when
1349 uses an internal piping mechanism.
1351 The input file is not changed by this command.
1360 Mount font position\~\c
1362 (a non-negative integer) with font named\~\c
1366 .BR groff_font (@MAN5EXT@).
1371 Set character height to\~\c
1373 (a positive integer in scaled points\~\c
1377 used the unit points (\c
1379 instead; see section
1387 This is the third command of the
1395 The classical documentation reads
1396 .I pause device, can be
1400 .x-command r "n\ h\ v"
1406 is the minimal horizontal motion, and
1408 the minimal vertical motion possible with this device; all arguments
1409 are positive integers in basic units\~\c
1413 This is the second command of the
1421 degrees (an integer in basic units\~\c
1427 Terminates the processing of the current file; issued as the last
1429 .I intermediate @g@troff
1435 Generate trailer information, if any.
1439 this is actually just ignored.
1444 Set name of device to word
1446 a sequence of characters ended by the next whitespace character.
1448 The possible device names coincide with those from the groff
1452 This is the first command of the
1458 Configure underlining of spaces.
1462 is\~1, start underlining of spaces;
1465 is\~0, stop underlining of spaces.
1467 This is needed for the
1471 mode and is ignored otherwise.
1478 .x-command X anything
1482 uninterpreted to the device.
1484 If the line following this command starts with a
1486 character this line is interpreted as a continuation line in the
1491 is ignored, but a newline character is sent instead to the device, the
1492 rest of the line is sent uninterpreted.
1494 The same applies to all following lines until the first character of a
1499 This command is generated by the
1502 .BR \*[@backslash]X .
1504 The line-continuing feature is a
1509 .\" --------------------------------------------------------------------
1510 .SS "Obsolete Command"
1511 .\" --------------------------------------------------------------------
1515 output, the writing of a single character was mostly done by a very
1516 strange command that combined a horizontal move and the printing of a
1519 It didn't have a command code, but is represented by a 3-character
1520 argument consisting of exactly 2\~digits and a character.
1526 (exactly two decimal digits) basic units\~\c
1528 then print character\~\c
1537 .I syntactical space
1538 around and within this command is allowed to be added.
1540 Only when a preceding command on the same line ends with an argument
1541 of variable length a separating space is obligatory.
1546 large clusters of these and other commands were used, mostly without
1547 spaces; this made such output almost unreadable.
1553 For modern high-resolution devices, this command does not make sense
1554 because the width of the characters can become much larger than two
1559 this is only used for the devices
1571 provide a better functionality.
1574 .\" --------------------------------------------------------------------
1575 .SH "POSTPROCESSING"
1576 .\" --------------------------------------------------------------------
1580 postprocessors are programs that have the task to translate the
1581 .I intermediate output
1582 into actions that are sent to a device.
1584 A device can be some piece of hardware such as a printer, or a software
1585 file format suitable for graphical or text processing.
1589 system provides powerful means that make the programming of such
1590 postprocessors an easy task.
1592 There is a library function that parses the
1593 .I intermediate output
1594 and sends the information obtained to the device via methods of a
1595 class with a common interface for each device.
1599 postprocessor must only redefine the methods of this class.
1601 For details, see the reference in section
1605 .\" --------------------------------------------------------------------
1607 .\" --------------------------------------------------------------------
1609 This section presents the
1610 .I intermediate output
1611 generated from the same input for three different devices.
1613 The input is the sentence
1617 on the command line.
1621 High-resolution device
1627 .ShellCommand echo "hell world" | groff -Z -T ps
1657 This output can be fed into the postprocessor
1658 .BR grops (@MAN1EXT@)
1659 to get its representation as a PostScript file.
1663 Low-resolution device
1669 This is similar to the high-resolution device except that the
1670 positioning is done at a minor scale.
1672 Some comments (lines starting with
1674 were added for clarification; they were not generated by the
1679 .ShellCommand echo "hell world" | groff -Z -T latin1
1689 .I "# begin a new page"
1697 .I "# initial positioning on the page"
1701 .I "# write text `hell'"
1704 .I "# inform about a space, and do it by a horizontal jump"
1707 .I "# write text `world'"
1710 .I "# announce line break, but do nothing because ..."
1713 .I "# ... the end of the document has been reached"
1724 This output can be fed into the postprocessor
1725 .BR grotty (@MAN1EXT@)
1726 to get a formatted text document.
1730 Classical style output
1735 As a computer monitor has a very low resolution compared to modern
1737 .I intermediate output
1738 for the X\~devices can use the jump-and-write command with its 2-digit
1743 .ShellCommand echo "hell world" | groff -Z -T X100
1758 .I "# write text with old-style jump-and-write command"
1760 ch07e07l03lw06w11o07r05l03dh7
1771 This output can be fed into the postprocessor
1774 .BR \%gxditview (@MAN1EXT@)
1775 for displaying in\~X.
1779 Due to the obsolete jump-and-write command, the text clusters in the
1780 classical output are almost unreadable.
1783 .\" --------------------------------------------------------------------
1785 .\" --------------------------------------------------------------------
1788 .I intermediate output
1791 was first documented in
1795 .I groff intermediate output
1796 format is compatible with this specification except for the following
1801 The classical quasi device independence is not yet implemented.
1805 The old hardware was very different from what we use today.
1809 devices are also fundamentally different from the ones in
1813 For example, the classical PostScript device was called
1815 and had a resolution of 720 units per inch,
1819 device has a resolution of 72000 units per inch.
1821 Maybe, by implementing some rescaling mechanism similar to the
1822 classical quasi device independence, these could be integrated into
1828 The B-spline command
1830 is correctly handled by the
1831 .I intermediate output
1832 parser, but the drawing routines aren't implemented in some of the
1833 postprocessor programs.
1837 The argument of the commands
1841 has the implicit unit scaled point\~\c
1850 This isn't an incompatibility, but a compatible extension, for both
1851 units coincide for all devices without a
1853 parameter, including all classical and the
1859 devices with a sizescale parameter either did not exist, had a
1860 different name, or seem to have had a different resolution.
1862 So conflicts with classical devices are very unlikely.
1865 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1867 The position changing after the commands
1872 is illogical, but as old versions of groff used this feature it is
1873 kept for compatibility reasons.
1874 .\} \" @STUPID_DRAWING_POSITIONING
1877 Temporarily, there existed some confusion on the positioning after the
1883 This has been clarified by establishing the classical rule for all
1884 groff drawing commands:
1890 The position after a graphic object has been drawn is at its end;
1891 for circles and ellipses, the "end" is at the right side.
1897 From this, the positionings specified for the drawing commands above
1898 follow quite naturally.
1899 .\} \" @STUPID_DRAWING_POSITIONING
1902 The differences between
1907 .BR groff_diff (@MAN7EXT@).
1910 .\" --------------------------------------------------------------------
1912 .\" --------------------------------------------------------------------
1915 .BI @FONTDIR@/dev name /DESC
1916 Device description file for device
1920 .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
1921 Defines the parser and postprocessor for the
1925 It is located relative to the top directory of the
1930 This parser is the definitive specification of the
1931 .I groff intermediate output
1935 .\" --------------------------------------------------------------------
1937 .\" --------------------------------------------------------------------
1940 .BR groff (@MAN7EXT@)
1941 refers to a manual page; here
1945 of the man-page documentation system.
1947 To read the example, look up section\~@MAN7EXT@ in your desktop help
1948 system or call from the shell prompt
1953 .ShellCommand man @MAN7EXT@ groff
1958 For more details, see
1963 .BR groff (@MAN1EXT@)
1966 and further readings on groff.
1970 .BR groff (@MAN7EXT@)
1973 language such as numerical units and escape sequences.
1977 .BR groff_font (@MAN5EXT@)
1978 for details on the device scaling parameters of the
1984 .BR @g@troff (@MAN1EXT@)
1985 generates the device-independent intermediate output.
1989 .BR roff (@MAN7EXT@)
1990 for historical aspects and the general structure of roff systems.
1994 .BR groff_diff (@MAN7EXT@)
1995 The differences between the intermediate output in groff and classical
2000 .BR gxditview (@MAN1EXT@)
2007 .BR \%grodvi (@MAN1EXT@),
2008 .BR \%grohtml (@MAN1EXT@),
2009 .BR \%grolbp (@MAN1EXT@),
2010 .BR \%grolj4 (@MAN1EXT@),
2011 .BR \%grops (@MAN1EXT@),
2012 .BR \%grotty (@MAN1EXT@)
2015 the groff postprocessor programs.
2020 For a treatment of all aspects of the groff system within a single
2025 It can be read within the integrated help systems, within
2027 or from the shell prompt by
2030 .ShellCommand info groff
2036 .I classical troff output language
2037 is described in two AT&T Bell Labs CSTR documents available on-line at
2038 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
2039 "Bell Labs CSTR site" .
2044 .I A Typesetter-independent TROFF
2047 is the original and most concise documentation on the output language;
2049 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
2054 The 1992 revision of the
2055 .I Nroff/\:Troff User's Manual
2062 regarding the output language; see
2063 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
2066 .\" --------------------------------------------------------------------
2068 .\" --------------------------------------------------------------------
2070 Copyright (C) 1989, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
2074 This document is distributed under the terms of the FDL (GNU Free
2075 Documentation License) version 1.1 or later.
2077 You should have received a copy of the FDL with this package; it is also
2078 available on-line at the
2079 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
2083 This document is part of
2089 It is based on a former version \- published under the GPL \- that
2090 described only parts of the
2092 extensions of the output language.
2094 It has been rewritten 2002 by \m[blue]Bernd Warken\m[] and is
2096 .MTO wl@gnu.org "Werner Lemberg" .
2100 .\" --------------------------------------------------------------------
2102 .\" --------------------------------------------------------------------
2104 .\" Local Variables:
tuxillo's projects / dragonfly.git / blob