# grn

## Name



           grn - embed Gremlin images in _groff_ documents
    


## Synopsis



           **grn**[**-C**] [**-T** _dev_] [**-M** _dir_] [**-F** _dir_] [_file_ ...]
    
           **grn -?**
    
           **grn --help**
    
           **grn -v**
    
           **grn --version**
    


## Description



           _grn_ is a preprocessor for including _gremlin_ pictures in _troff_(1)
           input.  _grn_ writes to standard output, processing only input lines
           between two that start with **.GS** and **.GE**.  Those lines must contain
           _grn_ commands (see below).  These macros request a _gremlin_ file;
           the picture in that file is converted and placed in the _troff_
           input stream.  **.GS** may be called with a **C** , **L** , or **R** argument to
           center, left-, or right-align 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 _grn_ 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**.
    
           _grn_ produces drawing escape sequences that use _groff_ 's color
           scheme extension (**\D'F**...**'**), and thus may not work with other
           _troff_ s.
    
       [1mgrn[24m commands
           Each input line between **.GS** and **.GE** may have one _grn_ command.
           Commands consist of one or two strings separated by whitespace,
           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.
    
           **1** _N_
           **2** _N_
           **3** _N_
           **4** _N_    Set _gremlin_ 's text size number 1 (2, 3, or 4) to _N_ points.
                  The default is 12 (16, 24, and 36, respectively).
    
           **roman** _f_
           **italics** _f_
           **bold** _f_
           **special** _f_
                  Set the roman (italics, bold, or special) font to _troff_ 's
                  font _f_ (either a name or number).  The default is R (I, B,
                  and S, respectively).
    
           **l** _f_
           **stipple** _f_
                  Set the stipple font to _troff_ 's stipple font _f_ (name or
                  number).  The command **stipple** may be abbreviated down as
                  far as “**st** ” (to avoid confusion with “**special** ”).  There is
                  _no_ default for stipples (unless one is set by the “**default** ”
                  command), and it is invalid to include a _gremlin_ picture
                  with polygons without specifying a stipple font.
    
           **x** _N_
           **scale** _N_
                  Magnify the picture (in addition to any default
                  magnification) by _N_ , a floating-point number larger than
                  zero.  The command **scale** may be abbreviated down to “**sc** ”.
    
           **narrow** _N_
           **medium** _N_
           **thick** _N_
                  Set the thickness of _gremlin_ 's narrow (medium and thick,
                  respectively) lines to _N_ times 0.15pt (this value can be
                  changed at compile time).  The default is 1.0 (3.0 and 5.0,
                  respectively), which corresponds to 0.15pt (0.45pt and
                  0.75pt, respectively).  A thickness value of zero selects
                  the smallest available line thickness.  Negative values
                  cause the line thickness to be proportional to the current
                  point size.
    
           **pointscale**[**off** |**on**]
                  Scale text to match the picture.  Gremlin text is usually
                  printed in the point size specified with the commands **1** , **2** ,
                  **3** , or **4** , regardless of any scaling factors in the picture.
                  Setting **pointscale** will cause the point sizes to scale with
                  the picture (within _troff_ 's limitations, of course).  An
                  operand of anything but **off** will turn text scaling on.
    
           **default**
                  Reset the picture environment defaults to the settings in
                  the current picture.  This is meant to be used as a global
                  parameter setting mechanism at the beginning of the _troff_
                  input, but can be used at any time to reset the default
                  settings.
    
           **width** _N_
                  Force the picture to be _N_ inches wide.  This overrides any
                  scaling factors present in the same picture.  “**width 0** ” is
                  ignored.
    
           **height** _N_
                  Force the picture to be _N_ inches high, overriding other
                  scaling factors.  If both **width** and **height** are specified,
                  the tighter constraint will determine the scale of the
                  picture.  **height** and **width** commands are not saved with a
                  “**default** ” command.  They will, however, affect point size
                  scaling if that option is set.
    
           **file** _name_
                  Get picture from _gremlin_ file _name_ located the current
                  directory (or in the library directory; see the **-M** option
                  above).  If multiple **file** commands are given, the last one
                  controls.  If _name_ doesn't exist, an error message is
                  reported and processing continues from the **.GE** line.
    
       [1mUsage with _groff_
           Since _grn_ is a preprocessor, it has no access to elements of
           formatter state, such as indentation, line length, type size, or
           register values.  Consequently, no _troff_ input can be placed
           between the **.GS** and **.GE** macros.  However, _gremlin_ text elements
           are subsequently processed by _troff_ , so anything valid in a single
           line of _troff_ 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 _grn_ along with other preprocessors, run _tbl_(1) before
           _grn_ , _pic_(1), and/or _ideal_.  If _eqn_(1) is needed, run it as the
           last preprocessor.  _groff_(1) automatically runs preprocessors in
           the correct order.
    
           A picture is considered an entity, but that doesn't stop _troff_
           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.
    
           _grn_ uses _troff_ '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).
    
       **Gremlin file format**
           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 _grn_.  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
    
           •  The first line of each _gremlin_ file contains either the string
              “**gremlinfile** ” (AED) or “**sungremlinfile** ” (Sun/X11).
    
           •  The second line of the file contains an orientation and _x_ and _y_
              values for a positioning point, separated by spaces.  The
              orientation, either **0** or **1** , is ignored by the Sun/X11 version.
              **0** means that _gremlin_ will display things in horizontal format
              (a drawing area wider than it is tall, with a menu across the
              top).  **1** means that _gremlin_ will display things in vertical
              format (a drawing area taller than it is wide, with a menu on
              the left side).  _x_ and _y_ are floating-point values giving a
              positioning point to be used when this file is read into
              another file.  The stuff on this line really isn't all that
              important; a value of “**1 0.00 0.00** ” is suggested.
    
           •  The rest of the file consists of zero or more element
              specifications.  After the last element specification is a line
              containing the string “**-1** ”.
    
           •  Lines longer than 127 characters are truncated to that length.
    
       **Element specifications**
           •  The first line of each element contains a single decimal number
              giving the type of the element (AED) or its name (Sun/X11).
    
                      _gremlin_ File Format: Object Type Specification
                 ──────────────────────────────────────────────────────────
                 AED Number   Sun/X11 Name            Description
                      **0       BOTLEFT** text aligned to bottom left
                      **1       BOTRIGHT** text aligned to bottom right
                      **2       CENTCENT** center object
                      **3       VECTOR** vector
                      **4       ARC** arc
                      **5       CURVE** curve
                      **6       POLYGON** polygon
                      **7       BSPLINE** b-spline
                      **8       BEZIER** Bézier
                     **10       TOPLEFT** text aligned to top left
                     **11       TOPCENT** text aligned to top center
                     **12       TOPRIGHT** text aligned to top right
                     **13       CENTLEFT** text aligned to center left
                     **14       CENTRIGHT** text aligned to center right
                     **15       BOTCENT** text aligned to bottom center
    
           •  Each line after the object type specifies a point used to
              display the element.  It contains an _x_ and a _y_ coordinate in
              floating-point format, separated by spaces.  The list of points
              is terminated by a line containing the string “**-1.0 -1.0** ” (AED)
              or a single asterisk, “***** ” (Sun/X11).
    
           •  After the points comes a line containing two decimal values,
              giving the brush and size for the element.  The brush
              determines the style in which things are drawn.  For vectors,
              arcs, and curves there are six valid brush values.
    
                                 **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
    
              For polygons, 0 is also valid: it specifies an invisible
              border.  For text, the brush selects a font as follows.
    
                               **1** roman (R font in _troff_)
                               **2** italics (I font in _troff_)
                               **3** bold (B font in _troff_)
                               **4** special (S font in _troff_)
    
              If you're using _grn_ to run your pictures through _groff_ , the
              font is really just a starting font.  The text string can
              contain formatting sequences like “\fI” or “\d” which may
              change the font (as well as do many other things).  For text,
              the size field is a decimal value between 1 and 4.  It selects
              the size of the font in which the text will be drawn.  For
              polygons, this size field is interpreted as a stipple number to
              fill the polygon with.  The number is used to index into a
              stipple font at print time.
    
           •  The last line of each element contains a decimal number and a
              string of characters, separated by a single space.  The number
              is a count of the number of characters in the string.  This
              information is used only for text elements, and contains the
              text string.  There can be spaces inside the text.  For arcs,
              curves, and vectors, the character count is zero (**0**), followed
              by exactly one space before the newline.
    
       **Coordinates**
           _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 _grn_
           code.
    
       **Sun/X11 coordinates**
           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.
    


## Options



           **-?** and **--help** display a usage message, while **-v** and **--version** show
           version information; all exit afterward.
    
           **-C** Recognize **.GS** and **.GE**(and **.GF**) even when followed by a
                  character other than space or newline.
    
           **-F** _dir_ Search _dir_ for subdirectories _dev_ name (_name_ is the name of
                  the output driver) for the _DESC_ file before the default
                  font directories _/usr/local/share/groff/site-font_ , _/usr/_
                  _local/share/groff/1.23.0/font_ , and _/usr/lib/font_.
    
           **-M** _dir_ Prepend _dir_ to the search path for _gremlin_ files.  The
                  default search path is the current directory, the home
                  directory, _/usr/local/share/groff/site-tmac_ , and _/usr/_
                  _local/share/groff/1.23.0/tmac_ , in that order.
    
           **-T** _dev_ Prepare device output using output driver _dev_.  The default
                  is **ps**.  See _groff_(1) for a list of valid devices.
    


## Exit status



           _grn_ exits with status **0** on successful operation, status **2** if the
           program cannot interpret its command-line arguments, and status **1**
           if it encounters an error during operation.
    


## Files



           _/usr/local/share/groff/1.23.0/font/dev_ name _/DESC_
                  describes the output device _name_.
    


## Authors



           David Slattengren and Barry Roitblat wrote the original Berkeley
           _grn_.  Daniel Senderowicz and Werner Lemberg ⟨wl@gnu.org⟩ modified
           it for _groff_.
    


## See also



           _gremlin_(1), _groff_(1), _pic_(1), _ideal_(1)
    


* * *