1GRN(1) General Commands Manual GRN(1)
2
6 grn - groff preprocessor for gremlin files
7
9 grn [-Cv] [-T dev] [-M dir] [-F dir] [file ...]
10
12 grn is a preprocessor for including gremlin pictures in groff input.
13 grn writes to standard output, processing only input lines between two
14 that start with .GS and .GE. Those lines must contain grn commands
15 (see below). These commands request a gremlin file, and the picture in
16 that file is converted and placed in the troff input stream. The .GS
17 request may be followed by a C, L, or R to center, left, or right jus‐
18 tify the whole gremlin picture (default justification is center). If
19 no file is mentioned, the standard input is read. At the end of the
20 picture, the position on the page is the bottom of the gremlin picture.
21 If the grn entry is ended with .GF instead of .GE, the position is left
22 at the top of the picture.
23 Please note that currently only the -me macro package has support for
25 .GS, .GE, and .GF.
26
28 Whitespace is permitted between a command-line option and its argument.
29 -Tdev Prepare output for printer dev. The default device is ps. See
31 groff(1) for acceptable devices.
32 -Mdir Prepend dir to the default search path for gremlin files. The
34 default path is (in that order) the current directory, the home
35 directory, /etc/groff/site-tmac, /etc/groff/site-tmac, and /usr/
36 share/groff/1.22.4/tmac.
37 -Fdir Search dir for subdirectories devname (name is the name of the
39 device) for the DESC file before the default font directories
40 /etc/groff/site-font, /usr/share/groff/1.22.4/font, and /usr/
41 lib/font.
42 -C Recognize .GS and .GE (and .GF) even when followed by a charac‐
44 ter other than space or newline.
45 -v Print the version number.
47
49 Each input line between .GS and .GE may have one grn command. Commands
50 consist of one or two strings separated by white space, the first
51 string being the command and the second its operand. Commands may be
52 upper or lower case and abbreviated down to one character.
53 Commands that affect a picture's environment (those listed before de‐
55 fault, see below) are only in effect for the current picture: The envi‐
56 ronment is reinitialized to the defaults at the start of the next pic‐
57 ture. The commands are as follows:
58 1 N
60 2 N
61 3 N
62 4 N Set gremlin's text size number 1 (2, 3, or 4) to N points. The
63 default is 12 (16, 24, and 36, respectively).
64 roman f
66 italics f
67 bold f
68 special f
69 Set the roman (italics, bold, or special) font to troff's font f
70 (either a name or number). The default is R (I, B, and S, re‐
71 spectively).
72 l f
74 stipple f
75 Set the stipple font to troff's stipple font f (name or number).
76 The command stipple may be abbreviated down as far as ‘st’ (to
77 avoid confusion with special). There is no default for stipples
78 (unless one is set by the default command), and it is invalid to
79 include a gremlin picture with polygons without specifying a
80 stipple font.
81 x N
83 scale N
84 Magnify the picture (in addition to any default magnification)
85 by N, a floating point number larger than zero. The command
86 scale may be abbreviated down to ‘sc’.
87 narrow N
89 medium N
90 thick N
91 Set the thickness of gremlin's narrow (medium and thick, respec‐
92 tively) lines to N times 0.15pt (this value can be changed at
93 compile time). The default is 1.0 (3.0 and 5.0, respectively),
94 which corresponds to 0.15pt (0.45pt and 0.75pt, respectively).
95 A thickness value of zero selects the smallest available line
96 thickness. Negative values cause the line thickness to be pro‐
97 portional to the current point size.
98 pointscale <off/on>
100 Scale text to match the picture. Gremlin text is usually
101 printed in the point size specified with the commands 1, 2, 3,
102 or 4, regardless of any scaling factors in the picture. Setting
103 pointscale will cause the point sizes to scale with the picture
104 (within troff's limitations, of course). An operand of anything
105 but off will turn text scaling on.
106 default
108 Reset the picture environment defaults to the settings in the
109 current picture. This is meant to be used as a global parameter
110 setting mechanism at the beginning of the troff input file, but
111 can be used at any time to reset the default settings.
112 width N
114 Forces the picture to be N inches wide. This overrides any
115 scaling factors present in the same picture. ‘width 0’ is ig‐
116 nored.
117 height N
119 Forces picture to be N inches high, overriding other scaling
120 factors. If both ‘width’ and ‘height’ are specified the tighter
121 constraint will determine the scale of the picture. Height and
122 width commands are not saved with a default command. They will,
123 however, affect point size scaling if that option is set.
124 file name
126 Get picture from gremlin file name located the current directory
127 (or in the library directory; see the -M option above). If two
128 file commands are given, the second one overrides the first. If
129 name doesn't exist, an error message is reported and processing
130 continues from the .GE line.
131
133 Since grn is a preprocessor, it doesn't know about current indents,
134 point sizes, margins, number registers, etc. Consequently, no troff
135 input can be placed between the .GS and .GE requests. However, gremlin
136 text is now processed by troff, so anything valid in a single line of
137 troff input is valid in a line of gremlin text (barring ‘.’ directives
138 at the beginning of a line). Thus, it is possible to have equations
139 within a gremlin figure by including in the gremlin file eqn expres‐
140 sions enclosed by previously defined delimiters (e.g. $$).
141 When using grn along with other preprocessors, it is best to run tbl
143 before grn, pic, and/or ideal to avoid overworking tbl. Eqn should al‐
144 ways be run last.
145 A picture is considered an entity, but that doesn't stop troff from
147 trying to break it up if it falls off the end of a page. Placing the
148 picture between ‘keeps’ in -me macros will ensure proper placement.
149 grn uses troff's number registers g1 through g9 and sets registers g1
151 and g2 to the width and height of the gremlin figure (in device units)
152 before entering the .GS request (this is for those who want to rewrite
153 these macros).
154
156 There exist two distinct gremlin file formats, the original format from
157 the AED graphic terminal version, and the SUN or X11 version. An ex‐
158 tension to the SUN/X11 version allowing reference points with negative
159 coordinates is not compatible with the AED version. As long as a grem‐
160 lin file does not contain negative coordinates, either format will be
161 read correctly by either version of gremlin or grn. The other differ‐
162 ence from SUN/X11 format is the use of names for picture objects (e.g.,
163 POLYGON, CURVE) instead of numbers. Files representing the same pic‐
164 ture are shown in Table 1 in each format.
165 sungremlinfile gremlinfile
168 0 240.00 128.00 0 240.00 128.00
169 CENTCENT 2
170 240.00 128.00 240.00 128.00
171 185.00 120.00 185.00 120.00
172 240.00 120.00 240.00 120.00
173 296.00 120.00 296.00 120.00
174 * -1.00 -1.00
175 2 3 2 3
176 10 A Triangle 10 A Triangle
177 POLYGON 6
178 224.00 416.00 224.00 416.00
179 96.00 160.00 96.00 160.00
180 384.00 160.00 384.00 160.00
181 * -1.00 -1.00
182 5 1 5 1
183 0 0
184 -1 -1
185 Table 1. File examples
187 • The first line of each gremlin file contains either the string
190 gremlinfile (AED version) or sungremlinfile (SUN/X11)
191 • The second line of the file contains an orientation, and x and y
193 values for a positioning point, separated by spaces. The orien‐
194 tation, either 0 or 1, is ignored by the SUN/X11 version. 0
195 means that gremlin will display things in horizontal format
196 (drawing area wider than it is tall, with menu across top). 1
197 means that gremlin will display things in vertical format (draw‐
198 ing area taller than it is wide, with menu on left side). x and
199 y are floating point values giving a positioning point to be
200 used when this file is read into another file. The stuff on
201 this line really isn't all that important; a value of “1 0.00
202 0.00” is suggested.
203 • The rest of the file consists of zero or more element specifica‐
205 tions. After the last element specification is a line contain‐
206 ing the string “-1”.
207 • Lines longer than 127 characters are chopped to this limit.
209
211 • The first line of each element contains a single decimal number
212 giving the type of the element (AED version) or its ASCII name
213 (SUN/X11 version). See Table 2.
214 gremlin File Format − Object Type Specification
217 AED Number SUN/X11 Name Description
219 0 BOTLEFT bottom-left-justified text
220 1 BOTRIGHT bottom-right-justified text
221 2 CENTCENT center-justified text
222 3 VECTOR vector
223 4 ARC arc
224 5 CURVE curve
225 6 POLYGON polygon
226 7 BSPLINE b-spline
227 8 BEZIER Bézier
228 10 TOPLEFT top-left-justified text
229 11 TOPCENT top-center-justified text
230 12 TOPRIGHT top-right-justified text
231 13 CENTLEFT left-center-justified text
232 14 CENTRIGHT right-center-justified text
233 15 BOTCENT bottom-center-justified text
234 Table 2.
236 Type Specifications in gremlin Files
237 • After the object type comes a variable number of lines, each
240 specifying a point used to display the element. Each line con‐
241 tains an x-coordinate and a y-coordinate in floating point for‐
242 mat, separated by spaces. The list of points is terminated by a
243 line containing the string “-1.0 -1.0” (AED version) or a single
244 asterisk, “*” (SUN/X11 version).
245 • After the points comes a line containing two decimal values,
247 giving the brush and size for the element. The brush determines
248 the style in which things are drawn. For vectors, arcs, and
249 curves there are six valid brush values:
250 1 − thin dotted lines
253 2 − thin dot-dashed lines
254 3 − thick solid lines
255 4 − thin dashed lines
256 5 − thin solid lines
257 6 − medium solid lines
258 For polygons, one more value, 0, is valid. It specifies a poly‐
260 gon with an invisible border. For text, the brush selects a
261 font as follows:
262 1 − roman (R font in groff)
265 2 − italics (I font in groff)
266 3 − bold (B font in groff)
267 4 − special (S font in groff)
268 If you're using grn to run your pictures through groff, the font
270 is really just a starting font: The text string can contain for‐
271 matting sequences like “\fI” or “\d” which may change the font
272 (as well as do many other things). For text, the size field is
273 a decimal value between 1 and 4. It selects the size of the
274 font in which the text will be drawn. For polygons, this size
275 field is interpreted as a stipple number to fill the polygon
276 with. The number is used to index into a stipple font at print
277 time.
278 • The last line of each element contains a decimal number and a
280 string of characters, separated by a single space. The number
281 is a count of the number of characters in the string. This in‐
282 formation is only used for text elements, and contains the text
283 string. There can be spaces inside the text. For arcs, curves,
284 and vectors, this line of the element contains the string “0”.
285
287 gremlin was designed for AEDs, and its coordinates reflect the AED co‐
288 ordinate space. For vertical pictures, x-values range 116 to 511, and
289 y-values from 0 to 483. For horizontal pictures, x-values range from 0
290 to 511 and y-values range from 0 to 367. Although you needn't abso‐
291 lutely stick to this range, you'll get best results if you at least
292 stay in this vicinity. Also, point lists are terminated by a point of
293 (-1, -1), so you shouldn't ever use negative coordinates. gremlin
294 writes out coordinates using format “%f1.2”; it's probably a good idea
295 to use the same format if you want to modify the grn code.
296
298 There is no longer a restriction on the range of coordinates used to
299 create objects in the SUN/X11 version of gremlin. However, files with
300 negative coordinates will cause problems if displayed on the AED.
301
303 /usr/share/groff/1.22.4/font/devname/DESC
304 Device description file for device name.
305
307 David Slattengren and Barry Roitblat wrote the original Berkeley grn.
308 Daniel Senderowicz and Werner Lemberg modified it for groff.
309
311 gremlin(1), groff(1), pic(1), ideal(1)
312groff 1.22.4 17 March 2021 GRN(1)