GIST - A Scientific Graphics Package
			For UNIX Workstations


------------------------------------------------------------------------------
   $Id: README,v 1.1 2005-09-18 22:04:19 dhmunro Exp $

------------------------------------------------------------------------------
Features:

1) Three levels of graphics functions:
	 P (primitives), A (advanced), and D (display list)
   Routines are provided for creating and editing display list elements.
   When a display list is rendered, calls to the advanced and primitive
   graphics functions are generated.  `A' level functions call `P' level
   functions.
	A few functions are provided at a fourth level, H (high level),
   which embodies the control functions described in the suggested
   interactive interface below.

2) The `P' level functions call virtual rendering functions for all
   active graphics `engines'.  Three types of engines are provided:

      X Window System engines- draw to an X Window.  If the `D' level
         Gist routines have been used to construct a display list, then
         a Gist X engine can redraw itself if it is damaged by X exposure
         events.

      PostScript engines- output to a PostScript file which can be sent
         to many printers directly.

      CGM engines- output to a binary CGM metafile to allow for archiving
         large numbers of graphics frames for which PostScript output
         is too disk-intensive.

   Additional types of engines can be added by supplying virtual functions
   for the six graphical primitives (DrawLines, DrawMarkers, DrawText,
   DrawFill, DrawCells, and DrawDisjoint), and a half dozen additional
   control functions to perform actions such as destroying the engine,
   changing coordinate transformations, advancing to a new page, etc.
   Input to the rendering functions is in floating point coordinates,
   with a coordinate transformation.  Gist supplies most of the functions
   you should need to convert these into device coordinates.  Input to
   the primitives has already been clipped to the current viewport.

   Care has been taken to assure that only those engines which your code
   actually uses will be linked.

3) The `D' and `A' level routines render the following types of objects:

     Decorated lines:  Open or closed polylines in several linestyles,
                       with any width or color, optionally including
                       overstruck occasional marker characters or
                       ray arrows.

     Quadrilateral meshes:  May have arbitrary logical holes (missing
                            zones), and you may optionally draw individual
                            regions or region boundaries (instead of the
                            full mesh).  In addition to mesh lines, there
                            are three other display list elements which
                            can be used to show information about
                            quadrilateral meshes:

        Contours:  Trace level curves.  Mesh triangulation may be specified.
        Vectors:  Filled or hollow vector arrows at each mesh point.
        Filled Mesh:  The color of each zone reflects the value of a
                      function-- an alternative to contour plots.

     Images:  Implemented as cell arrays, so the image cell size can be
              easily changed.

     Text:  Supports Courier, Times, Helvetica, Symbol, and New Century
            Schoolbook fonts on all devices (the X versions of these are
            supplied with the MIT R4 release).

     Axis ticks and labels:  Linear and logarithmic "rulers" appropriately
            labeled.  Ticks always at "nice" numbers (i.e.- numbers ending
            with 0, 1, 2, or 5) of labeled ticks and minor ticks adjustable.
            Tick lengths and number of tick levels in the ruler hierarchy
            adjustable.  Optional grid lines.  Axes can be drawn on any
            or all four sides of a plot, or at a "nice" intermediate
            position (to get x and y axes interior to the plot).  Provision
            for scales with extremely small fractional variation (and
            therefore extremely long tick labels).

4) Gist provides a browser, "gist", for its CGM metafiles (it is not
   sufficiently general to handle any other metafiles, but, like the rest
   of Gist, it is easy to port to any UNIX workstation).  The gist
   browser can output pages in arbitrary order to an X window, a
   PostScript file, another CGM file, or to an EPS file (for input to
   FrameMaker).





------------------------------------------------------------------------------
Known problems:

