1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: grops, Next: grodvi, Prev: grotty, Up: Output Devices
33 * Embedding PostScript::
36 File: groff, Node: Invoking grops, Next: Embedding PostScript, Prev: grops, Up: grops
42 File: groff, Node: Embedding PostScript, Prev: Invoking grops, Up: grops
48 File: groff, Node: grodvi, Next: grolj4, Prev: grops, Up: Output Devices
58 File: groff, Node: Invoking grodvi, Prev: grodvi, Up: grodvi
64 File: groff, Node: grolj4, Next: grolbp, Prev: grodvi, Up: Output Devices
74 File: groff, Node: Invoking grolj4, Prev: grolj4, Up: grolj4
80 File: groff, Node: grolbp, Next: grohtml, Prev: grolj4, Up: Output Devices
90 File: groff, Node: Invoking grolbp, Prev: grolbp, Up: grolbp
96 File: groff, Node: grohtml, Next: gxditview, Prev: grolbp, Up: Output Devices
104 * grohtml specific registers and strings::
107 File: groff, Node: Invoking grohtml, Next: grohtml specific registers and strings, Prev: grohtml, Up: grohtml
113 File: groff, Node: grohtml specific registers and strings, Prev: Invoking grohtml, Up: grohtml
115 `grohtml' specific registers and strings
116 ----------------------------------------
118 - Register: \n[ps4html]
119 - String: \*[www-image-template]
120 The registers `ps4html' and `www-image-template' are defined by
121 the `pre-grohtml' preprocessor. `pre-grohtml' reads in the
122 `troff' input, marks up the inline equations and passes the result
126 troff -Tps -rps4html=1 -dwww-image-template=TEMPLATE
133 The PostScript device is used to create all the image files, and
134 the register `ps4html' enables the macro sets to ignore floating
135 keeps, footers, and headings.
137 The register `www-image-template' is set to the user specified
138 template name or the default name.
141 File: groff, Node: gxditview, Prev: grohtml, Up: Output Devices
148 * Invoking gxditview::
151 File: groff, Node: Invoking gxditview, Prev: gxditview, Up: gxditview
157 File: groff, Node: File formats, Next: Installation, Prev: Output Devices, Up: Top
162 All files read and written by `gtroff' are text files. The
163 following two sections describe their format.
171 File: groff, Node: gtroff Output, Next: Font Files, Prev: File formats, Up: File formats
176 This section describes the intermediate output format of GNU
177 `troff'. This output is produced by a run of `gtroff' before it is fed
178 into a device postprocessor program.
180 As `groff' is a wrapper program around `gtroff' that automatically
181 calls a postprocessor, this output does not show up normally. This is
182 why it is called "intermediate". `groff' provides the option `-Z' to
183 inhibit postprocessing, such that the produced intermediate output is
184 sent to standard output just like calling `gtroff' manually.
186 Here, the term "troff output" describes what is output by `gtroff',
187 while "intermediate output" refers to the language that is accepted by
188 the parser that prepares this output for the postprocessors. This
189 parser is smarter on whitespace and implements obsolete elements for
190 compatibility, otherwise both formats are the same.(1) (*note gtroff
193 The main purpose of the intermediate output concept is to facilitate
194 the development of postprocessors by providing a common programming
195 interface for all devices. It has a language of its own that is
196 completely different from the `gtroff' language. While the `gtroff'
197 language is a high-level programming language for text processing, the
198 intermediate output language is a kind of low-level assembler language
199 by specifying all positions on the page for writing and drawing.
201 The intermediate output produced by `gtroff' is fairly readable,
202 while output from AT&T `troff' is rather hard to understand because of
203 strange habits that are still supported, but not used any longer by
208 * Language Concepts::
209 * Command Reference::
210 * Intermediate Output Examples::
211 * Output Language Compatibility::
214 File: groff, Node: gtroff Output-Footnotes, Up: gtroff Output
216 (1) The parser and postprocessor for intermediate output can be
218 `GROFF-SOURCE-DIR/src/libs/libdriver/input.cc'.
221 File: groff, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output
226 During the run of `gtroff', the input data is cracked down to the
227 information on what has to be printed at what position on the intended
228 device. So the language of the intermediate output format can be quite
229 small. Its only elements are commands with and without arguments. In
230 this section, the term "command" always refers to the intermediate
231 output language, and never to the `gtroff' language used for document
232 formatting. There are commands for positioning and text writing, for
233 drawing, and for device controlling.
242 File: groff, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts
247 AT&T `troff' output has strange requirements on whitespace. The
248 `gtroff' output parser, however, is smart about whitespace by making it
249 maximally optional. The whitespace characters, i.e., the tab, space,
250 and newline characters, always have a syntactical meaning. They are
251 never printable because spacing within the output is always done by
252 positioning commands.
254 Any sequence of space or tab characters is treated as a single
255 "syntactical space". It separates commands and arguments, but is only
256 required when there would occur a clashing between the command code and
257 the arguments without the space. Most often, this happens when
258 variable-length command names, arguments, argument lists, or command
259 clusters meet. Commands and arguments with a known, fixed length need
260 not be separated by syntactical space.
262 A line break is a syntactical element, too. Every command argument
263 can be followed by whitespace, a comment, or a newline character. Thus
264 a "syntactical line break" is defined to consist of optional
265 syntactical space that is optionally followed by a comment, and a
268 The normal commands, those for positioning and text, consist of a
269 single letter taking a fixed number of arguments. For historical
270 reasons, the parser allows to stack such commands on the same line, but
271 fortunately, in `gtroff''s intermediate output, every command with at
272 least one argument is followed by a line break, thus providing
273 excellent readability.
275 The other commands - those for drawing and device controlling - have
276 a more complicated structure; some recognize long command names, and
277 some take a variable number of arguments. So all `D' and `x' commands
278 were designed to request a syntactical line break after their last
279 argument. Only one command, `x X', has an argument that can stretch
280 over several lines; all other commands must have all of their arguments
281 on the same line as the command, i.e., the arguments may not be
282 splitted by a line break.
284 Empty lines (these are lines containing only space and/or a
285 comment), can occur everywhere. They are just ignored.
288 File: groff, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts
293 Some commands take integer arguments that are assumed to represent
294 values in a measurement unit, but the letter for the corresponding
295 scale indicator is not written with the output command arguments. Most
296 commands assume the scale indicator `u', the basic unit of the device,
297 some use `z', the scaled point unit of the device, while others, such
298 as the color commands, expect plain integers.
300 Note that single characters can have the eighth bit set, as can the
301 names of fonts and special characters. The names of characters and
302 fonts can be of arbitrary length. A character that is to be printed
303 will always be in the current font.
305 A string argument is always terminated by the next whitespace
306 character (space, tab, or newline); an embedded `#' character is
307 regarded as part of the argument, not as the beginning of a comment
308 command. An integer argument is already terminated by the next
309 non-digit character, which then is regarded as the first character of
310 the next argument or command.
313 File: groff, Node: Document Parts, Prev: Argument Units, Up: Language Concepts
318 A correct intermediate output document consists of two parts, the
319 "prologue" and the "body".
321 The task of the prologue is to set the general device parameters
322 using three exactly specified commands. `gtroff''s prologue is
323 guaranteed to consist of the following three lines (in that order):
330 with the arguments set as outlined in *Note Device Control Commands::.
331 Note that the parser for the intermediate output format is able to
332 swallow additional whitespace and comments as well even in the prologue.
334 The body is the main section for processing the document data.
335 Syntactically, it is a sequence of any commands different from the ones
336 used in the prologue. Processing is terminated as soon as the first
337 `x stop' command is encountered; the last line of any `gtroff'
338 intermediate output always contains such a command.
340 Semantically, the body is page oriented. A new page is started by a
341 `p' command. Positioning, writing, and drawing commands are always
342 done within the current page, so they cannot occur before the first `p'
343 command. Absolute positioning (by the `H' and `V' commands) is done
344 relative to the current page; all other positioning is done relative to
345 the current location within this page.
348 File: groff, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output
353 This section describes all intermediate output commands, both from
354 AT&T `troff' as well as the `gtroff' extensions.
360 * Graphics Commands::
361 * Device Control Commands::
365 File: groff, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference
370 `#ANYTHING<end of line>'
371 A comment. Ignore any characters from the `#' character up to the
372 next newline character.
374 This command is the only possibility for commenting in the
375 intermediate output. Each comment can be preceded by arbitrary
376 syntactical space; every command can be terminated by a comment.
379 File: groff, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference
384 The commands in this subsection have a command code consisting of a
385 single character, taking a fixed number of arguments. Most of them are
386 commands for positioning and text writing. These commands are smart
387 about whitespace. Optionally, syntactical space can be inserted
388 before, after, and between the command letter and its arguments. All
389 of these commands are stackable, i.e., they can be preceded by other
390 simple commands or followed by arbitrary other commands on the same
391 line. A separating syntactical space is only necessary when two
392 integer arguments would clash or if the preceding argument ends with a
396 Print a special character named XXX. The trailing syntactical
397 space or line break is necessary to allow glyph names of arbitrary
398 length. The glyph is printed at the current print position; the
399 glyph's size is read from the font file. The print position is
403 Print glyph G at the current print position;(1) (*note Simple
404 Commands-Footnote-1::) the glyph's size is read from the font
405 file. The print position is not changed.
408 Set font to font number N (a non-negative integer).
411 Move right to the absolute vertical position N (a non-negative
412 integer in basic units `u' relative to left edge of current page.
415 Move N (a non-negative integer) basic units `u' horizontally to
416 the right. The original UNIX troff manual allows negative values
417 for N also, but `gtroff' doesn't use this.
419 `m COLOR-SCHEME [COMPONENT ...]'
420 Set the color for text (glyphs), line drawing, and the outline of
421 graphic objects using different color schemes; the analoguous
422 command for the filling color of graphic objects is `DF'. The
423 color components are specified as integer arguments between 0 and
424 65536. The number of color components and their meaning vary for
425 the different color schemes. These commands are generated by
426 `gtroff''s escape sequence `\m'. No position changing. These
427 commands are a `gtroff' extension.
429 `mc CYAN MAGENTA YELLOW'
430 Set color using the CMY color scheme, having the 3 color
431 components CYAN, MAGENTA, and YELLOW.
434 Set color to the default color value (black in most cases).
435 No component arguments.
438 Set color to the shade of gray given by the argument, an
439 integer between 0 (black) and 65536 (white).
441 `mk CYAN MAGENTA YELLOW BLACK'
442 Set color using the CMYK color scheme, having the 4 color
443 components CYAN, MAGENTA, YELLOW, and BLACK.
446 Set color using the RGB color scheme, having the 3 color
447 components RED, GREEN, and BLUE.
450 Print glyph with index N (a non-negative integer) of the current
451 font. This command is a `gtroff' extension.
454 Inform the device about a line break, but no positioning is done by
455 this command. In AT&T `troff', the integer arguments B and A
456 informed about the space before and after the current line to make
457 the intermediate output more human readable without performing any
458 action. In `groff', they are just ignored, but they must be
459 provided for compatibility reasons.
462 Begin a new page in the outprint. The page number is set to N.
463 This page is completely independent of pages formerly processed
464 even if those have the same page number. The vertical position on
465 the outprint is automatically set to 0. All positioning, writing,
466 and drawing is always done relative to a page, so a `p' command
467 must be issued before any of these commands.
470 Set point size to N scaled points (this is unit `z'). AT&T
471 `troff' used the unit points (`p') instead. *Note Output Language
475 `t XXX DUMMY-ARG<whitespace>'
476 Print a word, i.e., a sequence of characters XXX representing
477 output glyphs which names are single characters, terminated by a
478 space character or a line break; an optional second integer
479 argument is ignored (this allows the formatter to generate an even
480 number of arguments). The first glyph should be printed at the
481 current position, the current horizontal position should then be
482 increased by the width of the first glyph, and so on for each
483 glyph. The widths of the glyphs are read from the font file,
484 scaled for the current point size, and rounded to a multiple of
485 the horizontal resolution. Special characters cannot be printed
486 using this command (use the `C' command for special characters).
487 This command is a `gtroff' extension; it is only used for devices
488 whose `DESC' file contains the `tcommand' keyword (*note DESC File
491 `u N XXX<whitespace>'
492 Print word with track kerning. This is the same as the `t'
493 command except that after printing each glyph, the current
494 horizontal position is increased by the sum of the width of that
495 glyph and N (an integer in basic units `u'). This command is a
496 `gtroff' extension; it is only used for devices whose `DESC' file
497 contains the `tcommand' keyword (*note DESC File Format::).
500 Move down to the absolute vertical position N (a non-negative
501 integer in basic units `u') relative to upper edge of current page.
504 Move N basic units `u' down (N is a non-negative integer). The
505 original UNIX troff manual allows negative values for N also, but
506 `gtroff' doesn't use this.
509 Informs about a paddable white space to increase readability. The
510 spacing itself must be performed explicitly by a move command.
513 File: groff, Node: Simple Commands-Footnotes, Up: Simple Commands
515 (1) `c' is actually a misnomer since it outputs a glyph.
518 File: groff, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference
523 Each graphics or drawing command in the intermediate output starts
524 with the letter `D', followed by one or two characters that specify a
525 subcommand; this is followed by a fixed or variable number of integer
526 arguments that are separated by a single space character. A `D'
527 command may not be followed by another command on the same line (apart
528 from a comment), so each `D' command is terminated by a syntactical
531 `gtroff' output follows the classical spacing rules (no space
532 between command and subcommand, all arguments are preceded by a single
533 space character), but the parser allows optional space between the
534 command letters and makes the space before the first argument optional.
535 As usual, each space can be any sequence of tab and space characters.
537 Some graphics commands can take a variable number of arguments. In
538 this case, they are integers representing a size measured in basic
539 units `u'. The arguments called H1, H2, ..., HN stand for horizontal
540 distances where positive means right, negative left. The arguments
541 called V1, V2, ..., VN stand for vertical distances where positive
542 means down, negative up. All these distances are offsets relative to
543 the current location.
545 Unless indicated otherwise, each graphics command directly
546 corresponds to a similar `gtroff' `\D' escape sequence. *Note Drawing
549 Unknown `D' commands are assumed to be device-specific. Its
550 arguments are parsed as strings; the whole information is then sent to
553 In the following command reference, the syntax element <line break>
554 means a syntactical line break as defined above.
556 `D~ H1 V1 H2 V2 ... HN VN<line break>'
557 Draw B-spline from current position to offset (H1,V1), then to
558 offset (H2,V2), if given, etc. up to (HN,VN). This command takes
559 a variable number of argument pairs; the current position is moved
560 to the terminal point of the drawn curve.
562 `Da H1 V1 H2 V2<line break>'
563 Draw arc from current position to (H1,V1)+(H2,V2) with center at
564 (H1,V1); then move the current position to the final point of the
568 `DC D DUMMY-ARG<line break>'
569 Draw a solid circle using the current fill color with diameter D
570 (integer in basic units `u') with leftmost point at the current
571 position; then move the current position to the rightmost point of
572 the circle. An optional second integer argument is ignored (this
573 allows the formatter to generate an even number of arguments).
574 This command is a `gtroff' extension.
577 Draw circle line with diameter D (integer in basic units `u') with
578 leftmost point at the current position; then move the current
579 position to the rightmost point of the circle.
582 Draw a solid ellipse in the current fill color with a horizontal
583 diameter of H and a vertical diameter of V (both integers in basic
584 units `u') with the leftmost point at the current position; then
585 move to the rightmost point of the ellipse. This command is a
589 Draw an outlined ellipse with a horizontal diameter of H and a
590 vertical diameter of V (both integers in basic units `u') with the
591 leftmost point at current position; then move to the rightmost
592 point of the ellipse.
594 `DF COLOR-SCHEME [COMPONENT ...]<line break>'
595 Set fill color for solid drawing objects using different color
596 schemes; the analoguous command for setting the color of text, line
597 graphics, and the outline of graphic objects is `m'. The color
598 components are specified as integer arguments between 0 and 65536.
599 The number of color components and their meaning vary for the
600 different color schemes. These commands are generated by
601 `gtroff''s escape sequences `\D'F ...'' and `\M' (with no other
602 corresponding graphics commands). No position changing. This
603 command is a `gtroff' extension.
605 `DFc CYAN MAGENTA YELLOW<line break>'
606 Set fill color for solid drawing objects using the CMY color
607 scheme, having the 3 color components CYAN, MAGENTA, and
611 Set fill color for solid drawing objects to the default fill
612 color value (black in most cases). No component arguments.
614 `DFg GRAY<line break>'
615 Set fill color for solid drawing objects to the shade of gray
616 given by the argument, an integer between 0 (black) and 65536
619 `DFk CYAN MAGENTA YELLOW BLACK<line break>'
620 Set fill color for solid drawing objects using the CMYK color
621 scheme, having the 4 color components CYAN, MAGENTA, YELLOW,
624 `DFr RED GREEN BLUE<line break>'
625 Set fill color for solid drawing objects using the RGB color
626 scheme, having the 3 color components RED, GREEN, and BLUE.
629 The argument N must be an integer in the range -32767 to 32767.
632 Set the color for filling solid drawing objects to a shade of
633 gray, where 0 corresponds to solid white, 1000 (the default)
634 to solid black, and values in between to intermediate shades
635 of gray; this is obsoleted by command `DFg'.
638 Set the filling color to the color that is currently being
639 used for the text and the outline, see command `m'. For
640 example, the command sequence
646 sets all colors to blue.
648 No position changing. This command is a `gtroff' extension.
651 Draw line from current position to offset (H,V) (integers in basic
652 units `u'); then set current position to the end of the drawn line.
654 `Dp H1 V1 H2 V2 ... HN VN<line break>'
655 Draw a polygon line from current position to offset (H1,V1), from
656 there to offset (H2,V2), etc. up to offset (HN,VN), and from there
657 back to the starting position. For historical reasons, the
658 position is changed by adding the sum of all arguments with odd
659 index to the actual horizontal position and the even ones to the
660 vertical position. Although this doesn't make sense it is kept
661 for compatibility. This command is a `gtroff' extension.
663 `Dp H1 V1 H2 V2 ... HN VN<line break>'
664 Draw a solid polygon in the current fill color rather than an
665 outlined polygon, using the same arguments and positioning as the
666 corresponding `Dp' command. This command is a `gtroff' extension.
669 Set the current line thickness to N (an integer in basic units
670 `u') if N>0; if N=0 select the smallest available line thickness;
671 if N<0 set the line thickness proportional to the point size (this
672 is the default before the first `Dt' command was specified). For
673 historical reasons, the horizontal position is changed by adding
674 the argument to the actual horizontal position, while the vertical
675 position is not changed. Although this doesn't make sense it is
676 kept for compatibility. This command is a `gtroff' extension.
679 File: groff, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference
681 Device Control Commands
682 .......................
684 Each device control command starts with the letter `x', followed by
685 a space character (optional or arbitrary space or tab in `gtroff') and
686 a subcommand letter or word; each argument (if any) must be preceded by
687 a syntactical space. All `x' commands are terminated by a syntactical
688 line break; no device control command can be followed by another
689 command on the same line (except a comment).
691 The subcommand is basically a single letter, but to increase
692 readability, it can be written as a word, i.e., an arbitrary sequence
693 of characters terminated by the next tab, space, or newline character.
694 All characters of the subcommand word but the first are simply ignored.
695 For example, `gtroff' outputs the initialization command `x i' as
696 `x init' and the resolution command `x r' as `x res'.
698 In the following, the syntax element <line break> means a
699 syntactical line break (*note Separation::).
701 `xF NAME<line break>'
702 The `F' stands for FILENAME.
704 Use NAME as the intended name for the current file in error
705 reports. This is useful for remembering the original file name
706 when `gtroff' uses an internal piping mechanism. The input file is
707 not changed by this command. This command is a `gtroff' extension.
710 The `f' stands for FONT.
712 Mount font position N (a non-negative integer) with font named S
713 (a text word). *Note Font Positions::.
716 The `H' stands for HEIGHT.
718 Set glyph height to N (a positive integer in scaled points `z').
719 AT&T `troff' uses the unit points (`p') instead. *Note Output
720 Language Compatibility::.
723 The `i' stands for INIT.
725 Initialize device. This is the third command of the prologue.
728 The `p' stands for PAUSE.
730 Parsed but ignored. The original UNIX troff manual writes
732 pause device, can be restarted
734 `xr N H V<line break>'
735 The `r' stands for RESOLUTION.
737 Resolution is N, while H is the minimal horizontal motion, and V
738 the minimal vertical motion possible with this device; all
739 arguments are positive integers in basic units `u' per inch. This
740 is the second command of the prologue.
743 The `S' stands for SLANT.
745 Set slant to N (an integer in basic units `u').
748 The `s' stands for STOP.
750 Terminates the processing of the current file; issued as the last
751 command of any intermediate troff output.
754 The `t' stands for TRAILER.
756 Generate trailer information, if any. In GTROFF, this is actually
760 The `T' stands for TYPESETTER.
762 Set name of device to word XXX, a sequence of characters ended by
763 the next white space character. The possible device names coincide
764 with those from the `groff' `-T' option. This is the first
765 command of the prologue.
768 The `u' stands for UNDERLINE.
770 Configure underlining of spaces. If N is 1, start underlining of
771 spaces; if N is 0, stop underlining of spaces. This is needed for
772 the `cu' request in nroff mode and is ignored otherwise. This
773 command is a `gtroff' extension.
775 `xX ANYTHING<line break>'
776 The `x' stands for X-ESCAPE.
778 Send string ANYTHING uninterpreted to the device. If the line
779 following this command starts with a `+' character this line is
780 interpreted as a continuation line in the following sense. The
781 `+' is ignored, but a newline character is sent instead to the
782 device, the rest of the line is sent uninterpreted. The same
783 applies to all following lines until the first character of a line
784 is not a `+' character. This command is generated by the `gtroff'
785 escape sequence `\X'. The line-continuing feature is a `gtroff'
789 File: groff, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference
794 In AT&T `troff' output, the writing of a single glyph is mostly done
795 by a very strange command that combines a horizontal move and a single
796 character giving the glyph name. It doesn't have a command code, but
797 is represented by a 3-character argument consisting of exactly 2 digits
801 Move right DD (exactly two decimal digits) basic units `u', then
802 print glyph G (represented as a single character).
804 In `gtroff', arbitrary syntactical space around and within this
805 command is allowed to be added. Only when a preceding command on
806 the same line ends with an argument of variable length a
807 separating space is obligatory. In AT&T `troff', large clusters
808 of these and other commands are used, mostly without spaces; this
809 made such output almost unreadable.
811 For modern high-resolution devices, this command does not make sense
812 because the width of the glyphs can become much larger than two decimal
813 digits. In `gtroff', this is only used for the devices `X75',
814 `X75-12', `X100', and `X100-12'. For other devices, the commands `t'
815 and `u' provide a better functionality.
818 File: groff, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output
820 Intermediate Output Examples
821 ----------------------------
823 This section presents the intermediate output generated from the same
824 input for three different devices. The input is the sentence `hell
825 world' fed into `gtroff' on the command line.
827 High-resolution device `ps'
828 This is the standard output of `gtroff' if no `-T' option is given.
830 shell> echo "hell world" | groff -Z -T ps
851 This output can be fed into `grops' to get its representation as a
854 Low-resolution device `latin1'
855 This is similar to the high-resolution device except that the
856 positioning is done at a minor scale. Some comments (lines
857 starting with `#') were added for clarification; they were not
858 generated by the formatter.
860 shell> echo "hell world" | groff -Z -T latin1
872 # initial positioning on the page
877 # inform about space, and issue a horizontal jump
881 # announce line break, but do nothing because ...
883 # ... the end of the document has been reached
888 This output can be fed into `grotty' to get a formatted text
892 Since a computer monitor has a very low resolution compared to
893 modern printers the intermediate output for the X Window devices
894 can use the jump-and-write command with its 2-digit displacements.
896 shell> echo "hell world" | groff -Z -T X100
907 # write text with jump-and-write commands
908 ch07e07l03lw06w11o07r05l03dh7
914 This output can be fed into `xditview' or `gxditview' for
917 Due to the obsolete jump-and-write command, the text clusters in
918 the AT&T `troff' output are almost unreadable.
921 File: groff, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output
923 Output Language Compatibility
924 -----------------------------
926 The intermediate output language of AT&T `troff' was first
927 documented in the UNIX troff manual, with later additions documented in
928 `A Typesetter-indenpendent TROFF', written by Brian Kernighan.
930 The `gtroff' intermediate output format is compatible with this
931 specification except for the following features.
933 * The classical quasi device independence is not yet implemented.
935 * The old hardware was very different from what we use today. So the
936 `groff' devices are also fundamentally different from the ones in
937 AT&T `troff'. For example, the AT&T PostScript device is called
938 `post' and has a resolution of only 720 units per inch, suitable
939 for printers 20 years ago, while `groff''s `ps' device has a
940 resolution of 72000 units per inch. Maybe, by implementing some
941 rescaling mechanism similar to the classical quasi device
942 independence, `groff' could emulate AT&T's `post' device.
944 * The B-spline command `D~' is correctly handled by the intermediate
945 output parser, but the drawing routines aren't implemented in some
946 of the postprocessor programs.
948 * The argument of the commands `s' and `x H' has the implicit unit
949 scaled point `z' in `gtroff', while AT&T `troff' has point (`p').
950 This isn't an incompatibility but a compatible extension, for both
951 units coincide for all devices without a `sizescale' parameter in
952 the `DESC' file, including all postprocessors from AT&T and
953 `groff''s text devices. The few `groff' devices with a
954 `sizescale' parameter either do not exist for AT&T `troff', have a
955 different name, or seem to have a different resolution. So
956 conflicts are very unlikely.
958 * The position changing after the commands `Dp', `DP', and `Dt' is
959 illogical, but as old versions of `gtroff' used this feature it is
960 kept for compatibility reasons.
964 File: groff, Node: Font Files, Prev: gtroff Output, Up: File formats
969 The `gtroff' font format is roughly a superset of the `ditroff' font
970 format (as used in later versions of AT&T `troff' and its descendants).
971 Unlike the `ditroff' font format, there is no associated binary
972 format; all files are text files.(1) (*note Font Files-Footnote-1::)
973 The font files for device NAME are stored in a directory `devNAME'.
974 There are two types of file: a device description file called `DESC'
975 and for each font F a font file called `F'.
983 File: groff, Node: Font Files-Footnotes, Up: Font Files
985 (1) Plan 9 `troff' has also abandoned the binary format.
988 File: groff, Node: DESC File Format, Next: Font File Format, Prev: Font Files, Up: Font Files
993 The `DESC' file can contain the following types of line. Except for
994 the `charset' keyword which must comes last (if at all), the order of
995 the lines is not important.
998 There are N machine units per inch.
1001 The horizontal resolution is N machine units.
1004 The vertical resolution is N machine units.
1007 The scale factor for point sizes. By default this has a value
1008 of 1. One scaled point is equal to one point/N. The arguments to
1009 the `unitwidth' and `sizes' commands are given in scaled points.
1010 *Note Fractional Type Sizes::, for more information.
1013 Quantities in the font files are given in machine units for fonts
1014 whose point size is N scaled points.
1017 Call PROGRAM as a preprocessor. Currently, this keyword is used
1018 by `groff' with option `-Thtml' only.
1021 Call PROGRAM as a postprocessor. For example, the line
1026 in the file `devdvi/DESC' makes `groff' call `grodvi' if option
1027 `-Tdvi' is given (and `-Z' isn't used).
1030 This means that the postprocessor can handle the `t' and `u'
1031 intermediate output commands.
1033 `sizes S1 S2 ... SN 0'
1034 This means that the device has fonts at S1, S2, ... SN scaled
1035 points. The list of sizes must be terminated by 0 (this is digit
1036 zero). Each SI can also be a range of sizes M-N. The list can
1037 extend over more than one line.
1039 `styles S1 S2 ... SM'
1040 The first M font positions are associated with styles S1 ... SM.
1042 `fonts N F1 F2 F3 ... FN'
1043 Fonts F1 ... FN are mounted in the font positions M+1, ..., M+N
1044 where M is the number of styles. This command may extend over
1045 more than one line. A font name of 0 means no font is mounted on
1046 the corresponding font position.
1049 The default font family is FAM.
1051 `use_charnames_in_special'
1052 This command indicates that `gtroff' should encode special
1053 characters inside special commands. Currently, this is only used
1054 by the HTML output device. *Note Postprocessor Access::.
1056 `papersize STRING ...'
1057 Select a paper size. Valid values for STRING are the ISO paper
1058 types `A0'-`A7', `B0'-`B7', `C0'-`C7', `D0'-`D7', `DL', and the US
1059 paper types `letter', `legal', `tabloid', `ledger', `statement',
1060 `executive', `com10', and `monarch'. Case is not significant for
1061 STRING if it holds predefined paper types. Alternatively, STRING
1062 can be a file name (e.g. `/etc/papersize'); if the file can be
1063 opened, `groff' reads the first line and tests for the above paper
1064 sizes. Finally, STRING can be a custom paper size in the format
1065 `LENGTH,WIDTH' (no spaces before and after the comma). Both
1066 LENGTH and WIDTH must have a unit appended; valid values are `i'
1067 for inches, `C' for centimeters, `p' for points, and `P' for
1068 picas. Example: `12c,235p'. An argument which starts with a
1069 digit is always treated as a custom paper format. `papersize'
1070 sets both the vertical and horizontal dimension of the output
1073 More than one argument can be specified; `groff' scans from left to
1074 right and uses the first valid paper specification.
1077 Tell `gtroff' to emit the name of the source file currently being
1078 processed. This is achieved by the intermediate output command
1079 `F'. Currently, this is only used by the HTML output device.
1082 Use PROGRAM as a spooler program for printing. If omitted, the
1083 `-l' and `-L' options of `groff' are ignored.
1086 This line and everything following in the file are ignored. It is
1087 allowed for the sake of backwards compatibility.
1089 The `res', `unitwidth', `fonts', and `sizes' lines are mandatory.
1090 Other commands are ignored by `gtroff' but may be used by
1091 postprocessors to store arbitrary information about the device in the
1094 Here a list of obsolete keywords which are recognized by `groff' but
1095 completely ignored: `spare1', `spare2', `biggestfont'.
1098 File: groff, Node: Font File Format, Prev: DESC File Format, Up: Font Files
1103 A "font file", also (and probably better) called a "font description
1104 file", has two sections. The first section is a sequence of lines each
1105 containing a sequence of blank delimited words; the first word in the
1106 line is a key, and subsequent words give a value for that key.
1109 The name of the font is F.
1112 The normal width of a space is N.
1115 The glyphs of the font have a slant of N degrees. (Positive means
1118 `ligatures LIG1 LIG2 ... LIGN [0]'
1119 Glyphs LIG1, LIG2, ..., LIGN are ligatures; possible ligatures are
1120 `ff', `fi', `fl', `ffi' and `ffl'. For backwards compatibility,
1121 the list of ligatures may be terminated with a 0. The list of
1122 ligatures may not extend over more than one line.
1125 The font is "special"; this means that when a glyph is requested
1126 that is not present in the current font, it is searched for in any
1127 special fonts that are mounted.
1129 Other commands are ignored by `gtroff' but may be used by
1130 postprocessors to store arbitrary information about the font in the font
1133 The first section can contain comments which start with the `#'
1134 character and extend to the end of a line.
1136 The second section contains one or two subsections. It must contain
1137 a `charset' subsection and it may also contain a `kernpairs'
1138 subsection. These subsections can appear in any order. Each
1139 subsection starts with a word on a line by itself.
1141 The word `charset' starts the character set subsection.(1) (*note
1142 Font File Format-Footnote-1::) The `charset' line is followed by a
1143 sequence of lines. Each line gives information for one glyph. A line
1144 comprises a number of fields separated by blanks or tabs. The format is
1146 NAME METRICS TYPE CODE [ENTITY-NAME] [`--' COMMENT]
1148 NAME identifies the glyph name(2) (*note Font File Format-Footnote-2::):
1149 If NAME is a single character C then it corresponds to the `gtroff'
1150 input character C; if it is of the form `\C' where C is a single
1151 character, then it corresponds to the special character `\[C]';
1152 otherwise it corresponds to the special character `\[NAME]'. If it is
1153 exactly two characters XX it can be entered as `\(XX'. Note that
1154 single-letter special characters can't be accessed as `\C'; the only
1155 exception is `\-' which is identical to `\[-]'.
1157 `gtroff' supports 8-bit input characters; however some utilities
1158 have difficulties with eight-bit characters. For this reason, there is
1159 a convention that the entity name `charN' is equivalent to the single
1160 input character whose code is N. For example, `char163' would be
1161 equivalent to the character with code 163 which is the pounds sterling
1162 sign in the ISO Latin-1 character set. You shouldn't use `charN'
1163 entities in font description files since they are related to input, not
1164 output. Otherwise, you get hard-coded connections between input and
1165 output encoding which prevents use of different (input) character sets.
1167 The name `---' is special and indicates that the glyph is unnamed;
1168 such glyphs can only be used by means of the `\N' escape sequence in
1171 The TYPE field gives the glyph type:
1174 the glyph has a descender, for example, `p';
1177 the glyph has an ascender, for example, `b';
1180 the glyph has both an ascender and a descender, for example, `('.
1182 The CODE field gives the code which the postprocessor uses to print
1183 the glyph. The glyph can also be input to `gtroff' using this code by
1184 means of the `\N' escape sequence. CODE can be any integer. If it
1185 starts with `0' it is interpreted as octal; if it starts with `0x' or
1186 `0X' it is interpreted as hexadecimal. Note, however, that the `\N'
1187 escape sequence only accepts a decimal integer.
1189 The ENTITY-NAME field gives an ASCII string identifying the glyph
1190 which the postprocessor uses to print the `gtroff' glyph NAME. This
1191 field is optional and has been introduced so that the HTML device
1192 driver can encode its character set. For example, the glyph `\[Po]' is
1193 represented as `£' in HTML 4.0.
1195 Anything on the line after the ENTITY-NAME field resp. after `--'
1198 The METRICS field has the form:
1200 WIDTH[`,'HEIGHT[`,'DEPTH[`,'ITALIC-CORRECTION
1201 [`,'LEFT-ITALIC-CORRECTION[`,'SUBSCRIPT-CORRECTION]]]]]
1203 There must not be any spaces between these subfields (it has been split
1204 here into two lines for better legibility only). Missing subfields are
1205 assumed to be 0. The subfields are all decimal integers. Since there
1206 is no associated binary format, these values are not required to fit
1207 into a variable of type `char' as they are in `ditroff'. The WIDTH
1208 subfield gives the width of the glyph. The HEIGHT subfield gives the
1209 height of the glyph (upwards is positive); if a glyph does not extend
1210 above the baseline, it should be given a zero height, rather than a
1211 negative height. The DEPTH subfield gives the depth of the glyph, that
1212 is, the distance from the baseline to the lowest point below the
1213 baseline to which the glyph extends (downwards is positive); if a glyph
1214 does not extend below the baseline, it should be given a zero depth,
1215 rather than a negative depth. The ITALIC-CORRECTION subfield gives the
1216 amount of space that should be added after the glyph when it is
1217 immediately to be followed by a glyph from a roman font. The
1218 LEFT-ITALIC-CORRECTION subfield gives the amount of space that should
1219 be added before the glyph when it is immediately to be preceded by a
1220 glyph from a roman font. The SUBSCRIPT-CORRECTION gives the amount of
1221 space that should be added after a glyph before adding a subscript.
1222 This should be less than the italic correction.
1224 A line in the `charset' section can also have the format
1229 This indicates that NAME is just another name for the glyph mentioned
1230 in the preceding line.
1232 The word `kernpairs' starts the kernpairs section. This contains a
1233 sequence of lines of the form:
1238 This means that when glyph C1 appears next to glyph C2 the space
1239 between them should be increased by N. Most entries in the kernpairs
1240 section have a negative value for N.
1243 File: groff, Node: Font File Format-Footnotes, Up: Font File Format
1245 (1) This keyword is misnamed since it starts a list of ordered
1246 glyphs, not characters.
1248 (2) The distinction between input, characters, and output, glyphs,
1249 is not clearly separated in the terminology of `groff'; for example,
1250 the `char' request should be called `glyph' since it defines an output
1254 File: groff, Node: Installation, Next: Copying This Manual, Prev: File formats, Up: Top
1260 File: groff, Node: Copying This Manual, Next: Request Index, Prev: Installation, Up: Top
1267 * GNU Free Documentation License:: License for copying this manual.
projects / dragonfly.git / blob