ggrn(1) | User Commands | ggrn(1) |
ggrn - embed Gremlin images in groff documents
ggrn |
[-C] [-T dev] [-M dir] [-F dir] [file ...] |
ggrn |
-? |
ggrn |
--help |
ggrn |
-v |
ggrn |
--version |
ggrn is a preprocessor for including gremlin pictures in gtroff(1) input. ggrn writes to standard output, processing only input lines between two that start with .GS and .GE. Those lines must contain ggrn commands (see below). These macros request a gremlin file; the picture in that file is converted and placed in the gtroff input stream. .GS may be called with a C, L, or R argument to center, left-, or right-justify the whole gremlin picture (the default is to center). If no file is mentioned, the standard input is read. At the end of the picture, the position on the page is the bottom of the gremlin picture. If the ggrn entry is ended with .GF instead of .GE, the position is left at the top of the picture.
Currently only the me macro package has support for .GS, .GE, and .GF.
ggrn produces drawing escape sequences that use groff's color scheme extension (\D'F ...'), and thus may not work with other troffs.
Each input line between .GS and .GE may have one ggrn command. Commands consist of one or two strings separated by white space, the first string being the command and the second its operand. Commands may be upper- or lowercase and abbreviated down to one character.
Commands that affect a picture's environment (those listed before “default”, see below) are only in effect for the current picture: the environment is reinitialized to the defaults at the start of the next picture. The commands are as follows.
Since ggrn is a preprocessor, it has no access to elements of formatter state, such as indentation, line length, type size, or register values. Consequently, no gtroff input can be placed between the .GS and .GE macros. However, gremlin text elements are subsequently processed by gtroff, so anything valid in a single line of gtroff input is valid in a line of gremlin text (barring the dot control character “.” at the beginning of a line). Thus, it is possible to have equations within a gremlin figure by including in the gremlin file eqn expressions enclosed by previously defined delimiters (e.g., “$$”).
When using ggrn along with other preprocessors, it is best to run gtbl(1) before ggrn, gpic(1), and/or ideal to avoid overworking gtbl. geqn(1) should always be run last. groff(1) will automatically run preprocessors in the correct order.
A picture is considered an entity, but that doesn't stop gtroff from trying to break it up if it falls off the end of a page. Placing the picture between “keeps” in the me macros will ensure proper placement.
ggrn uses gtroff's registers g1 through g9 and sets registers g1 and g2 to the width and height of the gremlin figure (in device units) before entering the .GS macro (this is for those who want to rewrite these macros).
There exist two distinct gremlin file formats: the original format for AED graphic terminals, and the Sun or X11 version. An extension used by the Sun/X11 version allowing reference points with negative coordinates is not compatible with the AED version. As long as a gremlin file does not contain negative coordinates, either format will be read correctly by either version of gremlin or ggrn. The other difference in Sun/X11 format is the use of names for picture objects (e.g., POLYGON, CURVE) instead of numbers. Files representing the same picture are shown below.
sungremlinfile | gremlinfile | |
0 240.00 128.00 | 0 240.00 128.00 | |
CENTCENT | 2 | |
240.00 128.00 | 240.00 128.00 | |
185.00 120.00 | 185.00 120.00 | |
240.00 120.00 | 240.00 120.00 | |
296.00 120.00 | 296.00 120.00 | |
* | -1.00 -1.00 | |
2 3 | 2 3 | |
10 A Triangle | 10 A Triangle | |
POLYGON | 6 | |
224.00 416.00 | 224.00 416.00 | |
96.00 160.00 | 96.00 160.00 | |
384.00 160.00 | 384.00 160.00 | |
* | -1.00 -1.00 | |
5 1 | 5 1 | |
0 | 0 | |
-1 | -1 |
gremlin File Format: Object Type Specification | ||
AED Number | Sun/X11 Name | Description |
0 | BOTLEFT | bottom-left-justified text |
1 | BOTRIGHT | bottom-right-justified text |
2 | CENTCENT | center-justified text |
3 | VECTOR | vector |
4 | ARC | arc |
5 | CURVE | curve |
6 | POLYGON | polygon |
7 | BSPLINE | b-spline |
8 | BEZIER | Bézier |
10 | TOPLEFT | top-left-justified text |
11 | TOPCENT | top-center-justified text |
12 | TOPRIGHT | top-right-justified text |
13 | CENTLEFT | left-center-justified text |
14 | CENTRIGHT | right-center-justified text |
15 | BOTCENT | bottom-center-justified text |
1 | thin dotted lines |
2 | thin dot-dashed lines |
3 | thick solid lines |
4 | thin dashed lines |
5 | thin solid lines |
6 | medium solid lines |
1 | roman (R font in gtroff) |
2 | italics (I font in gtroff) |
3 | bold (B font in gtroff) |
4 | special (S font in gtroff) |
gremlin was designed for AED terminals, and its coordinates reflect the AED coordinate space. For vertical pictures, x values range 116 to 511, and y values from 0 to 483. For horizontal pictures, x values range from 0 to 511, and y values from 0 to 367. Although you needn't absolutely stick to this range, you'll get better results if you at least stay in this vicinity. Also, point lists are terminated by a point of (-1, -1), so you shouldn't ever use negative coordinates. gremlin writes out coordinates using the printf(3) format “%f1.2”; it's probably a good idea to use the same format if you want to modify the ggrn code.
There is no restriction on the range of coordinates used to create objects in the Sun/X11 version of gremlin. However, files with negative coordinates will cause problems if displayed on the AED.
-? and --help display a usage message, while -v and --version show version information; all exit afterward.
David Slattengren and Barry Roitblat wrote the original Berkeley grn. Daniel Senderowicz and Werner Lemberg modified it for groff.
gremlin(1), groff(1), gpic(1), ideal(1)
2 July 2023 | groff 1.23.0 |