General note:
The event-driven input dispatcher (dispat.c, dispas.c, dispax.c) is not
very well designed.  The files events.[ch], osmem.c, ospoll.c, osterm.c,
and ostime.c are a sketch of a better design; they are not currently
used, but I'm working on it...

   a) In Xlib.h, the style for declaring struct typedefs is an unhappy
      one.  In particular, the HPUX 8.05 ANSI C compiler on HP 700
      series machines issues a warning about the XImage data structure;
      the complaint is that the declaration in Xlib.h reads:
      typedef struct _XImage {
        ...
        (*VirtualFunction)(.., struct _XImage *, ..);
      } XImage;
      And when you pass this VirtualFunction an XImage*, the compiler
      complains that an XImage* pointer shouldn't be cast to a
      struct _XImage* pointer.  The correct thing to do is to get HP to
      fix either Xlib.h, or to teach their compiler about this
      programming style.

   b) The HPUX 8.05 <stdio.h>, when _HPUX_SOURCE is defined, declares
      and provides a prototype for the select function.  I therefore
      removed my prototype (it returns an int, so it can be implicitly
      declared).  However, there is a slight disagreement in argument
      types which produces a warning message.

   c) If you get a warning or error about the cuserid() function when
      osys.c compiles, change the definition of D_CUSERID in the
      Makefile and try again.

   c) If you get a warning or error about the exp10() function when
      the bench program loads, change the definition of D_HAS_EXP10
      in the Makefile and try again.

   e) A strict ANSI compiler will often produce reams of warnings from
      subsidiary files included by Xlib.h.  Obviously, this is not my
      problem.  If you have this problem, experiment with a simple code
      which includes <X11/Xlib.h>, <X11/Xutil.h>, and <X11/Xos.h>, until
      you have worked out a way to curb the warnings, or convinced
      yourself that the warnings are harmless.




------------------------------------------------------------------------------
Suggested interactive interface (control functions are partially
                                 implemented in hlevel.h, hlevel.c):

1) Plotting functions:

   plg, x, y
   plg, y	Plot graph, with keywords to add markers, ray arrows, etc.
     gistA.l=  ...linestyle...
     gistA.dl= ...decorations...
     gistA.m=  ...marker style...
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdLines(n, x, y)

   plm, x, y, ireg
   plm, x, y
   plm		Plot mesh with optional zone region number array ireg
     gistA.l=  ...linestyle...
     gistA.mesh= ...(x, y, ireg)... (ireg can be NULL)
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdNewMesh(0)
     GdMesh(region, boundary)

   plc, z, x, y, ireg
   plc, z	Plot contours of point-centered function z, with levs=
                keyword to specify levels
     gistA.l=  ...linestyle...
     gistA.dl= ...decorations...
     gistA.m=  ...marker style...
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdContours(z, triangulation, levels, nLevels)

   plv, u, v, scale, x, y, ireg
   plv, u, v, scale	Plot vector arrows
     gistA.l=  ...linestyle (if hollow)...
     gistA.f=  ...fill style (if filled)...
     gistA.vect= ...vector style...
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdVectors(u, v, scale)

   plf, colors, x, y, ireg
   plf, colors	Plot filled mesh
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdFillMesh(colors)

   pli, image, px, py, qx, qy
   pli, image	Plot image (cell array)
     gistD.hide= 0
     gistD.legend= ...legend text...
     GdCells(px, py, qx, qy, width, height, width, image)

   plt, text, x0, y0	Plot text with keywords for font, size, alignment
     gistD.hide= 0
     gistD.legend= 0
     gistA.t= ...text properties...
     GdSetDrawing(current_drawing)  /* saves current coordinate system */
     GdText(x0, y0, text)           /* (x0, y0) in NDC coordinates */
     GdSetDrawing(0)                /* restore original coordinates */


