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