1GRN(1)                      General Commands Manual                     GRN(1)
2
3
4

NAME

6       grn - groff preprocessor for gremlin files
7

SYNOPSIS

9       grn [-Cv] [-T dev] [-M dir] [-F dir] [file ...]
10

DESCRIPTION

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
24       Please  note  that currently only the -me macro package has support for
25       .GS, .GE, and .GF.
26

OPTIONS

28       Whitespace is permitted between a command-line option and its argument.
29
30       -Tdev  Prepare output for printer dev.  The default device is ps.   See
31              groff(1) for acceptable devices.
32
33       -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
38       -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
43       -C     Recognize  .GS and .GE (and .GF) even when followed by a charac‐
44              ter other than space or newline.
45
46       -v     Print the version number.
47

GRN COMMANDS

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
54       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
59       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
65       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
73       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
82       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
88       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
99       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
107       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
113       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
118       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
125       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

NOTES ABOUT GROFF

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
142       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
146       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
150       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

GREMLIN FILE FORMAT

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
166
167                        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
186                               Table 1.  File examples
187
188
189       •      The first line of each gremlin file contains either  the  string
190              gremlinfile (AED version) or sungremlinfile (SUN/X11)
191
192       •      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
204       •      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
208       •      Lines longer than 127 characters are chopped to this limit.
209

ELEMENT SPECIFICATIONS

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
215
216                      gremlin File Format − Object Type Specification
217
218                  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
235                                          Table 2.
236                            Type Specifications in gremlin Files
237
238
239       •      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
246       •      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
251
252                              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
259              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
263
264                            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
269              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
279       •      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

NOTES ON COORDINATES

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

NOTES ON SUN/X11 COORDINATES

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

FILES

303       /usr/share/groff/1.22.4/font/devname/DESC
304              Device description file for device name.
305

AUTHORS

307       David Slattengren and Barry Roitblat wrote the original  Berkeley  grn.
308       Daniel Senderowicz and Werner Lemberg modified it for groff.
309

SEE ALSO

311       gremlin(1), groff(1), pic(1), ideal(1)
312
313
314
315groff 1.22.4                     17 March 2021                          GRN(1)
Impressum