2) Coordinate systems:

   {xmin, xmax, ymin, ymax, flags}= lquery()
		Return the current limits and flags.  The actual values
		of the limits after extreme value calculation and other
		adjustments are returned.
     GdGetLimits()

   limits, xmin, ymin, xmax, ymax
   limits, {xmin, xmax, ymin, ymax, flags}  /* returned by lquery */
   limits, xmin, xmax
   range, ymin, ymax
		Set plot limits, can be numbers or "e" to get extreme
		values.  Takes keywords nice=1 (to force ends of axes
		to "nice" numbers), square=1 (to force dy=dx if any of
		the limits are set to extreme values), and restrict=1
		(to cause the extreme value search for x limits to
		ignore any points outside of fixed y limits and vice
		versa)
     gistD.window= {xmin, xmax, ymin, ymax}
     gistD.flags= {extreme, nice, square, restrict}
     GdSetLimits()

   logxy, xFlag, yFlag
		Set or reset log axis scaling
     gistD.flags= {xIsLog, yIsLog}
     GdSetLimits()

   coordsys, systemNumber
		Set current coordinate system (for drawing styles with
                multiple coordinate systems on the page)
     GdGetSystem(systemNumber)


3) Plot editing:

   elementType= plquery(elementIndex, keywords=...)
   elementType= plquery(keywords=...)
		Get information about a display list element.  Keywords
                can be any keyword legal in any of plotting commands, or
                the name of any formal parameter name for those commands.
                One additional keyword, level=levelIndex, allows selection
                of individual contour levels.  Also takes default=1
		keyword to retrieve current default styles.
     GdGetElement(elementIndex)
       maybe GdGetContour(levelIndex)

   pledit, elementIndex_list, keywords=...
   pledit, keywords=...
		Edit values for one or more elements.  Keywords are same
		as for plquery.  Some keywords do not make sense with
		more than one elementIndex.
     for (i=0 ; i<sizeof(elementIndex_list) ; i++)
       GdGetElement(elementIndex_list[i])
         maybe GdGetContour(levelIndex)
       gistA.?= new value;  gistD.?= new value
       GdEdit(0 or 1)


4) Current window control functions:

   about_to_wait_for_keyboard_input
		Before pausing for keyboard input, the following Gist
		sequence should be issued to assure that the current X
		display is up-to-date:
     GhBeforeWait()

   fma		Frame advance.  Sends current drawing to all active
		devices.  Optionally activates hardcopy device.
		Optionally performs animation (see below).  If the
		animation mode is not set, the Gist calls are:
     GhFMA()

   redraw	erase and redraw current X display
     GhRedraw()

   hcp		Send current X display to hardcopy file.  Takes optional
		file= keyword to create a new output file.
     GhHCP()

   hcpon
   hcpoff	Toggle whether fma activates/deactivates the
		hardcopy engine.  There is no way to permanently activate
		the hcp_engine interactively, avoiding problems with new
		frames appearing for every interactive resetting of limits
		or editing.  If no interactive pauses occur before the
		fma, then full efficiency is attained; otherwise the
		display list will be traversed once to send to the screen,
		and a second time to send to hardcopy, just as for the
		explicit hcp command.
     GhFMAMode(1 or 0, 2)

   animate, 0 or 1
   animate	Toggle animation mode for the current coordinate system.
		If all four limits are fixed, then only the viewport for
		the system is animated, otherwise the viewport and its
		ticks and labels are animated.  In this mode, the X engine
		draws to an offscreen pixmap which "blits" to the screen
		when the fma command is issued (see fma above).  Only one
		coordinate system can be animated at a time (since there
		usually IS only one, this is not much of a limitation).
		When animate mode is turned on, the decision of whether
		to animate the tick marks or just the viewport of the
		current system is made depending on whether all four
		limits are fixed.  When animation is turned on:
     GhFMAMode(2, 0 or 1)

   palette, r, g, b
   palette, "standard_palette.gp"
   palette, r, g, b, query=1
		Set current color palette either from explicit (r, g, b)
		arrays, or from a Gist palette file.  Takes ntsc=1
		keyword if grays for monochrome output devices are to
		be computed using NTSC TV standard rather than simple
		intensity.  Takes query=1 keyword to output to (r, g, b).
     GpSetPalette(x_display_engine, {r, g, b}, nColors)
       GpGetPalette(x_display_engine, {r, g, b})
       GpReadPalette(x_display_engine, "standard_palette.gp")

   pllist, elementIndex_list
   pllist	Prints list of legends at terminal.  Takes levels=1
		keyword to print individual level legends.  This is
		how you can determine the elementIndex for a given
		display list element.
     GdGetElement(elementIndex)    /* called in a loop */


