| blob | d78402788c6fc6f35380005425b410ad44487b5d |
1 '\" e
2 .\" The above line should force the use of eqn as a preprocessor
3 .ig
4 groff_out.5
6 Last update: 31 Jan 2002
8 This file is part of groff, the GNU roff type-setting system.
10 Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
11 rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being this .ig-section and AUTHORS, with no
17 Front-Cover Texts, and with no Back-Cover Texts.
19 A copy of the Free Documentation License is included as a file called
20 FDL in the main directory of the groff source package.
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 .\}
35 .
36 .if '\*[.T]'dvi' \
37 . ftr CB CW
38 .
39 .if t \{\
40 .EQ
41 delim $$
42 .EN
43 .\}
44 .
45 .\" ----------------- Document configuration
46 .
47 .\" Number register to decide whether the commands `{' and `}' are used
48 .\" 0: disable (actual default); 1: enable
49 .nr @USE_ENV_STACK 0
50 .
51 .ig
52 Unfortunately, old versions of groff used an illogical position change
53 after some D-commands (Dp, DP, Dt). If the number register
54 @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
55 after these commands, otherwise the position is not changed.
56 ..
57 .nr @STUPID_DRAWING_POSITIONING 1
58 .
59 .\" ----------------- Syntactical definitions
60 .
61 .\" comments when escapes are switched off
62 .de c
63 ..
64 .\" Begin of macro definitions
65 .eo
66 .
67 .de Text
68 . nop \)\$*
69 ..
70 .c follow-up line for a .TP header
71 .de TP+
72 . br
73 . ns
74 . TP \$1
75 ..
76 .c a bulleted paragraph
77 .de Topic
78 . TP 2m
79 . nop \[bu]
80 ..
81 .de ShellCommand
82 . br
83 . IR "shell#" "\h'1m'\f[CB]\$*\f[P]\/"
84 ..
85 .ec
86 .\" End of macro definitions
87 .
88 .c ----------------- Semantical definitions
89 .
90 .nr @maxcolor 65536
91 .ds @backslash \[rs]\"
92 .ds @linebreak \f[R]\[la]line_break\[ra]\f[P]\"
93 .
94 .\" Begin of macro definitions
95 .eo
96 .
97 .c format: .unit <letter> <punctuation>
98 .de unit
99 . BR \$@
100 ..
101 .c argument in italic with punctuation
102 .de argument
103 . if (\n[.$] == 0) \
104 . return
105 . IR \$@
106 ..
107 .c comma separated list of indexed variables
108 .de list1..n
109 . ds @arg1 \$1\"
110 . nop \c
111 . ie t \
112 . nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c
113 . el \{\
114 . IR \*[@arg1]1 ,
115 . IR \*[@arg1]2 ,
116 . nop \&...,
117 . I \*[@arg1]n
118 . \}
119 . rm @arg1
120 ..
121 .de offset
122 . if (\n[.$] < 2) \
123 . ab `.offset' needs at least 2 arguments
124 . ds @arg1 \$1\"
125 . ds @arg2 \$2\"
126 . shift 2
127 . nop (\f[I]\,\*[@arg1]\/\f[P],\ \f[I]\,\*[@arg2]\/\f[P])\$*
128 . rm @arg1
129 . rm @arg2
130 ..
131 .de indexed_offset
132 . if (\n[.$] < 4) \
133 . ab `.indexed_offset' needs at least 4 arguments
134 . ds @arg1 \$1\"
135 . ds @index1 \$2\"
136 . ds @arg2 \$3\"
137 . ds @index2 \$4\"
138 . shift 4
139 . ie t \{\
140 . ie \B'\*[@index1]' \{\
141 . nop ($\*[@arg1] sub roman \*[@index1]$,\ \c
142 . \}
143 . el \{\
144 . nop ($\*[@arg1] sub \*[@index1]$,\ \c
145 . \}
146 . ie \B'\*[@index2]' \{\
147 . nop $\*[@arg2] sub roman \*[@index2]$)\$* \c
148 . \}
149 . el \{\
150 . nop $\*[@arg2] sub \*[@index2]$)\$* \c
151 . \}
152 . \}
153 . el \{\
154 . nop (\f[I]\*[@arg1]\*[@index1]\f[P],\ \c
155 . nop \f[I]\*[@arg2]\*[@index2]\f[P])\$* \c
156 . \}
157 . rm @arg1
158 . rm @arg2
159 . rm @index1
160 . rm @index2
161 ..
162 .c format: .command <name> "<arguments>" <punctuation>
163 .de command
164 . ds @arg1 \$1\"
165 . ds @arg2 \$2\"
166 . shift 2
167 . IP "\f[B]\*[@arg1]\f[P]\ \f[I]\,\*[@arg2]\/\f[P]\$*"
168 . rm @arg1
169 . rm @arg2
170 ..
171 .c format: .command+ <name> "<arguments>" <punctuation>
172 .c continue previous .command heading
173 .de command+
174 . ds @arg1 \$1\"
175 . ds @arg2 \$2\"
176 . shift 2
177 . TP+
178 . Text "\f[B]\*[@arg1]\f[P]\ \f[I]\,\*[@arg2]\/\f[P]\$*"
179 . rm @arg1
180 . rm @arg2
181 ..
182 .c format: .D-command <subcommand> "<arguments>"
183 .de D-command
184 . ds @sub \$1\"
185 . shift 1
186 . IP "\f[B]D\*[@sub]\f[P]\ \f[I]\,\$*\/\f[P]\|\*[@linebreak]"
187 . rm @sub
188 ..
189 .c format: .D-command+ <subcommand> "<arguments>"
190 .c continue previous .D-command heading
191 .de D-command+
192 . ds @sub \$1\"
193 . shift 1
194 . TP+
195 . Text "\f[B]D\*[@sub]\f[P]\ \f[I]\,\$*\/\f[P]\*[@linebreak]"
196 . rm @sub
197 ..
198 .de Da-command
199 . shift 1
200 . ie t \
201 . ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\"
202 . el \
203 . ds @args \f[I]h1\~v1 h2\~v2\f[P]\"
204 . IP "\f[B]Da\f[P]\ \*[@args]\|\*[@linebreak]"
205 . rm @args
206 ..
207 .c graphical command .D with a variable number of arguments
208 .c format: .D-multiarg <subcommand>
209 .de D-multiarg
210 . ds @sub \$1\"
211 . shift 1
212 . ie t \{\
213 . ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \"
214 . as @args "$h sub n$\~$v sub n$\"
215 . \}
216 . el \
217 . ds @args \f[I]h1\~v1 h2\~v2\f[P] ... \f[I]\,hn\~vn\f[P]\"
218 . IP "\f[B]D\*[@sub]\f[P]\ \*[@args]\|\*[@linebreak]"
219 . rm @args
220 . rm @sub
221 ..
222 .c format: .x-command <subname> "<arguments>"
223 .de x-command
224 . ds @sub \$1\"
225 . shift 1
226 . ds @args
227 . if (\n[.$] > 0) \
228 . ds @args \ \f[I]\,\$*\/\f[P]\"
229 . IP "\f[B]x\*[@sub]\f[P]\*[@args]\f[P]\|\*[@linebreak]"
230 . rm @sub
231 . rm @args
232 ..
233 .de xsub
234 . RI \[lq] "x\ \$1" \[rq]:
235 ..
236 .ec
237 .\" End of macro definitions
238 .
239 .
240 .\" --------------------------------------------------------------------
241 .\" Title
242 .\" --------------------------------------------------------------------
243 .
244 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
245 .
246 .SH NAME
247 groff_out \- groff intermediate output format
248 .
249 .
250 .\" --------------------------------------------------------------------
251 .SH DESCRIPTION
252 .\" --------------------------------------------------------------------
253 .
254 This manual page describes the intermediate output format of the GNU
255 .BR roff (@MAN7EXT@)
256 text processing system.
257 .
258 This output is produced by a run of the GNU
259 .BR troff (@MAN1EXT@)
260 program before it is fed into a device postprocessor program.
261 .
262 .P
263 As the GNU roff processor
264 .BR groff (@MAN1EXT@)
265 is a wrapper program around troff that automatically calls a
266 postprocessor, this output does not show up automatically.
267 .
268 This is why it is called
269 .I intermediate
270 within the
271 .I groff
272 .IR system .
273 .
274 The
275 .B groff
276 program provides the option
277 .B -Z
278 to inhibit postprocessing, such that the produced intermediate output
279 is sent to standard output just like calling
280 .B troff
281 manually.
282 .
283 .P
284 In this document, the term
285 .I troff output
286 describes what is output by the GNU troff program, while
287 .I intermediate output
288 refers to the language that is accepted by the parser that prepares
289 this output for the postprocessors.
290 .
291 This parser is smarter on white space and implements obsolete elements
292 for compatibility, otherwise both formats are the same.
293 .
294 The pre-groff roff versions are denoted by
295 .I classical
296 .IR troff .
297 .
298 .P
299 The main purpose of the intermediate output concept is to facilitate
300 the development of postprocessors by providing a common programming
301 interface for all devices.
302 .
303 It has a language of its own that is completely different from the
304 .BR groff (@MAN7EXT@)
305 language.
306 .
307 While the
308 .I groff
309 language is a high-level programming language for text processing, the
310 intermediate output language is a kind of low-level assembler by
311 specifying all positions on the page for writing and drawing.
312 .
313 .P
314 The intermediate output produced by
315 .I groff
316 is fairly readable, while
317 .I classical troff
318 output was hard to understand because of strange habits that are
319 still supported, but not used any longer by
320 .I GNU
321 .IR troff .
322 .
323 .
324 .\" --------------------------------------------------------------------
325 .SH "LANGUAGE CONCEPTS"
326 .\" --------------------------------------------------------------------
327 .
328 During the run of
329 .BR troff ,
330 the roff input is cracked down to the information on what has to be
331 printed at what position on the intended device.
332 .
333 So the language of the intermediate output format can be quite small.
334 .
335 Its only elements are commands with or without arguments.
336 .
337 In this document, the term "command" always refers to the intermediate
338 output language, never to the roff language used for document
339 formatting.
340 .
341 There are commands for positioning and text writing, for drawing, and
342 for device controlling.
343 .
344 .
345 .\" --------------------------------------------------------------------
346 .SS "Separation"
347 .\" --------------------------------------------------------------------
348 .
349 .I Classical troff output
350 had strange requirements on white space.
351 .
352 The
353 .I groff
354 output parser, however, is smart about white space by making it
355 maximally optional.
356 .
357 The white space characters, i.e.\& the
358 .IR tab ,
359 .IR space ,
360 and
361 .I newline
362 characters, always have a syntactical meaning.
363 .
364 They are never printable because spacing within the output is always
365 done by positioning commands.
366 .
367 .P
368 Any sequence of
369 .I space
370 or
371 .I tab
372 characters is treated as a single
373 .B syntactical
374 .BR space .
375 .
376 It separates commands and arguments, but is only required when there
377 would occur a clashing between the command code and the arguments
378 without the space.
379 .
380 Most often, this happens when variable length command names,
381 arguments, argument lists, or command clusters meet.
382 .
383 Commands and arguments with a known, fixed length need not be
384 separated by syntactical space.
385 .
386 .P
387 A line break is a syntactical element, too.
388 .
389 Every command argument can be followed by white space, a comment, or a
390 newline character.
391 .
392 Thus a
393 .B syntactical line break
394 is defined to consist of optional syntactical space that is optionally
395 followed by a comment, and a newline character.
396 .
397 .P
398 The normal commands, those for positioning and text, consist of a
399 single letter taking a fixed number of arguments.
400 .
401 For historical reasons, the parser allows to stack such commands on
402 the same line, but fortunately, in groff intermediate output, every
403 command with at least one argument is followed by a line break, thus
404 providing excellent readability.
405 .
406 .P
407 The other commands \[em] those for drawing and device controlling \[em]
408 have a more complicated structure; some recognize long command names,
409 and some take a variable number of arguments.
410 .
411 So all
412 .B D
413 and
414 .B x
415 commands were designed to request a
416 .I syntactical line break
417 after their last argument.
418 .
419 Only one command,
420 .RB ` x\ X '
421 has an argument that can stretch over several lines, all other
422 commands must have all of their arguments on the same line as the
423 command, i.e.\& the arguments may not be splitted by a line break.
424 .
425 .P
426 Empty lines, i.e.\& lines containing only space and/or a comment can
427 occur everywhere.
428 .
429 They are just ignored.
430 .
431 .
432 .\" --------------------------------------------------------------------
433 .SS "Argument Units"
434 .\" --------------------------------------------------------------------
435 .
436 Some commands take integer arguments that are assumed to represent
437 values in a measurement unit, but the letter for the corresponding
438 .I scale indicator
439 is not written with the output command arguments; see
440 .BR groff (@MAN7EXT@)
441 and the groff info file for more on this topic.
442 .
443 Most commands assume the scale indicator\~\c
444 .unit u ,
445 the basic unit of the device, some use\~\c
446 .unit z ,
447 the
448 .I scaled point unit
449 of the device, while others, such as the color commands expect plain
450 integers.
451 .
452 Note that these scale indicators are relative to the chosen device.
453 .
454 They are defined by the parameters specified in the device's
455 .I DESC
456 file; see
457 .BR groff_font (@MAN5EXT@).
458 .
459 .P
460 Note that single characters can have the eighth bit set, as can the
461 names of fonts and special characters.
462 .
463 The names of characters and fonts can be of arbitrary length.
464 .
465 A character that is to be printed will always be in the current font.
466 .
467 .P
468 A string argument is always terminated by the next white space
469 character (space, tab, or newline); an embedded
470 .B #
471 character is regarded as part of the argument, not as the beginning of
472 a comment command.
473 .
474 An integer argument is already terminated by the next non-digit
475 character, which then is regarded as the first character of the next
476 argument or command.
477 .
478 .
479 .\" --------------------------------------------------------------------
480 .SS "Document Parts"
481 .\" --------------------------------------------------------------------
482 A correct intermediate output document consists of two parts, the
483 prologue and the body.
484 .
485 .P
486 The task of the
487 .I prologue
488 is to set the general device parameters using three exactly specified
489 commands.
490 .
491 The
492 .I groff prologue
493 is guaranteed to consist of the following three lines:
494 .RS
495 .P
496 .B x\ T
497 .I device
498 .br
499 .B x\ res
500 .I n\ h\ v
501 .br
502 .B x init
503 .RE
504 .P
505 with the arguments set as outlined in the section
506 .BR "Device Control Commands" .
507 .
508 But the parser for the intermediate output format is able to swallow
509 additional white space and comments as well.
510 .
511 .P
512 The
513 .I body
514 is the main section for processing the document data.
515 .
516 Syntactically, it is a sequence of any commands different from the
517 ones used in the prologue.
518 .
519 Processing is terminated as soon as the first
520 .B x\ stop
521 command is encountered; the last line of any groff intermediate output
522 always contains such a command.
523 .
524 .P
525 Semantically, the body is page oriented.
526 .
527 A new page is started by a
528 .BR p \~command.
529 .
530 Positioning, writing, and drawing commands are always done within the
531 current page, so they cannot occur before the first
532 .BR p \~command.
533 .
534 Absolute positioning (by the
535 .B H
536 and
537 .BR V \~commands)
538 is done relative to the current page, all other positioning
539 is done relative to the current location within this page.
540 .
541 .
542 .\" --------------------------------------------------------------------
543 .SH "COMMAND REFERENCE"
544 .\" --------------------------------------------------------------------
545 .
546 This section describes all intermediate output commands, the classical
547 commands as well as the
548 .I groff
549 extensions.
550 .
551 .
552 .\" --------------------------------------------------------------------
553 .SS "Comment Command"
554 .\" --------------------------------------------------------------------
555 .
556 .TP
557 .BI # anything \[la]end_of_line\[ra]
558 comment, ignore any characters from the
559 .B #
560 character up to the next newline character.
561 .
562 .P
563 This command is the only possibility for commenting in the intermediate
564 output.
565 .
566 Each comment can be preceded by arbitrary
567 .I syntactical
568 .IR space ;
569 every command can be terminated by a comment.
570 .
571 .
572 .\" --------------------------------------------------------------------
573 .SS "Simple Commands"
574 .\" --------------------------------------------------------------------
575 .
576 The commands in this subsection have a command code consisting of a
577 single character, taking a fixed number of arguments.
578 .
579 Most of them are commands for positioning and text writing.
580 .
581 These commands are smart about white space.
582 .
583 Optionally,
584 .I syntactical space
585 can be inserted before, after, and between the command letter and its
586 arguments.
587 .
588 All of these commands are stackable, i.e.\& they can be preceded by
589 other simple commands or followed by arbitrary other commands on the
590 same line.
591 .
592 A separating syntactical space is only necessary when two integer
593 arguments would clash or if the preceding argument ends with a string
594 argument.
595 .
596 .if (\n[@USE_ENV_STACK] == 1) \{\
597 .command {
598 Open a new environment by copying the actual device configuration data
599 to the environment stack.
600 .
601 The current environment is setup by the device specification and
602 manipulated by the setting commands.
603 .
604 .command }
605 Close the actual environment (opened by a preceding
606 .BR { \~command)
607 and restore the previous environment from the environment
608 stack as the actual device configuration data.
609 .
610 \} \" endif @USE_ENV_STACK
611 .
612 .command C xxx \[la]white_space\[ra]
613 Print a special groff character named
614 .argument xxx .
615 .
616 The trailing syntactical space or line break is necessary to allow
617 character names of arbitrary length.
618 .
619 The character is printed at the current print position;
620 the character's size is read from the font file.
621 .
622 The print position is not changed.
623 .
624 .command c c
625 Print character\~\c
626 .argument c
627 at the current print position;
628 the character's size is read from the font file.
629 .
630 The print position is not changed.
631 .
632 .command f n
633 Set font to font number\~\c
634 .argument n
635 (a non-negative integer).
636 .
637 .command H n
638 Move right to the absolute vertical position\~\c
639 .argument n
640 (a non-negative integer in basic units\~\c
641 .unit u )
642 relative to left edge of current page.
643 .
644 .command h n
645 Move
646 .argument n
647 (a non-negative integer) basic units\~\c
648 .unit u
649 horizontally to the right.
650 .
651 .I [54]
652 allows negative values for
653 .I n
654 also, but
655 .I groff
656 doesn't use this.
657 .
658 .command mc "cyan magenta yellow"
659 Set color for glyphs and line drawing using the CMY color scheme,
660 where all arguments are integers between 0 and \n[@maxcolor] with black
661 having all arguments\~0.
662 .
663 This command is a groff extension.
664 .
665 .command md
666 Set color for glyphs and line drawing to the default drawing color value
667 (black in most cases).
668 .
669 This command is a groff extension.
670 .
671 .command mg "gray"
672 Set color for glyphs and line drawing to the shade of gray given by
673 the argument, an integer between\~0 (black) and \n[@maxcolor] (white).
674 .
675 This command is a groff extension.
676 .
677 .command mk "cyan magenta yellow black"
678 Set color for glyphs and line drawing using the CMYK color scheme,
679 where all arguments are integers between\~0 and \n[@maxcolor].
680 .
681 This command is a groff extension.
682 .
683 .command mr "red green blue"
684 Set color for glyphs and line drawing using the RGB color scheme,
685 where all arguments are integers between\~0 and \n[@maxcolor] with black
686 having all arguments\~0.
687 .
688 This command is a groff extension.
689 .
690 .command N n
691 Print character with index\~\c
692 .argument n
693 (a non-negative integer) of the current font.
694 .
695 This command is a groff extension.
696 .
697 .command n b\ a
698 Inform the device about a line break, but no positioning is done by
699 this command.
700 .
701 In classical troff, the integer arguments
702 .argument b
703 and\~\c
704 .argument a
705 informed about the space before and after the current line to
706 make the intermediate output more human readable without performing
707 any action.
708 .
709 In groff, they are just ignored, but they must be provided for
710 compatibility reasons.
711 .
712 .command p n
713 Begin a new page in the outprint.
714 .
715 The page number is set to\~\c
716 .argument n .
717 .
718 This page is completely independent of pages formerly processed even
719 if those have the same page number.
720 .
721 The vertical position on the outprint is automatically set to\~0.
722 .
723 All positioning, writing, and drawing is always done relative to a
724 page, so a
725 .BR p \~command
726 must be issued before any of these commands.
727 .
728 .command s n
729 Set point size to
730 .argument n
731 scaled points
732 (this is unit\~\c
733 .unit z
734 in GNU
735 .BR troff ).
736 .
737 Classical troff used the unit
738 .I points
739 (\c
740 .unit p )
741 instead; see section
742 .BR COMPATIBILITY .
743 .
744 .command t xxx \[la]white_space\[ra]
745 .command+ t "xxx dummy_arg" \[la]white_space\[ra]
746 Print a word, i.e.\& a sequence of characters
747 .argument xxx
748 terminated by a space character or a line break; an optional second
749 integer argument is ignored (this allows the formatter to generate
750 an even number of arguments).
751 .
752 The first character should be printed at the current position, the
753 current horizontal position should be increased by the width of the
754 first character, and so on for each character.
755 .
756 The widths of the characters are read from the font file, scaled for the
757 current point size, and rounded to a multiple of the horizontal
758 resolution.
759 .
760 Special characters cannot be printed using this command (use the
761 .B C
762 command for named characters).
763 .
764 This command is a groff extension; it is only used for devices whose
765 .I DESC
766 file contains the
767 .B tcommand
768 line; see
769 .BR groff_font (@MAN5EXT@).
770 .
771 .command u "n xxx" \[la]white_space\[ra]
772 Print word with track kerning.
773 .
774 This is the same as the
775 .B t
776 command except that after printing each character, the current
777 horizontal position is increased by the sum of the width of that
778 character and\~\c
779 .argument n
780 (an integer in
781 basic units\~\c
782 .unit u ).
783 This command is a groff extension; it is only used for devices whose
784 .I DESC
785 file contains the
786 .B tcommand
787 line; see
788 .BR groff_font (@MAN5EXT@).
789 .
790 .command V n
791 Move down to the absolute vertical position\~\c
792 .argument n
793 (a non-negative integer in basic units\~\c
794 .unit u )
795 relative to upper edge of current page.
796 .
797 .command v n
798 Move
799 .argument n
800 basic units\~\c
801 .unit u
802 down
803 .RI ( n
804 is a non-negative integer).
805 .
806 .I [54]
807 allows negative values for
808 .I n
809 also, but
810 .I groff
811 doesn't use this.
812 .
813 .command w
814 Informs about a paddable white space to increase readability.
815 .
816 The spacing itself must be performed explicitly by a move command.
817 .
818 .
819 .\" --------------------------------------------------------------------
820 .SS "Graphics Commands"
821 .\" --------------------------------------------------------------------
822 .
823 Each graphical or drawing command in the intermediate output starts
824 with the letter\~\c
825 .B D
826 followed by another single character that specifies a subcommand; this
827 is followed by a fixed or variable number of integer arguments that
828 are separated by a single space character.
829 .
830 A
831 .BR D \ command
832 may not be followed by another command on the same line
833 (apart from a comment), so each
834 .BR D \ command
835 is terminated by a syntactical line break.
836 .
837 .P
838 .I troff
839 output follows the classical spacing rules (no space between command
840 and subcommand, all arguments are preceded by a single space
841 character), but the parser allows optional space between the command
842 letters and makes the space before the first argument optional.
843 .
844 As usual, each space can be any sequence of tab and space characters.
845 .
846 .P
847 Some graphical commands can take a variable number of arguments.
848 .
849 In this case, they are integers representing a size measured in basic
850 units\~\c
851 .unit u .
852 .
853 The arguments called
854 .list1..n h
855 stand for horizontal distances where positive means right, negative
856 left.
857 .
858 The arguments called
859 .list1..n v
860 stand for vertical distances where positive means down, negative up.
861 .
862 All these distances are offsets relative to the current location.
863 .
864 .P
865 Unless indicated otherwise, each graphics command directly corresponds
866 to a similar
867 .I groff
868 .B \*[@backslash]D
869 escape sequence; see
870 .BR groff (@MAN7EXT@).
871 .
872 .P
873 Unknown D-commands are assumed to be device-specific.
874 .
875 Its arguments are parsed as strings; the whole information is then
876 sent to the postprocessor.
877 .
878 .P
879 In the following command references, the syntax element
880 .I \[la]line_break\[ra]
881 means a
882 .I syntactical line break
883 as defined in section
884 .BR Separation .
885 .
886 .D-multiarg ~
887 Draw B-spline from current position to offset
888 .indexed_offset h 1 v 1 ,
889 then to offset
890 .indexed_offset h 2 v 2
891 if given, etc.\& up to
892 .indexed_offset h n v n .
893 This command takes a variable number of argument pairs;
894 the current position is moved to the terminal point of the drawn curve.
895 .
896 .Da-command
897 Draw arc from current position to
898 .indexed_offset h 1 v 1 \|+\|\c
899 .indexed_offset h 2 v 2
900 with center at
901 .indexed_offset h 1 v 1 ;
902 then move the current position to the final point of the arc.
903 .
904 .D-command C d
905 .D-command+ C d dummy_arg
906 Draw a solid circle using the current fill color with diameter\~\c
907 .argument d
908 (integer in basic units\~\c
909 .unit u )
910 with leftmost point at the current position; then move the current
911 position to the rightmost point of the circle.
912 .
913 An optional second integer argument is ignored (this allows to the
914 formatter to generate an even number of arguments).
915 .
916 This command is a groff extension.
917 .
918 .D-command c d
919 Draw circle line with diameter\~\c
920 .argument d
921 (integer in basic units\~\c
922 .unit u )
923 with leftmost point at the current position; then move the current
924 position to the rightmost point of the circle.
925 .
926 .D-command E "h v"
927 Draw a solid ellipse in the current fill color with a horizontal
928 diameter of\~\c
929 .argument h
930 and a vertical diameter of\~\c
931 .argument v
932 (both integers in basic units\~\c
933 .unit u )
934 with the leftmost point at the current position; then move to the
935 rightmost point of the ellipse.
936 .
937 This command is a groff extension.
938 .
939 .D-command e "h v"
940 Draw an outlined ellipse with a horizontal diameter of\~\c
941 .argument h
942 and a vertical diameter of\~\c
943 .argument v
944 (both integers in basic units\~\c
945 .unit u )
946 with the leftmost point at current position; then move to the
947 rightmost point of the ellipse.
948 .
949 .D-command Fc "cyan magenta yellow"
950 Set fill color for solid drawing objects using the CMY color scheme,
951 where all arguments are integers between 0 and \n[@maxcolor] with black
952 having all arguments\~0.
953 .
954 No position changing.
955 .
956 This command is a groff extension.
957 .
958 .D-command Fd
959 Set fill color for solid drawing objects to the default fill color value
960 (black in most cases).
961 .
962 No position changing.
963 .
964 This command is a groff extension.
965 .
966 .D-command Fg "gray"
967 Set fill color for solid drawing objects to the shade of gray given by
968 the argument, an integer between 0 (black) and \n[@maxcolor] (white).
969 .
970 No position changing.
971 .
972 This command is a groff extension.
973 .
974 .D-command Fk "cyan magenta yellow black"
975 Set fill color for solid drawing objects using the CMYK color scheme,
976 where all arguments are integers between 0 and \n[@maxcolor].
977 .
978 No position changing.
979 .
980 This command is a groff extension.
981 .
982 .D-command Fr "red green blue"
983 Set fill color for solid drawing objects using the RGB color scheme,
984 where all arguments are integers between 0 and \n[@maxcolor] with black
985 having all arguments\~0.
986 .
987 No position changing.
988 .
989 This command is a groff extension.
990 .
991 .D-command f n
992 Obsolete color command; sets the shade of gray for filling solid
993 drawing objects to integer\~\c
994 .argument n ,
995 where 0 corresponds to solid white, 1000 (the default) to solid black,
996 and values in between to intermediate shades of gray.
997 .
998 Values outside of this range selects the shade of gray that is currently
999 being used for lines and text (normally black).
1000 .
1001 This is internally mapped to the
1002 .B DFg
1003 command.
1004 .
1005 No position changing.
1006 .
1007 This command is a groff extension.
1008 .
1009 .D-command l "h v"
1010 Draw line from current position to offset
1011 .offset h v
1012 (integers in basic units\~\c
1013 .unit u );
1014 then set current position to the end of the drawn line.
1015 .
1016 .D-multiarg p
1017 Draw a polygon line from current position to offset
1018 .offset h1 v1 ,
1019 from there to offset
1020 .offset h2 v2 ,
1021 etc.\& up to offset
1022 .offset hn vn ,
1023 and from there back to the starting position.
1024 .
1025 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1026 For historical reasons, the position is changed by adding the sum of
1027 all arguments with odd index to the actual horizontal position and the
1028 even ones to the vertical position.
1029 .
1030 Although this doesn't make sense it is kept for compatibility.
1031 .
1032 \}
1033 .el \{\
1034 As the polygon is closed, the end of drawing is the starting point, so
1035 the position doesn't change.
1036 \}
1037 .
1038 This command is a groff extension.
1039 .
1040 .D-multiarg P
1041 The same macro as the corresponding
1042 .B Dp
1043 command with the same arguments, but draws a solid polygon in the
1044 current fill color rather than an outlined polygon.
1045 .
1046 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1047 The position is changed in the same way as with
1048 .BR Dp .
1049 \}
1050 .el \
1051 No position changing.
1052 .
1053 This command is a groff extension.
1054 .
1055 .D-command t n
1056 Set the current line thickness to\~\c
1057 .argument n
1058 (an integer in basic units\~\c
1059 .unit u )
1060 if
1061 .argument n >0;
1062 if
1063 .argument n =0
1064 select the smallest available line thickness; if
1065 .argument n <0
1066 set the line thickness proportional to the point size (this is the
1067 default before the first
1068 .B Dt
1069 command was specified).
1070 .
1071 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1072 For historical reasons, the horizontal position is changed by adding
1073 the argument to the actual horizontal position, while the vertical
1074 position is not changed.
1075 .
1076 Although this doesn't make sense it is kept for compatibility.
1077 .
1078 \}
1079 .el \
1080 No position changing.
1081 .
1082 This command is a groff extension.
1083 .
1084 .
1085 .\" --------------------------------------------------------------------
1086 .SS "Device Control Commands"
1087 .\" --------------------------------------------------------------------
1088 .
1089 Each device control command starts with the letter
1090 .B x
1091 followed by a space character (optional or arbitrary space/\:tab in
1092 groff) and a subcommand letter or word; each argument (if any) must be
1093 preceded by a syntactical space.
1094 .
1095 All
1096 .B x
1097 commands are terminated by a
1098 .IR "syntactical line break" ;
1099 no device control command can be followed by another command on the same
1100 line (except a comment).
1101 .
1102 .P
1103 The subcommand is basically a single letter, but to increase
1104 readability, it can be written as a word, i.e.\& an arbitrary sequence
1105 of characters terminated by the next tab, space, or newline character.
1106 .
1107 All characters of the subcommand word but the first are simply ignored.
1108 .
1109 For example,
1110 .I troff
1111 outputs the initialization command
1112 .B x\ i
1113 as
1114 .B x\ init
1115 and the resolution command
1116 .B x\ r
1117 as
1118 .BR "x\ res" .
1119 .
1120 But writings like
1121 .B x\ i_like_groff
1122 and
1123 .B x\ roff_is_groff
1124 resp.\& are accepted as well to mean the same commands.
1125 .
1126 .P
1127 In the following, the syntax element
1128 .I \[la]line_break\[ra]
1129 means a
1130 .I syntactical line break
1131 as defined in section
1132 .BR Separation .
1133 .
1134 .x-command F filename
1135 .xsub Filename
1136 Use
1137 .argument filename
1138 as the intended name for the current file in error reports.
1139 .
1140 This is useful for remembering the original file name when groff uses
1141 an internal piping mechanism.
1142 .
1143 The input file is not changed by this command.
1144 .
1145 This command is a groff extension.
1146 .
1147 .x-command f "n\ s"
1148 .xsub font
1149 Mount font position\~\c
1150 .argument n
1151 (a non-negative integer) with font named\~\c
1152 .argument s
1153 (a word),
1154 cf.
1155 .BR groff_font (@MAN5EXT@).
1156 .
1157 .x-command H n
1158 .xsub Height
1159 Set character height to\~\c
1160 .argument n
1161 (a positive integer in scaled points\~\c
1162 .unit z ).
1163 .
1164 Classical troff used the unit
1165 points (\c
1166 .unit p )
1167 instead; see section
1168 .BR COMPATIBILITY .
1169 .
1170 .x-command i
1171 .xsub init
1172 Initialize device.
1173 .
1174 This is the third command of the prologue.
1175 .
1176 .x-command p
1177 .xsub pause
1178 Parsed but ignored.
1179 .
1180 The classical documentation reads
1181 .I pause device, can be
1182 .IR restarted .
1183 .
1184 .x-command r "n\ h\ v"
1185 .xsub resolution
1186 Resolution is\~\c
1187 .argument n ,
1188 while
1189 .argument h
1190 is the minimal horizontal motion, and
1191 .argument v
1192 the minimal vertical motion; all arguments are positive integers in
1193 basic units\~\c
1194 .unit u
1195 per inch.
1196 .
1197 This is the second command of the prologue.
1198 .
1199 .x-command S n
1200 .xsub Slant
1201 Set slant to\~\c
1202 .argument n
1203 (an integer in basic units\~\c
1204 .unit u ).
1205 .
1206 .x-command s
1207 .xsub stop
1208 Terminates the processing of the current file; issued as the last
1209 command of any intermediate troff output.
1210 .
1211 .x-command t
1212 .xsub trailer
1213 Generate trailer information, if any.
1214 .
1215 In
1216 .IR groff ,
1217 this is actually just ignored.
1218 .
1219 .x-command T xxx
1220 .xsub Typesetter
1221 Set name of device to word
1222 .argument xxx ,
1223 a sequence of characters ended by the next white space character.
1224 .
1225 This is the first command of the prologue.
1226 .
1227 .x-command u n
1228 .xsub underline
1229 Configure underlining of spaces.
1230 .
1231 If
1232 .argument n
1233 is\~1, start underlining of spaces;
1234 if
1235 .argument n
1236 is\~0, stop underlining of spaces.
1237 .
1238 This is needed for the
1239 .B cu
1240 request in
1241 .I nroff
1242 mode and is ignored otherwise.
1243 .
1244 This command is a groff extension.
1245 .
1246 .x-command X anything
1247 .xsub X-escape
1248 Send string
1249 .argument anything
1250 uninterpreted to the device.
1251 .
1252 If the line following this command starts with a
1253 .B +
1254 character this line is interpreted as a continuation line in the
1255 following sense.
1256 .
1257 The
1258 .B +
1259 is ignored, but a newline character is sent instead to the device, the
1260 rest of the line is sent uninterpreted.
1261 .
1262 The same applies to all following lines until the first character of a
1263 line is not a
1264 .B +
1265 character.
1266 .
1267 This command is generated by the
1268 .I groff
1269 escape sequence
1270 .BR \*[@backslash]X .
1271 .
1272 The line continuing feature is a groff extension.
1273 .
1274 .
1275 .\" --------------------------------------------------------------------
1276 .SS "Obsolete Command"
1277 .\" --------------------------------------------------------------------
1278 .
1279 In
1280 .I classical troff
1281 output, the writing of a single character was mostly done by a very
1282 strange command that combined a horizontal move and the printing of a
1283 character.
1284 .
1285 It didn't have a command code, but is represented by a 3-character
1286 argument consisting of exactly 2 digits and a character.
1287 .TP
1288 .argument ddc
1289 Move right
1290 .argument dd
1291 (exactly two decimal digits) basic units\~\c
1292 .unit u ,
1293 then print character\~\c
1294 .argument c .
1295 .
1296 .IP
1297 In groff, arbitrary syntactical space around and within this command
1298 is allowed to be added.
1299 .
1300 Only when a preceding command on the same line ends with an argument
1301 of variable length a separating space is obligatory.
1302 .
1303 In
1304 .I classical
1305 .IR troff ,
1306 large cluster of these and other commands were used, mostly without
1307 spaces; this made such output almost unreadable.
1308 .
1309 .IP
1310 For modern high-resolution devices, this command does not make sense
1311 because the width of the characters can become much larger than two
1312 decimal digits.
1313 .
1314 In groff, this is only used for the devices
1315 .BR X75 ,
1316 .BR X75-12 ,
1317 .BR X100 ,
1318 and
1319 .B X100-12 .
1320 .
1321 For other devices,
1322 the commands
1323 .B t
1324 and\~\c
1325 .B u
1326 provide a better functionality.
1327 .
1328 .
1329 .\" --------------------------------------------------------------------
1330 .SH "EXAMPLES"
1331 .\" --------------------------------------------------------------------
1332 .
1333 This section presents the intermediate output generated from the same
1334 input for three different devices.
1335 .
1336 The input is the sentence
1337 .I `hell world'
1338 fed into groff on the command line.
1339 .
1340 .Topic
1341 High-resolution device
1342 .I ps
1343 .
1344 .RS
1345 .P
1346 .ShellCommand echo "hell world" | groff -Z -T ps
1347 .
1348 .P
1349 .nf
1350 .ft CB
1351 x T ps
1352 x res 72000 1 1
1353 x init
1354 p1
1355 x font 5 TR
1356 f5
1357 s10000
1358 V12000
1359 H72000
1360 thell
1361 wh2500
1362 tw
1363 H96620
1364 torld
1365 n12000 0
1366 x trailer
1367 V792000
1368 x stop
1369 .ft P
1370 .fi
1371 .RE
1372 .
1373 .Topic
1374 Low-resolution device
1375 .I latin1
1376 .
1377 .RS
1378 .P
1379 .ShellCommand echo "hell world" | groff -Z -T latin1
1380 .
1381 .P
1382 .nf
1383 .ft CB
1384 x T latin1
1385 x res 240 24 40
1386 x init
1387 p1
1388 x font 1 R
1389 f1
1390 s10
1391 V40
1392 H0
1393 thell
1394 wh24
1395 tworld
1396 n40 0
1397 x trailer
1398 V2640
1399 x stop
1400 .ft P
1401 .fi
1402 .RE
1403 .
1404 .Topic
1405 Classical style output for the X devices
1406 .
1407 .RS
1408 .P
1409 .ShellCommand echo "hell world" | groff -Z -T X100
1410 .
1411 .P
1412 .nf
1413 .ft CB
1414 x T X100
1415 x res 100 1 1
1416 x init
1417 p1
1418 x font 5 TR
1419 f5
1420 s10
1421 V16
1422 H100
1423 ch07e07l03lw06w11o07r05l03dh7
1424 n16 0
1425 x trailer
1426 V1100
1427 x stop
1428 .ft P
1429 .fi
1430 .RE
1431 .
1432 .P
1433 The text clusters of the classical output are much harder to be read,
1434 due to the obsolete jump'n'write command.
1435 .
1436 .
1437 .\" --------------------------------------------------------------------
1438 .SH "POSTPROCESSING"
1439 .\" --------------------------------------------------------------------
1440 .
1441 The
1442 .I roff
1443 postprocessors are programs that have the task to translate the
1444 intermediate output into actions that are sent to a device.
1445 .
1446 A device can be some piece of hardware such as a printer, or a software
1447 file format suitable for graphical or text processing.
1448 .
1449 The
1450 .I groff
1451 system provides powerful means that make the programming of such
1452 postprocessors an easy task.
1453 .P
1454 There is a library function that parses the intermediate output and
1455 sends the information obtained to the device via methods of a class
1456 with a common interface for each device.
1457 .
1458 So a
1459 .I groff
1460 postprocessor must only redefine the methods of this class.
1461 .
1462 For details, see the reference in section
1463 .BR FILES .
1464 .
1465 .
1466 .\" --------------------------------------------------------------------
1467 .SH "COMPATIBILITY"
1468 .\" --------------------------------------------------------------------
1469 .
1470 The intermediate output language of the
1471 .I classical troff
1472 was first documented in
1473 .IR [97] .
1474 .
1475 The
1476 .I groff
1477 intermediate output format is compatible with this specification
1478 except for the following features.
1479 .Topic
1480 The classical quasi device independence is not yet implemented.
1481 .
1482 .Topic
1483 The old hardware was very different from what we use today.
1484 .
1485 So the groff devices are also fundamentally different from the ones in
1486 classical troff.
1487 .
1488 For example, the classical PostScript device was called
1489 .I post
1490 and had a resolution of 720 units per inch,
1491 while groff's
1492 .I ps
1493 device has a resolution of 72000 units per inch.
1494 .
1495 Maybe, by implementing some rescaling mechanism similar to the
1496 classical quasi device independence, these could be integrated into
1497 modern groff.
1498 .
1499 .Topic
1500 The B-spline command
1501 .B D~
1502 is correctly handled by the intermediate output parser, but the
1503 drawing routines aren't implemented in some of the postprocessor
1504 programs.
1505 .Topic
1506 The argument of the commands
1507 .B s
1508 and
1509 .B x H
1510 has the implicit unit scaled point\~\c
1511 .unit z
1512 in groff, while classical troff had point (\c
1513 .unit p ).
1514 .
1515 This isn't an incompatibility, but a compatible extension.
1516 .
1517 For, both units coincide for all devices without a
1518 .I sizescale
1519 parameter, this includes all classical and the groff text devices.
1520 .
1521 The few groff devices with a sizescale parameter either did
1522 not exist, had a different name, or seem to have had a different
1523 resolution.
1524 .
1525 So conflicts with classical devices are very unlikely.
1526 .
1527 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1528 .Topic
1529 The position changing after the commands
1530 .BR Dp ,
1531 .BR DP ,
1532 and
1533 .B Dt
1534 is illogical, but as old versions of groff used this feature it is
1535 kept for compatibility reasons.
1536 .\} \" @STUPID_DRAWING_POSITIONING
1537 .el \{\
1538 .Topic
1539 Temporarily, there existed some confusion on the positioning after the
1540 .B D
1541 commands that are groff extensions.
1542 .
1543 This has been clarified by establishing the classical rule for all
1544 groff drawing commands:
1545 .
1546 .RS
1547 .P
1548 .I The position after a graphical object has been drawn is at its end;
1549 .I for circles and ellipses, the "end" is at the right side.
1550 .RE
1551 .
1552 .P
1553 From this, the positionings specified for the drawing commands above
1554 follow quite naturally.
1555 .\} \" @STUPID_DRAWING_POSITIONING
1556 .
1557 .P
1558 The differences between groff and classical troff are documented in
1559 .BR groff_diff (@MAN7EXT@).
1560 .
1561 .
1562 .\" --------------------------------------------------------------------
1563 .SH "FILES"
1564 .\" --------------------------------------------------------------------
1565 .
1566 .TP
1567 .BI @FONTDIR@/dev name /DESC
1568 Device description file for device
1569 .IR name .
1570 .
1571 .TP
1572 .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cc
1573 Defines the parser and postprocessor for the intermediate output.
1574 .
1575 It is located relative to the top directory of the
1576 .I groff
1577 source tree, e.g.
1578 .IR @GROFFSRCDIR@ .
1579 .
1580 This parser is the definitive specification of the
1581 .I groff
1582 intermediate output format.
1583 .
1584 .
1585 .\" --------------------------------------------------------------------
1586 .SH "SEE ALSO"
1587 .\" --------------------------------------------------------------------
1588 .
1589 A reference like
1590 .BR groff (@MAN7EXT@)
1591 refers to a manual page; here
1592 .I groff
1593 in section\~\c
1594 .I 7
1595 of the man-page documentation system.
1596 .
1597 To read the example, look up section\~7 in your desktop help system or
1598 call from the shell prompt
1599 .
1600 .RS
1601 .P
1602 .ShellCommand man @MAN7EXT@ groff
1603 .RE
1604 .
1605 .P
1606 For more details, see
1607 .BR man (1).
1608 .
1609 .TP
1610 .BR troff (@MAN1EXT@)
1611 .TP+
1612 .BR groff (@MAN1EXT@)
1613 for getting the device-independent intermediate output from the shell
1614 prompt.
1615 .
1616 .TP
1617 .BR groff (@MAN7EXT@)
1618 for details of the
1619 .I groff
1620 language such as numerical units and escape sequences.
1621 .
1622 .TP
1623 .BR groff_font (@MAN5EXT@)
1624 for details on the device scaling parameters of the
1625 .B DESC
1626 file.
1627 .
1628 .TP
1629 .BR roff (@MAN7EXT@)
1630 for historical aspects, a list of the available postprocessors, and
1631 further readings.
1632 .
1633 .TP
1634 .BR groff_diff (@MAN7EXT@)
1635 The differences between the intermediate output in groff and classical
1636 troff.
1637 .
1638 .P
1639 The main source of information on all aspects of the groff system is
1640 the
1641 .I groff info
1642 .IR file .
1643 .
1644 It can be read within the integrated help systems, within
1645 .BR emacs (1)
1646 or from the shell prompt by
1647 .
1648 .RS
1649 .P
1650 .ShellCommand info groff
1651 .RE
1652 .
1653 .P
1654 The
1655 .I classical troff output language
1656 is described in two AT&T Bell Labs CSTR documents available on-line at
1657 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
1658 "Bell Labs CSTR site" .
1659 .
1660 .TP
1661 .I [CSTR #97]
1662 .I A Typesetter-independent TROFF
1663 by
1664 .I Brian Kernighan
1665 is the original and most concise documentation on the output language;
1666 see
1667 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
1668 .
1669 .TP
1670 .I [CSTR\~#54]
1671 The 1992 revision of the
1672 .I Nroff/\:Troff User's Manual
1673 by
1674 .I J.\& F.\& Osanna
1675 and
1676 .I Brian Kernighan
1677 isn't as concise as
1678 .I [CSTR\~#97]
1679 regarding the output language;
1680 see
1681 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
1682 .
1683 .
1684 .\" --------------------------------------------------------------------
1685 .SH "AUTHORS"
1686 .\" --------------------------------------------------------------------
1687 .
1688 Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
1689 .P
1690 This document is distributed under the terms of the FDL (GNU Free
1691 Documentation License) version 1.1 or later.
1692 .
1693 You should have received a copy of the FDL with this package; it is also
1694 available on-line at the
1695 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1696 .
1697 .P
1698 This document is part of
1699 .IR groff ,
1700 the GNU roff distribution.
1701 .
1702 It is based on a former version \- published under the GPL \- that
1703 described only parts of the
1704 .I groff
1705 extensions of the output language.
1706 .
1707 It has been rewritten 2001 by
1708 .MTO bwarken@mayn.de "Bernd Warken"
1709 and is maintained by
1710 .MTO wl@gnu.org "Werner Lemberg" .
1711 .
1712 .\" --------------------------------------------------------------------
1713 .\" Emacs settings
1714 .\" --------------------------------------------------------------------
1715 .\"
1716 .\" Local Variables:
1717 .\" mode: nroff
1718 .\" End: