
		GIST - A CGM viewer especially for use
                       on metafiles written using the
                       Gist graphics library


------------------------------------------------------------------------------
   $Id: README,v 1.1 1993/08/27 17:19:10 munro Exp $

------------------------------------------------------------------------------

     This CGM viewer does not attempt to be a full CGM interpreter.
It assumes that all of the data sizes and formats have their default
values as specified in the ANSI standard X3.122 - 1986 Part 3 (binary
encoding).  Thus, a point in VDC space consists of two 16 bit integers,
a color index is 8 bits (one octet), and so on.

     The CGM standard, unlike the PostScript language, does NOT specify
what marks go on a page.  The purpose of this CGM viewer is to recreate
a PostScript file or X window from a Gist metafile, which is identical
to the PostScript or X output that Gist would have produced.  This allows
CGM to be used as a means for archiving large amounts of graphical
output generated by Gist, without losing any information.  A CGM file
does not contain enough information for any other CGM viewer to accomplish
this, since the standard (intentionally) does not supply a complete
graphical meaning for the data in a CGM file.  (Text is the worst problem;
the CGM standard does not say, for example, at what point size text must
be rendered, only what the abstract "character height" must be.  The
gist viewer can reconstruct the point size which Gist intended from the
"character height" it earlier dumped into the file.  Other CGM viewers
will disagree on the meaning of "character height", not to mention
"font number".)

     The gist viewer can be run interactively, in batch mode, or as a
UNIX filter which places PostScript output on stdout.  The general
execute line is:

     gist [cgmfile] [options] [page number list]

where:
     cgmfile    - a CGM, preferably written by the Gist library
     options    - one or more of the following:
        -in cgmfile     to specify a (binary) CGM input file
                        (The "-in" is necessary if and only if the input
                         filename begins with a digit or - sign.)
        -cgm cgmout     to specify a (binary) CGM output file
        -ps psout       to specify a PostScript output file
        -display host:server.screen
        -d host:server.screen
                        to specify an X server connection
                        If this option is not given, gist will use the
                        DISPLAY environment variable.
        -75             create X display(s) at 75 dpi
        -100            create X display(s) at 100 dpi (default)
        -gks            create X displays at 8x8 inches (default 6x6)
        -nd             to supress the automatic display of the first
                        picture when gist starts in interactive mode
        -b              to run in batch mode (either -cgm or -ps must
                        also be specified, implies -nd)
        -f              to run in filter mode, placing PostScript
                        output on stdout (implies -b)
        -x              to run as a pure X window program (no keyboard)
        -fmbug          to compensate for a bug in FrameMaker 3.0X,
                        reverse the EPS preview top-for-bottom in
                        EPS files
        -bg0fg1         commercial packages which produce CGM files
                        may use color index 0 to mean background,
                        index 1 to mean foreground, despite their own
                        palette -- this switch compensates
     page number list
                        any number of space delimited list elements:
        n1        just page n1
        n1-n2     pages n1 through n2, inclusive
        n1-n2-n3  pages n1 through n2 in steps of n3
                        Using n1<=0 or n2>=total number of pages
                        is legal, causing the loop to terminate at
                        the end-of-file (or end-of-file-family)

     To look at a Yorick or other Gist-generated CGM, the command line is:

          gist myfile.cgm

which makes a large X window, or

          gist -75 myfile.cgm

which makes a smaller window.

     Using gist on a file generated by a GKS package such as ATC or NCAR
requires more fiddling, and will never give perfect results.  Remember that
the CGM standard does not specify where the ink will fall on the page,
unlike PostScript!  A reasonable command line to try is:

          gist -75 -gks -bg0fg1 gksfile.cgm

     Unless the -b or -f options were specified, gist will respond
with the prompt "gist> ", and wait for keyboard input.  The commands
may be abbreviated by their first few characters, as long as the
abbreviation is unique:

     open cgmfile   - close the current CGM and open a new one (this
                      has no effect on any output engines)
     exit
     quit
     end            - finish and close any output files, then exit

     cgm cgmout [size] - create a new output CGM (with given max size)
     ps psout       - create a new output PostScript file
     display host:server.screen [dpi]  - create a new output X window
                      by default, the resolution will be 100 dpi, but
                      you can specify 75

     draw [page number list]  - render specified pages (default is
                                current page) on selected engines.
     send [page number list]  - render specified pages (default is
                                current page) on selected engines.

     info           - list current output engines and their states
     draw to e1 [e2 ...] - specify engines for draw (e1 is a number,
                           which is printed by the info command)
     send to e1 [e2 ...] - specify engines for send
     free e1 [e2 ...]    - kill the listed engines (finish and close
                           files, destroy X windows)

        The cgm and ps commands create engines which are initially selected
        for send, while the display command creates an X window which
        is initially selected for draw.  Hence, unless you explicitly use
        send to or draw to, draw will render the pictures on all X windows,
        not on output files.  Conversely, send will render the pictures
        ONLY on output files, not X windows.  Use "send to all" and
        "draw to all" to restore this default state of affairs.

     eps epsout  - create an Encapsulated PostScript file, render the
                   current page there, then close it.  The EPS preview
                   comments will show the page bounding box.

     nf       - (e.g.- "f" or "2f" or "31f") advance n (default 1) pages
                and draw
     nb       - (e.g.- "b" or "2b" or "31b") back up n (default 1) pages
                and draw
     ng       - (e.g.- "g" or "2g" or "31g") go to page n (default 1)
                and draw
     s        - (shortest abbreviation for send command) send current
                picture

The nf, nb, ng, and s commands may also be typed directly in an
X window owned by gist.  Also, q in that window is the quit command.