5) Multiple window control functions:

   By default, you get one X window.  At the first use of the hcp command,
   a metafile will be created.  By default, this is a CGM file with a
   unique name, although both hcp and hcpon take a file= keyword to specify
   the filename.  By default, hardcopy files are CGM files whose filename
   will have ".cgm" appended (if not present).  You get a PostScript file
   by explicitly specifying a filename ending with ".ps".  You can close
   the existing file and not create a new one by specifying file="".

   If you want, you can switch to a second or third X window.  The plotting
   commands only deliver output to one X window at a time, but the other
   windows remain visible, and you can reinstate them whenever you want.
   Each X window has its own display list.  You can also have a display
   list which is not associated with any X window-- only a hardcopy file.
   Finally, each display list can have its own hardcopy file, which overrides
   the default hardcopy file shared among all display lists.

   All this is handled by two somewhat complicated functions:

   pldevice, number     /* 0<= number < 8 */
		Sets current display list to `number', if a display list
		with this number already exists, or creates a new display
		list with this number if there is none.  Takes keywords:
      display= "host:server.screen"
		Sets the display for X window.  Use "" to get no X window,
		since if this keyword is omitted you get a window on
		the display named by your DISPLAY environment variable.
      file= "hcp_file"
		Sets the name for the associated hardcopy file.  Use ""
		to revert to the default hcp file.  If you don't specify
		file= when creating a new display list, this is what you
		get by default.
      style= "standard_style"
		Name of style file to use for specifying layout of drawing.
		Default is "work.gs".  If you change this for an existing
		display list (X window), its current contents are erased
		as a side effect.
      hcplegends= 0 or 1
		Legends are not displayed in the X windows (use pllist);
		this switch controls whether legends are written to the
		hcp file.  Default is hcplegends=1.
      dpi= 75 or 100
		Resolution for the X window.  75 makes a small window; 100
		is the default.

   hcpdevice, file= "hcp_file"
		Sets the default hardcopy device used by any display lists
		which don't have their own hcp file as specified with
		pldevice.  Use file="" to close the current file.  If there
		is no default hcp file and an hcp command requires one,
		a default CGM file with a unique name will be created
		automatically.

   If no explicit pldevice command is issued, the first plotting command
   does an implicit "pldevice, 0", which brings up a local X window and
   makes it the current output device.  The first hcp command then triggers
   the creation of a hardcopy file as mentioned under the description
   of hcpdevice.  To preempt this sequence, you must call pldevice
   explicitly before plotting anything.  Use ` pldevice,0, display="" '
   to plot without creating any X windows.


6) Summary of interactive functions:
     Plotting:     plg, plm, plc, plv, plf, pli, plt
     Coordinates:  lquery, limits, range, logxy, coordsys
     Editing:      plquery, pledit
     Control:      fma, redraw, hcp, hcpon, hcpoff, animate, palette,
		   pllist, plus implied screen update
     Multiple:     pldevice, hcpdevice


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

      The BENCH program benchmarks and tests Gist

      $Id: README.B,v 1.1 2005-09-18 22:04:20 dhmunro Exp $

The execute line for the program is

     bench [useps [host:server.screen]]

where useps is 0 (the default) to use a CGM file as the hardcopy
device, and 1 to use a PostScript file.  If the optional X display
argument is not given, the Gist default is to use the DISPLAY
environment variable, like other X programs.  (If you built bench
with NO_XLIB, both arguments are ignored-- the "display" device is
a CGM file, and the hardcopy device is a PostScript file.)  The
output files, if any, will be "bench.ps" for PostScript output,
and "bench.cgm" for CGM output.  (Gist automatically families large
CGM files to about 1 Meg per file, so check for "benci.cgm",
"bencj.cgm", etc.  The gist CGM browser automatically jumps
between files in a family.)

