* tmac/hyphenex.sh: Replaced with...
[s-roff.git] / man / groff_out.man
blobb45e82f29c7ce42ddd118ea72325ce8b8e68ebbe
1 '\" e
2 .\" The above line should force the use of eqn as a preprocessor
3 .ig
4 groff_out.5
6 Last update: 13 Apr 2003
8 This file is part of groff, the GNU roff type-setting system.
10 Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
11 rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being this .ig-section and AUTHORS, with no
17 Front-Cover Texts, and with no Back-Cover Texts.
19 A copy of the Free Documentation License is included as a file called
20 FDL in the main directory of the groff source package.
23 .\" --------------------------------------------------------------------
24 .\" Setup
25 .\" --------------------------------------------------------------------
27 .mso www.tmac
29 .if n \{\
30 .  mso tty-char.tmac
31 .  ftr CR R
32 .  ftr CI I
33 .  ftr CB B
34 .\}
36 .if '\*[.T]'dvi' \
37 .  ftr CB CW
39 .if t \{\
40 .EQ
41 delim $$
42 .EN
43 .\}
45 .\" ----------------- Document configuration
47 .\" Number register to decide whether the commands `{' and `}' are used
48 .\" 0: disable (actual default); 1: enable
49 .nr @USE_ENV_STACK 0
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.
57 .nr @STUPID_DRAWING_POSITIONING 1
59 .\" ----------------- Syntactical definitions
61 .\" comments when escapes are switched off
62 .de c
64 .\" Begin of macro definitions
65 .eo
67 .de Text
68 .  nop \)\$*
70 .c follow-up line for a .TP header
71 .de TP+
72 .  br
73 .  ns
74 .  TP \$1
76 .c a bulleted paragraph
77 .de Topic
78 .  TP 2m
79 .  nop \[bu]
81 .de ShellCommand
82 .  br
83 .  IR "shell>" "\h'1m'\f[CB]\$*\f[]\/"
85 .ec
86 .\" End of macro definitions
88 .c ----------------- Semantical definitions
90 .nr @maxcolor 65536
91 .ds @backslash \[rs]\"
92 .ds @linebreak \f[R]\[la]line_break\[ra]\f[]\"
94 .\" Begin of macro definitions
95 .eo
97 .c format: .unit <letter> <punctuation>
98 .de unit
99 .  BR \$@
101 .c argument in italic with punctuation
102 .de argument
103 .  if (\n[.$] == 0) \
104 .    return
105 .  IR \$@
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
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[],\ \f[I]\,\*[@arg2]\/\f[])\$*
128 .  rm @arg1
129 .  rm @arg2
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[],\ \c
155 .    nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c
156 .  \}
157 .  rm @arg1
158 .  rm @arg2
159 .  rm @index1
160 .  rm @index2
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[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
168 .  rm @arg1
169 .  rm @arg2
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[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
179 .  rm @arg1
180 .  rm @arg2
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[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]"
187 .  rm @sub
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[]\ \f[I]\,\$*\/\f[]\*[@linebreak]"
196 .  rm @sub
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[]\"
204 .  IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]"
205 .  rm @args
207 .c graphics 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[] ... \f[I]\,hn\~vn\f[]\"
218 .  IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]"
219 .  rm @args
220 .  rm @sub
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[]\"
229 .  IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]"
230 .  rm @sub
231 .  rm @args
233 .de xsub
234 .  RI "(" "\$1" " control command)"
235 .  br
238 .\" End of macro definitions 
241 .\" --------------------------------------------------------------------
242 .\" Title
243 .\" --------------------------------------------------------------------
245 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
247 .SH NAME
248 groff_out \- groff intermediate output format
251 .\" --------------------------------------------------------------------
252 .SH DESCRIPTION
253 .\" --------------------------------------------------------------------
255 This manual page describes the intermediate output format of the GNU
256 .BR roff (@MAN7EXT@)
257 text processing system.
259 This output is produced by a run of the GNU
260 .BR troff (@MAN1EXT@)
261 program before it is fed into a device postprocessor program.
264 As the GNU roff processor
265 .BR groff (@MAN1EXT@)
266 is a wrapper program around troff that automatically calls a
267 postprocessor, this output does not show up normally.
269 This is why it is called
270 .I intermediate
271 within the
272 .I groff
273 .IR system .
276 .B groff
277 program provides the option
278 .B -Z
279 to inhibit postprocessing, such that the produced intermediate output
280 is sent to standard output just like calling
281 .B troff
282 manually.
285 In this document, the term
286 .I troff output
287 describes what is output by the GNU troff program, while
288 .I intermediate output
289 refers to the language that is accepted by the parser that prepares
290 this output for the postprocessors.
292 This parser is smarter on whitespace and implements obsolete elements
293 for compatibility, otherwise both formats are the same.
295 The pre-groff roff versions are denoted as
296 .I classical
297 .IR troff .
300 The main purpose of the intermediate output concept is to facilitate
301 the development of postprocessors by providing a common programming
302 interface for all devices.
304 It has a language of its own that is completely different from the
305 .BR groff (@MAN7EXT@)
306 language.
308 While the
309 .I groff
310 language is a high-level programming language for text processing, the
311 intermediate output language is a kind of low-level assembler language
312 by specifying all positions on the page for writing and drawing.
315 The intermediate output produced by
316 .I groff
317 is fairly readable, while
318 .I classical troff
319 output was hard to understand because of strange habits that are
320 still supported, but not used any longer by
321 .I GNU
322 .IR troff .
325 .\" --------------------------------------------------------------------
326 .SH "LANGUAGE CONCEPTS"
327 .\" --------------------------------------------------------------------
329 During the run of
330 .BR troff , 
331 the roff input is cracked down to the information on what has to be
332 printed at what position on the intended device.
334 So the language of the intermediate output format can be quite small.
336 Its only elements are commands with or without arguments.
338 In this document, the term "command" always refers to the intermediate
339 output language, never to the roff language used for document
340 formatting.
342 There are commands for positioning and text writing, for drawing, and
343 for device controlling.
346 .\" --------------------------------------------------------------------
347 .SS "Separation"
348 .\" --------------------------------------------------------------------
350 .I Classical troff output
351 had strange requirements on whitespace.
354 .I groff
355 output parser, however, is smart about whitespace by making it
356 maximally optional.
358 The whitespace characters, i.e.\& the
359 .IR tab ,
360 .IR space ,
362 .I newline
363 characters, always have a syntactical meaning.
365 They are never printable because spacing within the output is always
366 done by positioning commands.
369 Any sequence of
370 .I space
372 .I tab
373 characters is treated as a single
374 .B syntactical
375 .BR space .
377 It separates commands and arguments, but is only required when there
378 would occur a clashing between the command code and the arguments
379 without the space.
381 Most often, this happens when variable length command names,
382 arguments, argument lists, or command clusters meet.
384 Commands and arguments with a known, fixed length need not be
385 separated by syntactical space.
388 A line break is a syntactical element, too.
390 Every command argument can be followed by whitespace, a comment, or a
391 newline character.
393 Thus a
394 .B syntactical line break
395 is defined to consist of optional syntactical space that is optionally
396 followed by a comment, and a newline character.
399 The normal commands, those for positioning and text, consist of a
400 single letter taking a fixed number of arguments.
402 For historical reasons, the parser allows to stack such commands on
403 the same line, but fortunately, in groff intermediate output, every
404 command with at least one argument is followed by a line break, thus
405 providing excellent readability.
408 The other commands \[em] those for drawing and device controlling \[em]
409 have a more complicated structure; some recognize long command names,
410 and some take a variable number of arguments.
412 So all
413 .B D
415 .B x
416 commands were designed to request a
417 .I syntactical line break
418 after their last argument.
420 Only one command,
421 .RB ` x\ X '
422 has an argument that can stretch over several lines, all other
423 commands must have all of their arguments on the same line as the
424 command, i.e.\& the arguments may not be splitted by a line break.
427 Empty lines, i.e.\& lines containing only space and/or a comment, can
428 occur everywhere.
430 They are just ignored.
433 .\" --------------------------------------------------------------------
434 .SS "Argument Units"
435 .\" --------------------------------------------------------------------
437 Some commands take integer arguments that are assumed to represent
438 values in a measurement unit, but the letter for the corresponding
439 .I scale indicator
440 is not written with the output command arguments; see
441 .BR groff (@MAN7EXT@)
442 and the groff info file for more on this topic.
444 Most commands assume the scale indicator\~\c
445 .unit u ,
446 the basic unit of the device, some use\~\c
447 .unit z , 
449 .I scaled point unit
450 of the device, while others, such as the color commands expect plain
451 integers.
453 Note that these scale indicators are relative to the chosen device.
455 They are defined by the parameters specified in the device's
456 .I DESC
457 file; see
458 .BR groff_font (@MAN5EXT@).
461 Note that single characters can have the eighth bit set, as can the
462 names of fonts and special characters.
464 The names of characters and fonts can be of arbitrary length.
466 A character that is to be printed will always be in the current font.
469 A string argument is always terminated by the next whitespace
470 character (space, tab, or newline); an embedded
471 .B #
472 character is regarded as part of the argument, not as the beginning of
473 a comment command.
475 An integer argument is already terminated by the next non-digit
476 character, which then is regarded as the first character of the next
477 argument or command.
480 .\" --------------------------------------------------------------------
481 .SS "Document Parts"
482 .\" --------------------------------------------------------------------
483 A correct intermediate output document consists of two parts, the
484 prologue and the body.
487 The task of the
488 .I prologue
489 is to set the general device parameters using three exactly specified
490 commands.
493 .I groff prologue
494 is guaranteed to consist of the following three lines (in that order):
497 .B x\ T
498 .I device
500 .B x\ res
501 .I n\ h\ v
503 .B x init
506 with the arguments set as outlined in the section
507 .BR "Device Control Commands" .
509 But the parser for the intermediate output format is able to swallow
510 additional whitespace and comments as well.
514 .I body
515 is the main section for processing the document data.
517 Syntactically, it is a sequence of any commands different from the
518 ones used in the prologue.
520 Processing is terminated as soon as the first
521 .B x\ stop
522 command is encountered; the last line of any groff intermediate output
523 always contains such a command.
526 Semantically, the body is page oriented.
528 A new page is started by a
529 .BR p \~command.
531 Positioning, writing, and drawing commands are always done within the
532 current page, so they cannot occur before the first
533 .BR p \~command.
535 Absolute positioning (by the
536 .B H
538 .BR V \~commands)
539 is done relative to the current page, all other positioning
540 is done relative to the current location within this page.
543 .\" --------------------------------------------------------------------
544 .SH "COMMAND REFERENCE"
545 .\" --------------------------------------------------------------------
547 This section describes all intermediate output commands, the classical
548 commands as well as the
549 .I groff
550 extensions.
553 .\" --------------------------------------------------------------------
554 .SS "Comment Command"
555 .\" --------------------------------------------------------------------
558 .BI # anything \[la]end_of_line\[ra]
559 A comment.
561 Ignore any characters from the
562 .BR # \~\c
563 character up to the next newline character.
566 This command is the only possibility for commenting in the intermediate
567 output.
569 Each comment can be preceded by arbitrary
570 .I syntactical
571 .IR space ;
572 every command can be terminated by a comment.
575 .\" --------------------------------------------------------------------
576 .SS "Simple Commands"
577 .\" --------------------------------------------------------------------
579 The commands in this subsection have a command code consisting of a
580 single character, taking a fixed number of arguments.
582 Most of them are commands for positioning and text writing.
584 These commands are smart about whitespace.
586 Optionally,
587 .I syntactical space
588 can be inserted before, after, and between the command letter and its
589 arguments.
591 All of these commands are stackable, i.e., they can be preceded by
592 other simple commands or followed by arbitrary other commands on the
593 same line.
595 A separating syntactical space is only necessary when two integer
596 arguments would clash or if the preceding argument ends with a string
597 argument.
600 .if (\n[@USE_ENV_STACK] == 1) \{\
601 .command {
602 Open a new environment by copying the actual device configuration data
603 to the environment stack.
605 The current environment is setup by the device specification and
606 manipulated by the setting commands.
609 .command }
610 Close the actual environment (opened by a preceding
611 .BR { \~command)
612 and restore the previous environment from the environment
613 stack as the actual device configuration data.
615 \}              \" endif @USE_ENV_STACK
618 .command C xxx \[la]white_space\[ra]
619 Print a special groff character named
620 .argument xxx .
622 The trailing syntactical space or line break is necessary to allow
623 character names of arbitrary length.
625 The character is printed at the current print position;
626 the character's size is read from the font file.
628 The print position is not changed.
631 .command c c
632 Print character\~\c
633 .argument c
634 at the current print position;
635 the character's size is read from the font file.
637 The print position is not changed.
640 .command f n
641 Set font to font number\~\c
642 .argument n
643 (a non-negative integer).
646 .command H n
647 Move right to the absolute vertical position\~\c
648 .argument n
649 (a non-negative integer in basic units\~\c
650 .unit u )
651 relative to left edge of current page.
654 .command h n
655 Move
656 .argument n
657 (a non-negative integer) basic units\~\c
658 .unit u
659 horizontally to the right.
661 .I [54]
662 allows negative values for
663 .I n
664 also, but
665 .I groff
666 doesn't use this.
669 .command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
670 Set the color for text (glyphs), line drawing, and the outline of
671 graphic objects using different color schemes; the analoguous command
672 for the filling color of graphic objects is
673 .BR DF .
675 The color components are specified as integer arguments between 0 and
676 \n[@maxcolor].
678 The number of color components and their meaning vary for the
679 different color schemes.
681 These commands are generated by the groff escape sequence
682 .BR \*[@backslash]m .
684 No position changing.
686 These commands are a groff extension.
691 .command mc "cyan magenta yellow"
692 Set color using the CMY color scheme, having the 3\~color components
693 cyan, magenta, and yellow.
696 .command md
697 Set color to the default color value
698 (black in most cases).
700 No component arguments.
703 .command mg "gray"
704 Set color to the shade of gray given by the argument, an integer
705 between 0 (black) and \n[@maxcolor] (white).
708 .command mk "cyan magenta yellow black"
709 Set color using the CMYK color scheme, having the 4\~color components
710 cyan, magenta, yellow, and black.
712 .command mr "red green blue"
713 Set color using the RGB color scheme, having the 3\~color components
714 red, green, and blue.
719 .command N n
720 Print character with index\~\c
721 .argument n
722 (an integer, normally non-negative) of the current font.
724 The print position is not changed.
727 .B \-T\~html
728 is used, negative values are emitted also to indicate an unbreakable space
729 with given width.
731 For example,
732 .B N\~-193
733 represents an unbreakable space which has a width of 193u.
735 This command is a groff extension.
738 .command n b\ a
739 Inform the device about a line break, but no positioning is done by
740 this command.
742 In classical troff, the integer arguments
743 .argument b
744 and\~\c
745 .argument a
746 informed about the space before and after the current line to
747 make the intermediate output more human readable without performing
748 any action.
750 In groff, they are just ignored, but they must be provided for
751 compatibility reasons.
754 .command p n
755 Begin a new page in the outprint.
757 The page number is set to\~\c
758 .argument n .
760 This page is completely independent of pages formerly processed even
761 if those have the same page number.
763 The vertical position on the outprint is automatically set to\~0.
765 All positioning, writing, and drawing is always done relative to a
766 page, so a
767 .BR p \~command
768 must be issued before any of these commands.
771 .command s n
772 Set point size to
773 .argument n
774 scaled points
775 (this is unit\~\c
776 .unit z
777 in GNU
778 .BR troff ).
780 Classical troff used the unit
781 .I points
783 .unit p )
784 instead; see section
785 .BR COMPATIBILITY .
788 .command t xxx \[la]white_space\[ra]
789 .command+ t "xxx dummy_arg" \[la]white_space\[ra]
790 Print a word, i.e.\& a sequence of characters
791 .argument xxx
792 terminated by a space character or a line break; an optional second
793 integer argument is ignored (this allows the formatter to generate
794 an even number of arguments).
796 The first character should be printed at the current position, the
797 current horizontal position should then be increased by the width of
798 the first character, and so on for each character.
800 The widths of the characters are read from the font file, scaled for the
801 current point size, and rounded to a multiple of the horizontal
802 resolution.
804 Special characters cannot be printed using this command (use the
805 .B C
806 command for named characters).
808 This command is a groff extension; it is only used for devices whose
809 .I DESC
810 file contains the
811 .B tcommand
812 keyword; see
813 .BR groff_font (@MAN5EXT@).
816 .command u "n xxx" \[la]white_space\[ra]
817 Print word with track kerning.
819 This is the same as the
820 .B t
821 command except that after printing each character, the current
822 horizontal position is increased by the sum of the width of that
823 character and\~\c
824 .argument n
825 (an integer in
826 basic units\~\c
827 .unit u ).
828 This command is a groff extension; it is only used for devices whose
829 .I DESC
830 file contains the
831 .B tcommand
832 keyword; see
833 .BR groff_font (@MAN5EXT@).
836 .command V n
837 Move down to the absolute vertical position\~\c
838 .argument n
839 (a non-negative integer in basic units\~\c
840 .unit u )
841 relative to upper edge of current page.
844 .command v n
845 Move
846 .argument n
847 basic units\~\c
848 .unit u
849 down
850 .RI ( n
851 is a non-negative integer).
853 .I [54]
854 allows negative values for
855 .I n
856 also, but
857 .I groff
858 doesn't use this.
861 .command w
862 Informs about a paddable whitespace to increase readability.
864 The spacing itself must be performed explicitly by a move command.
867 .\" --------------------------------------------------------------------
868 .SS "Graphics Commands"
869 .\" --------------------------------------------------------------------
871 Each graphics or drawing command in the intermediate output starts
872 with the letter\~\c
873 .B D
874 followed by one or two characters that specify a subcommand; this
875 is followed by a fixed or variable number of integer arguments that
876 are separated by a single space character.
879 .BR D \ command
880 may not be followed by another command on the same line
881 (apart from a comment), so each
882 .BR D \ command
883 is terminated by a syntactical line break.
886 .I troff
887 output follows the classical spacing rules (no space between command
888 and subcommand, all arguments are preceded by a single space
889 character), but the parser allows optional space between the command
890 letters and makes the space before the first argument optional.
892 As usual, each space can be any sequence of tab and space characters.
895 Some graphics commands can take a variable number of arguments.
897 In this case, they are integers representing a size measured in basic
898 units\~\c
899 .unit u .
901 The arguments called
902 .list1..n h
903 stand for horizontal distances where positive means right, negative
904 left.
906 The arguments called
907 .list1..n v
908 stand for vertical distances where positive means down, negative up.
910 All these distances are offsets relative to the current location.
913 Unless indicated otherwise, each graphics command directly corresponds
914 to a similar
915 .I groff
916 .B \*[@backslash]D
917 escape sequence; see
918 .BR groff (@MAN7EXT@).
921 Unknown D\~commands are assumed to be device-specific.
923 Its arguments are parsed as strings; the whole information is then
924 sent to the postprocessor.
927 In the following command reference, the syntax element
928 .I \[la]line_break\[ra]
929 means a
930 .I syntactical line break
931 as defined in section
932 .BR Separation .
935 .D-multiarg ~
936 Draw B-spline from current position to offset
937 .indexed_offset h 1 v 1 ,
938 then to offset
939 .indexed_offset h 2 v 2
940 if given, etc.\& up to
941 .indexed_offset h n v n .
942 This command takes a variable number of argument pairs;
943 the current position is moved to the terminal point of the drawn curve.
946 .Da-command
947 Draw arc from current position to
948 .indexed_offset h 1 v 1 \|+\|\c
949 .indexed_offset h 2 v 2
950 with center at
951 .indexed_offset h 1 v 1 ;
952 then move the current position to the final point of the arc.
955 .D-command C d
956 .D-command+ C d dummy_arg
957 Draw a solid circle using the current fill color with diameter\~\c
958 .argument d
959 (integer in basic units\~\c
960 .unit u )
961 with leftmost point at the current position; then move the current
962 position to the rightmost point of the circle.
964 An optional second integer argument is ignored (this allows to the
965 formatter to generate an even number of arguments).
967 This command is a groff extension.
970 .D-command c d
971 Draw circle line with diameter\~\c
972 .argument d
973 (integer in basic units\~\c
974 .unit u )
975 with leftmost point at the current position; then move the current
976 position to the rightmost point of the circle.
979 .D-command E "h v"
980 Draw a solid ellipse in the current fill color with a horizontal
981 diameter of\~\c
982 .argument h
983 and a vertical diameter of\~\c
984 .argument v
985 (both integers in basic units\~\c
986 .unit u )
987 with the leftmost point at the current position; then move to the
988 rightmost point of the ellipse.
990 This command is a groff extension.
993 .D-command e "h v"
994 Draw an outlined ellipse with a horizontal diameter of\~\c
995 .argument h
996 and a vertical diameter of\~\c
997 .argument v
998 (both integers in basic units\~\c
999 .unit u )
1000 with the leftmost point at current position; then move to the
1001 rightmost point of the ellipse.
1004 .D-command F "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
1005 Set fill color for solid drawing objects using different color
1006 schemes; the analoguous command for setting the color of text, line
1007 graphics, and the outline of graphic objects is
1008 .BR m .
1010 The color components are specified as integer arguments between 0 and
1011 \n[@maxcolor].
1013 The number of color components and their meaning vary for the
1014 different color schemes.
1016 These commands are generated by the groff escape sequences
1017 .B \*[@backslash]D'F\ .\|.\|.'
1019 .B \*[@backslash]M
1020 (with no other corresponding graphics commands).
1022 No position changing.
1024 This command is a groff extension.
1029 .D-command Fc "cyan magenta yellow"
1030 Set fill color for solid drawing objects using the CMY color scheme,
1031 having the 3\~color components cyan, magenta, and yellow.
1034 .D-command Fd
1035 Set fill color for solid drawing objects to the default fill color value
1036 (black in most cases).
1038 No component arguments.
1041 .D-command Fg "gray"
1042 Set fill color for solid drawing objects to the shade of gray given by
1043 the argument, an integer between 0 (black) and \n[@maxcolor] (white).
1046 .D-command Fk "cyan magenta yellow black"
1047 Set fill color for solid drawing objects using the CMYK color scheme,
1048 having the 4\~color components cyan, magenta, yellow, and black.
1050 .D-command Fr "red green blue"
1051 Set fill color for solid drawing objects using the RGB color scheme,
1052 having the 3\~color components red, green, and blue.
1057 .D-command f n
1058 The argument
1059 .argument n
1060 must be an integer in the range -32767 to 32767.
1064 .RI "0 \[<=] " n " \[<=] 1000"
1065 Set the color for filling solid drawing objects to a shade of gray,
1066 where 0 corresponds to solid white, 1000 (the default) to solid black,
1067 and values in between to intermediate shades of gray; this is
1068 obsoleted by command
1069 .BR DFg .
1072 .IR n " < 0 or " n " > 1000"
1073 Set the filling color to the color that is currently being used for
1074 the text and the outline, see command
1075 .BR m .
1076 For example, the command sequence
1079 .ft CB
1082 mg 0 0 \n[@maxcolor]
1083 Df -1
1088 sets all colors to blue.
1092 No position changing.
1094 This command is a groff extension.
1099 .D-command l "h v"
1100 Draw line from current position to offset
1101 .offset h v
1102 (integers in basic units\~\c
1103 .unit u );
1104 then set current position to the end of the drawn line.
1107 .D-multiarg p
1108 Draw a polygon line from current position to offset
1109 .offset h1 v1 ,
1110 from there to offset
1111 .offset h2 v2 ,
1112 etc.\& up to offset
1113 .offset hn vn ,
1114 and from there back to the starting position.
1116 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1117 For historical reasons, the position is changed by adding the sum of
1118 all arguments with odd index to the actual horizontal position and the
1119 even ones to the vertical position.
1121 Although this doesn't make sense it is kept for compatibility.
1124 .el \{\
1125 As the polygon is closed, the end of drawing is the starting point, so
1126 the position doesn't change.
1129 This command is a groff extension.
1132 .D-multiarg P
1133 The same macro as the corresponding
1134 .B Dp
1135 command with the same arguments, but draws a solid polygon in the
1136 current fill color rather than an outlined polygon.
1138 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1139 The position is changed in the same way as with
1140 .BR Dp .
1142 .el \
1143 No position changing.
1145 This command is a groff extension.
1148 .D-command t n
1149 Set the current line thickness to\~\c
1150 .argument n
1151 (an integer in basic units\~\c
1152 .unit u )
1154 .argument n >0;
1156 .argument n =0
1157 select the smallest available line thickness; if
1158 .argument n <0
1159 set the line thickness proportional to the point size (this is the
1160 default before the first
1161 .B Dt
1162 command was specified).
1164 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1165 For historical reasons, the horizontal position is changed by adding
1166 the argument to the actual horizontal position, while the vertical
1167 position is not changed.
1169 Although this doesn't make sense it is kept for compatibility.
1172 .el \
1173 No position changing.
1175 This command is a groff extension.
1178 .\" --------------------------------------------------------------------
1179 .SS "Device Control Commands"
1180 .\" --------------------------------------------------------------------
1182 Each device control command starts with the letter
1183 .B x
1184 followed by a space character (optional or arbitrary space/\:tab in
1185 groff) and a subcommand letter or word; each argument (if any) must be
1186 preceded by a syntactical space.
1189 .B x
1190 commands are terminated by a
1191 .IR "syntactical line break" ;
1192 no device control command can be followed by another command on the same
1193 line (except a comment).
1196 The subcommand is basically a single letter, but to increase
1197 readability, it can be written as a word, i.e.\& an arbitrary sequence
1198 of characters terminated by the next tab, space, or newline character.
1200 All characters of the subcommand word but the first are simply ignored.
1202 For example,
1203 .I troff
1204 outputs the initialization command
1205 .B x\ i
1207 .B x\ init
1208 and the resolution command
1209 .B x\ r
1211 .BR "x\ res" .
1213 But writings like
1214 .B x\ i_like_groff
1216 .B x\ roff_is_groff
1217 resp.\& are accepted as well to mean the same commands.
1220 In the following, the syntax element
1221 .I \[la]line_break\[ra]
1222 means a
1223 .I syntactical line break
1224 as defined in section
1225 .BR Separation .
1227 .x-command F name
1228 .xsub Filename
1230 .argument name
1231 as the intended name for the current file in error reports.
1233 This is useful for remembering the original file name when groff uses
1234 an internal piping mechanism.
1236 The input file is not changed by this command.
1238 This command is a groff extension.
1241 .x-command f "n\ s"
1242 .xsub font
1243 Mount font position\~\c
1244 .argument n
1245 (a non-negative integer) with font named\~\c
1246 .argument s
1247 (a text word),
1249 .BR groff_font (@MAN5EXT@).
1252 .x-command H n
1253 .xsub Height
1254 Set character height to\~\c
1255 .argument n
1256 (a positive integer in scaled points\~\c
1257 .unit z ).
1259 Classical troff used the unit
1260 points (\c
1261 .unit p )
1262 instead; see section
1263 .BR COMPATIBILITY .
1266 .x-command i
1267 .xsub init
1268 Initialize device.
1270 This is the third command of the prologue.
1273 .x-command p
1274 .xsub pause
1275 Parsed but ignored.
1277 The classical documentation reads
1278 .I pause device, can be
1279 .IR restarted .
1282 .x-command r "n\ h\ v"
1283 .xsub resolution
1284 Resolution is\~\c
1285 .argument n ,
1286 while
1287 .argument h
1288 is the minimal horizontal motion, and
1289 .argument v
1290 the minimal vertical motion possible with this device; all arguments
1291 are positive integers in basic units\~\c
1292 .unit u
1293 per inch.
1295 This is the second command of the prologue.
1298 .x-command S n
1299 .xsub Slant
1300 Set slant to\~\c
1301 .argument n
1302 degrees (an integer in basic units\~\c
1303 .unit u ).
1306 .x-command s
1307 .xsub stop
1308 Terminates the processing of the current file; issued as the last
1309 command of any intermediate troff output.
1312 .x-command t
1313 .xsub trailer
1314 Generate trailer information, if any.
1317 .IR groff ,
1318 this is actually just ignored.
1321 .x-command T xxx
1322 .xsub Typesetter
1323 Set name of device to word
1324 .argument xxx ,
1325 a sequence of characters ended by the next whitespace character.
1327 The possible device names coincide with those from the groff
1328 .B -T
1329 option.
1331 This is the first command of the prologue.
1334 .x-command u n
1335 .xsub underline
1336 Configure underlining of spaces.
1339 .argument n
1340 is\~1, start underlining of spaces;
1342 .argument n
1343 is\~0, stop underlining of spaces.
1345 This is needed for the
1346 .B cu
1347 request in
1348 .I nroff
1349 mode and is ignored otherwise.
1351 This command is a groff extension.
1354 .x-command X anything
1355 .xsub X-escape
1356 Send string
1357 .argument anything
1358 uninterpreted to the device.
1360 If the line following this command starts with a
1361 .B +
1362 character this line is interpreted as a continuation line in the
1363 following sense.
1366 .B +
1367 is ignored, but a newline character is sent instead to the device, the
1368 rest of the line is sent uninterpreted.
1370 The same applies to all following lines until the first character of a
1371 line is not a
1372 .B +
1373 character.
1375 This command is generated by the
1376 .I groff
1377 escape sequence
1378 .BR \*[@backslash]X .
1380 The line-continuing feature is a groff extension.
1383 .\" --------------------------------------------------------------------
1384 .SS "Obsolete Command"
1385 .\" --------------------------------------------------------------------
1388 .I classical troff
1389 output, the writing of a single character was mostly done by a very
1390 strange command that combined a horizontal move and the printing of a
1391 character.
1393 It didn't have a command code, but is represented by a 3-character
1394 argument consisting of exactly 2\~digits and a character.
1397 .argument ddc
1398 Move right
1399 .argument dd
1400 (exactly two decimal digits) basic units\~\c
1401 .unit u ,
1402 then print character\~\c
1403 .argument c .
1407 In groff, arbitrary syntactical space around and within this command
1408 is allowed to be added.
1410 Only when a preceding command on the same line ends with an argument
1411 of variable length a separating space is obligatory.
1414 .I classical
1415 .IR troff ,
1416 large clusters of these and other commands were used, mostly without
1417 spaces; this made such output almost unreadable.
1422 For modern high-resolution devices, this command does not make sense
1423 because the width of the characters can become much larger than two
1424 decimal digits.
1426 In groff, this is only used for the devices
1427 .BR X75 ,
1428 .BR X75-12 ,
1429 .BR X100 ,
1431 .BR X100-12 .
1433 For other devices,
1434 the commands
1435 .B t
1436 and\~\c
1437 .B u
1438 provide a better functionality.
1441 .\" --------------------------------------------------------------------
1442 .SH "POSTPROCESSING"
1443 .\" --------------------------------------------------------------------
1446 .I roff
1447 postprocessors are programs that have the task to translate the
1448 intermediate output into actions that are sent to a device.
1450 A device can be some piece of hardware such as a printer, or a software
1451 file format suitable for graphical or text processing.
1454 .I groff
1455 system provides powerful means that make the programming of such
1456 postprocessors an easy task.
1458 There is a library function that parses the intermediate output and
1459 sends the information obtained to the device via methods of a class
1460 with a common interface for each device.
1462 So a
1463 .I groff
1464 postprocessor must only redefine the methods of this class.
1466 For details, see the reference in section
1467 .BR FILES .
1470 .\" --------------------------------------------------------------------
1471 .SH "EXAMPLES"
1472 .\" --------------------------------------------------------------------
1474 This section presents the intermediate output generated from the same
1475 input for three different devices.
1477 The input is the sentence
1478 .I hell world
1479 fed into groff on the command line.
1481 .Topic
1482 High-resolution device
1483 .I ps
1488 .ShellCommand echo "hell world" | groff -Z -T ps
1492 .ft CB
1493 x T ps
1494 x res 72000 1 1
1495 x init
1497 x font 5 TR
1499 s10000
1500 V12000
1501 H72000
1502 thell
1503 wh2500
1505 H96620
1506 torld
1507 n12000 0
1508 x trailer
1509 V792000
1510 x stop
1511 .ft P
1516 This output can be fed into the postprocessor
1517 .BR grops (@MAN1EXT@)
1518 to get its representation as a PostScript file.
1521 .Topic
1522 Low-resolution device
1523 .I latin1
1528 This is similar to the high-resolution device except that the
1529 positioning is done at a minor scale.
1531 Some comments (lines starting with
1532 .IR # )
1533 were added for clarification; they were not generated by the
1534 formatter.
1537 .ShellCommand echo "hell world" | groff -Z -T latin1
1541 .I # prologue
1542 .ft CB
1543 x T latin1
1544 x res 240 24 40
1545 x init
1546 .I # begin a new page
1547 .ft CB
1549 .I # font setup
1550 .ft CB
1551 x font 1 R
1554 .I # initial positioning on the page
1555 .ft CB
1558 .I # write text `hell'
1559 .ft CB
1560 thell
1561 .I # inform about a space, and do it by a horizontal jump
1562 .ft CB
1563 wh24
1564 .I # write text `world'
1565 .ft CB
1566 tworld
1567 .I # announce line break, but do nothing because ...
1568 .ft CB
1569 n40 0
1570 .I # ... the end of the document has been reached
1571 .ft CB
1572 x trailer
1573 V2640
1574 x stop
1575 .ft P
1580 This output can be fed into the postprocessor
1581 .BR grotty (@MAN1EXT@)
1582 to get a formatted text document.
1585 .Topic
1586 Classical style output
1591 As a computer monitor has a very low resolution compared to modern
1592 printers the intermediate output for the X\~devices can use the
1593 jump-and-write command with its 2-digit displacements.
1596 .ShellCommand echo "hell world" | groff -Z -T X100
1600 .ft CB
1601 x T X100
1602 x res 100 1 1
1603 x init
1605 x font 5 TR
1609 H100
1610 .I # write text with old-style jump-and-write command
1611 .ft CB
1612 ch07e07l03lw06w11o07r05l03dh7
1613 n16 0
1614 x trailer
1615 V1100
1616 x stop
1617 .ft P
1622 This output can be fed into the postprocessor
1623 .BR xditview (1x)
1625 .BR gxditview (@MAN1EXT@)
1626 for displaying in\~X.
1629 Due to the obsolete jump-and-write command, the text clusters in the
1630 classical output are almost unreadable.
1633 .\" --------------------------------------------------------------------
1634 .SH "COMPATIBILITY"
1635 .\" --------------------------------------------------------------------
1637 The intermediate output language of the 
1638 .I classical troff
1639 was first documented in
1640 .IR [97] .
1643 .I groff
1644 intermediate output format is compatible with this specification
1645 except for the following features.
1646 .Topic
1647 The classical quasi device independence is not yet implemented.
1649 .Topic
1650 The old hardware was very different from what we use today.
1652 So the groff devices are also fundamentally different from the ones in
1653 classical troff.
1655 For example, the classical PostScript device was called
1656 .I post
1657 and had a resolution of 720 units per inch,
1658 while groff's
1659 .I ps
1660 device has a resolution of 72000 units per inch.
1662 Maybe, by implementing some rescaling mechanism similar to the
1663 classical quasi device independence, these could be integrated into
1664 modern groff.
1666 .Topic
1667 The B-spline command
1668 .B D~
1669 is correctly handled by the intermediate output parser, but the
1670 drawing routines aren't implemented in some of the postprocessor
1671 programs.
1672 .Topic
1673 The argument of the commands
1674 .B s
1676 .B x H
1677 has the implicit unit scaled point\~\c
1678 .unit z
1679 in groff, while classical troff had point (\c
1680 .unit p ).
1682 This isn't an incompatibility, but a compatible extension,
1683 for both units coincide for all devices without a
1684 .I sizescale
1685 parameter, including all classical and the groff text devices.
1687 The few groff devices with a sizescale parameter either did
1688 not exist, had a different name, or seem to have had a different
1689 resolution.
1691 So conflicts with classical devices are very unlikely.
1693 .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
1694 .Topic
1695 The position changing after the commands
1696 .BR Dp ,
1697 .BR DP ,
1699 .B Dt
1700 is illogical, but as old versions of groff used this feature it is
1701 kept for compatibility reasons.
1702 .\}             \" @STUPID_DRAWING_POSITIONING
1703 .el \{\
1704 .Topic
1705 Temporarily, there existed some confusion on the positioning after the
1706 .B D
1707 commands that are groff extensions.
1709 This has been clarified by establishing the classical rule for all
1710 groff drawing commands:
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.
1719 From this, the positionings specified for the drawing commands above
1720 follow quite naturally.
1721 .\}             \" @STUPID_DRAWING_POSITIONING
1724 The differences between groff and classical troff are documented in
1725 .BR groff_diff (@MAN7EXT@).
1728 .\" --------------------------------------------------------------------
1729 .SH "FILES"
1730 .\" --------------------------------------------------------------------
1733 .BI @FONTDIR@/dev name /DESC
1734 Device description file for device
1735 .IR name .
1738 .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
1739 Defines the parser and postprocessor for the intermediate output.
1741 It is located relative to the top directory of the
1742 .I groff
1743 source tree, e.g.
1744 .IR @GROFFSRCDIR@ .
1746 This parser is the definitive specification of the
1747 .I groff
1748 intermediate output format.
1751 .\" --------------------------------------------------------------------
1752 .SH "SEE ALSO"
1753 .\" --------------------------------------------------------------------
1755 A reference like
1756 .BR groff (@MAN7EXT@)
1757 refers to a manual page; here
1758 .I groff
1759 in section\~\c
1760 .I @MAN7EXT@
1761 of the man-page documentation system.
1763 To read the example, look up section\~@MAN7EXT@ in your desktop help
1764 system or call from the shell prompt
1768 .ShellCommand man @MAN7EXT@ groff
1772 For more details, see
1773 .BR man (1).
1776 .BR groff (@MAN1EXT@)
1777 option
1778 .B -Z
1779 and further readings on groff.
1782 .BR groff (@MAN7EXT@)
1783 for details of the
1784 .I groff
1785 language such as numerical units and escape sequences.
1788 .BR groff_font (@MAN5EXT@)
1789 for details on the device scaling parameters of the
1790 .B DESC
1791 file.
1794 .BR troff (@MAN1EXT@)
1795 generates the device-independent intermediate output.
1798 .BR roff (@MAN7EXT@)
1799 for historical aspects and the general structure of roff systems.
1802 .BR groff_diff (@MAN7EXT@)
1803 The differences between the intermediate output in groff and classical
1804 troff.
1807 .BR \%grodvi (@MAN1EXT@),
1808 .BR \%grohtml (@MAN1EXT@),
1809 .BR \%grolbp (@MAN1EXT@),
1810 .BR \%grolj4 (@MAN1EXT@),
1811 .BR \%grops (@MAN1EXT@),
1812 .BR \%grotty (@MAN1EXT@)
1815 the groff postprocessor programs.
1819 For a treatment of all aspects of the groff system within a single
1820 document, see the
1821 .I groff info
1822 .IR file .
1824 It can be read within the integrated help systems, within
1825 .BR emacs (1)
1826 or from the shell prompt by
1829 .ShellCommand info groff
1834 .I classical troff output language
1835 is 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" .
1840 .I [CSTR #97]
1841 .I A Typesetter-independent TROFF
1843 .I Brian Kernighan
1844 is the original and most concise documentation on the output language;
1846 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
1849 .I [CSTR\~#54]
1850 The 1992 revision of the
1851 .I Nroff/\:Troff User's Manual
1853 .I J.\& F.\& Osanna
1855 .I Brian Kernighan
1856 isn't as concise as
1857 .I [CSTR\~#97]
1858 regarding the output language;
1860 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
1863 .\" --------------------------------------------------------------------
1864 .SH "AUTHORS"
1865 .\" --------------------------------------------------------------------
1867 Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
1869 This document is distributed under the terms of the FDL (GNU Free
1870 Documentation License) version 1.1 or later.
1872 You should have received a copy of the FDL with this package; it is also
1873 available on-line at the
1874 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1877 This document is part of
1878 .IR groff ,
1879 the GNU roff distribution.
1881 It is based on a former version \- published under the GPL \- that
1882 described only parts of the
1883 .I groff
1884 extensions of the output language.
1886 It has been rewritten 2002 by
1887 .MTO bwarken@mayn.de "Bernd Warken"
1888 and is maintained by
1889 .MTO wl@gnu.org "Werner Lemberg" .
1891 .\" --------------------------------------------------------------------
1892 .\" Emacs settings
1893 .\" --------------------------------------------------------------------
1895 .\" Local Variables:
1896 .\" mode: nroff
1897 .\" End: