## SYNOPSIS

           grn [ -Cv ] [ -Tdev ] [ -Mdir ] [ -Fdir ] [ file...  ]

           It  is  possible to have whitespace between a command line
           option and its parameter.

## DESCRIPTION

           grn is a preprocessor for including  gremlin  pictures  in
           groff  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
           commands request a gremlin file, and the picture  in  that
           file  is  converted  and placed in the troff input stream.
           The .GS request may be followed by a C, L, or R to center,
           left,  or right justify the whole gremlin picture (default
           justification is 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.

           Please note that currently only the -me macro package  has
           support for .GS, .GE, and .GF.

           The following command-line options are understood:

           -Tdev  Prepare output for printer dev.  The default device
                  is ps.  See groff(1) for acceptable devices.

           -Mdir  Prepend dir to the default search path for  gremlin
                  files.   The  default  path  is (in that order) the
                  current    directory,    the    home     directory,
                  /usr/lib/groff/site-tmac,    /usr/share/groff/site-
                  tmac, and /usr/share/groff/1.17.2/tmac.

           -Fdir  Search dir for subdirectories devname (name is  the
                  name  of  the  device) for the DESC file before the
                  normal /usr/share/groff/1.17.2/font.

           -C     Recognize .GS and .GE (resp.  .GF) even  when  fol
                  lowed by a character other than space or newline.

           -v     Print the version number.

## GRN COMMANDS

           Each  input line between .GS and .GE may have one grn com
           mand.  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  lower  case
           and abbreviated down to one character.

           Commands that affect a picture's environment (those listed
           special f
                  Set  the  roman (italics, bold, or special) font to
                  troff's font f (either  a  name  or  number).   The
                  default is R (resp. I, B, and S).

           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 illegal to include a gremlin picture with  poly
                  gons 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 (resp. medium
                  and  thick) lines to N times 0.15pt (this value can
                  be changed at compile time).  The  default  is  1.0
                  (resp.  3.0  and  5.0), which corresponds to 0.15pt
                  (resp. 0.45pt and 0.75pt).  A  thickness  value  of
                  zero selects the smallest available line thickness.
                  Negative values cause the line thickness to be pro
                  portional 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 scal
                  ing factors in  the  picture.   Setting  pointscale
                  will  cause  the point sizes to scale with the pic
                  ture (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  set
                  tings  in the current picture.  This is meant to be
                  used as a global parameter setting mechanism at the
                  beginning  of the troff input file, but can be used
                  at any time to reset the default settings.

           width N
                  Get picture from gremlin file name located the cur
                  rent  directory  (or  in the library directory; see
                  the -M option above).  If  two  file  commands  are
                  given, the second one overrides the first.  If name
                  doesn't exist, an error  message  is  reported  and
                  processing continues from the .GE line.

## NOTES ABOUT GROFF

           Since grn is a preprocessor, it doesn't know about current
           indents, point  sizes,  margins,  number  registers,  etc.
           Consequently, no troff input can be placed between the .GS
           and .GE requests.  However, gremlin text is now  processed
           by  troff,  so  anything  legal  in a single line of troff
           input is legal in a line  of  gremlin  text  (barring  `.'
           directives  at the beginning of a line).  Thus, it is pos
           sible to have equations within a gremlin figure by includ
           ing in the gremlin file eqn expressions enclosed by previ
           ously defined delimiters (e.g.  $$).

           When using grn along with other preprocessors, it is  best
           to  run  tbl  before grn, pic, and/or ideal to avoid over
           working tbl.  Eqn should always be run last.

           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  -me
           macros will ensure proper placement.

           grn  uses  troff's number 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 request
           (this is for those who want to rewrite these macros).

## GREMLIN FILE FORMAT

           There exist two distinct gremlin file formats, the  origi
           nal  format from the AED graphic terminal version, and the
           SUN or X11 version.  An extension to 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 to the 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 in Table 1 in each format.

                     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
                            Table 1. File examples

           ·      The first line of each gremlin file contains either
                  the string gremlinfile (AED version) or sungremlin
                  file (SUN/X11)

           ·      The second line of the file  contains  an  orienta
                  tion,  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
                  (drawing  area  wider  than  it  is tall, with menu
                  across top).  1 means  that  gremlin  will  display
                  things in vertical format (drawing area taller than
                  it is wide, with menu on 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 impor
                  tant; a value of ``1 0.00 0.00'' is suggested.

           ·      The rest of the file consists of zero or more  ele
                  ment specifications.  After the last element speci
                  fication is a line containing the string ``-1''.

## ELEMENT SPECIFICATIONS

           ·      The first line of each element  contains  a  single
                  decimal  number giving the type of the element (AED
                  version) or its ASCII name (SUN/X11 version).   See
                  Table 2.

                    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
                    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

                                        Table 2.
                          Type Specifications in gremlin Files

                            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,  one  more  value,  0, is legal.  It
                  specifies a polygon with an invisible border.   For
                  text, the brush selects a font as follows:

                          1 -       roman (R font in groff)
                          2 -       italics (I font in groff)
                          3 -       bold (B font in groff)
                          4 -       special (S font in groff)

                  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  inter
                  preted  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
                  only  used for text elements, and contains the text
                  string.  There can be spaces inside the text.   For
                  arcs, curves, and vectors, this line of the element
                  contains the string ``0''.

## NOTES ON COORDINATES

           gremlin was designed for AEDs, 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  hori
           zontal pictures, x-values range from 0 to 511 and y-values
           range from 0 to  367.   Although  you  needn't  absolutely
           stick  to  this  range,  you'll get best results if you at
           least stay in this vicinity.  Also, point lists are termi
           nated  by  a  point of (-1, -1), so you shouldn't ever use
           negative  coordinates.   gremlin  writes  out  coordinates
           using  format  ``%f1.2''; it's probably a good idea to use
           the same format if you want to modify the grn code.

## NOTES ON SUN/X11 COORDINATES

           There is no longer a restriction on the range  of  coordi

           Daniel Senderowicz and  Werner  Lemberg  modified  it  for
           groff.

    Groff Version 1.17.2       27 June 2001                    GRN(1)