The program waits for you to type a command, then exercises the
specified feature of Gist.  Some of the commands merely set attributes
rather than producing any graphics output.  Some commands add a
graphical element to the current drawing; others produce movies
to get an idea of Gist performance during animation.  Most commands
test the `D' and `H' level routines, but a few `A' and `P' level
benchmarks allow you to see how much performance penalty is incurred
by the higher level routines.  These low level tests also provide
fair comparisons of Gist with other graphics packages.

The 'help' command produces the following output, describing the
various commands:

	miggle[50] bench
	Initializing 51x51 contour function, STANDBY...  DONE
	bench> help

	   This is the GIST benchmark/test program, commands are:

	    Movies to test low level Gist functions--
	0   - raw performance test GaMesh (direct)
	1   - raw performance test GaMesh (animated)
	2   - raw performance test GaFillMesh (direct)
	3   - raw performance test GaFillMesh (animated)
	clr - toggle interframe clear for tests 0-3
	c   - clear screen
	im  - raw performance test GpCells
	clip  - toggle floating point clip
	zoom  - toggle zoom for 0-3, im, pli

	    Property toggles for high level tests--
	bnd  - mesh boundary          odd0  - mesh region to 0
	odd2  - mesh region to 2      reg0  - plot region to 0
	reg1  - plot region to 1      reg2  - plot region to 2
	nocopy - toggle noCopy mode for mesh-based tests
	cmode - toggle dumping of colormap in hcp file
	earth - use earthtones palette (default).  Others are:
	     stern   rainbow   heat   gray   yarg
	work  - use work stylesheet (default).  Others are:
	     boxed   axes
	wide      - toggle wide lines in all line drawings
	linetype  - cycle through 5 line types in all line drawings
	closed    - toggle closed lines in plg tests
	rays      - toggle ray arrows in plg tests
	smooth    - cycle through 3 hcp smoothnesses in plg tests
	limits, xmin, xmax, ymin, ymax, nice=1/0, square=1/0,
		restrict=1/0   - set limits (default limits,e,e,e,e)
	logxy, 1/0, 1/0   - set/reset log scaling for x,y axes
	animate  - toggle animation mode
	marks    - toggle occasional curve markers for line drawings
	legends  - toggle dumping of legends into hcp file

	    Movies to test high level Gist functions--
	plg  - test GdLines
	plm  - test GdMesh
	plf  - test GdFillMesh
	plv  - test GdVectors
	plc  - test GdContours

	    Single frame tests of high level Gist functions--
	plg1  - test GdLines
	plm1  - test GdMesh
	plf1  - test GdFillMesh
	plc1  - test GdContours
	pli   - test GdCells
	plt   - test GdText
	pls   - test GdLines in polymarker mode
	pldj  - test GdDisjoint
	txin  - test GdText     txout  - 2nd test of GdText
	calib - text calibration frame
	cfont - toggle font for calibration frame

	    Tests of high level Gist control functions--
	fma    - frame advance
	hcp    - send current frame to hardcopy file
	hcpon  - send every frame to hardcopy file
	hcpoff - stop sending every frame to hardcopy file
	redraw - redraw the X window

	quit  - exit bench program (just q works too)

	bench>


Here are 3 sample sessions with the bench program.  Input lines that you
type are marked with bench>.  Most of the features of Gist are
demonstrated here.  The three sessions are:
 (1) A performance test, both for "fastest possible" rendering using
     A-level and P-level Gist routines, and for the D-level display
     list routines that could reasonably be used by an interpreter.
     Gist's "animation" mode is exhibited (smooth animation requires
     a picture to be built up offscreen, then "blitted" onscreen).
     The polyline and filled area primitives are exercised.
 (2) Generate a relatively small CGM file which contains nearly
     everything that Gist will ever throw at a CGM interpreter.
     This file is useful for exercising the gist CGM browser, as well
     as for seeing how badly Gist CGM file break your second favorite
     CGM interpreter.
 (3) Exercise other high level features of Gist, especially the
     tick drawing and labeling routine.  Also exhibits D-level style
     and palette files.

For the record, "miggle" is a Sun-4/330 running the X11R4 sample server
from MIT.  Gist was compiled by gcc with no optimization (optimization
speeds up the low level benchmarks by about 30%).  The display is to
an HP 730 workstation, which has a very fast X server.


(1)---------------------------------------------------------------------


IMPORTANT-- If you care about the timings in the first test, be sure
to clear all other jobs off of the machine which is running your
X server, AND DON'T MOVE THE MOUSE OR TYPE DURING A TEST!

	miggle[51] bench
	Initializing 51x51 contour function, STANDBY...  DONE
	bench> 0
	   Begin benchmark 0 -- GaMesh (direct).
	elapsed seconds: 3.370000 user, 0.710000 system, 13.409998 wall
	Plots per wall second= 3.728561

	bench> 1
	   Begin benchmark 1 -- GaMesh (animated).
	elapsed seconds: 3.210000 user, 0.820000 system, 15.399998 wall
	Plots per wall second= 3.246754

	bench> 2
	   Begin benchmark 2 -- GaFillMesh (direct).
	elapsed seconds: 9.770000 user, 2.260000 system, 36.759997 wall
	Plots per wall second= 1.360174

	bench> 3
	   Begin benchmark 3 -- GaFillMesh (animated).
	elapsed seconds: 9.790000 user, 2.380000 system, 22.969997 wall
	Plots per wall second= 2.176753

	bench> clip
	   Toggle floating point clip (now on)

	bench> 0
	   Begin benchmark 0 -- GaMesh (direct).
	elapsed seconds: 4.870000 user, 0.780000 system, 15.829997 wall
	Plots per wall second= 3.158560

	bench> 1
	   Begin benchmark 1 -- GaMesh (animated).
	elapsed seconds: 5.010000 user, 0.630000 system, 15.849998 wall
	Plots per wall second= 3.154575

	bench> 2
	   Begin benchmark 2 -- GaFillMesh (direct).
	elapsed seconds: 13.390000 user, 2.410000 system, 40.499997 wall
	Plots per wall second= 1.234568

	bench> 3
	   Begin benchmark 3 -- GaFillMesh (animated).
	elapsed seconds: 13.570000 user, 2.330000 system, 28.999997 wall
	Plots per wall second= 1.724138

	bench> fma
	   Frame advance

	bench> plm
	   Begin mesh benchmark.
	elapsed seconds: 6.940000 user, 0.820000 system, 15.439997 wall
	Plots per wall second= 3.238343

	bench> animate
	   Toggle animation mode (now on)

	bench> plm
	   Begin mesh benchmark.
	elapsed seconds: 7.000000 user, 0.710000 system, 17.179998 wall
	Plots per wall second= 2.910361

	bench> animate
	   Toggle animation mode (now off)

	bench> plf
	   Begin filled mesh benchmark.
	elapsed seconds: 19.500000 user, 2.180000 system, 37.429997 wall
	Plots per wall second= 1.335827

	bench> animate
	   Toggle animation mode (now on)

	bench> plf
	   Begin filled mesh benchmark.
	elapsed seconds: 19.230000 user, 2.320000 system, 37.099997 wall
	Plots per wall second= 1.347709

	bench> quit
	120.5u 18.8s 7:42 30% 0+568k 1+1io 1pf+0w

Several features of these benchmark results are worth contemplating:
Most important, for the X Engine (at least on my Sun-4/330), the time
is dominated by the rendering time of the server, NOT by the CPU time
required by Gist.  Secondly, of the CPU time used by Gist, the time to
do the floating point clip explains much of the additional time used
by the Gist D-level routines (there is no very practical way to avoid
the clipping operation in the D-level routines).  Thirdly, animation
mode costs little in performance.


(2)---------------------------------------------------------------------

Generate a CGM test file for exercising the gist browser:

	miggle[52] bench
	Initializing 51x51 contour function, STANDBY...  DONE
	bench> plg1
	   Plot small graph.

	bench> marks
	   Toggle markers (now on)

	bench> plg1
	   Plot small graph.

	bench> marks
	   Toggle markers (now off)

	bench> rays
	   Toggle rays (now on)

	bench> plg1
	   Plot small graph.

	bench> rays
	   Toggle rays (now off)

	bench> wide
	   Toggle wide lines (now on)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dashed)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dotted)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dash-dot)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dash-dot-dot)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now solid)

	bench> wide
	   Toggle wide lines (now off)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dashed)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dotted)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dash-dot)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now dash-dot-dot)

	bench> plg1
	   Plot small graph.

	bench> linetype
	   Toggle line type (now solid)

	bench> txout
	   Exterior text

	bench> hcp
	   Sent frame to hcp

	bench> fma
	   Frame advance

	bench> plt
	   Text test

	bench> hcp
	   Sent frame to hcp

	bench> fma
	   Frame advance

	bench> pli
	   Plot image.

	bench> hcp
	   Sent frame to hcp

	bench> fma
	   Frame advance

	bench> plf1
	   GdFillMesh test

	bench> hcp
	   Sent frame to hcp

	bench> fma
	   Frame advance

	bench> cmode
	   Toggle hcp color mode (now dump)

	bench> plg1
	   Plot small graph.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> plg1
	   Plot small graph.

	bench> txout
	   Exterior text

	bench> hcp
	   Sent frame to hcp

	bench> fma
	   Frame advance

	bench> pli
	   Plot image.

	bench> hcp
	   Sent frame to hcp

	bench> stern
	OK

	bench> fma
	   Frame advance

	bench> plf1
	   GdFillMesh test

	bench> hcp
	   Sent frame to hcp

	bench> quit
	miggle[53] mv bench.cgm check.cgm



Repeat this test with the command line "bench 1" to generate a PostScript
file which you can send to your printer to be sure that Gist doesn't
produce anything which confuses it.  Alternatively, you can build the
gist previewer and run check.cgm through it to convert to PostScript:

	miggle[54] gist/gist check.cgm -b -ps check.ps

Or view the CGM file on your X server:

	miggle[55] gist/gist check.cgm
	check.cgm metafile description:
	Fri Oct 30 13:53:07 1992;  For: munro
	gist> f
	gist> f
	gist> f
	gist> f
	gist> f
	gist> f
	gist> draw 1
	gist> quit

You can also compare the relative sizes of PostScript and CGM output.
On a more extensive test, I found that:

  (1) A Gist PostScript file is roughly twice the size of the Gist CGM
      file produced by the same commands (two hex characters represent
      one byte).
  (2) The CPU time required by Gist to produce a PostScript file is two
      to three times the CPU time required by Gist to produce a CGM file
      from the same commands.
  (3) The compress utility will squeeze the PostScript file by about 60%,
      to a size just slightly smaller than the CGM file.  The CGM file
      compresses only 10-15% (not worth doing, but slightly smaller than
      the compressed PostScript).

The moral is- use Gist CGM output and don't bother to compress it.  The
gist CGM browser will translate Gist CGM files into exactly the same
PostScript file Gist would have produced in the first place.


(3)---------------------------------------------------------------------

The plg, plm, plc, plv, plf, plt, and pli commands to bench test
features of the proposed interactive interface routines of the
same names described in README.  The fma, redraw, limits, and
logxy commands are also similar to the proposed interface, except
that the limits command in bench takes the logarithms of the
limits, while the interactive routine would work in the intuitive
way.

Whenever the screen looks interesting, type "hcp" to send it to the
CGM file "bench.ps", which you can send to your printer.  (Note-
this will fail silently for the frame displayed at the end of any
of the movies, or for the "stale" frame displayed after fma.)


	miggle[67] bench
	Initializing 51x51 contour function, STANDBY...  DONE
	bench> plm1
	   GdMesh test

	bench> txin
	   Interior text

	bench> txout
	   Exterior text

	bench> fma
	   Frame advance

	bench> plt
	   Text test

	bench> plm1
	   GdMesh test

	bench> redraw
	   Redraw

	bench> fma
	   Frame advance

	bench> plm1
	   GdMesh test

	bench> limits, .02, 1.48, .31, .59
	   Setting limits

	bench> limits, -.2, 1.2, e, e
	   Setting limits

	bench> limits, -.2, e, e, e, square=1
	   Setting limits

	bench> limits, -.2, 1.5, e, e
	   Setting limits

	bench> limits, square=0
	   Setting limits

	bench> logxy, 1, 1
	   Setting logxy

	bench> limits, 105, 190, -.001, 1
	   Setting limits

	bench> limits, 17, 39.5, .001, .1
	   Setting limits

	bench> limits, 17, 32, 1, 100
	   Setting limits

	bench> limits, 16, 19, 1.e4, 1.e6
	   Setting limits

	bench> logxy, 0, 0
	   Setting logxy

	bench> limits, e, e, e, e
	   Setting limits

	bench> plg
	   Lissajous test
	elapsed seconds: 2.410000 user, 0.180000 system, 2.839997 wall
	Plots per wall second= 17.605653

	bench> animate
	   Toggle animation mode (now on)

	bench> plg
	   Lissajous test
	elapsed seconds: 2.320000 user, 0.150000 system, 4.079997 wall
	Plots per wall second= 12.254911

	bench> marks
	   Toggle markers (now on)

	bench> plg
	   Lissajous test
	elapsed seconds: 3.170000 user, 0.280000 system, 4.389997 wall
	Plots per wall second= 11.389529

	bench> wide
	   Toggle wide lines (now on)

	bench> limits, square=1
	   Setting limits

	bench> marks
	   Toggle markers (now off)

	bench> plg
	   Lissajous test
	elapsed seconds: 2.260000 user, 0.160000 system, 5.779997 wall
	Plots per wall second= 8.650523

	bench> wide
	   Toggle wide lines (now off)

	bench> rays
	   Toggle rays (now on)

	bench> plg
	   Lissajous test
	elapsed seconds: 3.090000 user, 0.270000 system, 3.409997 wall
	Plots per wall second= 14.662770

	bench> rays
	   Toggle rays (now off)

	bench> limits, square=0
	   Setting limits

	bench> plm
	   Begin mesh benchmark.
	elapsed seconds: 6.930000 user, 0.830000 system, 16.279997 wall
	Plots per wall second= 3.071254

	bench> marks
	   Toggle markers (now on)

	bench> plc
	   Begin contour benchmark.
	elapsed seconds: 15.810000 user, 0.310000 system, 16.179997 wall
	Plots per wall second= 3.090235

	bench> limits, .25, .75, .25, .75
	   Setting limits

	bench> plv
	   Begin vector benchmark.
	elapsed seconds: 12.650000 user, 0.860000 system, 14.929997 wall
	Plots per wall second= 3.348963

	bench> animate
	   Toggle animation mode (now off)

	bench> limits, e, e, e, e
	   Setting limits

	bench> pli
	   Plot image.

	bench> rainbow
	OK

	bench> redraw
	   Redraw

	bench> cmode
	   Toggle hcp color mode (now dump)

	bench> stern
	OK

	bench> redraw
	   Redraw

	bench> heat
	OK

	bench> gray
	OK

	bench> yarg
	OK

	bench> earth
	OK

	bench> fma
	   Frame advance

	bench> plg1
	   Plot small graph.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> pls
	   Plot small scatter.

	bench> plg1
	   Plot small graph.

	bench> boxed
	OK

	bench> plg1
	   Plot small graph.

	bench> axes
	OK

	bench> plg1
	   Plot small graph.

	bench> work
	OK

	bench> plg1
	   Plot small graph.

	bench> quit
	55.9u 4.1s 9:32 10% 0+736k 6+1io 6pf+0w

Note that in non-dump cmode, a redraw is required after a palette change
to change the pixel numbers of the image.