1'\" e
2.\" The above line should force the use of eqn as a preprocessor
3.ig
4groff_out.5
5
6Last update: 13 Apr 2003
7
8This file is part of groff, the GNU roff type-setting system.
9
10Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
11rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
12
13Permission is granted to copy, distribute and/or modify this document
14under the terms of the GNU Free Documentation License, Version 1.1 or
15any later version published by the Free Software Foundation; with the
16Invariant Sections being this .ig-section and AUTHORS, with no
17Front-Cover Texts, and with no Back-Cover Texts.
18
19A copy of the Free Documentation License is included as a file called
20FDL in the main directory of the groff source package.
21..
22.
23.\" --------------------------------------------------------------------
24.\" Setup
25.\" --------------------------------------------------------------------
26.
27.mso www.tmac
28.
29.if n \{\
30. mso tty-char.tmac
31. ftr CR R
32. ftr CI I
33. ftr CB B
34.\}
--- 212 unchanged lines hidden (view full) ---
247.SH NAME
248groff_out \- groff intermediate output format
249.
250.
251.\" --------------------------------------------------------------------
252.SH DESCRIPTION
253.\" --------------------------------------------------------------------
254.
255This manual page describes the intermediate output format of the GNU
256.BR roff (@MAN7EXT@)
257text processing system.
258.
259This output is produced by a run of the GNU
260.BR troff (@MAN1EXT@)
261program before it is fed into a device postprocessor program.
262.
263.P
264As the GNU roff processor
265.BR groff (@MAN1EXT@)
266is a wrapper program around troff that automatically calls a
267postprocessor, this output does not show up normally.
268.
269This is why it is called
270.I intermediate
271within the
272.I groff
273.IR system .
274.
275The
276.B groff
277program provides the option
278.B -Z
279to inhibit postprocessing, such that the produced intermediate output
280is sent to standard output just like calling
281.B troff
282manually.
283.
284.P
285In this document, the term
286.I troff output
287describes what is output by the GNU troff program, while
288.I intermediate output
289refers to the language that is accepted by the parser that prepares
290this output for the postprocessors.
291.
292This parser is smarter on whitespace and implements obsolete elements
293for compatibility, otherwise both formats are the same.
294.
295The pre-groff roff versions are denoted as
296.I classical
297.IR troff .
298.
299.P
300The main purpose of the intermediate output concept is to facilitate
301the development of postprocessors by providing a common programming
302interface for all devices.
303.
304It has a language of its own that is completely different from the
305.BR groff (@MAN7EXT@)
306language.
307.
308While the
309.I groff
310language is a high-level programming language for text processing, the
311intermediate output language is a kind of low-level assembler language
312by specifying all positions on the page for writing and drawing.
313.
314.P
315The intermediate output produced by
316.I groff
317is fairly readable, while
318.I classical troff
319output was hard to understand because of strange habits that are
320still supported, but not used any longer by
321.I GNU
322.IR troff .
323.
324.
325.\" --------------------------------------------------------------------
326.SH "LANGUAGE CONCEPTS"
327.\" --------------------------------------------------------------------
328.
329During the run of
330.BR troff ,
331the roff input is cracked down to the information on what has to be
332printed at what position on the intended device.
333.
334So the language of the intermediate output format can be quite small.
335.
336Its only elements are commands with or without arguments.
337.
338In this document, the term "command" always refers to the intermediate
339output language, never to the roff language used for document
340formatting.
341.
342There are commands for positioning and text writing, for drawing, and
343for device controlling.
344.
345.
346.\" --------------------------------------------------------------------
347.SS "Separation"
348.\" --------------------------------------------------------------------
349.
350.I Classical troff output
351had strange requirements on whitespace.
352.
353The
354.I groff
355output parser, however, is smart about whitespace by making it
356maximally optional.
357.
358The whitespace characters, i.e.\& the
359.IR tab ,
360.IR space ,
361and
362.I newline
363characters, always have a syntactical meaning.
364.
365They are never printable because spacing within the output is always
366done by positioning commands.
367.
368.P
369Any sequence of
370.I space
371or
372.I tab
373characters is treated as a single
374.B syntactical
375.BR space .
376.
377It separates commands and arguments, but is only required when there
378would occur a clashing between the command code and the arguments
379without the space.
380.
381Most often, this happens when variable length command names,
382arguments, argument lists, or command clusters meet.
383.
384Commands and arguments with a known, fixed length need not be
385separated by syntactical space.
386.
387.P
388A line break is a syntactical element, too.
389.
390Every command argument can be followed by whitespace, a comment, or a
391newline character.
392.
393Thus a
394.B syntactical line break
395is defined to consist of optional syntactical space that is optionally
396followed by a comment, and a newline character.
397.
398.P
399The normal commands, those for positioning and text, consist of a
400single letter taking a fixed number of arguments.
401.
402For historical reasons, the parser allows to stack such commands on
403the same line, but fortunately, in groff intermediate output, every
404command with at least one argument is followed by a line break, thus
405providing excellent readability.
406.
407.P
408The other commands \[em] those for drawing and device controlling \[em]
409have a more complicated structure; some recognize long command names,
410and some take a variable number of arguments.
411.
412So all
413.B D
414and
415.B x
416commands were designed to request a
417.I syntactical line break
418after their last argument.
419.
420Only one command,
421.RB ` x\ X '
422has an argument that can stretch over several lines, all other
423commands must have all of their arguments on the same line as the
424command, i.e.\& the arguments may not be splitted by a line break.
425.
426.P
427Empty lines, i.e.\& lines containing only space and/or a comment, can
428occur everywhere.
429.
430They are just ignored.
431.
432.
433.\" --------------------------------------------------------------------
434.SS "Argument Units"
435.\" --------------------------------------------------------------------
436.
437Some commands take integer arguments that are assumed to represent
438values in a measurement unit, but the letter for the corresponding
439.I scale indicator
440is not written with the output command arguments; see
441.BR groff (@MAN7EXT@)
442and the groff info file for more on this topic.
443.
444Most commands assume the scale indicator\~\c
445.unit u ,
446the basic unit of the device, some use\~\c
447.unit z ,
448the
449.I scaled point unit
450of the device, while others, such as the color commands expect plain
451integers.
452.
453Note that these scale indicators are relative to the chosen device.
454.
455They are defined by the parameters specified in the device's
456.I DESC
457file; see
458.BR groff_font (@MAN5EXT@).
459.
460.P
461Note that single characters can have the eighth bit set, as can the
462names of fonts and special characters.
463.
464The names of characters and fonts can be of arbitrary length.
465.
466A character that is to be printed will always be in the current font.
467.
468.P
469A string argument is always terminated by the next whitespace
470character (space, tab, or newline); an embedded
471.B #
472character is regarded as part of the argument, not as the beginning of
473a comment command.
474.
475An integer argument is already terminated by the next non-digit
476character, which then is regarded as the first character of the next
477argument or command.
478.
479.
480.\" --------------------------------------------------------------------
481.SS "Document Parts"
482.\" --------------------------------------------------------------------
483A correct intermediate output document consists of two parts, the
484prologue and the body.
485.
486.P
487The task of the
488.I prologue
489is to set the general device parameters using three exactly specified
490commands.
491.
492The
--- 8 unchanged lines hidden (view full) ---
501.I n\ h\ v
502.br
503.B x init
504.RE
505.P
506with the arguments set as outlined in the section
507.BR "Device Control Commands" .
508.
509But the parser for the intermediate output format is able to swallow
510additional whitespace and comments as well.
511.
512.P
513The
514.I body
515is the main section for processing the document data.
516.
517Syntactically, it is a sequence of any commands different from the
518ones used in the prologue.
519.
520Processing is terminated as soon as the first
521.B x\ stop
522command is encountered; the last line of any groff intermediate output
523always contains such a command.
524.
525.P
526Semantically, the body is page oriented.
527.
528A new page is started by a
529.BR p \~command.
530.
531Positioning, writing, and drawing commands are always done within the
532current page, so they cannot occur before the first
533.BR p \~command.
534.
--- 4 unchanged lines hidden (view full) ---
539is done relative to the current page, all other positioning
540is done relative to the current location within this page.
541.
542.
543.\" --------------------------------------------------------------------
544.SH "COMMAND REFERENCE"
545.\" --------------------------------------------------------------------
546.
547This section describes all intermediate output commands, the classical
548commands as well as the
549.I groff
550extensions.
551.
552.
553.\" --------------------------------------------------------------------
554.SS "Comment Command"
555.\" --------------------------------------------------------------------
556.
557.TP
558.BI # anything \[la]end_of_line\[ra]
559A comment.
560.
561Ignore any characters from the
562.BR # \~\c
563character up to the next newline character.
564.
565.P
566This command is the only possibility for commenting in the intermediate
567output.
568.
569Each comment can be preceded by arbitrary
570.I syntactical
571.IR space ;
572every command can be terminated by a comment.
573.
574.
575.\" --------------------------------------------------------------------
--- 11 unchanged lines hidden (view full) ---
587.I syntactical space
588can be inserted before, after, and between the command letter and its
589arguments.
590.
591All of these commands are stackable, i.e., they can be preceded by
592other simple commands or followed by arbitrary other commands on the
593same line.
594.
595A separating syntactical space is only necessary when two integer
596arguments would clash or if the preceding argument ends with a string
597argument.
598.
599.
600.if (\n[@USE_ENV_STACK] == 1) \{\
601.command {
602Open a new environment by copying the actual device configuration data
603to the environment stack.
604.
605The current environment is setup by the device specification and
--- 8 unchanged lines hidden (view full) ---
614.
615\} \" endif @USE_ENV_STACK
616.
617.
618.command C xxx \[la]white_space\[ra]
619Print a special groff character named
620.argument xxx .
621.
622The trailing syntactical space or line break is necessary to allow
623character names of arbitrary length.
624.
625The character is printed at the current print position;
626the character's size is read from the font file.
627.
628The print position is not changed.
629.
630.
631.command c c
632Print character\~\c
633.argument c
634at the current print position;
--- 18 unchanged lines hidden (view full) ---
653.
654.command h n
655Move
656.argument n
657(a non-negative integer) basic units\~\c
658.unit u
659horizontally to the right.
660.
661.I [54]
662allows negative values for
663.I n
664also, but
665.I groff
666doesn't use this.
667.
668.
669.command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
670Set the color for text (glyphs), line drawing, and the outline of
671graphic objects using different color schemes; the analoguous command
672for the filling color of graphic objects is
673.BR DF .
674.
675The color components are specified as integer arguments between 0 and
676\n[@maxcolor].
677.
678The number of color components and their meaning vary for the
679different color schemes.
680.
681These commands are generated by the groff escape sequence
682.BR \*[@backslash]m .
683.
684No position changing.
685.
686These commands are a groff extension.
687.
688.
689.RS
690.
691.command mc "cyan magenta yellow"
692Set color using the CMY color scheme, having the 3\~color components
693cyan, magenta, and yellow.
694.
--- 32 unchanged lines hidden (view full) ---
727.B \-T\~html
728is used, negative values are emitted also to indicate an unbreakable space
729with given width.
730.
731For example,
732.B N\~-193
733represents an unbreakable space which has a width of 193u.
734.
735This command is a groff extension.
736.
737.
738.command n b\ a
739Inform the device about a line break, but no positioning is done by
740this command.
741.
742In classical troff, the integer arguments
743.argument b
744and\~\c
745.argument a
746informed about the space before and after the current line to
747make the intermediate output more human readable without performing
748any action.
749.
750In groff, they are just ignored, but they must be provided for
751compatibility reasons.
752.
753.
754.command p n
755Begin a new page in the outprint.
756.
757The page number is set to\~\c
758.argument n .
759.
--- 10 unchanged lines hidden (view full) ---
770.
771.command s n
772Set point size to
773.argument n
774scaled points
775(this is unit\~\c
776.unit z
777in GNU
778.BR troff ).
779.
780Classical troff used the unit
781.I points
782(\c
783.unit p )
784instead; see section
785.BR COMPATIBILITY .
786.
787.
788.command t xxx \[la]white_space\[ra]
789.command+ t "xxx dummy_arg" \[la]white_space\[ra]
790Print a word, i.e.\& a sequence of characters
791.argument xxx
792terminated by a space character or a line break; an optional second
793integer argument is ignored (this allows the formatter to generate
794an even number of arguments).
795.
796The first character should be printed at the current position, the
797current horizontal position should then be increased by the width of
798the first character, and so on for each character.
799.
800The widths of the characters are read from the font file, scaled for the
801current point size, and rounded to a multiple of the horizontal
802resolution.
803.
804Special characters cannot be printed using this command (use the
805.B C
806command for named characters).
807.
808This command is a groff extension; it is only used for devices whose
809.I DESC
810file contains the
811.B tcommand
812keyword; see
813.BR groff_font (@MAN5EXT@).
814.
815.
816.command u "n xxx" \[la]white_space\[ra]
817Print word with track kerning.
818.
819This is the same as the
820.B t
821command except that after printing each character, the current
822horizontal position is increased by the sum of the width of that
823character and\~\c
824.argument n
825(an integer in
826basic units\~\c
827.unit u ).
828This command is a groff extension; it is only used for devices whose
829.I DESC
830file contains the
831.B tcommand
832keyword; see
833.BR groff_font (@MAN5EXT@).
834.
835.
836.command V n
--- 8 unchanged lines hidden (view full) ---
845Move
846.argument n
847basic units\~\c
848.unit u
849down
850.RI ( n
851is a non-negative integer).
852.
853.I [54]
854allows negative values for
855.I n
856also, but
857.I groff
858doesn't use this.
859.
860.
861.command w
862Informs about a paddable whitespace to increase readability.
863.
864The spacing itself must be performed explicitly by a move command.
865.
866.
867.\" --------------------------------------------------------------------
868.SS "Graphics Commands"
869.\" --------------------------------------------------------------------
870.
871Each graphics or drawing command in the intermediate output starts
872with the letter\~\c
873.B D
874followed by one or two characters that specify a subcommand; this
875is followed by a fixed or variable number of integer arguments that
876are separated by a single space character.
877.
878A
879.BR D \ command
880may not be followed by another command on the same line
881(apart from a comment), so each
882.BR D \ command
883is terminated by a syntactical line break.
884.
885.P
886.I troff
887output follows the classical spacing rules (no space between command
888and subcommand, all arguments are preceded by a single space
889character), but the parser allows optional space between the command
890letters and makes the space before the first argument optional.
891.
892As usual, each space can be any sequence of tab and space characters.
893.
894.P
895Some graphics commands can take a variable number of arguments.
896.
897In this case, they are integers representing a size measured in basic
898units\~\c
899.unit u .
900.
901The arguments called
902.list1..n h
903stand for horizontal distances where positive means right, negative
904left.
905.
906The arguments called
907.list1..n v
908stand for vertical distances where positive means down, negative up.
909.
910All these distances are offsets relative to the current location.
911.
912.P
913Unless indicated otherwise, each graphics command directly corresponds
914to a similar
915.I groff
916.B \*[@backslash]D
917escape sequence; see
918.BR groff (@MAN7EXT@).
919.
920.P
921Unknown D\~commands are assumed to be device-specific.
922.
923Its arguments are parsed as strings; the whole information is then
924sent to the postprocessor.
925.
926.P
927In the following command reference, the syntax element
928.I \[la]line_break\[ra]
929means a
930.I syntactical line break
931as defined in section
932.BR Separation .
933.
934.
935.D-multiarg ~
936Draw B-spline from current position to offset
937.indexed_offset h 1 v 1 ,
938then to offset
939.indexed_offset h 2 v 2
940if given, etc.\& up to
941.indexed_offset h n v n .
942This command takes a variable number of argument pairs;
943the current position is moved to the terminal point of the drawn curve.
944.
945.
946.Da-command
947Draw arc from current position to
948.indexed_offset h 1 v 1 \|+\|\c
949.indexed_offset h 2 v 2
950with center at
951.indexed_offset h 1 v 1 ;
--- 7 unchanged lines hidden (view full) ---
959(integer in basic units\~\c
960.unit u )
961with leftmost point at the current position; then move the current
962position to the rightmost point of the circle.
963.
964An optional second integer argument is ignored (this allows to the
965formatter to generate an even number of arguments).
966.
967This command is a groff extension.
968.
969.
970.D-command c d
971Draw circle line with diameter\~\c
972.argument d
973(integer in basic units\~\c
974.unit u )
975with leftmost point at the current position; then move the current
--- 6 unchanged lines hidden (view full) ---
982.argument h
983and a vertical diameter of\~\c
984.argument v
985(both integers in basic units\~\c
986.unit u )
987with the leftmost point at the current position; then move to the
988rightmost point of the ellipse.
989.
990This command is a groff extension.
991.
992.
993.D-command e "h v"
994Draw an outlined ellipse with a horizontal diameter of\~\c
995.argument h
996and a vertical diameter of\~\c
997.argument v
998(both integers in basic units\~\c
--- 9 unchanged lines hidden (view full) ---
1008.BR m .
1009.
1010The color components are specified as integer arguments between 0 and
1011\n[@maxcolor].
1012.
1013The number of color components and their meaning vary for the
1014different color schemes.
1015.
1016These commands are generated by the groff escape sequences
1017.B \*[@backslash]D'F\ .\|.\|.'
1018and
1019.B \*[@backslash]M
1020(with no other corresponding graphics commands).
1021.
1022No position changing.
1023.
1024This command is a groff extension.
1025.
1026.
1027.RS
1028.
1029.D-command Fc "cyan magenta yellow"
1030Set fill color for solid drawing objects using the CMY color scheme,
1031having the 3\~color components cyan, magenta, and yellow.
1032.
--- 50 unchanged lines hidden (view full) ---
1083Df -1
1084.RE
1085.ft
1086.fi
1087.
1088sets all colors to blue.
1089.RE
1090.
1091.P
1092No position changing.
1093.
1094This command is a groff extension.
1095.
1096.RE
1097.
1098.
1099.D-command l "h v"
1100Draw line from current position to offset
1101.offset h v
1102(integers in basic units\~\c
--- 18 unchanged lines hidden (view full) ---
1121Although this doesn't make sense it is kept for compatibility.
1122.
1123\}
1124.el \{\
1125As the polygon is closed, the end of drawing is the starting point, so
1126the position doesn't change.
1127\}
1128.
1129This command is a groff extension.
1130.
1131.
1132.D-multiarg P
1133The same macro as the corresponding
1134.B Dp
1135command with the same arguments, but draws a solid polygon in the
1136current fill color rather than an outlined polygon.
1137.
1138.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1139The position is changed in the same way as with
1140.BR Dp .
1141\}
1142.el \
1143No position changing.
1144.
1145This command is a groff extension.
1146.
1147.
1148.D-command t n
1149Set the current line thickness to\~\c
1150.argument n
1151(an integer in basic units\~\c
1152.unit u )
1153if
--- 13 unchanged lines hidden (view full) ---
1167position is not changed.
1168.
1169Although this doesn't make sense it is kept for compatibility.
1170.
1171\}
1172.el \
1173No position changing.
1174.
1175This command is a groff extension.
1176.
1177.
1178.\" --------------------------------------------------------------------
1179.SS "Device Control Commands"
1180.\" --------------------------------------------------------------------
1181.
1182Each device control command starts with the letter
1183.B x
1184followed by a space character (optional or arbitrary space/\:tab in
1185groff) and a subcommand letter or word; each argument (if any) must be
1186preceded by a syntactical space.
1187.
1188All
1189.B x
1190commands are terminated by a
1191.IR "syntactical line break" ;
1192no device control command can be followed by another command on the same
1193line (except a comment).
1194.
1195.P
1196The subcommand is basically a single letter, but to increase
1197readability, it can be written as a word, i.e.\& an arbitrary sequence
1198of characters terminated by the next tab, space, or newline character.
1199.
1200All characters of the subcommand word but the first are simply ignored.
1201.
1202For example,
1203.I troff
1204outputs the initialization command
1205.B x\ i
1206as
1207.B x\ init
1208and the resolution command
1209.B x\ r
1210as
1211.BR "x\ res" .
--- 13 unchanged lines hidden (view full) ---
1225.BR Separation .
1226.
1227.x-command F name
1228.xsub Filename
1229Use
1230.argument name
1231as the intended name for the current file in error reports.
1232.
1233This is useful for remembering the original file name when groff uses
1234an internal piping mechanism.
1235.
1236The input file is not changed by this command.
1237.
1238This command is a groff extension.
1239.
1240.
1241.x-command f "n\ s"
1242.xsub font
1243Mount font position\~\c
1244.argument n
1245(a non-negative integer) with font named\~\c
1246.argument s
--- 4 unchanged lines hidden (view full) ---
1251.
1252.x-command H n
1253.xsub Height
1254Set character height to\~\c
1255.argument n
1256(a positive integer in scaled points\~\c
1257.unit z ).
1258.
1259Classical troff used the unit
1260points (\c
1261.unit p )
1262instead; see section
1263.BR COMPATIBILITY .
1264.
1265.
1266.x-command i
1267.xsub init
1268Initialize device.
1269.
1270This is the third command of the prologue.
1271.
1272.
1273.x-command p
1274.xsub pause
1275Parsed but ignored.
1276.
1277The classical documentation reads
1278.I pause device, can be
--- 8 unchanged lines hidden (view full) ---
1287.argument h
1288is the minimal horizontal motion, and
1289.argument v
1290the minimal vertical motion possible with this device; all arguments
1291are positive integers in basic units\~\c
1292.unit u
1293per inch.
1294.
1295This is the second command of the prologue.
1296.
1297.
1298.x-command S n
1299.xsub Slant
1300Set slant to\~\c
1301.argument n
1302degrees (an integer in basic units\~\c
1303.unit u ).
1304.
1305.
1306.x-command s
1307.xsub stop
1308Terminates the processing of the current file; issued as the last
1309command of any intermediate troff output.
1310.
1311.
1312.x-command t
1313.xsub trailer
1314Generate trailer information, if any.
1315.
1316In
1317.IR groff ,
1318this is actually just ignored.
1319.
1320.
1321.x-command T xxx
1322.xsub Typesetter
1323Set name of device to word
1324.argument xxx ,
1325a sequence of characters ended by the next whitespace character.
1326.
1327The possible device names coincide with those from the groff
1328.B -T
1329option.
1330.
1331This is the first command of the prologue.
1332.
1333.
1334.x-command u n
1335.xsub underline
1336Configure underlining of spaces.
1337.
1338If
1339.argument n
1340is\~1, start underlining of spaces;
1341if
1342.argument n
1343is\~0, stop underlining of spaces.
1344.
1345This is needed for the
1346.B cu
1347request in
1348.I nroff
1349mode and is ignored otherwise.
1350.
1351This command is a groff extension.
1352.
1353.
1354.x-command X anything
1355.xsub X-escape
1356Send string
1357.argument anything
1358uninterpreted to the device.
1359.
--- 12 unchanged lines hidden (view full) ---
1372.B +
1373character.
1374.
1375This command is generated by the
1376.I groff
1377escape sequence
1378.BR \*[@backslash]X .
1379.
1380The line-continuing feature is a groff extension.
1381.
1382.
1383.\" --------------------------------------------------------------------
1384.SS "Obsolete Command"
1385.\" --------------------------------------------------------------------
1386.
1387In
1388.I classical troff
--- 8 unchanged lines hidden (view full) ---
1397.argument ddc
1398Move right
1399.argument dd
1400(exactly two decimal digits) basic units\~\c
1401.unit u ,
1402then print character\~\c
1403.argument c .
1404.
1405.RS
1406.P
1407In groff, arbitrary syntactical space around and within this command
1408is allowed to be added.
1409.
1410Only when a preceding command on the same line ends with an argument
1411of variable length a separating space is obligatory.
1412.
1413In
1414.I classical
1415.IR troff ,
1416large clusters of these and other commands were used, mostly without
1417spaces; this made such output almost unreadable.
1418.
1419.RE
1420.
1421.P
1422For modern high-resolution devices, this command does not make sense
1423because the width of the characters can become much larger than two
1424decimal digits.
1425.
1426In groff, this is only used for the devices
1427.BR X75 ,
1428.BR X75-12 ,
1429.BR X100 ,
1430and
1431.BR X100-12 .
1432.
1433For other devices,
1434the commands
--- 5 unchanged lines hidden (view full) ---
1440.
1441.\" --------------------------------------------------------------------
1442.SH "POSTPROCESSING"
1443.\" --------------------------------------------------------------------
1444.
1445The
1446.I roff
1447postprocessors are programs that have the task to translate the
1448intermediate output into actions that are sent to a device.
1449.
1450A device can be some piece of hardware such as a printer, or a software
1451file format suitable for graphical or text processing.
1452.
1453The
1454.I groff
1455system provides powerful means that make the programming of such
1456postprocessors an easy task.
1457.P
1458There is a library function that parses the intermediate output and
1459sends the information obtained to the device via methods of a class
1460with a common interface for each device.
1461.
1462So a
1463.I groff
1464postprocessor must only redefine the methods of this class.
1465.
1466For details, see the reference in section
1467.BR FILES .
1468.
1469.
1470.\" --------------------------------------------------------------------
1471.SH "EXAMPLES"
1472.\" --------------------------------------------------------------------
1473.
1474This section presents the intermediate output generated from the same
1475input for three different devices.
1476.
1477The input is the sentence
1478.I hell world
1479fed into groff on the command line.
1480.
1481.Topic
1482High-resolution device
1483.I ps
1484.
1485.RS
1486.
1487.P
1488.ShellCommand echo "hell world" | groff -Z -T ps
1489.
1490.P
1491.nf
1492.ft CB
1493x T ps
1494x res 72000 1 1
1495x init
1496p1
1497x font 5 TR
--- 9 unchanged lines hidden (view full) ---
1507n12000 0
1508x trailer
1509V792000
1510x stop
1511.ft P
1512.fi
1513.RE
1514.
1515.P
1516This output can be fed into the postprocessor
1517.BR grops (@MAN1EXT@)
1518to get its representation as a PostScript file.
1519.
1520.
1521.Topic
1522Low-resolution device
1523.I latin1
1524.
1525.RS
1526.
1527.P
1528This is similar to the high-resolution device except that the
1529positioning is done at a minor scale.
1530.
1531Some comments (lines starting with
1532.IR # )
1533were added for clarification; they were not generated by the
1534formatter.
1535.
1536.P
1537.ShellCommand echo "hell world" | groff -Z -T latin1
1538.
1539.P
1540.nf
1541.I # prologue
1542.ft CB
1543x T latin1
1544x res 240 24 40
1545x init
1546.I # begin a new page
1547.ft CB
1548p1
1549.I # font setup
1550.ft CB
1551x font 1 R
1552f1
1553s10
1554.I # initial positioning on the page
1555.ft CB
1556V40
1557H0
1558.I # write text `hell'
1559.ft CB
1560thell
1561.I # inform about a space, and do it by a horizontal jump
1562.ft CB
1563wh24
1564.I # write text `world'
1565.ft CB
1566tworld
1567.I # announce line break, but do nothing because ...
1568.ft CB
1569n40 0
1570.I # ... the end of the document has been reached
1571.ft CB
1572x trailer
1573V2640
1574x stop
1575.ft P
1576.fi
1577.RE
1578.
1579.P
1580This output can be fed into the postprocessor
1581.BR grotty (@MAN1EXT@)
1582to get a formatted text document.
1583.
1584.
1585.Topic
1586Classical style output
1587.
1588.RS
1589.
1590.P
1591As a computer monitor has a very low resolution compared to modern
1592printers the intermediate output for the X\~devices can use the
1593jump-and-write command with its 2-digit displacements.
1594.
1595.P
1596.ShellCommand echo "hell world" | groff -Z -T X100
1597.
1598.P
1599.nf
1600.ft CB
1601x T X100
1602x res 100 1 1
1603x init
1604p1
1605x font 5 TR
1606f5
1607s10
1608V16
1609H100
1610.I # write text with old-style jump-and-write command
1611.ft CB
1612ch07e07l03lw06w11o07r05l03dh7
1613n16 0
1614x trailer
1615V1100
1616x stop
1617.ft P
1618.fi
1619.RE
1620.
1621.P
1622This output can be fed into the postprocessor
1623.BR xditview (1x)
1624or
1625.BR gxditview (@MAN1EXT@)
1626for displaying in\~X.
1627.
1628.P
1629Due to the obsolete jump-and-write command, the text clusters in the
1630classical output are almost unreadable.
1631.
1632.
1633.\" --------------------------------------------------------------------
1634.SH "COMPATIBILITY"
1635.\" --------------------------------------------------------------------
1636.
1637The intermediate output language of the
1638.I classical troff
1639was first documented in
1640.IR [97] .
1641.
1642The
1643.I groff
1644intermediate output format is compatible with this specification
1645except for the following features.
1646.Topic
1647The classical quasi device independence is not yet implemented.
1648.
1649.Topic
1650The old hardware was very different from what we use today.
1651.
1652So the groff devices are also fundamentally different from the ones in
1653classical troff.
1654.
1655For example, the classical PostScript device was called
1656.I post
1657and had a resolution of 720 units per inch,
1658while groff's
1659.I ps
1660device has a resolution of 72000 units per inch.
1661.
1662Maybe, by implementing some rescaling mechanism similar to the
1663classical quasi device independence, these could be integrated into
1664modern groff.
1665.
1666.Topic
1667The B-spline command
1668.B D~
1669is correctly handled by the intermediate output parser, but the
1670drawing routines aren't implemented in some of the postprocessor
1671programs.
1672.Topic
1673The argument of the commands
1674.B s
1675and
1676.B x H
1677has the implicit unit scaled point\~\c
1678.unit z
1679in groff, while classical troff had point (\c
1680.unit p ).
1681.
1682This isn't an incompatibility, but a compatible extension,
1683for both units coincide for all devices without a
1684.I sizescale
1685parameter, including all classical and the groff text devices.
1686.
1687The few groff devices with a sizescale parameter either did
1688not exist, had a different name, or seem to have had a different
1689resolution.
1690.
1691So conflicts with classical devices are very unlikely.
1692.
1693.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1694.Topic
1695The position changing after the commands
1696.BR Dp ,
1697.BR DP ,
1698and
1699.B Dt
1700is illogical, but as old versions of groff used this feature it is
1701kept for compatibility reasons.
1702.\} \" @STUPID_DRAWING_POSITIONING
1703.el \{\
1704.Topic
1705Temporarily, there existed some confusion on the positioning after the
1706.B D
1707commands that are groff extensions.
1708.
1709This has been clarified by establishing the classical rule for all
1710groff drawing commands:
1711.
1712.RS
1713.P
1714.I The position after a graphic object has been drawn is at its end;
1715.I for circles and ellipses, the "end" is at the right side.
1716.RE
1717.
1718.P
1719From this, the positionings specified for the drawing commands above
1720follow quite naturally.
1721.\} \" @STUPID_DRAWING_POSITIONING
1722.
1723.P
1724The differences between groff and classical troff are documented in
1725.BR groff_diff (@MAN7EXT@).
1726.
1727.
1728.\" --------------------------------------------------------------------
1729.SH "FILES"
1730.\" --------------------------------------------------------------------
1731.
1732.TP
1733.BI @FONTDIR@/dev name /DESC
1734Device description file for device
1735.IR name .
1736.
1737.TP
1738.IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
1739Defines the parser and postprocessor for the intermediate output.
1740.
1741It is located relative to the top directory of the
1742.I groff
1743source tree, e.g.
1744.IR @GROFFSRCDIR@ .
1745.
1746This parser is the definitive specification of the
1747.I groff
1748intermediate output format.
1749.
1750.
1751.\" --------------------------------------------------------------------
1752.SH "SEE ALSO"
1753.\" --------------------------------------------------------------------
1754.
1755A reference like
1756.BR groff (@MAN7EXT@)
1757refers to a manual page; here
1758.I groff
1759in section\~\c
1760.I @MAN7EXT@
1761of the man-page documentation system.
1762.
1763To read the example, look up section\~@MAN7EXT@ in your desktop help
1764system or call from the shell prompt
1765.
1766.RS
1767.P
1768.ShellCommand man @MAN7EXT@ groff
1769.RE
1770.
1771.P
1772For more details, see
1773.BR man (1).
1774.
1775.TP
1776.BR groff (@MAN1EXT@)
1777option
1778.B -Z
1779and further readings on groff.
1780.
1781.TP
1782.BR groff (@MAN7EXT@)
1783for details of the
1784.I groff
1785language such as numerical units and escape sequences.
1786.
1787.TP
1788.BR groff_font (@MAN5EXT@)
1789for details on the device scaling parameters of the
1790.B DESC
1791file.
1792.
1793.TP
1794.BR troff (@MAN1EXT@)
1795generates the device-independent intermediate output.
1796.
1797.TP
1798.BR roff (@MAN7EXT@)
1799for historical aspects and the general structure of roff systems.
1800.
1801.TP
1802.BR groff_diff (@MAN7EXT@)
1803The differences between the intermediate output in groff and classical
1804troff.
1805.
1806.P
1807.BR \%grodvi (@MAN1EXT@),
1808.BR \%grohtml (@MAN1EXT@),
1809.BR \%grolbp (@MAN1EXT@),
1810.BR \%grolj4 (@MAN1EXT@),
1811.BR \%grops (@MAN1EXT@),
1812.BR \%grotty (@MAN1EXT@)
1813.br
1814.RS
1815the groff postprocessor programs.
1816.RE
1817.
1818.P
1819For a treatment of all aspects of the groff system within a single
1820document, see the
1821.I groff info
1822.IR file .
1823.
1824It can be read within the integrated help systems, within
1825.BR emacs (1)
1826or from the shell prompt by
1827.
1828.RS
1829.ShellCommand info groff
1830.RE
1831.
1832.P
1833The
1834.I classical troff output language
1835is described in two AT&T Bell Labs CSTR documents available on-line at
1836.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
1837 "Bell Labs CSTR site" .
1838.
1839.TP
1840.I [CSTR #97]
1841.I A Typesetter-independent TROFF
1842by
1843.I Brian Kernighan
1844is the original and most concise documentation on the output language;
1845see
1846.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
1847.
1848.TP
1849.I [CSTR\~#54]
1850The 1992 revision of the
1851.I Nroff/\:Troff User's Manual
1852by
1853.I J.\& F.\& Osanna
1854and
1855.I Brian Kernighan
1856isn't as concise as
1857.I [CSTR\~#97]
1858regarding the output language;
1859see
1860.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
1861.
1862.
1863.\" --------------------------------------------------------------------
1864.SH "AUTHORS"
1865.\" --------------------------------------------------------------------
1866.
1867Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
1868.P
1869This document is distributed under the terms of the FDL (GNU Free
1870Documentation License) version 1.1 or later.
1871.
1872You should have received a copy of the FDL with this package; it is also
1873available on-line at the
1874.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1875.
1876.P
1877This document is part of
1878.IR groff ,
1879the GNU roff distribution.
1880.
1881It is based on a former version \- published under the GPL \- that
1882described only parts of the
1883.I groff
1884extensions of the output language.
1885.
1886It has been rewritten 2002 by
1887.MTO bwarken@mayn.de "Bernd Warken"
1888and is maintained by
1889.MTO wl@gnu.org "Werner Lemberg" .
1890.
1891.\" --------------------------------------------------------------------
1892.\" Emacs settings
1893.\" --------------------------------------------------------------------
1894.\"
1895.\" Local Variables:
1896.\" mode: nroff
1897.\" End:
2.\" The above line should force the use of eqn as a preprocessor
3.ig
4groff_out.5
5
6Last update: 13 Apr 2003
7
8This file is part of groff, the GNU roff type-setting system.
9
10Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
11rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
12
13Permission is granted to copy, distribute and/or modify this document
14under the terms of the GNU Free Documentation License, Version 1.1 or
15any later version published by the Free Software Foundation; with the
16Invariant Sections being this .ig-section and AUTHORS, with no
17Front-Cover Texts, and with no Back-Cover Texts.
18
19A copy of the Free Documentation License is included as a file called
20FDL in the main directory of the groff source package.
21..
22.
23.\" --------------------------------------------------------------------
24.\" Setup
25.\" --------------------------------------------------------------------
26.
27.mso www.tmac
28.
29.if n \{\
30. mso tty-char.tmac
31. ftr CR R
32. ftr CI I
33. ftr CB B
34.\}
--- 212 unchanged lines hidden (view full) ---
247.SH NAME
248groff_out \- groff intermediate output format
249.
250.
251.\" --------------------------------------------------------------------
252.SH DESCRIPTION
253.\" --------------------------------------------------------------------
254.
255This manual page describes the intermediate output format of the GNU
256.BR roff (@MAN7EXT@)
257text processing system.
258.
259This output is produced by a run of the GNU
260.BR troff (@MAN1EXT@)
261program before it is fed into a device postprocessor program.
262.
263.P
264As the GNU roff processor
265.BR groff (@MAN1EXT@)
266is a wrapper program around troff that automatically calls a
267postprocessor, this output does not show up normally.
268.
269This is why it is called
270.I intermediate
271within the
272.I groff
273.IR system .
274.
275The
276.B groff
277program provides the option
278.B -Z
279to inhibit postprocessing, such that the produced intermediate output
280is sent to standard output just like calling
281.B troff
282manually.
283.
284.P
285In this document, the term
286.I troff output
287describes what is output by the GNU troff program, while
288.I intermediate output
289refers to the language that is accepted by the parser that prepares
290this output for the postprocessors.
291.
292This parser is smarter on whitespace and implements obsolete elements
293for compatibility, otherwise both formats are the same.
294.
295The pre-groff roff versions are denoted as
296.I classical
297.IR troff .
298.
299.P
300The main purpose of the intermediate output concept is to facilitate
301the development of postprocessors by providing a common programming
302interface for all devices.
303.
304It has a language of its own that is completely different from the
305.BR groff (@MAN7EXT@)
306language.
307.
308While the
309.I groff
310language is a high-level programming language for text processing, the
311intermediate output language is a kind of low-level assembler language
312by specifying all positions on the page for writing and drawing.
313.
314.P
315The intermediate output produced by
316.I groff
317is fairly readable, while
318.I classical troff
319output was hard to understand because of strange habits that are
320still supported, but not used any longer by
321.I GNU
322.IR troff .
323.
324.
325.\" --------------------------------------------------------------------
326.SH "LANGUAGE CONCEPTS"
327.\" --------------------------------------------------------------------
328.
329During the run of
330.BR troff ,
331the roff input is cracked down to the information on what has to be
332printed at what position on the intended device.
333.
334So the language of the intermediate output format can be quite small.
335.
336Its only elements are commands with or without arguments.
337.
338In this document, the term "command" always refers to the intermediate
339output language, never to the roff language used for document
340formatting.
341.
342There are commands for positioning and text writing, for drawing, and
343for device controlling.
344.
345.
346.\" --------------------------------------------------------------------
347.SS "Separation"
348.\" --------------------------------------------------------------------
349.
350.I Classical troff output
351had strange requirements on whitespace.
352.
353The
354.I groff
355output parser, however, is smart about whitespace by making it
356maximally optional.
357.
358The whitespace characters, i.e.\& the
359.IR tab ,
360.IR space ,
361and
362.I newline
363characters, always have a syntactical meaning.
364.
365They are never printable because spacing within the output is always
366done by positioning commands.
367.
368.P
369Any sequence of
370.I space
371or
372.I tab
373characters is treated as a single
374.B syntactical
375.BR space .
376.
377It separates commands and arguments, but is only required when there
378would occur a clashing between the command code and the arguments
379without the space.
380.
381Most often, this happens when variable length command names,
382arguments, argument lists, or command clusters meet.
383.
384Commands and arguments with a known, fixed length need not be
385separated by syntactical space.
386.
387.P
388A line break is a syntactical element, too.
389.
390Every command argument can be followed by whitespace, a comment, or a
391newline character.
392.
393Thus a
394.B syntactical line break
395is defined to consist of optional syntactical space that is optionally
396followed by a comment, and a newline character.
397.
398.P
399The normal commands, those for positioning and text, consist of a
400single letter taking a fixed number of arguments.
401.
402For historical reasons, the parser allows to stack such commands on
403the same line, but fortunately, in groff intermediate output, every
404command with at least one argument is followed by a line break, thus
405providing excellent readability.
406.
407.P
408The other commands \[em] those for drawing and device controlling \[em]
409have a more complicated structure; some recognize long command names,
410and some take a variable number of arguments.
411.
412So all
413.B D
414and
415.B x
416commands were designed to request a
417.I syntactical line break
418after their last argument.
419.
420Only one command,
421.RB ` x\ X '
422has an argument that can stretch over several lines, all other
423commands must have all of their arguments on the same line as the
424command, i.e.\& the arguments may not be splitted by a line break.
425.
426.P
427Empty lines, i.e.\& lines containing only space and/or a comment, can
428occur everywhere.
429.
430They are just ignored.
431.
432.
433.\" --------------------------------------------------------------------
434.SS "Argument Units"
435.\" --------------------------------------------------------------------
436.
437Some commands take integer arguments that are assumed to represent
438values in a measurement unit, but the letter for the corresponding
439.I scale indicator
440is not written with the output command arguments; see
441.BR groff (@MAN7EXT@)
442and the groff info file for more on this topic.
443.
444Most commands assume the scale indicator\~\c
445.unit u ,
446the basic unit of the device, some use\~\c
447.unit z ,
448the
449.I scaled point unit
450of the device, while others, such as the color commands expect plain
451integers.
452.
453Note that these scale indicators are relative to the chosen device.
454.
455They are defined by the parameters specified in the device's
456.I DESC
457file; see
458.BR groff_font (@MAN5EXT@).
459.
460.P
461Note that single characters can have the eighth bit set, as can the
462names of fonts and special characters.
463.
464The names of characters and fonts can be of arbitrary length.
465.
466A character that is to be printed will always be in the current font.
467.
468.P
469A string argument is always terminated by the next whitespace
470character (space, tab, or newline); an embedded
471.B #
472character is regarded as part of the argument, not as the beginning of
473a comment command.
474.
475An integer argument is already terminated by the next non-digit
476character, which then is regarded as the first character of the next
477argument or command.
478.
479.
480.\" --------------------------------------------------------------------
481.SS "Document Parts"
482.\" --------------------------------------------------------------------
483A correct intermediate output document consists of two parts, the
484prologue and the body.
485.
486.P
487The task of the
488.I prologue
489is to set the general device parameters using three exactly specified
490commands.
491.
492The
--- 8 unchanged lines hidden (view full) ---
501.I n\ h\ v
502.br
503.B x init
504.RE
505.P
506with the arguments set as outlined in the section
507.BR "Device Control Commands" .
508.
509But the parser for the intermediate output format is able to swallow
510additional whitespace and comments as well.
511.
512.P
513The
514.I body
515is the main section for processing the document data.
516.
517Syntactically, it is a sequence of any commands different from the
518ones used in the prologue.
519.
520Processing is terminated as soon as the first
521.B x\ stop
522command is encountered; the last line of any groff intermediate output
523always contains such a command.
524.
525.P
526Semantically, the body is page oriented.
527.
528A new page is started by a
529.BR p \~command.
530.
531Positioning, writing, and drawing commands are always done within the
532current page, so they cannot occur before the first
533.BR p \~command.
534.
--- 4 unchanged lines hidden (view full) ---
539is done relative to the current page, all other positioning
540is done relative to the current location within this page.
541.
542.
543.\" --------------------------------------------------------------------
544.SH "COMMAND REFERENCE"
545.\" --------------------------------------------------------------------
546.
547This section describes all intermediate output commands, the classical
548commands as well as the
549.I groff
550extensions.
551.
552.
553.\" --------------------------------------------------------------------
554.SS "Comment Command"
555.\" --------------------------------------------------------------------
556.
557.TP
558.BI # anything \[la]end_of_line\[ra]
559A comment.
560.
561Ignore any characters from the
562.BR # \~\c
563character up to the next newline character.
564.
565.P
566This command is the only possibility for commenting in the intermediate
567output.
568.
569Each comment can be preceded by arbitrary
570.I syntactical
571.IR space ;
572every command can be terminated by a comment.
573.
574.
575.\" --------------------------------------------------------------------
--- 11 unchanged lines hidden (view full) ---
587.I syntactical space
588can be inserted before, after, and between the command letter and its
589arguments.
590.
591All of these commands are stackable, i.e., they can be preceded by
592other simple commands or followed by arbitrary other commands on the
593same line.
594.
595A separating syntactical space is only necessary when two integer
596arguments would clash or if the preceding argument ends with a string
597argument.
598.
599.
600.if (\n[@USE_ENV_STACK] == 1) \{\
601.command {
602Open a new environment by copying the actual device configuration data
603to the environment stack.
604.
605The current environment is setup by the device specification and
--- 8 unchanged lines hidden (view full) ---
614.
615\} \" endif @USE_ENV_STACK
616.
617.
618.command C xxx \[la]white_space\[ra]
619Print a special groff character named
620.argument xxx .
621.
622The trailing syntactical space or line break is necessary to allow
623character names of arbitrary length.
624.
625The character is printed at the current print position;
626the character's size is read from the font file.
627.
628The print position is not changed.
629.
630.
631.command c c
632Print character\~\c
633.argument c
634at the current print position;
--- 18 unchanged lines hidden (view full) ---
653.
654.command h n
655Move
656.argument n
657(a non-negative integer) basic units\~\c
658.unit u
659horizontally to the right.
660.
661.I [54]
662allows negative values for
663.I n
664also, but
665.I groff
666doesn't use this.
667.
668.
669.command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
670Set the color for text (glyphs), line drawing, and the outline of
671graphic objects using different color schemes; the analoguous command
672for the filling color of graphic objects is
673.BR DF .
674.
675The color components are specified as integer arguments between 0 and
676\n[@maxcolor].
677.
678The number of color components and their meaning vary for the
679different color schemes.
680.
681These commands are generated by the groff escape sequence
682.BR \*[@backslash]m .
683.
684No position changing.
685.
686These commands are a groff extension.
687.
688.
689.RS
690.
691.command mc "cyan magenta yellow"
692Set color using the CMY color scheme, having the 3\~color components
693cyan, magenta, and yellow.
694.
--- 32 unchanged lines hidden (view full) ---
727.B \-T\~html
728is used, negative values are emitted also to indicate an unbreakable space
729with given width.
730.
731For example,
732.B N\~-193
733represents an unbreakable space which has a width of 193u.
734.
735This command is a groff extension.
736.
737.
738.command n b\ a
739Inform the device about a line break, but no positioning is done by
740this command.
741.
742In classical troff, the integer arguments
743.argument b
744and\~\c
745.argument a
746informed about the space before and after the current line to
747make the intermediate output more human readable without performing
748any action.
749.
750In groff, they are just ignored, but they must be provided for
751compatibility reasons.
752.
753.
754.command p n
755Begin a new page in the outprint.
756.
757The page number is set to\~\c
758.argument n .
759.
--- 10 unchanged lines hidden (view full) ---
770.
771.command s n
772Set point size to
773.argument n
774scaled points
775(this is unit\~\c
776.unit z
777in GNU
778.BR troff ).
779.
780Classical troff used the unit
781.I points
782(\c
783.unit p )
784instead; see section
785.BR COMPATIBILITY .
786.
787.
788.command t xxx \[la]white_space\[ra]
789.command+ t "xxx dummy_arg" \[la]white_space\[ra]
790Print a word, i.e.\& a sequence of characters
791.argument xxx
792terminated by a space character or a line break; an optional second
793integer argument is ignored (this allows the formatter to generate
794an even number of arguments).
795.
796The first character should be printed at the current position, the
797current horizontal position should then be increased by the width of
798the first character, and so on for each character.
799.
800The widths of the characters are read from the font file, scaled for the
801current point size, and rounded to a multiple of the horizontal
802resolution.
803.
804Special characters cannot be printed using this command (use the
805.B C
806command for named characters).
807.
808This command is a groff extension; it is only used for devices whose
809.I DESC
810file contains the
811.B tcommand
812keyword; see
813.BR groff_font (@MAN5EXT@).
814.
815.
816.command u "n xxx" \[la]white_space\[ra]
817Print word with track kerning.
818.
819This is the same as the
820.B t
821command except that after printing each character, the current
822horizontal position is increased by the sum of the width of that
823character and\~\c
824.argument n
825(an integer in
826basic units\~\c
827.unit u ).
828This command is a groff extension; it is only used for devices whose
829.I DESC
830file contains the
831.B tcommand
832keyword; see
833.BR groff_font (@MAN5EXT@).
834.
835.
836.command V n
--- 8 unchanged lines hidden (view full) ---
845Move
846.argument n
847basic units\~\c
848.unit u
849down
850.RI ( n
851is a non-negative integer).
852.
853.I [54]
854allows negative values for
855.I n
856also, but
857.I groff
858doesn't use this.
859.
860.
861.command w
862Informs about a paddable whitespace to increase readability.
863.
864The spacing itself must be performed explicitly by a move command.
865.
866.
867.\" --------------------------------------------------------------------
868.SS "Graphics Commands"
869.\" --------------------------------------------------------------------
870.
871Each graphics or drawing command in the intermediate output starts
872with the letter\~\c
873.B D
874followed by one or two characters that specify a subcommand; this
875is followed by a fixed or variable number of integer arguments that
876are separated by a single space character.
877.
878A
879.BR D \ command
880may not be followed by another command on the same line
881(apart from a comment), so each
882.BR D \ command
883is terminated by a syntactical line break.
884.
885.P
886.I troff
887output follows the classical spacing rules (no space between command
888and subcommand, all arguments are preceded by a single space
889character), but the parser allows optional space between the command
890letters and makes the space before the first argument optional.
891.
892As usual, each space can be any sequence of tab and space characters.
893.
894.P
895Some graphics commands can take a variable number of arguments.
896.
897In this case, they are integers representing a size measured in basic
898units\~\c
899.unit u .
900.
901The arguments called
902.list1..n h
903stand for horizontal distances where positive means right, negative
904left.
905.
906The arguments called
907.list1..n v
908stand for vertical distances where positive means down, negative up.
909.
910All these distances are offsets relative to the current location.
911.
912.P
913Unless indicated otherwise, each graphics command directly corresponds
914to a similar
915.I groff
916.B \*[@backslash]D
917escape sequence; see
918.BR groff (@MAN7EXT@).
919.
920.P
921Unknown D\~commands are assumed to be device-specific.
922.
923Its arguments are parsed as strings; the whole information is then
924sent to the postprocessor.
925.
926.P
927In the following command reference, the syntax element
928.I \[la]line_break\[ra]
929means a
930.I syntactical line break
931as defined in section
932.BR Separation .
933.
934.
935.D-multiarg ~
936Draw B-spline from current position to offset
937.indexed_offset h 1 v 1 ,
938then to offset
939.indexed_offset h 2 v 2
940if given, etc.\& up to
941.indexed_offset h n v n .
942This command takes a variable number of argument pairs;
943the current position is moved to the terminal point of the drawn curve.
944.
945.
946.Da-command
947Draw arc from current position to
948.indexed_offset h 1 v 1 \|+\|\c
949.indexed_offset h 2 v 2
950with center at
951.indexed_offset h 1 v 1 ;
--- 7 unchanged lines hidden (view full) ---
959(integer in basic units\~\c
960.unit u )
961with leftmost point at the current position; then move the current
962position to the rightmost point of the circle.
963.
964An optional second integer argument is ignored (this allows to the
965formatter to generate an even number of arguments).
966.
967This command is a groff extension.
968.
969.
970.D-command c d
971Draw circle line with diameter\~\c
972.argument d
973(integer in basic units\~\c
974.unit u )
975with leftmost point at the current position; then move the current
--- 6 unchanged lines hidden (view full) ---
982.argument h
983and a vertical diameter of\~\c
984.argument v
985(both integers in basic units\~\c
986.unit u )
987with the leftmost point at the current position; then move to the
988rightmost point of the ellipse.
989.
990This command is a groff extension.
991.
992.
993.D-command e "h v"
994Draw an outlined ellipse with a horizontal diameter of\~\c
995.argument h
996and a vertical diameter of\~\c
997.argument v
998(both integers in basic units\~\c
--- 9 unchanged lines hidden (view full) ---
1008.BR m .
1009.
1010The color components are specified as integer arguments between 0 and
1011\n[@maxcolor].
1012.
1013The number of color components and their meaning vary for the
1014different color schemes.
1015.
1016These commands are generated by the groff escape sequences
1017.B \*[@backslash]D'F\ .\|.\|.'
1018and
1019.B \*[@backslash]M
1020(with no other corresponding graphics commands).
1021.
1022No position changing.
1023.
1024This command is a groff extension.
1025.
1026.
1027.RS
1028.
1029.D-command Fc "cyan magenta yellow"
1030Set fill color for solid drawing objects using the CMY color scheme,
1031having the 3\~color components cyan, magenta, and yellow.
1032.
--- 50 unchanged lines hidden (view full) ---
1083Df -1
1084.RE
1085.ft
1086.fi
1087.
1088sets all colors to blue.
1089.RE
1090.
1091.P
1092No position changing.
1093.
1094This command is a groff extension.
1095.
1096.RE
1097.
1098.
1099.D-command l "h v"
1100Draw line from current position to offset
1101.offset h v
1102(integers in basic units\~\c
--- 18 unchanged lines hidden (view full) ---
1121Although this doesn't make sense it is kept for compatibility.
1122.
1123\}
1124.el \{\
1125As the polygon is closed, the end of drawing is the starting point, so
1126the position doesn't change.
1127\}
1128.
1129This command is a groff extension.
1130.
1131.
1132.D-multiarg P
1133The same macro as the corresponding
1134.B Dp
1135command with the same arguments, but draws a solid polygon in the
1136current fill color rather than an outlined polygon.
1137.
1138.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1139The position is changed in the same way as with
1140.BR Dp .
1141\}
1142.el \
1143No position changing.
1144.
1145This command is a groff extension.
1146.
1147.
1148.D-command t n
1149Set the current line thickness to\~\c
1150.argument n
1151(an integer in basic units\~\c
1152.unit u )
1153if
--- 13 unchanged lines hidden (view full) ---
1167position is not changed.
1168.
1169Although this doesn't make sense it is kept for compatibility.
1170.
1171\}
1172.el \
1173No position changing.
1174.
1175This command is a groff extension.
1176.
1177.
1178.\" --------------------------------------------------------------------
1179.SS "Device Control Commands"
1180.\" --------------------------------------------------------------------
1181.
1182Each device control command starts with the letter
1183.B x
1184followed by a space character (optional or arbitrary space/\:tab in
1185groff) and a subcommand letter or word; each argument (if any) must be
1186preceded by a syntactical space.
1187.
1188All
1189.B x
1190commands are terminated by a
1191.IR "syntactical line break" ;
1192no device control command can be followed by another command on the same
1193line (except a comment).
1194.
1195.P
1196The subcommand is basically a single letter, but to increase
1197readability, it can be written as a word, i.e.\& an arbitrary sequence
1198of characters terminated by the next tab, space, or newline character.
1199.
1200All characters of the subcommand word but the first are simply ignored.
1201.
1202For example,
1203.I troff
1204outputs the initialization command
1205.B x\ i
1206as
1207.B x\ init
1208and the resolution command
1209.B x\ r
1210as
1211.BR "x\ res" .
--- 13 unchanged lines hidden (view full) ---
1225.BR Separation .
1226.
1227.x-command F name
1228.xsub Filename
1229Use
1230.argument name
1231as the intended name for the current file in error reports.
1232.
1233This is useful for remembering the original file name when groff uses
1234an internal piping mechanism.
1235.
1236The input file is not changed by this command.
1237.
1238This command is a groff extension.
1239.
1240.
1241.x-command f "n\ s"
1242.xsub font
1243Mount font position\~\c
1244.argument n
1245(a non-negative integer) with font named\~\c
1246.argument s
--- 4 unchanged lines hidden (view full) ---
1251.
1252.x-command H n
1253.xsub Height
1254Set character height to\~\c
1255.argument n
1256(a positive integer in scaled points\~\c
1257.unit z ).
1258.
1259Classical troff used the unit
1260points (\c
1261.unit p )
1262instead; see section
1263.BR COMPATIBILITY .
1264.
1265.
1266.x-command i
1267.xsub init
1268Initialize device.
1269.
1270This is the third command of the prologue.
1271.
1272.
1273.x-command p
1274.xsub pause
1275Parsed but ignored.
1276.
1277The classical documentation reads
1278.I pause device, can be
--- 8 unchanged lines hidden (view full) ---
1287.argument h
1288is the minimal horizontal motion, and
1289.argument v
1290the minimal vertical motion possible with this device; all arguments
1291are positive integers in basic units\~\c
1292.unit u
1293per inch.
1294.
1295This is the second command of the prologue.
1296.
1297.
1298.x-command S n
1299.xsub Slant
1300Set slant to\~\c
1301.argument n
1302degrees (an integer in basic units\~\c
1303.unit u ).
1304.
1305.
1306.x-command s
1307.xsub stop
1308Terminates the processing of the current file; issued as the last
1309command of any intermediate troff output.
1310.
1311.
1312.x-command t
1313.xsub trailer
1314Generate trailer information, if any.
1315.
1316In
1317.IR groff ,
1318this is actually just ignored.
1319.
1320.
1321.x-command T xxx
1322.xsub Typesetter
1323Set name of device to word
1324.argument xxx ,
1325a sequence of characters ended by the next whitespace character.
1326.
1327The possible device names coincide with those from the groff
1328.B -T
1329option.
1330.
1331This is the first command of the prologue.
1332.
1333.
1334.x-command u n
1335.xsub underline
1336Configure underlining of spaces.
1337.
1338If
1339.argument n
1340is\~1, start underlining of spaces;
1341if
1342.argument n
1343is\~0, stop underlining of spaces.
1344.
1345This is needed for the
1346.B cu
1347request in
1348.I nroff
1349mode and is ignored otherwise.
1350.
1351This command is a groff extension.
1352.
1353.
1354.x-command X anything
1355.xsub X-escape
1356Send string
1357.argument anything
1358uninterpreted to the device.
1359.
--- 12 unchanged lines hidden (view full) ---
1372.B +
1373character.
1374.
1375This command is generated by the
1376.I groff
1377escape sequence
1378.BR \*[@backslash]X .
1379.
1380The line-continuing feature is a groff extension.
1381.
1382.
1383.\" --------------------------------------------------------------------
1384.SS "Obsolete Command"
1385.\" --------------------------------------------------------------------
1386.
1387In
1388.I classical troff
--- 8 unchanged lines hidden (view full) ---
1397.argument ddc
1398Move right
1399.argument dd
1400(exactly two decimal digits) basic units\~\c
1401.unit u ,
1402then print character\~\c
1403.argument c .
1404.
1405.RS
1406.P
1407In groff, arbitrary syntactical space around and within this command
1408is allowed to be added.
1409.
1410Only when a preceding command on the same line ends with an argument
1411of variable length a separating space is obligatory.
1412.
1413In
1414.I classical
1415.IR troff ,
1416large clusters of these and other commands were used, mostly without
1417spaces; this made such output almost unreadable.
1418.
1419.RE
1420.
1421.P
1422For modern high-resolution devices, this command does not make sense
1423because the width of the characters can become much larger than two
1424decimal digits.
1425.
1426In groff, this is only used for the devices
1427.BR X75 ,
1428.BR X75-12 ,
1429.BR X100 ,
1430and
1431.BR X100-12 .
1432.
1433For other devices,
1434the commands
--- 5 unchanged lines hidden (view full) ---
1440.
1441.\" --------------------------------------------------------------------
1442.SH "POSTPROCESSING"
1443.\" --------------------------------------------------------------------
1444.
1445The
1446.I roff
1447postprocessors are programs that have the task to translate the
1448intermediate output into actions that are sent to a device.
1449.
1450A device can be some piece of hardware such as a printer, or a software
1451file format suitable for graphical or text processing.
1452.
1453The
1454.I groff
1455system provides powerful means that make the programming of such
1456postprocessors an easy task.
1457.P
1458There is a library function that parses the intermediate output and
1459sends the information obtained to the device via methods of a class
1460with a common interface for each device.
1461.
1462So a
1463.I groff
1464postprocessor must only redefine the methods of this class.
1465.
1466For details, see the reference in section
1467.BR FILES .
1468.
1469.
1470.\" --------------------------------------------------------------------
1471.SH "EXAMPLES"
1472.\" --------------------------------------------------------------------
1473.
1474This section presents the intermediate output generated from the same
1475input for three different devices.
1476.
1477The input is the sentence
1478.I hell world
1479fed into groff on the command line.
1480.
1481.Topic
1482High-resolution device
1483.I ps
1484.
1485.RS
1486.
1487.P
1488.ShellCommand echo "hell world" | groff -Z -T ps
1489.
1490.P
1491.nf
1492.ft CB
1493x T ps
1494x res 72000 1 1
1495x init
1496p1
1497x font 5 TR
--- 9 unchanged lines hidden (view full) ---
1507n12000 0
1508x trailer
1509V792000
1510x stop
1511.ft P
1512.fi
1513.RE
1514.
1515.P
1516This output can be fed into the postprocessor
1517.BR grops (@MAN1EXT@)
1518to get its representation as a PostScript file.
1519.
1520.
1521.Topic
1522Low-resolution device
1523.I latin1
1524.
1525.RS
1526.
1527.P
1528This is similar to the high-resolution device except that the
1529positioning is done at a minor scale.
1530.
1531Some comments (lines starting with
1532.IR # )
1533were added for clarification; they were not generated by the
1534formatter.
1535.
1536.P
1537.ShellCommand echo "hell world" | groff -Z -T latin1
1538.
1539.P
1540.nf
1541.I # prologue
1542.ft CB
1543x T latin1
1544x res 240 24 40
1545x init
1546.I # begin a new page
1547.ft CB
1548p1
1549.I # font setup
1550.ft CB
1551x font 1 R
1552f1
1553s10
1554.I # initial positioning on the page
1555.ft CB
1556V40
1557H0
1558.I # write text `hell'
1559.ft CB
1560thell
1561.I # inform about a space, and do it by a horizontal jump
1562.ft CB
1563wh24
1564.I # write text `world'
1565.ft CB
1566tworld
1567.I # announce line break, but do nothing because ...
1568.ft CB
1569n40 0
1570.I # ... the end of the document has been reached
1571.ft CB
1572x trailer
1573V2640
1574x stop
1575.ft P
1576.fi
1577.RE
1578.
1579.P
1580This output can be fed into the postprocessor
1581.BR grotty (@MAN1EXT@)
1582to get a formatted text document.
1583.
1584.
1585.Topic
1586Classical style output
1587.
1588.RS
1589.
1590.P
1591As a computer monitor has a very low resolution compared to modern
1592printers the intermediate output for the X\~devices can use the
1593jump-and-write command with its 2-digit displacements.
1594.
1595.P
1596.ShellCommand echo "hell world" | groff -Z -T X100
1597.
1598.P
1599.nf
1600.ft CB
1601x T X100
1602x res 100 1 1
1603x init
1604p1
1605x font 5 TR
1606f5
1607s10
1608V16
1609H100
1610.I # write text with old-style jump-and-write command
1611.ft CB
1612ch07e07l03lw06w11o07r05l03dh7
1613n16 0
1614x trailer
1615V1100
1616x stop
1617.ft P
1618.fi
1619.RE
1620.
1621.P
1622This output can be fed into the postprocessor
1623.BR xditview (1x)
1624or
1625.BR gxditview (@MAN1EXT@)
1626for displaying in\~X.
1627.
1628.P
1629Due to the obsolete jump-and-write command, the text clusters in the
1630classical output are almost unreadable.
1631.
1632.
1633.\" --------------------------------------------------------------------
1634.SH "COMPATIBILITY"
1635.\" --------------------------------------------------------------------
1636.
1637The intermediate output language of the
1638.I classical troff
1639was first documented in
1640.IR [97] .
1641.
1642The
1643.I groff
1644intermediate output format is compatible with this specification
1645except for the following features.
1646.Topic
1647The classical quasi device independence is not yet implemented.
1648.
1649.Topic
1650The old hardware was very different from what we use today.
1651.
1652So the groff devices are also fundamentally different from the ones in
1653classical troff.
1654.
1655For example, the classical PostScript device was called
1656.I post
1657and had a resolution of 720 units per inch,
1658while groff's
1659.I ps
1660device has a resolution of 72000 units per inch.
1661.
1662Maybe, by implementing some rescaling mechanism similar to the
1663classical quasi device independence, these could be integrated into
1664modern groff.
1665.
1666.Topic
1667The B-spline command
1668.B D~
1669is correctly handled by the intermediate output parser, but the
1670drawing routines aren't implemented in some of the postprocessor
1671programs.
1672.Topic
1673The argument of the commands
1674.B s
1675and
1676.B x H
1677has the implicit unit scaled point\~\c
1678.unit z
1679in groff, while classical troff had point (\c
1680.unit p ).
1681.
1682This isn't an incompatibility, but a compatible extension,
1683for both units coincide for all devices without a
1684.I sizescale
1685parameter, including all classical and the groff text devices.
1686.
1687The few groff devices with a sizescale parameter either did
1688not exist, had a different name, or seem to have had a different
1689resolution.
1690.
1691So conflicts with classical devices are very unlikely.
1692.
1693.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1694.Topic
1695The position changing after the commands
1696.BR Dp ,
1697.BR DP ,
1698and
1699.B Dt
1700is illogical, but as old versions of groff used this feature it is
1701kept for compatibility reasons.
1702.\} \" @STUPID_DRAWING_POSITIONING
1703.el \{\
1704.Topic
1705Temporarily, there existed some confusion on the positioning after the
1706.B D
1707commands that are groff extensions.
1708.
1709This has been clarified by establishing the classical rule for all
1710groff drawing commands:
1711.
1712.RS
1713.P
1714.I The position after a graphic object has been drawn is at its end;
1715.I for circles and ellipses, the "end" is at the right side.
1716.RE
1717.
1718.P
1719From this, the positionings specified for the drawing commands above
1720follow quite naturally.
1721.\} \" @STUPID_DRAWING_POSITIONING
1722.
1723.P
1724The differences between groff and classical troff are documented in
1725.BR groff_diff (@MAN7EXT@).
1726.
1727.
1728.\" --------------------------------------------------------------------
1729.SH "FILES"
1730.\" --------------------------------------------------------------------
1731.
1732.TP
1733.BI @FONTDIR@/dev name /DESC
1734Device description file for device
1735.IR name .
1736.
1737.TP
1738.IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
1739Defines the parser and postprocessor for the intermediate output.
1740.
1741It is located relative to the top directory of the
1742.I groff
1743source tree, e.g.
1744.IR @GROFFSRCDIR@ .
1745.
1746This parser is the definitive specification of the
1747.I groff
1748intermediate output format.
1749.
1750.
1751.\" --------------------------------------------------------------------
1752.SH "SEE ALSO"
1753.\" --------------------------------------------------------------------
1754.
1755A reference like
1756.BR groff (@MAN7EXT@)
1757refers to a manual page; here
1758.I groff
1759in section\~\c
1760.I @MAN7EXT@
1761of the man-page documentation system.
1762.
1763To read the example, look up section\~@MAN7EXT@ in your desktop help
1764system or call from the shell prompt
1765.
1766.RS
1767.P
1768.ShellCommand man @MAN7EXT@ groff
1769.RE
1770.
1771.P
1772For more details, see
1773.BR man (1).
1774.
1775.TP
1776.BR groff (@MAN1EXT@)
1777option
1778.B -Z
1779and further readings on groff.
1780.
1781.TP
1782.BR groff (@MAN7EXT@)
1783for details of the
1784.I groff
1785language such as numerical units and escape sequences.
1786.
1787.TP
1788.BR groff_font (@MAN5EXT@)
1789for details on the device scaling parameters of the
1790.B DESC
1791file.
1792.
1793.TP
1794.BR troff (@MAN1EXT@)
1795generates the device-independent intermediate output.
1796.
1797.TP
1798.BR roff (@MAN7EXT@)
1799for historical aspects and the general structure of roff systems.
1800.
1801.TP
1802.BR groff_diff (@MAN7EXT@)
1803The differences between the intermediate output in groff and classical
1804troff.
1805.
1806.P
1807.BR \%grodvi (@MAN1EXT@),
1808.BR \%grohtml (@MAN1EXT@),
1809.BR \%grolbp (@MAN1EXT@),
1810.BR \%grolj4 (@MAN1EXT@),
1811.BR \%grops (@MAN1EXT@),
1812.BR \%grotty (@MAN1EXT@)
1813.br
1814.RS
1815the groff postprocessor programs.
1816.RE
1817.
1818.P
1819For a treatment of all aspects of the groff system within a single
1820document, see the
1821.I groff info
1822.IR file .
1823.
1824It can be read within the integrated help systems, within
1825.BR emacs (1)
1826or from the shell prompt by
1827.
1828.RS
1829.ShellCommand info groff
1830.RE
1831.
1832.P
1833The
1834.I classical troff output language
1835is described in two AT&T Bell Labs CSTR documents available on-line at
1836.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
1837 "Bell Labs CSTR site" .
1838.
1839.TP
1840.I [CSTR #97]
1841.I A Typesetter-independent TROFF
1842by
1843.I Brian Kernighan
1844is the original and most concise documentation on the output language;
1845see
1846.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
1847.
1848.TP
1849.I [CSTR\~#54]
1850The 1992 revision of the
1851.I Nroff/\:Troff User's Manual
1852by
1853.I J.\& F.\& Osanna
1854and
1855.I Brian Kernighan
1856isn't as concise as
1857.I [CSTR\~#97]
1858regarding the output language;
1859see
1860.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
1861.
1862.
1863.\" --------------------------------------------------------------------
1864.SH "AUTHORS"
1865.\" --------------------------------------------------------------------
1866.
1867Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
1868.P
1869This document is distributed under the terms of the FDL (GNU Free
1870Documentation License) version 1.1 or later.
1871.
1872You should have received a copy of the FDL with this package; it is also
1873available on-line at the
1874.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1875.
1876.P
1877This document is part of
1878.IR groff ,
1879the GNU roff distribution.
1880.
1881It is based on a former version \- published under the GPL \- that
1882described only parts of the
1883.I groff
1884extensions of the output language.
1885.
1886It has been rewritten 2002 by
1887.MTO bwarken@mayn.de "Bernd Warken"
1888and is maintained by
1889.MTO wl@gnu.org "Werner Lemberg" .
1890.
1891.\" --------------------------------------------------------------------
1892.\" Emacs settings
1893.\" --------------------------------------------------------------------
1894.\"
1895.\" Local Variables:
1896.\" mode: nroff
1897.\" End: