Repatch (from linux) of OSX IRAF

1 files changed, 3498 insertions, 0 deletions

diff --git a/sys/gio/doc/gio.hlp b/sys/gio/doc/gio.hlp
new file mode 100644
index 00000000..f8749c23
--- /dev/null
+++ b/sys/gio/doc/gio.hlp
@@ -0,0 +1,3498 @@
+.help gio Dec84 "Graphics I/O"
+.ce
+\fBGraphics I/O Design\fR
+.ce
+Doug Tody
+.ce
+December 1984
+.ce
+(revised October 1987)
+.sp 3
+.nh
+Introduction
+
+    The graphics i/o (GIO) interface is a library of SPP or Fortran callable
+procedures for interactive vector graphics.  The interface is designed primarily
+for scientific applications (graphing 1-dimensional data vectors).  Limited
+support is also provided for displaying 2-dimensional image data.  GIO is fully
+integrated into the IRAF system and is not intended for use in systems other
+than IRAF.  The principal design objectives of GIO are outlined below.
+
+.ls
+.ls o
+Simple and efficient interactive graphics.  For interactive data analysis
+applications speed is typically much more important than the quality of
+the plot.
+.le
+.ls o
+Ease of use.  The interface must be easy to use for scientific data analysis
+applications.  Ease of use for interactive graphics in scientific applications
+is considered more important than the flexibility required to produce
+publication quality graphics.
+.le
+.ls o
+Compact size.  That portion of the graphics system required for interactive
+graphics must be small enough to be linked into every process which performs
+interactive graphics.
+.le
+.ls o
+Device independence.  The interface must be device independent without
+compromising compactness and speed.  True device independence means that
+an applications program that normally uses interactive graphics can be run
+noninteractively or from a nongraphics workstation.
+.le
+.le
+
+
+IRAF needs its own graphics interface partly because no existing graphics
+interface meets all of the above requirements, and partly because we do not
+want our applications to be dependent upon any particular external graphics
+package.  The existing large graphics interfaces such as GKS and CORE are
+likely to make it easier to interface GIO to new graphics devices, but to
+be completely and directly dependent on any one such interface is unwise since
+implementations are sometimes hard to come by.  Furthermore, packages such
+as GKS and CORE were designed to serve as the kernel of a graphics system
+and are cumbersome to use directly in applications software.  GIO will serve
+as a front end to the graphics kernel, providing a higher level interface
+for applications software and isolating the IRAF applications from the kernel,
+making it possible to switch to a different kernel without rewriting the
+applications packages.
+
+.nh
+Conceptual Design
+
+    GIO is intended to be used either as a self contained interface to a
+graphics device, with GIO writing device instructions directly to the device,
+or as an interface to a more general device independent graphics kernel.
+For maximum speed in interactive applications GIO will use a special builtin
+kernel capable of driving only the interactive graphics devices in use at
+a particular site (e.g., tektronix compatible graphics terminals).
+Other devices will be driven by a device independent graphics kernel resident
+in a separate process.  GIO will select the data path to be used for a
+particular device transparently to the calling program.  Thus, the overhead
+of process initiation and IPC will be eliminated in common interactive
+applications without sacrificing device independence.  The builtin kernel
+will be table driven using a \fBtermcap\fR format graphics device database,
+allowing maximum flexibility for adapting GIO to new graphics devices.
+
+The device independent graphics kernel may be GKS, CORE, NSPP, or any other
+reasonably capable kernel.  GIO will be designed to require only a few simple
+graphics primitives at the bottom end, making it straightforward to interface
+to different graphics kernels.  Any application which requires a more
+sophisticated graphics interface than that provided by GIO may bypass GIO
+and talk directly to the underlying graphics kernel, but doing so will
+render the application usable only with that particular graphics kernel.
+
+Placing the device independent graphics kernel in a separate process makes
+it possible to use a large, sophisticated graphics kernel without linking
+enormous libraries of subroutines into applications processes.  Bugs can be
+fixed and new features and devices added without relinking applications
+processes.  In principle it is even possible to interface simultaneously
+to more than one graphics kernel, e.g., one might drive some devices with
+an NSPP kernel and others with a GKS kernel.  On a different host CORE might
+be the only thing available and GIO would have to be interfaced to CORE on
+such a host.
+
+
+.ks
+.nf
+	        __________
+	       /          \
+	       | graphics |
+	       | terminal |
+	       \__________/
+		   |  ^
+		   |  |(device codes)
+		   v  |                           _________
+		+--------+     +-----------+     /         \
+		|   CL+  |<----| graphics  |<----|         |
+		|  fast  |     |  kernel   |     | gdevice |
+		| kernel |---->|   task    |---->|         |
+		+--------+     +-----------+     \_________/
+		   |  ^                 |
+		   |  |(gki metacode)   |          (core metacode)
+		   v  |                 +--------> (nspp metacode)
+		+--------+                         (gks vdm)
+		|  user  |
+		|  task  |-----------------------> (gki metacode)
+		+--------+
+
+
+	          simple                   plotters
+	  |---  interactive ---|------     metafile    ------|
+		 graphics               special devices
+
+
+.fi
+.ce
+Figure 1. Graphics Task Structure
+.ke
+
+
+The IRAF command language (CL) is the user interface to IRAF programs and
+as such moderates all interaction with the user, including interaction via
+graphics devices.  GIO is primarily a graphics \fIoutput\fR interface;
+graphics input (other than pixel readback) is decoupled from graphics output
+and is controlled by the CL.  Often the task requesting cursor input will
+differ from that which produced the graphics.  The CL, under control of the
+user, may set the default graphics input and output devices, redirect graphics
+input and/or output to devices other than the default, and control whether
+a graphics task is used interactively or in batch mode.
+
+.nh
+Specifications
+
+    The GIO graphics output procedures draw various flavors of vectors and
+fill or color two dimensional areas.  Cursor input is a way of interacting
+with the user and is therefore handled by CLIO (the command language
+interface).  We first define important terms and define the coordinate
+systems used by GIO.  Next follows an overview of the input and output
+procedures.  Finally, we describe in detail the individual procedures and
+the interface to the graphics kernel.
+
+.nh 2
+Coordinate Systems
+
+    The full plotting surface of a device defines the domain of definition
+of the coordinate systems used by GIO.
+GIO supports up to sixteen user defined \fBworld coordinate systems\fR
+(WCS) per open device, numbered 1 through 16.
+One additional coordinate system (WCS 0) with values ranging from 0 to 1 in
+either axis is predefined for every device; this \fBnormalized device
+coordinate system\fR (NDC) spans the full plotting surface of the device.  
+
+The mapping of world coordinates to device coordinates is
+defined by a \fBwindow\fR into world space and a corresponding \fBviewport\fR
+into device space.  Each window-viewport pair defines one of the 16 world
+coordinate systems.  At \fBgopen\fR time GIO is initialized to WCS 1,
+which has both window and viewport set to NDC coordinates.  A subsequent
+call to either \fBgswind\fR or \fBgscale\fR will set the window and a
+subsequent call to \fBgsview\fR will set the viewport.  The WCS is not fixed
+to the device until a plotting operation occurs which requires use of the WCS.
+Hence, multiple calls to \fBgscale\fR to determine the range of data values
+in X and Y for a family of curves are possible before fixing the WCS to the
+device, e.g. in a call to \fBglabax\fR.
+
+A \fBviewport\fR is any rectangular plotting area lying entirely within the
+plotting area of the device.  The viewport defines the area in which data
+can be plotted, i.e., the boundary at which \fBclipping\fR will occur if
+enabled.  The viewport is the area framed by \fBglabax\fR; the tick and axis
+labels will be plotted in the area just outside the viewport.
+A square viewport need not have the same resolution in both X and Y.
+Devices with variable resolution, e.g. pen plotters, have a default
+resolution in either axis which can be overridden when the plot is drawn.
+The aspect ratio of the device is the ratio of the physical size of a
+device pixel in Y to that in X.  Most devices have an aspect ratio of
+unity, but it is common for the resolution to be different in X and Y.
+The aspect ratio of the device is available via a \fBgget\fR inquiry,
+as is the device resolution in either axis.
+
+A \fBwindow\fR is the range of world coordinates which GIO will map to the
+corresponding viewport.  The world coordinates must be cartesian and
+either linear or logarithmic (base 10) in either axis.
+There are no restrictions on the range of world coordinates other than
+those imposed by the single precision floating point hardware of the
+host computer, provided that the WCS is not degenerate
+(zero range in either axis).
+
+Most applications will use only a single WCS, hence the WCS number is not
+included explicitly in the argument lists of the GIO procedures.
+A call to \fBgset\fR is required to change to a different WCS.
+Thereafter all graphics output and cursor input will refer to the new WCS.
+Multiple WCS are useful when plotting in several distinct (nonoverlapping)
+viewports on a device, or when overplotting curves within the same viewport
+but with different world coordinate windows.
+
+.nh 2
+Graphics Output Procedures
+
+    The GIO output procedures range from \fBgplotv\fR and \fBgploto\fR,
+which can draw an entire plot with autoscaling and axis labeling in one call,
+to the polyline, polymarker, move, draw, and text drawing primitives at
+the low end.
+
+
+.ks
+.nf
+	       gplotv (v, npts, x1, x2, title)
+	       gploto (gp, v, npts, x1, x2, title)
+	    gpagefile (gp, fname, prompt)
+		
+	   gp = gopen (device, mode, fd)
+	       gclose (gp)
+	  gdeactivate (gp, flags)
+	  greactivate (gp, flags)
+	      gcancel (gp)
+	       gflush (gp)
+	       gclear (gp)
+	       gframe (gp)
+	       greset (gp, flags)
+	     gmftitle (gp, metafile_title)
+
+	        gscan (gp, text)
+	    gset[irs] (gp, param, value)
+     val = gstat[irs] (gp, param[, outstr, maxch])
+     val = gget[birs] (gp, devcap[, outstr, maxch])
+	    g[sg]view (gp, x1, x2, y1, y2)
+	    g[sg]wind (gp, x1, x2, y1, y2)
+	   g[ar]scale (gp, v, npts, axis)
+	      ggscale (gp, x, y, dx, dy)
+	       gctran (gp, x1, y1, x2, y2, wcs1, wcs2)
+	      gcurpos (gp, x, y)
+	      gescape (gp, fn, instruction, nwords)
+
+	       glabax (gp, title, xlabel, ylabel)
+	        gline (gp, x1, y1, x2, y2)
+	       gpline (gp, x, y, npts)
+	       gvline (gp, v, npts, x1, x2)
+	        gmark (gp, x, y, marktype, xsize, ysize)
+	       gpmark (gp, x, y, npts, marktype, xsize, ysize)
+	       gvmark (gp, v, npts, x1, x2, marktype, xsize, ysize)
+	       gumark (gp, x, y, npts, xcen, ycen, xsize, ysize, fill)
+	    g[ar]move (gp, x, y)
+	    g[ar]draw (gp, x, y)
+		gtext (gp, x, y, text, format)
+		gfill (gp, x, y, npts, style)
+	    g[pg]cell (gp, m, nx, ny, x1, y1, x2, y2)
+
+	        gscur (gp, x, y)
+	 stat = ggcur (gp, x, y, key)
+.fi
+.ke
+
+
+All coordinates are given in world coordinates (user coordinates)
+except the viewport coordinates and the marker sizes, which are given in
+device coordinates.  Low level graphics i/o requires that the graphics
+device first be opened with \fBgopen\fR and later closed with \fBgclose\fR.
+Several graphics devices may be open simultaneously.
+
+When a graphics device is opened with \fBgopen\fR all internal parameters
+are initialized to their default values, unless the device is opened in
+APPEND mode.  The default values of these internal parameters may be changed
+via explicit \fBgset\fR, \fBgswind\fR, \fBgscale\fR, or \fBgscan\fR calls.
+Most powerful is \fBgscan\fR, which interprets graphics commands passed
+either as an explicit string or in a text file.
+
+Much of the flexibility of GIO derives from its parameter defaulting
+mechanism.  The interface may be expanded indefinitely by adding new
+internal parameters accessed via \fBgset\fR calls, without changing the
+basic interface.
+
+.nh 2
+Graphics Input Procedures
+
+    The most commonly used type of graphics input is cursor readback.
+Two forms of cursor input are supported: cursor input via the CLIO procedure
+\fBclgcur\fR, and cursor input via the GIO procedure \fBggcur\fR.
+CLIO based cursor input should be used whenever possible, i.e., when writing
+to \fBstdgraph\fR or \fBstdimage\fR.  The advantage of cursor input via the
+CL is that input may come from a list file or the terminal as well as from
+a physical cursor read, allowing programs to be used either interactively
+or in batch mode.  Furthermore, WCS selection and conversion of NDC cursor
+coordinates to WCS and cursor mode interaction are only available with
+\fBclgcur\fR.  Programs which do not produce any graphics output may read
+the cursor via CLIO without using any part of the GIO interface.
+The lower level GIO cursor read procedure always reads the physical device
+cursor in NDC coordinates and is device dependent (it is what is called by
+\fBclgcur\fR).
+
+Cursors are implemented as abstract datatypes within the CL.  A user task
+accesses a cursor by reading the value of a CL parameter of type \fBgcur\fR
+(stdgraph cursor) or \fBimcur\fR (stdimage cursor).  Multiple cursors may
+be implemented using multiple cursor type parameters.  A cursor parameter
+is assumed to have a \fIlist\fR of values; EOF is returned when the end of
+the list is reached.  Reading the cursor automatically causes any graphics
+output to be flushed.
+
+        stat = clgcur (param, wx, wy, wcs, key, strval, maxch)
+
+The CLIO function \fBclgcur\fR reads the next cursor value from the named
+cursor parameter, returning as output arguments the cursor position in world
+coordinates, the index of the referenced WCS, the keystroke value (character
+typed) of the cursor event, and a string value if the key was ':', the
+cursor mode set option escape character.
+A cursor read sequence begins with a prompt, i.e., the cursor lights up
+or starts blinking.  The user is then free to move the cursor about;
+the cursor position is not read until a key is typed on the user terminal.
+Using a keystroke on the user terminal to terminate both \fBstdgraph\fR
+and \fBstdimage\fR cursor reads provides a rich and device independent set of
+keystroke values for identifying the action to be performed (imaging devices
+are typically very limited in this area).
+
+GIO always returns the cursor position in world coordinates, along with
+the index of the WCS selected.  Typically there will be exactly one world
+coordinate system (excluding WCS 0) and the WCS value may be ignored.
+If no world coordinate systems are defined for the device the cursor
+position will be returned in NDC coordinates with WCS=0.
+
+If multiple world coordinate systems are defined GIO will select the WCS
+closest to the position of the cursor, i.e., the cursor may lie outside the
+viewport and GIO will still return WCS coordinates.  If the cursor lies
+within two or more overlapping viewports GIO will select the WCS with the
+highest number.  The cursor read protocol will allow the user to force
+the selection of a particular viewport by first placing the cursor on a
+nonoverlapping portion of the viewport and typing a special code,
+e.g., W (see next section), and then continuing with the normal cursor read.
+If the application wishes to override the automatic WCS selection it may
+do so by calling \fBgctran\fR to transform the cursor coordinates returned
+by \fBclgcur\fR to a different world coordinate system.
+
+.nh 3
+Cursor Mode
+
+    In cursor mode, i.e., after a call to \fBclgcur\fR or after typing "=gcur",
+a number of special keystrokes shall be recognized for interactive display
+control.  All graphics output to stdgraph and stdimage is routed through the
+CL on the way to the graphics kernel.  The CL will optionally spool in an
+internal buffer all graphics instructions output to an interactive device.
+This internal buffer is emptied whenever the device screen is cleared.
+In cursor mode, special keystrokes may be used to redraw all or any portion
+of the spooled graphics, e.g., one may zoom in on a portion of the plot and
+then roam about on the plot at high magnification.  Since the spooled graphics
+vectors typically contain more information than can be displayed at normal
+magnification, zooming in on a feature may bring out additional detail
+(the maximum resolution is 32768 points in either axis).  Increasing the
+magnification will increase the precision of the cursor by the same factor.
+
+Cursor mode is implemented by performing coordinate transformation and
+clipping on each GKI instruction in the frame buffer, passing the transformed
+and clipped instructions on to the graphics kernel.
+The cursor mode operations perform a simple geometric transformation on
+the spooled graphics frame, mapping a rectangular window of the spooled
+frame onto the device screen.  The graphics frame itself is not modified,
+hence zoom out or reset and redraw will restore the original display.
+
+If the graphics frame is a typical vector plot with drawn and labeled
+axes, magnifying a portion of the plot may cause the axes to be lost.
+If this is not what is desired a keystroke is provided to draw and label
+the axes of the displayed window.  The axes will be overplotted on the
+current display and will not be saved in the frame buffer, hence they
+will be lost when the frame is redrawn.  In cursor mode the viewport is
+the full display area of the output device, hence the tick mark labels
+of the drawn axes will be drawn inside the viewport.  This form of axes
+labeling is used because it is simple and because it is appropriate for
+both vector graphics and image display output devices (and cursor mode
+must serve both).
+
+
+.ks
+.nf
+	A 			draw and label the axes of current viewport
+	B			backup over last instruction in frame buffer
+	C			print the cursor position as it moves
+	D 			draw a line by marking the endpoints
+	E			expand plot by setting window corners
+	F			set fast cursor (for HJKL)
+	H			step cursor left
+	J			step cursor down
+	K			step cursor up
+	L			step cursor right
+	M			move point under cursor to center of screen
+	P			zoom out (restore previous expansion)
+	R			redraw the screen
+	T 			draw a text string
+	U 			undo last frame buffer edit
+	V			set slow cursor (for HJKL)
+	W 			select WCS at current position of cursor
+	X			zoom in, X only
+	Y			zoom in, Y only
+	Z			zoom in, both X and Y
+	<			set lower limit of plot to the cursor y value
+	>			set upper limit of plot to the cursor y value
+	\ 			escape next character
+	:			set cursor mode options
+	:!			send a command to the host system
+	=			shorthand for :.snap (make graphics hardcopy)
+	0			reset and redraw
+       1-9			roam
+.fi
+.ce
+Figure 2. Cursor Mode Keystrokes
+.ke
+
+
+By default the cursor mode keystrokes are all upper case letters, reserving
+lower case for applications programs.  The terminal shift lock key may be
+used to simplify typing in lengthy interactive cursor mode sessions.
+The cursor motions are decoupled from roam since zoom and roam are often used
+merely to increase the precision of a cursor read.  Special keystrokes are
+provided for stepwise cursor motions to increase the speed of cursor setting
+on terminals that do not have fast cursor motions (e.g., the retro-graphics
+enhanced VT100).  The recognized keystrokes are shown in Figure 2.
+
+If the character : is typed while in cursor mode the alpha cursor will appear
+at the bottom of the screen, allowing a command line to be entered.  Commands
+which begin with a period, e.g., ":." are interpreted by the graphics system;
+any other command will terminate the cursor read, returning the character ':'
+as the key value, and the command string as the string value of the cursor
+read.  The commands recognized by the graphics system are summarized in
+figure 3.
+
+
+.ks
+.nf
+	:.axes[+-]		draw axes of viewport whenever screen is redrawn
+	:.case[+-]		enable case sensitivity for keystrokes
+	:.clear			clear alpha memory (e.g, this text)
+	:.cursor n		select cursor (0=normal,1=crosshair,2=lightpen)
+	:.gflush		flush plotter output
+	:.help			print help text for cursor mode
+	:.init			initialize the graphics system
+	:.markcur[+-]		mark cursor position after each cursor read
+	:.off [keys]		disable selected cursor mode keys
+	:.on [keys]		enable selected cursor mode keys
+	:.page[+-]		enable screen clear before printing help text
+	:.read file		fill frame buffer from a file
+	:.show			print cursor mode and graphics kernel status
+	:.snap [device]		make hardcopy of graphics display
+	:.txqual qual		set character generator quality (normal,l,m,h)
+	:.txset format		set text drawing parameters (size,up,hj,vj,etc)
+	:.xres=value		set X resolution (stdgraph only)
+	:.yres=value		set Y resolution (stdgraph only)
+	:.viewport x1 x2 y1 y2	set workstation viewport in world coordinates
+	:.write[!][+] file	save frame buffer in a spool file
+	:.zero			reset viewport and redraw frame
+.fi
+
+
+.ce
+Figure 3. Cursor Mode Commands
+.ke
+
+
+Minimum match abbreviations are permitted for cursor mode command names.
+Multiple commands may be given on one line, delimited by semicolons.
+If the CL environment variable \fBcminit\fR is defined when cursor mode is
+first entered, the string value will be interpreted as a cursor mode command
+and used for initialization.  For example, to disable the numeric keys and
+set the graphics resolution to 200 points in X and 100 points in Y, one
+could add the following \fBset\fR declaration to their "login.cl" file:
+
+	set cminit = "xres=200; yres=150; off 0-9"
+
+The numeric keypad of the terminal (if it has one) is used to roam about
+when the zoom factor is greater than one.  If the magnification is normal
+the numeric keys are not recognized as special keystrokes, i.e., typing
+a numeric key will exit cursor mode, returning the character typed to the
+applications program.  In roam mode a numeric key must be escaped to exit
+cursor mode.  The directional significance of the numeric keys in roam
+mode is obvious if the terminal has a keypad, and is illustrated below.
+
+
+.ks
+.nf
+	7   8   9	135 090 045
+
+	4   5   6	180 000 000
+
+	1   2   3	225 -90 -45
+.fi
+.ke
+
+
+There is a fixed upper limit on the size of the cursor mode frame buffer.
+If the frame data overflows the frame buffer while plotting the plot will
+still come out correctly, but only the final plotting instructions will be
+retained in the buffer.  Redisplay of the frame in cursor mode will thus
+result in only a portion of the full frame being drawn.  If this is a problem
+the user can increase the upper limit on the size of the frame buffer by
+setting the value of the environment variable \fBcmbuflen\fR, e.g.,
+
+	gflush; set cmbuflen = 512000
+
+would initialize the graphics system (freeing the old frame buffer) and set
+the upper limit on the size of the frame buffer to 512K words or 1Mb.
+
+.nh 2
+Example
+
+    At this point a brief example may help to illustrate the use of the GIO
+procedures.  The following procedure will plot a data vector (pixel array)
+and then repeatedly read the cursor, drawing a mark at successive positions
+of the cursor.  The procedure exits if the user types either the character
+'q' or EOF, e.g., <ctrl/z> or carriage return.
+
+
+.ks
+.nf
+	include	<gset.h>
+
+	# MARKPLOT -- Plot a data array and then enter a loop, drawing
+	# circles at successive cursor positions.
+
+	procedure markplot (data, npts, x1, x2)
+
+	real	data[npts]		# data vector to be plotted
+	int	npts			# length of array
+	real	x1, x2			# world X-coords of vector
+
+	pointer	gp
+	int	wcs, key
+	char	str[32]
+	real	wx, wy
+	pointer	gopen()
+	int	clgcur()
+
+	begin
+		gp = gopen ("stdgraph", NEW_FILE, STDGRAPH)
+
+		call gploto (gp, data, npts, x1, x2, "data")
+
+		while (clgcur ("points", wx, wy, wcs, key, str, 32) != EOF)
+		    if (key == 'q')
+			break
+		    else
+			call gmark (gp, wx, wy, GM_CIRCLE, 1., 1.)
+
+		call gclose (gp)
+	end
+.fi
+.ke
+
+.nh 2
+Graphics Output Devices
+
+    While the graphics output device may be specified explicitly by name,
+more often graphics output devices will be specified by one of the logical
+device names shown below.  Examples of the installation dependent device name
+associated with each logical name are also shown.
+
+
+.ks
+.nf
+	stdgraph	= "gterm"
+	stdimage	= "deanza"
+	stdplot		= "qms"
+	stdvdm		= "uparm$vdm"
+.fi
+.ke
+
+
+Interaction (via the CL) is supported only for \fBstdgraph\fR and
+\fBstdimage\fR.  The standard batch plotter device is \fBstdplot\fR,
+and the standard metafile (for spooling graphics output) is \fBstdvdm\fR.
+
+The user should not normally set the value of \fBstdgraph\fR directly with
+\fIset\fR, rather they should set the terminal type with \fIstty\fR and let
+the latter specify the value of \fBstdgraph\fR.  If the terminal specified
+is not a graphics terminal (no ":gd" capability in the termcap entry for the
+device) the value of \fBstdgraph\fR will be set to "none", otherwise
+\fBstdgraph\fR will be set to the name of the stdgraph device entry for the
+graphics terminal.
+
+The device name associated with a logical graphics output
+device must have an associated entry in the \fBgraphcap\fR file,
+a text file used to describe the characteristics of each device.
+New graphcap entries may easily be added by the user to interface to
+special graphics devices.
+System privledge is not required to modify graphcap, since the name
+of the graphcap file is taken from a CL environment variable of the
+same name (which can be redefined by the user to point to a file in a
+private directory).  The graphcap entries for the most commonly used
+devices at a given site may be precompiled by the system manager to
+eliminate the overhead of searching the graphcap file at \fBgopen\fR time.
+
+The graphcap parameters (device \fIcapabilities\fR) are too involved to
+be presented here and will be described in a later section.
+Examples of device capabilities are the device resolution, whether a frame
+advance is required before or after a plot, indication of device capabilities
+such as the ability to generate text, and the name of the executable
+graphics kernel file associated with the device.  Many additional parameters
+are defined for interactive devices.  The graphcap device capabilities
+may be inspected with the \fBgget[birs]\fR procedures, which resolve into
+calls to the TTY interface, used to access both graphcap and termcap files.
+
+The sequence of actions taken by GIO to access the graphcap entry for a
+device is summarized below.
+
+
+.ks
+.nf
+	if (standard graphics output device)
+	    get device name from environment
+
+	if (device name is actually a filename) {
+	    load graphics device descriptor using the first device entry
+		from the named graphcap format file
+	} else {
+	    get filename of graphcap file from environment
+	    load graphics device descriptor by searching the graphcap file
+		for the named device
+	}
+.fi
+.ke
+
+.nh 2
+Graphics Input Devices
+
+    The technique used to associate an input source with a graphics cursor
+is similar to that used for output devices.  A CL environment variable is
+associated with each cursor type.  The names and default values of the
+environment variables are shown below.
+
+
+.ks
+.nf
+	stdgcur		= "stdgraph"
+	stdimcur	= "stdimage"
+.fi
+.ke
+
+
+The default input source for a cursor is the graphics output device associated
+with the graphics output stream.  If the cursor device is "stdgraph" or
+"stdimage" the graphics kernel is called to read the physical device cursor
+for \fIstdgraph\fR or \fIstdimage\fR.  If the cursor device is "text"
+the cursor value is a line of text read from the user terminal.
+In this mode the user enters at least two of the fields defining
+a cursor value.  Missing fields are assigned the value zero (the user
+presumably will know that the program does not use the extra fields).
+
+
+.ks
+.nf
+	cl> set stdgcur = "text"
+	cl> = gcur
+	gcur: 345.33 23.22 1 c
+	345.33 23.22 1 c
+	cl>
+.fi
+.ke
+
+
+An example of a cursor read request entered interactively by the user,
+taking input from the terminal and sending output to the terminal,
+is shown above (the CL typed the "gcur: " query and the user entered the
+remainder of that line).  If the cursor device were "stdgraph" a real
+cursor read would occur and the equivalent interaction might appear as
+shown below.  The cursor position is returned in world coordinates,
+where the world coordinate system was defined by the last plot output to
+the device.  For an imaging device the world coordinates will typically
+be the pixel coordinates of the image section being displayed.
+
+
+.ks
+.nf
+	cl> = gcur
+	345.33 23.22 1 c
+	cl>
+.fi
+.ke
+
+
+Redirecting cursor input to the terminal is useful when working from a
+nongraphics workstation and when debugging programs.  ASCII cursor queries
+are the only type supported when running an IRAF program outside the CL.
+Cursor input may also be taken from a list file by assigning a filename
+to a cursor parameter, i.e., by assigning a list file to a list structured
+parameter and overriding query mode:
+
+
+.ks
+.nf
+	cl> gcur = filename
+	cl> = gcur
+	345.33 23.22 1 c
+	cl>
+.fi
+.ke
+
+
+This last mechanism is a standard technique used with CL list structured
+parameters and will not be discussed further here.
+
+.NH 2
+Mixed Terminal and Graphics I/O
+
+    Interactive graphics programs are normally (but not necessarily) executed
+on a graphics terminal or workstation supporting both ordinary terminal i/o
+and vector graphics.  IRAF is designed to use a single terminal for both text
+and graphics; text and graphics on separate devices is also supported but is
+not the norm.  By text we refer here to ordinary line or screen oriented
+terminal i/o (e.g., for \fIhelp\fR or \fIeparam\fR), not the use of text in
+the graphics plane to annotate plots.
+
+.NH 3
+Text and Graphics Mode
+
+    Most modern graphics terminals provide separate memory planes for text
+and graphics.  Depending upon the device, these planes may be displayed
+simultaneously, displayed alternately, or only a single memory plane may be
+available for both terminal modes, in which case a mode switch is destructive.
+The graphics device model implemented by GIO and the STDGRAPH kernel is
+flexible enough to deal with all or nearly all such devices.
+
+The normal mode for the terminal or workstation is text mode.  Activating the
+workstation causes a switch to graphics mode; deactivating the workstation
+restores the terminal to text mode.  Activation is implied whenever a device
+is opened with \fBgopen\fR, unless the AW_DEFER mode bit is set to defer the
+activate workstation until graphics i/o is actually done to the device.
+Closing the workstation automatically deactivates the workstation.  The GIO
+procedures \fBgreactivate\fR and \fBgdeactivate\fR are provided to simplify
+mode switching while a device is open on a graphics stream.
+
+Occasionally it is necessary to print out a large amount of text in response
+to a user command entered in a cursor loop while in graphics mode.  If the
+text is in a file this is done most easily by calling \fBgpagefile\fR to page
+the file in text mode, restoring graphics mode when the operation is completed.
+If the application generates the output text dynamically then the workstation
+must be explicitly deactivated and later reactivated before resuming graphics
+i/o, e.g.,
+
+.ks
+.nf
+	while (clgcur (gp, ...) != EOF) {
+	    switch (key) {
+	    case XXX:
+		call gdeactivate (gp, AW_CLEAR)
+		    <write the text to STDOUT>
+		call greactivate (gp, AW_PAUSE)
+	    case YYY:
+		...
+	    }
+	}
+.fi
+.ke
+
+The sequence shown will switch to text mode, clear the screen, output the
+text, and pause for the user to read the text before restoring graphics mode
+and initiating another cursor read.
+
+.NH 3
+Status Line I/O
+
+    The deactivate/reactivate workstation technique is fine for outputting
+large amounts of text, but is not well suited for small amounts of text,
+e.g., single line commands to interactively set internal parameters,
+output of single lines of text to prompt the user, print the value of a
+calculation or some variable, and so on.  The so-called "status line"
+interface is provided for this purpose.  Status line i/o makes it possible
+to interact directly with the user without interfering with the contents of
+the graphics frame, and without leaving graphics mode.
+
+What the status line actually is determined by the graphcap entry for the
+device and the characteristics or limitations of the actual device.
+On most devices, the status line is a single line at the bottom of the screen.
+This only works, however, if the device can dynamically erase the status line;
+if this is not possible the status "line" may actually be the entire screen,
+with successive output lines being drawn on top of the graph.
+
+To output text to the status line while in graphics mode one merely writes to
+STDOUT or STDERR in the usual way, e.g., in a call to \fBprintf\fR.  When
+newline is seen a flag is set which causes the status line to be cleared when
+the next output character is received.  Output lines may be built up in
+successive calls to output procedures, outputting a single newline to terminate
+the line and start a new one.  After a newline delimited line of text has been
+output, output of a single newline (blank line) will clear the status line.
+
+It is also possible to read from the status line.  This is most commonly done
+after writing a prompt string to the status line.  The prompt should be
+terminated with a colon (e.g., "enter value: ") rather than a newline,
+to signal to the user that input is expected, and to avoid having the
+subsequent status line read clear the prompt string.  In many cases such
+explicit prompting and decoding of the return string can be avoided by using
+the standard CLIO parameter prompting mechanism for interactive input.
+CL parameter prompts are also permitted in graphics mode, and will interact
+with the user on the status line in the expected way, without interfering
+with the graphics state of the device.
+
+When mixing status line i/o and graphics i/o one must be careful to flush any
+buffered graphics or textual output before switching modes.  In many cases the
+system will do this for you automatically, but there are exceptions where
+explicitly flushing of buffered output is necessary (e.g., STDOUT and STDERR
+are low level facilities with no knowledge of GIO, and output to one of these
+streams will not automatically cause any graphics output to be flushed).
+
+.NH 2
+User Interface Conventions
+
+    While different interactive (cursor driven) graphics programs will differ
+in many ways, there are certain operations which are common to all such
+programs.  In order to present a more consistent interface to the user,
+conventions have been defined for these common operations.
+
+.NH 3
+On Line Help
+
+    All interactive graphics programs should respond to the key '?' with a
+description of the keystrokes and colon commands recognized by the program
+(or submenu, in the case of a menu structured interface).  This is normally
+done by calling \fBgpagefile\fR to interactively page the ".key" keystrokes
+help file for the program.  The keystroke files for system programs are
+stored in the directory lib$scr; non-system programs keep their keys files
+either in the package directory, or in a global package library.
+
+.NH 3
+Cursor and Device Names
+
+    In general, applications programs should not read directly from \fBgcur\fR
+or \fBimcur\fR (the global cursor parameters), nor should the open the
+"stdgraph", "stdimage", or "stdplot" device directly by these explicit string
+values.  This works, but is inflexible.  To make it easy for the user to
+run an otherwise interactive program in batch mode, taking input from a cursor
+list file, the task should include a cursor type parameter in its parameter
+set.  Likewise, to make it easy for the user to temporarily redirect the
+output of the program to a device other than the current stdgraph, stdplot,
+etc., device, the device name should be parameterized as a string type CL
+parameter.
+
+For example, if task \fBplotit\fR  has cursor and device parameters named
+"cursor" and "device", the command
+
+	cl> plotit cursor=listfile device=qms
+
+would run the task taking cursor input from the text file "listfile", with
+stdgraph graphics output directed to the plotter device "qms".
+
+.NH 3
+Exiting an Interactive Cursor Loop
+
+    The following standards have been defined for dealing with EOF/quit in
+interactive cursor loops.
+.ls
+.ls EOF	
+End of file is indicated for a cursor list either by an actual
+end of file in the case of a true cursor list, or by typing the EOF character
+(e.g., <ctrl/z>, <ctrl/d>, or the interrupt character) in an interactive
+cursor read.  EOF on the cursor list should be taken seriously by the
+applications program, and not treated as just another key, hence it should
+not be something that the user is expected to type routinely to exit a cursor
+loop.  If a program gets EOF back as the value of \fBclgcur\fR it should exit
+immediately, without any verification queries etc, since it may well have
+been run in batch mode with input redirected to a cursor list file.
+.le
+.ls q
+The standard interactive cursor loop exit character is 'q'.  
+All interactive graphics programs should recognize this character
+and take some action to exit the cursor loop, e.g.:
+
+.ks
+.nf
+	while (clgcur (...) != EOF)
+	    switch (key) {
+	    case 'q':
+		break
+	    case ...
+.fi
+.ke
+
+The 'q' character is intended to be handled directly by the application
+program, rather than mapped into EOF by the system (like Q was, and CR and
+the gt_gcur 'q' before that in old versions of IRAF),
+to distinguish this case from a hard-EOF and to provide maximum
+flexibility in how the program treats a request from the user to exit.
+If the user would suffer from an accidental program exit then the 'q' key
+action should do something before exiting, e.g., ask that the user first
+update the database, ask that CR be hit to verify the quit, and so on.
+In general, if it would take the user more than a minute to recover after
+an accidental program exit, one should consider coding some sort of
+verification action to be executed before exiting when 'q' is typed (but not
+when EOF is seen on the list).
+.le
+.le
+
+The GIO procedure \fBgqverify\fR is provided for programming convenience in
+cases where only simple verification is desired.  Note that lightweight tasks
+or submenus which can easily be reentered should not bother even with this,
+but should simply exit.  For example:
+
+.ks
+.nf
+	case 'q':
+	    if (gqverify() == YES)
+		break
+.fi
+.ke
+
+As a more complex example, suppose the program is used to edit or
+create a database which could be lost or damaged in an accidental
+exit, if not updated first.  We do not want to update the database
+automatically because this would overwrite the former contents of
+the database.  The program might be set up as follows.
+
+.ks
+.nf
+	'q'		program prints error message on status line, e.g.,
+			  "No write since last change (:quit! overrides)"
+	:w[rite]	updates the database; q will execute silently
+	:q[uit]!	force a quit w/o an update; discard changes
+.fi
+.ke
+
+.nh 2
+Detailed Procedure Specifications
+
+    The graphics output procedures provided by GIO fall into four main
+groups.  First are the high level "plot at a time" procedures,
+used to plot entire data vectors.  Second are the control procedures,
+used to open and close a device, to flush output and clear the screen,
+and to cancel output in the event of an interrupt.
+Third are the procedures used to set and stat (inquire) the GIO
+internal parameters, e.g. to define a WCS, change pens, select axis labeling
+options, or inquire the device resolution.  Fourth and last are the output
+procedures, used to draw and label the axes of a viewport, set the cursor,
+draw lines or marks, plot text, or fill areas.
+
+.nh 3
+High Level Procedures
+.ls 4
+.tp 8
+.ls gplotv (v, npts, x1, x2, title)
+
+.nf
+real	v[npts]		# data vector
+int	npts		# number of data points
+real	x1, x2		# WC assigned v[1] and v[npts]
+char	title[ARB]	# plot title
+.fi
+
+Open GIO, clear the screen, autoscale and plot the data vector, then close GIO.
+A default viewport is used.  The axes are drawn, tick marks are selected,
+marked, and labeled, and the plot title is printed.  The data is plotted
+using solid line segments.  The X values of the data points are evenly
+distributed from X1 to X2.
+.le
+
+.tp 8
+.ls gploto (gp, v, npts, x1, x2, title)
+
+.nf
+pointer	gp		# graphics descriptor
+real	v[npts]		# data vector
+int	npts		# number of data points
+real	x1, x2		# WC assigned v[1] and v[npts]
+char	title[ARB]	# plot title
+.fi
+
+A more flexible version of \fBgplotv\fR.  The graphics device must already
+have been opened with an explicit call to \fBgopen\fR.  The explicit open
+call makes it possible to append to an existing plot or to change plotting
+options with calls to \fBgset\fR before calling \fBgploto\fR to autoscale,
+draw the axes, and plot the data vector.  Annotation of the plot via calls
+to the low level output primitives is possible before a final call to
+\fBgclose\fR to close the device and free the graphics descriptor.
+.le
+
+.tp 8
+.ls gpagefile (gp, fname, prompt)
+
+.nf
+pointer	gp		# graphics descriptor
+char	fname[ARB]	# file to be paged
+char	prompt[ARB]	# end of page prompt string
+.fi
+
+Interactively page through a file on the terminal in text mode, e.g., to
+display help text in response to the '?' standard help query key.
+The workstation is deactivated, the screen is cleared and the file is paged,
+with the usual file pager prompt being displayed at the bottom of each page
+of text.  When the pager is exited the workstation is reactivated if it was
+active when the pager was called.  If the prompt string is null the file
+name is used.
+.le
+.le
+
+.nh 3
+Control Procedures
+.ls
+.tp 8
+.ls gopen (device, mode, fd)
+
+.nf
+char	device[ARB]	# name of device to be opened
+int	mode		# access mode
+int	fd		# graphics stream to be written
+.fi
+
+The named graphics device is opened for graphics i/o.  A pointer to the GIO
+graphics descriptor assigned to the device is returned as the function value.
+The device name may be the name of one of the standard logical graphics
+devices, i.e., \fBstdgraph\fR, \fBstdimage\fR, \fBstdplot\fR, or \fBstdvdm\fR,
+or the actual name of a physical device.
+
+The only meaningful device access modes at present are NEW_FILE and APPEND.
+In NEW_FILE mode all WCS are initialized to NDC coordinates.
+Opening the stdgraph device in NEW_FILE mode causes a screen clear on the next
+call to \fIgflush\fR.  In APPEND mode the WCS are restored to the values they
+had when the device was last accessed.
+The GIO internal state variables are initialized to their default values
+at \fBgopen\fR time regardless of the access mode for the device.
+
+Opening the stdgraph device causes an implicit reactivate workstation unless
+the AW_DEFER flag (<gset.h>) is set in the access mode, e.g.,
+
+	gp = gopen (device, NEW_FILE+AW_DEFER, fd)
+
+Defer mode allows the graphics descriptor to be opened once, e.g., during task
+startup, before any graphics output is required.  This is sometimes useful in
+applications which switch back and forth between text and graphics mode often,
+by bracketing each graphics sequence with calls to \fIgreactivate\fR to enter
+graphics mode, and \fIgdeactivate\fR to return to text mode.  Defer mode may
+be combined with any normal access mode code.
+
+Graphics output will be written to the stream \fIfd\fR, which may be one
+of the standard streams STDGRAPH, STDIMAGE, or STDPLOT, or to a binary file
+opened explicitly by the user before calling \fBgopen\fR.
+.le
+
+.tp 5
+.ls gclose (gp)
+
+The graphics device associated with graphics descriptor \fBgp\fR is closed,
+freeing all resources allocated to the device.  Any buffered graphics output
+is automatically flushed before closing the device.
+.le
+
+.tp 4
+.ls gdeactivate (gp, flags)
+
+.nf
+pointer	gp		# graphics descriptor
+int	flags		# AW_CLEAR, AW_PAUSE (see <gset.h>)
+.fi
+
+The graphics workstation is deactivated, i.e., restored to the normal terminal
+(text drawing) mode, the state the terminal was in prior to \fIgopen\fR, and to
+which it will be restored after a \fIgclose\fR.  This function is intended for
+interactive graphics applications and may be may be ignored by some graphics
+kernels.  If the AW_PAUSE flag bit is set the user will be asked to type a
+key before the terminal is restored to text mode.  If the AW_CLEAR flag bit
+is set the terminal (text) screen will be cleared after the workstation is
+deactivated.
+
+.le
+
+.tp 4
+.ls greactivate (gp, flags)
+
+.nf
+pointer	gp		# graphics descriptor
+int	flags		# AW_CLEAR, AW_PAUSE (see <gset.h>)
+.fi
+
+The graphics workstation is reactivated, i.e., restored to graphics mode from
+the normal terminal (text drawing) mode.  This function is intended for
+interactive graphics applications and may be may be ignored by some graphics
+kernels.  If the AW_PAUSE flag bit is set the user will be asked to type a
+key before the terminal is restored to graphics mode.  If the AW_CLEAR flag
+bit is set the graphics frame will be cleared.
+.le
+
+.tp 4
+.ls gcancel (gp)
+
+Any buffered graphics output is discarded and any output operation currently
+in progress is aborted.  Used to recover from an interrupt.
+.le
+
+.tp 3
+.ls gflush (gp)
+
+Any buffered graphics output is flushed to the output device.
+.le
+
+.tp 4
+.ls gclear (gp)
+
+If the output device is a CRT the screen is erased (including all viewports).
+If the output device is a plotter a formfeed is issued, advancing to the next
+page of output (whether or not any graphics output has occurred).
+All WCS are initialized to NDC coordinates and the internal state of GIO
+is initialized, i.e., the state of each drawing instruction attribute packet
+is set to UNSET to force retransmission to the graphics kernel as i/o occurs,
+and the current settings of the \fIgset\fR options, e.g., line style and width,
+\fIglabax\fR options, etc., are all initialized to their default (\fBgopen\fR)
+values.
+.le
+
+.tp 4
+.ls gframe (gp)
+
+Issue a screen clear or frame advance.  This call is equivalent to \fBgclear\fR
+except that the internal state of GIO is not initialized.  An application
+might want to call \fBgframe\fR and \fBgreset\fR directly rather than using
+\fBgclear\fR, if the full initialization implied by \fBgclear\fR is not what
+is desired.
+.le
+
+.tp 4
+.ls greset (gp, flags)
+
+.nf
+pointer	gp		# graphics descriptor
+int	flags		# bitflags noting what to reset (0 is a no-op)
+.fi
+
+The \fBgreset\fR may be used to reset all or parts of the internal state of
+GIO, without actually doing any i/o to the graphics device.  The \fIflags\fR
+argument is used to specify what is to be reset.  The bitflags (defined in
+<gset.h>) are enumerated below.
+
+.nf
+	GR_RESETALL		reset everything
+	GR_RESETGIO		reset only GIO drawing parameters
+	GR_RESETWCS		reset the WCS to wcs=1, all NDC
+	GR_RESETGLABAX		reset the GLABAX parameters
+.fi
+
+A \fBgclear\fR is equivalent to a \fBgframe\fR followed by a
+greset(gp,GR_RESETALL).
+.le
+
+.tp 8
+.ls gmftitle (gp, mftitle)
+
+.nf
+pointer	gp		# graphics descriptor
+char	mftitle[ARB]	# comment (metafile title string)
+.fi
+
+Place a comment describing the graphics being generated in the output
+stream.  Useful primarily when the output is expected to be saved in a
+metafile.  No graphics is generated.
+.le
+.le
+
+.nh 3
+Set and Stat Procedures
+.ls
+.tp 8
+.ls gscan (gp, text)  [NOT YET IMPLEMENTED]
+
+.nf
+pointer	gp		# graphics descriptor
+char	text[ARB]	# graphics commands
+.fi
+
+The string \fBtext\fR, consisting of an arbitrary length sequence of
+printable ASCII graphics commands delimited by semicolons or newlines,
+is interpreted and executed by GIO.  Each GIO procedure has a corresponding
+command of the same syntax, minus the parenthesis, commas, and the argument
+\fBgp\fR.  The syntax of a \fBgset\fR command is "param=value".
+File inclusion is provided by the operator "@" followed by the filename
+of the file to be included.
+The include operator may appear anywhere a token is expected and includes
+may be nested up to some maximum depth.
+The sequence "@STDIN" is especially useful for entering commands or data
+interactively.
+.le
+
+.tp 8
+.ls gset[irs] (gp, param, value)
+
+.nf
+pointer	gp		# graphics descriptor
+int	param		# parameter to be set
+[irs]	value		# new value for parameter
+.fi
+
+Set the value of the indicated parameter.  A separate procedure is used for
+integer, real, and string valued parameters, i.e., gseti, gsetr, gsets.
+GIO parameters may be either internal state variables (e.g. the number of
+ticks on an axis) or device parameters (e.g. the number of the pen to be
+used to draw lines).
+The GIO parameters are defined in the global include file \fB<gset.h>\fR.
+.le
+
+.tp 10
+.sp
+.nf
+gstati (gp, param)
+gstatr (gp, param)
+gstats (gp, param, outstr, maxch)
+.fi
+.ls
+.nf
+pointer	gp		# graphics descriptor
+int	param		# parameter to be set
+char	outstr[maxch]	# output string
+.fi
+
+Inquire the value of the indicated GIO internal parameter.
+The integer and real functions \fBgstati\fR and \fBgstatr\fR return
+the parameter value as the function value, whereas \fBgstats\fR is
+a procedure returning the string value of a parameter as an output argument.
+The GIO parameters are defined in the global include file \fB<gset.h>\fR.
+.le
+
+.tp 11
+.sp
+.nf
+ggetb (gp, cap)
+ggeti (gp, cap)
+ggetr (gp, cap)
+ggets (gp, cap, outstr, maxch)
+.fi
+.ls
+.nf
+pointer	gp		# graphics descriptor
+char	cap[2]		# device capability
+char	outstr[maxch]	# output string
+.fi
+
+Inquire the value of the indicated graphics device capability.
+The device capability \fIcap\fR is the two character name of the capability
+as it appears in the \fIgraphcap\fR file.  Aside from the device capabilities
+required by GIO, GIO itself knows nothing about the graphcap device
+capabilities.  New capabilities may be added without modifying GIO.
+The \fBgget\fR procedures call the corresponding procedures in the TTY
+interface.  If more control over device capabilities is required than
+that provided by GIO, the TTY interface may be used directly, following a
+call to \fBgstati\fR to get the pointer to the TTY descriptor for the device.
+
+The boolean function \fBggetb\fR tests whether the device has the named
+capability.  The integer and real functions \fBggeti\fR and \fBggetr\fR return
+the capability value as the function value, or zero if the capability is
+not defined for the device.  String valued capabilities are returned by
+\fBggets\fR as an output argument; the null string is returned if the
+device does not have the indicated capability.
+.le
+
+.tp 8
+.ls g[sg]view (gp, x1, x2, y1, y2)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x1, x2		# range of NDC coordinates in X
+real	y1, y2		# range of NDC coordinates in Y
+.fi
+
+Set or get the NDC coordinates of the viewport associated with the current WCS.
+The default viewport is the full display area of the device.
+.le
+
+.tp 8
+.ls g[sg]wind (gp, x1, x2, y1, y2)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x1, x2		# range of world coordinates in X
+real	y1, y2		# range of world coordinates in Y
+.fi
+
+Set or get the world coordinates of the window associated with the current WCS.
+The default window ranges from 0 to 1 in both X and Y, i.e., the default
+window associates a normalized coordinate system with the associated viewport.
+Any window limits passed as INDEF will be ignored, i.e., those window
+parameters will not be modified.
+.le
+
+.tp 9
+.ls g[ar]scale (gp, v, npts, axis)
+
+.nf
+pointer	gp		# graphics descriptor
+real	v[npts]		# data vector window is to be scaled to
+int	npts		# length of data vector
+int	axis		# axis to be scaled (1=X, 2=Y).
+.fi
+
+Set absolute (\fIgascale\fR) or rescale (\fBgrscale\fR) the minimum and
+maximum world coordinates of the indicated axis of the current window,
+i.e., scale the window to fit a data vector.
+May be called repeatedly if overplotting several curves.  The current minimum
+and maximum values for either axis may be obtained at any time by calling
+\fBggwind\fR.  To scale the window to fit a family of curves,
+call \fBgascale\fR for the first curve and \fBgrscale\fR for the remaining
+curves, thereby computing the range in X and or Y of all curves.
+.le
+
+.tp 9
+.ls ggscale (gp, x, y, dx, dy)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# point at which scale is desired (wc)
+real	dx, dy		# scale, wcs units per ndc unit
+.fi
+
+Determine the scale in world coordinate units at the point (x,y).  Useful
+for computing the size of an object in world coordinates given its size
+in ndc coordinates, or vice versa.  An approximation is used to determine
+the scale if log scaling is in use.  Note that the scale is a function of
+position for the nonlinear coordinate systems.
+.le
+
+.tp 9
+.ls gctran (gp, x1, y1, x2, y2, wcs1, wcs2)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x1, y1		# input point in WCS1 coords
+real	x2, y2		# output point in WCS2 coords
+int	wcs1, wcs2	# input, output world coordinate systems
+.fi
+
+Transform a point in world coordinate system \fIwcs1\fR to world coordinate
+system \fIwcs2\fR.  If \fIwcs1\fR is zero the transformation is from NDC
+coordinates to WCS coordinates.  If \fIwcs2\fR is zero the transformation is
+from WCS coordinates to NDC coordinates.  Otherwise the transformation is
+between two user defined world coordinate systems.  The point need not fall
+within the viewports of the two world coordinate systems.  World coordinate
+systems which were never set are equivalent to WCS=0.
+.le
+
+.tp 9
+.ls gcurpos (gp, x, y)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# current pen position in world coordinates
+.fi
+
+Return the "current pen position" in the current world coordinate system.
+The current pen position is the position set by the last move or draw
+command.
+.le
+
+.tp 10
+.ls gescape (gp, fn, instruction, nwords)
+
+.nf
+pointer	gp		# graphics descriptor
+int	fn		# function code
+short	instruction[nwords]	# instruction sequence to be passed
+int	nwords		# length of instruction sequence
+.fi
+
+Send a device dependent instruction sequence to the graphics kernel.
+Escape functions are ignored by GIO and by graphics kernels that do
+not recognize the function code.
+.le
+.le
+
+.nh 3
+Output Procedures
+
+    Data passed to the polyline or polymarker output procedures may contain
+embedded INDEF (indefinite) values in the X, Y, or V arrays.  Indefinite valued
+points appear as gaps in the plot and are ignored when autoscaling.
+Indefinite valued pixels are not permitted in a cell array since GIO does
+not look at the values of the pixels.
+
+.ls
+.tp 9
+.ls glabax (gp, title, xlabel, ylabel)
+
+.nf
+pointer	gp		# graphics descriptor
+char	title[ARB]	# plot title
+char	xlabel[ARB]	# X axis label
+char	ylabel[ARB]	# Y axis label
+.fi
+
+Draw and label the axes of the viewport.
+If the WCS has not yet been fixed it will be fixed by this call.
+If desired, \fBglabax\fR may modify the window slightly to place
+simple values on the tick marks.  Numerous \fBgset\fR options are
+available for controlling the number and sizes of the tick marks,
+the format of tick labels, the axes on which tick labels appear,
+and so on.  If the device viewport has not yet been set and axis labeling
+is enabled, \fBglabax\fR will set a default size viewport which allows room
+for the label text outside the viewport.
+.le
+
+.tp 8
+.ls gline (gp, x1, y1, x2, y2)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x1, y1		# start of line
+real	x2, y2		# end of line
+.fi
+
+Draw a line connecting the point (x1,y1) to the point (x2,y2) (WCS coordinates).
+The linetype, linewidth, and color may be changed beforehand with a call
+to \fBgset\fR.  The relevant parameters and their possible values are shown
+below.  Linetype zero (clear) may be used to erase lines drawn with any of the
+other linetypes (device permitting).
+
+.ks
+.nf
+	G_PLTYPE	0=clear, 1=solid, 2=dashed, 3=dotted,
+			    4=dotdash, >4=device dependent
+	G_PLWIDTH	relative line width (default 1.0)
+	G_PLCOLOR	color index
+.fi
+.ke
+.le
+
+.tp 8
+.ls gpline (gp, x, y, npts)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x[npts]		# X coordinates of the line endpoints
+real	y[npts]		# Y coordinates of the line endpoints
+int	npts		# number of line endpoints
+.fi
+
+Polyline.  Draw a line connecting the points (WCS coordinates).
+The linetype, linewidth, and color may be changed beforehand with a call
+to \fBgset\fR.
+.le
+
+.tp 8
+.ls gvline (gp, v, npts, x1, x2)
+
+.nf
+pointer	gp		# graphics descriptor
+real	v[npts]		# vector to be plotted (Y values)
+int	npts		# number of line endpoints
+real	x1, x2		# range of vector in X 
+.fi
+
+Vector polyline.  Draw a polyline wherein the Y values of the polyline are
+taken from V and the X values are evenly distributed along the X-axis,
+ranging from X1 at point V[1] to X2 at point V[npts] (WCS coordinates).
+.le
+
+.tp 9
+.ls gmark (gp, x, y, marktype, xsize, ysize)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# WCS coordinates of marker
+int	marktype	# marker type
+real	xsize, ysize	# marker sizes
+.fi
+
+Mark drawing primitive.  Draw a mark of type \fImarktype\fR and size
+\fImarksize\fR at the given position in WCS coordinates.
+The marker type codes recognized are shown below and are defined in <gset.h>.
+Marktype codes may be summed to make composite marks, e.g.,
+
+	call gmark (gp, x, y, GM_PLUS+GM_CROSS, 1.)
+
+is an asterisk.  The pseudo-mark GM_FILL may be combined with GM_CIRCLE,
+GM_BOX, or GM_DIAMOND to output the mark as a filled area, using the current
+fill area attributes.  A positive \fImarksize\fR specifies the mark size in NDC
+coordinates, whereas negative signifies WCS coordinates.
+The positive marksizes 1., 2., 3., and 4. signify default size marks of
+increasing size.
+
+.ks
+.nf
+    typecode      name                symbol
+
+	0 	GM_POINT	smallest plottable point
+        1	GM_FILL		fill interior of mark
+	2	GM_BOX		square box
+        4	GM_PLUS		plus
+	8	GM_CROSS	cross
+       16	GM_DIAMOND	diamond
+       32	GM_HLINE	horizontal line
+       64	GM_VLINE	vertical line
+      128	GM_HEBAR	horizontal error bar
+      256	GM_VEBAR	vertical error bar
+      512	GM_CIRCLE	circle
+.fi
+.ke
+
+The linetype for a mark is set by the parameter G_PMLTYPE.  A mark may
+be erased (device permitting) by setting the marker linetype to clear and
+redrawing the mark.  The color index used for marks is controlled by the
+\fBgset\fR parameter G_PMCOLOR.
+.le
+
+.tp 9
+.ls gpmark (gp, x, y, npts, marktype, xsize, ysize)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x[npts]		# WCS X coordinates of markers
+real	y[npts]		# WCS Y coordinates of markers
+int	npts		# number of markers
+int	marktype	# marker type
+real	xsize, ysize	# marker sizes
+.fi
+
+Polymarker.  Plot a sequence of \fInpts\fR markers at the positions given
+by successive WCS coordinate pairs (x[i],y[i]).  All markers will be of
+the same type and size.  The significance of the marker type and size codes
+is the same as for \fBgmark\fR.
+.le
+
+.tp 9
+.ls gvmark (gp, v, npts, x1, x2, marktype, xsize, ysize)
+
+.nf
+pointer	gp		# graphics descriptor
+real	v[npts]		# WCS Y coordinates of markers
+int	npts		# number of markers
+real	x1, x2		# range of WCS X coordinates
+int	marktype	# marker type
+real	xsize, ysize	# marker sizes
+.fi
+
+Vector polymarker.  Plot a sequence of \fInpts\fR markers at the positions given
+by successive WCS coordinate pairs (x[i],y[i]), where the x[i] are evenly
+distributed from X1 at V[1] to X2 at V[npts].  All markers will be of the same
+type and size.  The significance of the marker type and size codes is the same
+as for \fBgmark\fR.
+.le
+
+.tp 11
+.ls gumark (gp, x, y, npts, xcen, ycen, xsize, ysize, fill)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x[npts],y[npts]	# normalized polyline defining marker
+int	npts		# number of points in polyline
+real	xcen, xcen	# world coordinates of center of marker
+real	xsize, ysize	# marker size in X and Y
+int	fill		# draw mark using area fill
+.fi
+
+Draw a user defined marker.  The marker is defined by the polyline (X[i],Y[i]),
+normalized to the unit square.  The marker polyline is scaled to fit the
+window defined by \fIxcen\fR, \fIycen\fR, \fIxsize\fR, and \fIysize\fR,
+where the center is always defined in world coordinates but the marker sizes
+may be defined in any of a number of ways (see \fBgmark\fR).  If \fIfill\fR
+is YES the marker will be drawn using area fill rather than as a polyline.
+.le
+
+.tp 8
+.ls g[ar]move (gp, x, y)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# WCS coordinates to move or shift
+.fi
+
+Move absolute (\fBgamove\fR) or move relative (\fBgrmove\fR),
+with the "pen up".  A move relative should be preceded by a move absolute
+to unambiguously define the "current pen position" in WCS coordinates.
+Only the move, draw, and mark primitives leave the pen in a defined position.
+Calls to \fBgset\fR may be intermixed with move and draw commands without
+affecting the current pen position.
+.le
+
+.tp 8
+.ls g[ar]draw (gp, x, y)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# WCS coordinates to move or shift
+.fi
+
+Move absolute (\fBgadraw\fR) or move relative (\fBgrdraw\fR),
+with the "pen down".  Draws a line segment.
+The type of line drawn (linetype or "pen number") defaults to solid but
+may be changed beforehand with a call to \fBgset\fR.
+Calls to \fBgset\fR may be intermixed with move and draw commands without
+affecting the current pen position.
+.le
+
+.tp 9
+.ls gtext (gp, x, y, text, format)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# WCS coordinates of text string
+char	text[ARB]	# text to be plotted
+char	format[ARB]	# text characteristics
+.fi
+
+Plot the string \fItext\fR at the position (x,y) in WCS coordinates.
+The default size, orientation, and justification of the generated string 
+may be set by a prior call to \fBgset\fR or overridden for the duration
+of the current call by the \fIformat\fR string.  A null format string
+is permtted.
+
+
+.ks
+.nf
+          keyword               values                 default
+
+        up	        degrees ccw, zero = +x          90
+        size            character size scale factor	1.0
+        path	        left,right,up,down              r
+        hjustify        normal,center,left,right	l
+        vjustify        normal,center,top,bottom        b
+	font		roman,greek,italic,bold		r
+	quality		normal,low,medium,high		n
+	color		integers greater than one	1
+.fi
+.ke
+
+
+The attributes controlling how text is generated are shown above.
+The character up vector (attribute \fIup\fR) defines the horizontal and
+vertical axes (the horizontal axis is perpendicular to the character up
+vector).  Directions left and right, up and down are relative to these axes.
+The attribute \fIpath\fR defines the direction in which characters are
+to be plotted.  The attribute \fBquality\fR makes it possible to choose
+between low or medium quality (fast) and high quality (expensive) character
+generation techniques, e.g., hardware versus software character generation.
+This attribute is normally best set to "normal" and then overridden at
+metafile translation time.
+
+The attributes are set in the format string by a semicolon delimited list of
+keyword=value constructs.  Only the first character of keyword and value
+strings is significant, i.e., keywords and values may be abbreviated to as
+little as one character if desired.  For example, the format "p=d;v=c"
+would plot characters downward in a vertical string centered at the position
+given.
+
+The default font is set by the font attribute at the beginning of each call.
+Font changes may also be signaled by placing the sequence "\fF" in the text,
+where F is one of the characters RGIB, denoting the fonts roman, greek,
+italic, and bold.  In this manner the font may change from character
+to character within a single line of text.  Additional escape sequences may
+be added to represent special symbols.
+.le
+
+.tp 10
+.ls gfill (gp, x, y, npts, style)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x[npts]		# X coordinates of polygon
+real	y[npts]		# Y coordinates of polygon
+int	npts		# number of vertices of polygon
+int	style		# type of fill
+.fi
+
+Area fill.  The points (x[i],y[i]) define a closed area which will be filled
+in the indicated \fIstyle\fR.  The recognized style codes, defined in <gset.h>,
+are:
+
+.ks
+.nf
+	0	GF_CLEAR	clear area
+	1	GF_HOLLOW	draw only outline of area
+	2	GF_SOLID	fill area with a color
+       3-6	GF_HATCH[1234]	fill area with a pattern
+       7-N			device dependent
+.fi
+.ke
+
+If the device can support multiple colors the color index for area fill may
+be set beforehand with a call to \fBgset\fR to set the parameter G_FILLCOLOR.
+.le
+
+.tp 10
+.ls gpcell (gp, m, nx, ny, x1, y1, x2, y2)
+
+.nf
+pointer	gp		# graphics descriptor
+short	m[nx,ny]	# greylevels or colors (pixels)
+int	nx, ny		# number of pixels in X and Y
+real	x1, y1		# lower left corner of output area
+real	x2, y2		# upper right corner of output area
+.fi
+
+Output a cell array.
+Map each pixel in the input array into the corresponding area
+of the output device.  For maximum efficiency the resolution of M should
+match that of the area of the output device defined by the window (x1,y1)
+and (x2,y2), otherwise M is subsampled or replicated to best fill the output
+area.  The aspect ratio of a pixel need not be preserved in the mapping.
+The pixel values (greylevels or color indices) are passed on to the kernel
+without modification.
+.le
+
+.tp 7
+.ls gscur (gp, x, y)
+
+.nf
+pointer	gp		# graphics descriptor
+real	x, y		# new cursor position
+.fi
+
+Move the device cursor to the indicated position (WCS coordinates).
+.le
+.le
+
+.nh 3
+Input Procedures
+
+    Input procedures are available for cursor and pixel input.  Inquiry of GIO
+parameters and device capabilities is handled by the \fBgstat\fR and \fBgget\fR
+procedures and is not considered graphics input.
+
+.ls
+.tp 8
+.ls clgcur (param, wx, wy, wcs, key, strval, maxch)
+
+.nf
+char	param[ARB]	# CL parameter to be input
+real	wx, wy		# world coordinates of cursor event
+int	wcs		# index of WCS selected
+int	key		# keystroke value of cursor event
+char	strval[maxch]	# string value if set option (key = ':')
+int	maxch		# max chars to be returned in strval
+.fi
+
+The next value of the list structured CL cursor type parameter \fIparam\fR
+is read and the cursor coordinates in WCS units are decoded and returned
+as output arguments, along with the WCS number and the keystroke value,
+i.e., the character typed by the user causing the cursor to be read.
+The range of keystroke values is the full ASCII character set, minus a system
+dependent subset of control codes (if a physical cursor is read, the read is
+always terminated by the user typing a key on the user terminal).
+No GIO device need be open to read the cursor.  EOF is returned as the
+function value when the end of the cursor list is reached.
+The number of output arguments successfully decoded is returned as the
+function value for a normal read.  Values not converted are set to zero.
+.le
+
+.tp 8
+.ls ggcur (gp, sx, sy, key)
+
+.nf
+pointer	gp		# graphics descriptor
+real	sx, sy		# NDC coordinates of cursor event
+int	key		# keystroke value of cursor event
+.fi
+
+The physical cursor of the graphics device associated with graphics
+descriptor \fIgp\fR is read and the cursor coordinates in NDC units are
+returned as output arguments, along with the keystroke value, i.e.,
+the character typed or button pushed causing the cursor to be read.
+On many devices the cursor read will be instantaneous (the cursor position
+will be sampled), and the keystroke value will always be zero.  The range
+of possible keystroke values is device dependent.  EOF is returned as the
+function value when the end of the cursor list is reached.  An error action
+is taken if the device is not readable.  The GIO device must have previously
+been opened with \fBgopen\fR.
+
+Use of this low level procedure is not recommended since it forces a program
+to be used interactively, operation is device dependent, and cursor mode
+interaction is not supported.  The main uses for \fBggcur\fR are cursor input
+from special graphics devices, i.e., devices other than \fBstdgraph\fR or
+\fBstdimage\fR, and continuous sampling of the cursor position on devices
+which support it.  The characteristics of the device cursors are described
+in the graphcap entry for the device.
+.le
+
+.tp 10
+.ls ggcell (gp, m, nx, ny, x1, y1, x2, y2)
+
+.nf
+pointer	gp		# graphics descriptor
+short	m[nx,ny]	# output pixel array
+int	nx, ny		# number of pixels out in X and Y
+real	x1, y1		# lower left corner of input area
+real	x2, y2		# upper right corner of input area
+.fi
+
+Input a cell array.  The cell array defined by the rectangular window
+from point (x1,y1) to (x2,y2) is read into the output array M of size
+NX columns by NY lines.
+For maximum efficiency the resolution of the output array should match
+that of the device area defined by the input window.
+If the resolution of the output array does not match that of the device
+output lines will be subsampled or replicated to best fit the output array.
+Unaddressable pixels are returned as negative values.  An error action is
+taken if the device is not readable.
+.le
+.le
+
+.nh 2
+GIO Internal Parameters
+
+    The GIO internal parameters may be set with either a \fBgset\fR or
+\fBgscan\fR call, and inspected with a \fBgstat\fR function call.
+Parameters are identified to \fBgset\fR and \fBgscan\fR by an integer
+code.  Each integer code is assigned a symbolic name of the form G_PARAM
+in the include file <gset.h>.  In input to \fBgscan\fR, parameters are
+referred to by name in lower case, without the "g_" prefix.  The parameters
+and their default values are shown below.
+
+
+.tp 5
+.nf
+        \fBparameter     default            description\fR
+
+	wcs		1	index of current WCS
+	xtran		linear	linear, log, or nlog (WCS attribute)
+	ytran		linear	linear, log, or nlog (WCS attribute)
+	clip		yes	clip at viewport boundary (WCS attribute)
+	cursor		1	current cursor number
+	pltype		1	polyline linetype
+	plwidth		1.0	polyline relative line width
+	plcolor		1	polyline color index
+	pmltype		1	polymarker linetype
+	pmcolor		1	polymarker color index
+	szmarker[1-4] (.5:2)*ch	standard marker sizes, NDC coordinates
+	fastyle		1	fill area interior style
+	facolor		1	fill area color index
+	txsize		1.0	relative character size
+	txup		90	character up vector
+	txpath		right	direction in which characters are drawn
+	txspacing	0.0	character spacing relative to height
+	txhjustify	left	horizontal justification (n,c,l,r)
+	txvjustify	bottom	vertical justification (n,c,t,b)
+	txfont		roman	text font (roman,greek,italic,bold)
+	txquality	normal	text generator precision (n,l,m,h)
+	txcolor		1	text color index
+.fi
+
+.tp 9
+.nf
+	    (axis labeling parameters)
+
+	drawtitle	yes	draw plot title if given
+	titlesize	1.0	character size for plot title
+	titlejust	center	horizontal justification of title
+	ntitlelines	1	number of lines in title block
+	aspect		0.0	aspect ratio of viewport (0=dontcare)	
+
+	    (the following are duplicated for the Y axis)
+
+	xdrawaxes	3	draw X axis 1, 2, both (3), none (0)
+	xsetaxispos	no	set world coords of X axes
+	xaxispos1	0.0	world coord of X axis 1 (default wx1)
+	xaxispos2	0.0	world coord of X axis 2 (default wx2)
+	xdrawgrid	yes	draw grid marks connecting X ticks
+	xround		no	extend WCS to end at a tick mark
+	xlabelaxis	yes	draw axis label string if given
+	xaxislabelsize	1.0	character size for X axis label
+	xdrawticks	yes	draw and label X ticks
+	xlabelticks	yes	label X ticks
+	xnmajor		6	number of major ticks in X
+	xnminor		4	number of minor ticks in X
+	xmajorlength	0.8ch	length of a major tick, X
+	xminorlength	0.4ch	length of a minor tick, X
+	xmajorwidth	1.0	linewidth of a major tick, X
+	xminorwidth	1.0	linewidth of a minor tick, X
+	xaxiswidth	1.0	linewidth of the axis
+	xticklabelsize	1.0	character size for X tick labels
+	xtickformat	""	override format for X tick labels
+.fi
+
+.tp 4
+.nf
+	    (read only variables)
+
+	tty		-	pointer to TTY graphcap descriptor
+	fd		-	file descriptor of output stream
+	devname		-	device name as passed to gopen
+.fi
+
+
+The Y axis parameters have names equivalent to those shown with the
+X prefix replaced by a Y.  If the prefix is omitted entirely then the
+parameters for both axes will be set or queried.
+The \fBglabax\fR code and parameters are built upon the GIO graphics
+primitives and may be replaced by a more sophisticated user program
+if desired.
+
+Drawing and labeling of the X and Y axes is parameterized independently
+in X and Y.  If drawing and labeling of an axis is disabled, tick drawing
+and labeling is automatically disabled.  Drawing and labeling of an axis
+may be disabled on only one side of the viewport (useful when a single viewport
+is used simultaneously for two different world coordinate systems).
+If tick drawing is disabled tick labeling is automatically disabled.
+The tick marks, if drawn, may be connected by dotted lines within the
+interior of the plot.
+
+Given the approximate number of major ticks, GIO will compute the nearest
+number of tick marks resulting in round numbers for the tick mark labels.
+If rounding is enabled the window will be enlarged to the nearest tick
+outward on either end of an axis, otherwise an axis will end at the window
+boundary, which need not fall on a tick mark.
+If linear scaling is indicated \fInminor\fR minor ticks will be drawn
+between each pair of major ticks.  If log scaling is indicated the
+\fInmajor\fR and \fInminor\fR parameters are ignored and
+major ticks will be placed at powers of ten with eight minor ticks
+(e.g., 2,3,4,5,6,7,8,9) between each pair of major ticks.
+Tick lengths are given in NDC coordinates.  The default tick lengths
+are parameterized in terms of the character height for the device.
+
+
+.nh 2
+Graphcap Parameters
+
+    Each logical graphics device accessible to GIO must have an entry
+in the \fBgraphcap\fR (graphics capabilities) file.  The name of the
+device entry in the graphcap file must agree with that specified in the
+\fBgopen\fR call when the device is opened.  Multiple logical device
+entries may be given for a single physical device, each with slightly
+different parameters.  The name of the graphcap file is parameterized
+by the CL environment variable "graphcap", making it easy for the user
+to customize or extend the graphcap file.  The graphcap entries for
+common devices may be precompiled by the system manager to eliminate
+the overhead of searching the graphcap file at run time.
+
+The format of the graphcap file is identical to that of a UNIX \fBtermcap\fR
+file, and indeed the same interface (TTY) is used to access both types of files.
+The set of capabilities defined for a graphics device is however quite
+different than that defined for a terminal.  Capabilities are typed 
+parameters referred to by a two character internal name.  The restriction to
+two characters is perhaps unfortunate but is desirable for efficiency reasons
+(as well as for compatablity with the original termcap) and may be alleviated
+at some point in the future by the use of macro defines.
+
+Graphcap parameters fall into two classes, those parameters which are
+common to all devices, and those parameters which are required only for
+devices accessed with a particular graphics kernel.  GIO is capable
+of supporting any number of quite different kernels, each of which may
+support any number of devices.  These kernels are free to add parameters
+to their graphcap entries provided they do not conflict with the standard
+parameters.  An example is the "fast" or \fBstdgraph\fR kernel, discussed
+in detail in a later section.  If a device is to be accessed by more than
+one kernel each kernel must typically have its own graphcap entry for the
+device, with selection of the graphcap entry (logical device name)
+specifying the kernel to be used.
+
+In the discussion which follows the reader is assumed to already be familiar
+with the syntax and usage of \fBtermcap\fR format files.  This is documented,
+for example, in section 5 of the UNIX manuals.  A sample termcap entry for
+the devices "vt100-nam" and "vt100-am" is included below as an example of
+a typical termcap entry.
+
+
+.tp 5
+.nf
+d1|vt100|vt100-nam|vt100 w/no am:\
+	:am@:xn@:tc=vt100-am:
+d0|vt100|vt100-am|vt100|dec vt100:\
+	:cr=^M:do=^J:nl=^J:bl=^G:co#80:li#24:cl=50\E[;H\E[2J:\
+	:le=^H:bs:am:cm=5\E[%i%d;%dH:nd=2\E[C:up=2\E[A:\
+	:ce=3\E[K:cd=50\E[J:so=2\E[7m:se=2\E[m:us=2\E[4m:ue=2\E[m:\
+	:md=2\E[1m:mr=2\E[7m:mb=2\E[5m:me=2\E[m:is=\E[1;24r\E[24;1H:\
+	:rs=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h:\
+	:if=/usr/lib/tabset/vt100:ku=\EOA:kd=\EOB:kr=\EOC:kl=\EOD:kb=^H:\
+	:ho=\E[H:k1=\EOP:k2=\EOQ:k3=\EOR:k4=\EOS:ta=^I:pt:sr=5\EM:vt#3:xn:\
+	:k5=\EOp:k6=\EOx:k7=\EOr:k8=\EOm:k9=\EOl:k0=\EOq:\
+	:sc=\E7:rc=\E8:cs=\E[%i%d;%dr:ks=\E[?1h\E=:ke=\E[?1l\E>:
+.fi
+
+
+Note that each device may be known by several names.  The device capabilities
+are delimited by colons, e.g., ":xx=...:yy=...:".  The special capability "tc"
+allows an entry to include another entry recursively.  Escape is represented
+as either "\E" or "^[", <ctrl/h> is "^H".  If a delay of so many milliseconds
+is required after transmission of a string, the number of milliseconds
+appears as the first few chars in an entry, e.g., "cl=50..." causes a
+delay of 50 milliseconds following a screen clear.  Numeric capabilities are
+prefaced by a sharp, e.g., ":co#80:" (screen has 80 columns).
+
+
+.nh 3
+Generic GRAPHCAP Parameters
+
+    To make the distinction between the generic and kernel graphcap parameters
+clear and to eliminate the possibility of redefinitions, the generic
+parameters have lower case names and the kernel parameters have upper case
+names.  Only the standard graphcap parameters should be accessed from within
+applications programs.  The standard parameters are listed and defined below.
+These parameters should be included in the graphcap entry for every device.
+
+.ls 4
+.ls 15 ar   real
+Aspect ratio dY/dX, i.e., the ratio of the size of the device screen in Y to
+that in X (equivalent to ys/xs).
+.le
+.ls ca   bool
+Device implements cellarray plotting in hardware, i.e, the \fIzr\fR greylevels
+are displayed by the hardware rather than emulated by software in the kernel.
+.le
+.ls ch   real
+Height in NDC units of a character of size 1.0.
+.le
+.ls co   int
+Number of columns of text displayable on the device screen at character
+size 1.0.
+.le
+.ls cw   real
+Width in NDC units of a character of size 1.0.
+.le
+.ls fa   bool
+Device implements fill area in hardware.
+.le
+.ls fs   int
+Number of fill area styles supported by the device.
+.le
+.ls in   bool
+Device supports at least one input function, i.e., cursor readback or cell
+array input.
+.le
+.ls k1   int
+Minimum possible key value in a cursor read.
+.le
+.ls k2   int
+Maximum possible key value in a cursor read.
+.le
+.ls kf   str
+Filename of the executable graphics kernel file for the device.
+If this is given as "cl", the kernel is assumed to be resident in the
+CL process.  Should be a virtual filename, e.g., "dev$x_device.e".
+See also parameter \fItn\fR.
+.le
+.ls li   int
+Number of lines of text displayable on the device screen at character
+size 1.0.
+.le
+.ls lt   int
+Number of linetypes supported by the device.
+.le
+.ls lw   int
+Number of linewidths supported by the device.
+.le
+.ls nc   int
+Number of cursors supported by the device.
+.le
+.ls nk   int
+Number of possible key values in a cursor read.
+.le
+.ls pl   bool
+Device implements polyline drawing in hardware.
+.le
+.ls pm   bool
+Device implements polymarker drawing in hardware.
+.le
+.ls ro   bool
+Device supports roam at the hardware level (used in cursor mode).
+.le
+.ls se   bool
+Device supports selective erase of portions of the screen.
+.le
+.ls tf   int
+Number of text fonts supported by the device.
+.le
+.ls th   int
+Number of text heights or sizes supported by the device.  If absent or zero
+it is assumed that characters may be freely scaled in size.  If only a number
+of discreet character sizes are available the sizes are given by the
+parameters \fItN\fR.
+.le
+.ls tn   str
+Taskname, i.e., name of the logical task within the kernel file \fIkf\fR
+to be run to exercise a kernel.
+.le
+.ls tq   int
+Number of text quality or precision levels supported by the device.
+.le
+.ls tN   real
+Sizes of the \fIth\fR possible character sizes, relative to a character
+of size 1.0 (expands to the set of parameters t1,t2,...,tN).
+.le
+.ls tx   bool
+Device implements text generation in hardware.
+.le
+.ls wc   bool
+Reading the cursor implies a wait, i.e., a cursor read is triggered by
+the user.
+.le
+.ls xr   int
+Device resolution in X.
+.le
+.ls xs   real
+Device scale in X, i.e., the width of the display area in meters.
+.le
+.ls yr   int
+Device resolution in Y.
+.le
+.ls ys   real
+Device scale in Y, i.e., the height of the display area in meters.
+.le
+.ls zo   bool
+Device supports zoom at the hardware level (used in cursor mode).
+.le
+.ls zr   int
+Device resolution in Z, i.e., the number of greylevels or colors displayable
+at each point using the cell array primitive.
+.le
+.le
+
+
+The graphcap parameters are accessed by name via \fBgget\fR calls.
+For example,
+
+	xr = ggetr (gp, "xr")
+
+would assign the value of the parameter "xr" into the local variable of
+the same name.
+
+.nh 3
+STDGRAPH Graphcap Parameters
+
+    The \fBstdgraph\fR kernel is the "fast" kernel, i.e., the graphics kernel
+resident in the CL process.  This kernel is capable of driving almost any
+modern graphics terminals given only a graphcap entry for the device,
+providing the graphics terminal is data driven and provides both character
+and vector generation in hardware.
+
+.nh 4
+Classes of Parameters
+
+    The stdgraph parameters fall into a number of classes which we shall
+describe separately.  An alphabetical summary of all parameters is given in
+a later section.
+
+The open and close workstation sequences are sent to the device whenever the
+workstation is activated (OW) or deactivated (CW), e.g., when the STDGRAPH
+kernel receives the open workstation or close workstation directive, or when
+the open workstation is explicitly deactivated and later reactivated by the
+applications program.
+
+The primary function of the open and close workstation sequences is to
+effect a mode switch from text mode to graphics mode and back again,
+but the sequences may also contain instructions used only for initialization
+or mode setting.  For example, OW might initialize user defined line types
+or enable the graphics board.  The close string CW might disable the graphics
+board and set the alpha cursor to a standard place on the screen.
+
+The graphics enable and disable strings (GE,GD) are sent to the terminal
+by the STDGRAPH kernel when status line i/o occurs.  The GD sequence should
+clear the status line, leaving the terminal in status line mode, with the
+text cursor positioned to the start of the status line.  The GE sequence
+restores the terminal to graphics mode, and is often the same as the OW
+sequence.  Note that GD should not cause the graphics frame to disappear,
+as the status line is supposed to be visible at the same time as the plot.
+
+The status line is normally the line at the bottom of the screen.  On terminals
+with separate text and graphics memories which can both be displayed at the
+same time, the status line is normally written into the text memory.  If the
+terminal has both text and graphics memories but can only display one at a time
+the graphics memory should be used, provided the status line can be erased in
+the graphics memory.  If the graphics plane must be used but erase is not
+possible, the best approach is probably to write successive lines of status
+line text on top of the plot, starting at the upper left corner and advancing
+downward for each line of output text (see the 4012 entry in dev$graphcap).
+
+The parameters X1, X2, Y1, and Y2 define the range of device coordinates
+to be output.  Normally these will span the full screen of the device,
+but in general they may define any rectangular window on the device screen.
+The fill area and font tables are array valued parameters mapping the GKI
+fill area and font indices into device codes (if the device should happen
+to support such niceties).
+
+
+.ks
+.nf
+	OW		open (reactivate) workstation
+	IF		initialization file, if OW string is large
+	CW		close (deactivate) workstation
+	GE		graphics enable (exit status line mode)
+	GD		graphics disable (enter status line mode)
+	CL		screen clear
+	LR		load registers (see "binary encoding")
+
+	X1,X2		range of device X coordinates
+	Y1,Y2		range of device Y coordinates
+.fi
+.ke
+
+
+The set attribute parameters are format strings used to encode set attribute
+commands, each of which has a single integer argument.  The format string is
+similar to a \fBprintf\fR format string with the addition of a notation for
+binary encoding (described below).
+
+
+.ks
+.nf
+	TH(i)		set text height
+	TC(i)		set text color
+	TF(i)		set text font
+	LT(i)		set line type
+	LC(i)		set line color
+	LW(i)		set line width
+	MC(i)		set marker color
+	FT(i)		set fill area type
+	FC(i)		set fill area color
+.fi
+.ke
+
+
+Polyline generation, i.e., vector drawing, is more difficult to parameterize.
+We assume that polylines, polymarkers, fill areas, etc. are all similar enough
+to be described by the same coordinate encoding format, but we allow each
+such instruction to have different head and tail strings.
+
+.ks
+.nf
+	PL		polyline flag
+	VS		move start
+	VE		move end
+	DS		draw start
+	DE		draw end
+	MS		marker start
+	ME		marker end
+	FS		fillarea start
+	FE		fillarea end
+	XY(i,j)		coord format
+.fi
+.ke
+
+
+A polyline command consists of a number of subcommands, as outlined in the
+drawing below.  The polyline is a move followed by one or more draws.
+The polyline flag PL is set to indicate that multiple coordinate pairs
+can be output between the DS and DE commands.  If PL is false (or omitted)
+each coordinate pair in the GKI polyline will be output surrounded by DS
+and DE commands.  The encoding of each coordinate pair is defined by the
+parameter XY.
+
+
+.ks
+.nf
+	set attributes if necessary
+	move start
+	    x, y
+	move end
+	draw start
+	    x, y
+		...
+	    x, y
+	draw end
+.fi
+.ke
+
+
+The polymarker and fillarea parameters are optional.  The kernel will
+emulate markers and fill area if not supported by the hardware.
+Recall that GIO handles all mark drawing except GM_POINT (point mode),
+hence sophisticated mark drawing facilities are not required.
+
+Text generation is handled by the kernel a character at a time.
+If character up is 90 degrees and the path is to the right, the kernel
+will assume that it can output a number of characters between a TS
+and a TE.  Otherwise each character will be output preceded by a TS
+and followed by a TE.  The TS parameter is a format string with two
+arguments, the device coordinates of the lower left corner of the
+character to be drawn.  The encoding of these coordinates is defined
+by the TS format string.  It is possible to perform a coordinate
+transformation using the binary encoding facilities, if such is necessary.
+If characters are not addressed at the lower left corner an offset
+may be applied to the given coordinates using the binary encoding
+facilities.
+
+
+.ks
+.nf
+	TS(i,j)		text start
+	TE		text end
+.fi
+.ke
+
+
+Cursor output is controlled by the parameter WC.
+Cursor input is initiated by output of the sequence defined by the format RC.
+RC has one integer argument, the number of the cursor to be read.
+The UC capability, if defined, will cause the cursor position to be updated
+(with WC) to the position at the last cursor read.  This is desirable if the
+device cannot maintain the cursor position, i.e., if unrelated graphics
+output commands affect the cursor position as an unwanted side effect.
+
+
+.ks
+.nf
+	UC		update cursor pos before read
+	WC(x,y,i)	write cursor 
+	RC(i)		read cursor start
+	RE		read cursor end
+	CN		cursor value length
+	CD		cursor value delimiter
+	SC		scan cursor (-> x,y,key)
+.fi
+.ke
+
+
+Following transmission of the RC sequence the kernel will read the
+response as defined by the parameters CN and CD.  At least one of CN or CD
+must be given.  If CN is given but not CD exactly CN characters will be
+read.  If CD is given then characters will be read until the delimiter string
+is matched (and until at least CN characters have been read).  If possible
+a delimiter string should be specified to permit recovery from bad cursor
+reads, e.g., when the user types something before the cursor is displayed.
+When a satisfactory cursor response string has been obtained the format SC
+will be used to decode the string into the output values X, Y, and KEY.
+The RE sequence is transmitted once the cursor read has successfully
+completed.
+
+.nh 4
+Binary Encoding
+
+    Graphics devices vary widely in the techniques used to encode numeric
+data such as a line type or color index, or the coordinate pairs of a
+polyline.  Our approach to the encoding problem is a generalization of the
+\fBprintf\fR format string.  The encoder is driven by a format string
+taken from the graphcap entry for the device.  A number of standard formats
+are recognized with encoding provided internally for these standard formats
+by the encoder.  To permit encoding of special formats the encoder provides
+a very general yet efficient RPN virtual machine capable of computing bit
+patterns according to a user supplied program embedded in the format string.
+
+A format string is a sequence of ASCII characters.  Any ASCII character,
+including all control characters, is permitted in the string.
+The significance of a character depends on the context in which it appears.
+Initially characters are simply copied to the output.  Three special
+characters are recognized in \fBcopy mode\fR (excluding the characters
+already counted as special by termcap):
+
+
+.ks
+.nf
+	'	escape next character (literal)
+	%	begin a formatted output string
+	(	begin an executable expression
+.fi
+.ke
+
+
+The encoder is a table driven interpreter which is programmed by the format
+given in the graphcap file.  Programming the encoder is rather
+like programming in assembler or microcode (its fun but easy to screw up).
+The encoder provides a set of 12 integer registers, an integer stack with a
+capacity of 50 values, and a dozen or so instructions.  It is fundamentally
+assumed that the character set is ASCII (this is guaranteed by the IRAF
+programming environment).
+
+Upon entry one or more of the registers 1 through 3 are initialized to the
+values of the input arguments, leaving the remaining registers, i.e., R4-R9
+and R0 (R10) available for general use.  Registers R11 and R12 are reserved
+for internal use.
+The interpreter is activated when an unescaped ( is encountered in the input.
+In \fBexecute mode\fR the following characters have special meanings
+(excluding :, ^, and \, which are special characters to termcap/TTY):
+
+.ks
+.nf
+	'	escape next character (recognized everywhere)
+	%	conventional formatted output
+	)	revert to copy mode
+	#nnn	push signed decimal integer number nnn
+	$ 	switch case construct
+	.	pop number from stack and place in output string
+	,	get next character from input string and push on stack
+	&	modulus (similar to AND of low bits)
+	+	add (similar to OR)
+	-	subtract (similar to AND)
+	*	multiply (shift left if pwr of 2)
+	/	divide (shift right if pwr of 2)
+	<	less than (0=false, 1=true)
+	> 	greater than (0=false, 1=true)
+	=	equals (0=false, 1=true)
+	;	branch if: <bool> <offset> ;.  The ; is at offset=0.
+       0-9	push contents of register 0 through 9
+	!N	pop stack into register N
+	!!	generate a N millisecond delay, where N is on the stack
+.fi
+.ke
+
+
+Any other character encountered in execute mode is interpreted as an integer
+number and pushed on the stack.  Hence, the character "@" is equivalent to
+"#64", i.e., octal 100.  A blank is the integer constant 40B.
+
+The output format directive % will format and output the number on the top
+of the stack, popping the stack in the process.  The format specification
+may be any legal \fBprintf\fR format.  The case construct is used to process
+set attribute commands, e.g., set linetype 0, 1, 2, text size 1, 2, 3, etc,
+and also provides a rudimentary conditional processing capability.  The branch
+if operator ; provides a rudimentary branching and looping capability.
+Beware that sequences like "^N" and "\E" compile as a single character in
+the format string.
+
+.nh 4
+Examples
+
+    As a simple example consider the encoding of the ANSI command to set
+the cursor of a nongraphics terminal.  The required sequence is the
+following:
+
+	ESC [ line ; col H
+
+Assuming that the column number is designated as X and the line number as
+Y, in registers 1 and 2 respectively, the format would be as follows
+(the quotes are not part of the format):
+
+	"\E[(2)%d;(1)%dH"
+
+Now assume that the output sequence is the same but the line and column
+numbers are one-indexed while the terminal requires zero-indexed
+coordinates:
+
+	"\E[(2#1-)%d;(1#1-)%dH"
+
+Thus far the examples have been pretty trivial and do not warrant the
+complexity of the RPN interpreter proposed here.  For our next example
+consider the encoding of a polyline coordinate pair for a Tektronix
+compatible graphics terminal and for an AED512, two quite different
+graphics terminals.  The Tektronix format for encoding an (X,Y) coordinate
+pair is as follows:
+
+
+.ks
+.nf
+	0 1 YA Y9 Y8 Y7 Y6
+	1 1 Y5 Y4 Y3 Y2 Y1
+	0 1 XA X9 X8 X7 X6
+	1 0 X5 X4 X3 X2 X1
+.fi
+.ke
+
+
+Since the Tektronix device is so common the special format %t is provided
+for encoding register 1 and 2 (X and Y) in this format, and writing out
+the result.  The format string
+
+	"%t"
+
+is all that is required.  The more general solution is provided by the
+following format.
+
+	"(2 / +.2 &`+.1 / +.1 &@+."
+
+To understand this last example one must look up the octal values of
+the characters " " (40B), "`" (140B), and "@" (100B).  The notation is
+admittedly rather cryptic but it is also concise and efficient, and works
+for a wide range of devices.
+
+Now consider the AED512 in binary mode (this is courtesy of NCAR; I do not
+have access to such a terminal).  The output encoding of a coordinate pair
+is as follows:
+
+
+.ks
+.nf
+	XA X9 X8 YB YA Y9 Y8
+	X7 X6 X5 X4 X3 X2 X1
+	Y7 Y6 Y5 Y4 Y3 Y2 Y1
+.fi
+.ke
+
+
+The format required to generate this is shown below.  Note the use of
+register 9 to store the constant 200B.  The "^N" signifies <ctrl/n>,
+i.e., 16B, used to effect a left shift of four bits.
+
+	"(#128!919/^N*29/+.19&.29&."
+
+This format could be further optimized by preloading register 9 at
+\fBopenws\fR time by moving the "(#128!9" to parameter LR.  The encoder
+registers maintain their values indefinitely.  Using LR the two parameters
+might appear in the graphcap entry as follows.
+
+	":LR=(#128!9:XY=(19/^N*29/+.19&.29&.:"
+
+The case construct makes it possible to generate output conditionally based
+on the value of an integer switch.  The syntax of a case statement is as
+follows:
+
+	$1 ... $2-5 ... $6 ... $D ... $$
+
+When the first $ is encountered the switch value is popped off the stack
+and converted into a character by addition of the constant '0' (60B).
+The interpreter will then scan forward until it finds the indicated case,
+at which point it resumes execution in case mode.  If the indicated case
+is not found scanning will stop at $D (the default case) or $$, whichever
+comes first.  When the next $ is seen the interpreter skips forward until
+it finds $$, which marks the end of the case.  Case constructs are not
+nestable.
+
+The case construct is used primarily for set attribute formats.
+For example, the GKI linetype codes are integers greater than or equal to zero,
+with case zero being the line clear and the other cases actual linetypes.
+For the VT640 there are nine possible linetypes, i.e., line clear,
+five builtin linetypes, and 3 user defined linetypes.  The strings to be
+output for the cases 0 through 5 are the following:
+
+
+.ks
+.nf
+	linetype		     string
+
+	    0			ESC / 1 d ESC `
+	    1			ESC / 0 d ESC `
+	    2			ESC / 0 d ESC a
+	    3			ESC / 0 d ESC b
+	  (etc)			     (etc)
+.fi
+.ke
+
+
+We could encode linetypes 0, 1 through 5, and everything else with the
+following format (linetype code in register 1):
+
+	"\E/(1$0)0d\E`($1-5)1d\E(1_+.$D)0d\E`($$"
+
+Note that case searching is a simple string matching operation that ignores
+operators such as ( and ).  Only $, ' (escape), and EOS are recognized when
+searching for a case.
+
+.nh 4
+Efficiency
+
+    The interpreter approach to solving the general encoding problem
+presented here is not the only solution to the problem.  Before adopting
+this approach several alternatives were considered.  One such alternative
+was the bitfield packing and unpacking scheme used by NCAR to solve the
+same problem.  The third alternative considered was to hand code a
+subroutine for each encoding required for each device.  Benchmarks run
+to compare the three alternatives yielded the following times in
+cpu seconds required to plot a 1000 point array with Tektronix encoding:
+
+
+.ks
+.nf
+	bitfields	approximately 30 seconds
+	interpreter	0.82 - 2.0 seconds
+	hand coded	0.78 seconds (mostly i/o)
+.fi
+.ke
+
+
+The time required for character output is included in the figures shown.
+The bitfields benchmark is an extrapolation from an actual timing of the
+prototype NCAR software as ported to the UNIX VAX by Cliff Stoll.
+The GBYTE and SBYTE primitives used to implement bitfields in the NCAR
+software were written in portable C by Cliff and did not use the VAX bitfield
+instructions, which would have helped significantly (but which would not
+have yielded a fair test: all IRAF target machines may not have bitfield
+instructions).  The two timings shown for the interpreter are for the "%t"
+format and the general format.  The clock time required by the hardware
+(VT100 with VT640 retrographics board) to draw the vectors was about 7 seconds.
+
+We conclude that the execution time overhead of the interpreter for encoding
+polyline points is acceptable and the use of hand coded, device dependent
+procedures is neither warranted nor desirable.  The bitfields technique
+is too inefficient to use in a production interface.
+
+.nh 4
+Decoding Cursor Input
+
+    Decoding of the cursor value string returned by the device into
+X, Y, and KEY (keystroke) values is carried out using the table driven
+interpreter for decoding rather than for encoding.  In this mode characters
+are input with "," and the decoded output values X, Y, and KEY are returned
+in registers 1 through 3.  The % format encoding operator is not used.
+If the cursor value is returned in ASCII X and Y must be converted to
+binary the hard way (e.g., "ch1 '0' - 100 * ch2 '0' - 10 * +", etc.).
+
+To verify that this scheme will work consider the cursor value returned
+by a Tektronix compatible terminal.  The return value is 6 characters,
+consisting of the character typed followed by the encoded X and Y in
+the next four characters, and lastly a CR terminator:
+
+
+.ks
+.nf
+	C7 C6 C5 C4 C3 C2 C1
+	 0  1 XA X9 X8 X7 X6
+	 0  1 X5 X4 X3 X2 X1
+	 0  1 YA Y9 Y8 Y7 Y6
+	 0  1 Y5 Y4 Y3 Y2 Y1
+	 0  0  0  1  1  0  1
+.fi
+.ke
+
+
+The required decoding format is shown below.
+
+	",!3, & *, &+!1, & *, &+!2"
+
+.nh 4
+Summary of STDGRAPH Graphcap Parameters
+
+    An alphabetical summary of the graphcap parameters used by the STDGRAPH
+kernel is given below.
+
+
+.tp 3
+.nf
+	CD		cursor value delimiter
+	CL		screen clear
+	CN		cursor response length
+	CW		close (deactivate) workstation
+	DE		draw end
+	DS		draw start
+	FC(i)		set fill area color
+	FE		fillarea end
+	FS		fillarea start
+	FT(i)		set fill area type
+	GD		graphics disable (exit status line mode)
+	GE		graphics enable (enter status line mode)
+	IF		initialization file, if OP string is large
+	LC(i)		set line color
+	LR		load registers
+	LT(i)		set line type
+	LW(i)		set line width
+	MC(i)		set marker color
+	ME		marker end
+	MS		marker start
+	OW		open (reactivate) workstation
+	PL		polyline flag
+	RC(i)		read cursor start
+	RE		read cursor end
+	SC		scan cursor (-> x,y,key)
+	TC(i)		set text color
+	TE		text end
+	TF(i)		set text font
+	TH(i)		set text height
+	TS(i,j)		text start
+	VE		move end
+	VS		move start
+	WC(x,y,i)	write cursor 
+	X1		first device X coordinate
+	X2		last device X coordinate
+	XY(i,j)		coordinate format
+	Y1		first device Y coordinate
+	Y2		last device Y coordinate
+.fi
+
+
+As a final example, the actual graphcap entry for the vt640 terminal
+(DEC VT100 with retrographics) is reproduced below.
+
+
+.ks
+.nf
+vt640|vt640g|vt100 with Retrographics:\
+    :RC=(1$2)^X\E[24;65H\E[7mLIGHT PEN READY\E[0m($$)^]\E"(1$2)5($D)4($$)g:\
+    :WC=^]%t\E/f:OW=150^]^_:CW=^X\E[24;0H\E[K:GE=150^]^_:GD=^X\E[24;0H\E[K:\
+    :lt#5:nc#2:se:CL=50^]\E^L:xr#640:yr#480:ar#.57:xs#.23:ys#.13:tc=4012:
+
+4012|tek4012|tektronix 4012:\
+    :ar#.70:ch#.0294:co#80:cw#.0125:in:k1#1:k2#127:kf=cl:li#35:\
+    :lt#5:nc#1:nk#127:pl:pm:th#4:t1#1:t2#2:t3#3:t4#4:tx:\
+    :wc:xr#1024:yr#780:xs#.20:ys#.14:\
+    :CD=^M:CN#6:LT=^]\E/(1$0)1d\E`($1-5)0d\E(1_+.$D)0d\E`($$:\
+    :MS=\034:PL:RC=\E^Z:SC=(,!3, & *, &+!1, & *, &+!2:\
+    :TH=\E(1#47+.:TS=^]%t^_:VS=^]:X1#0:X2#1023:XY=%t:Y1#0:Y2#779:\
+    :OW=^]^_:CW=(#682!2#0!1)^]%t^_:GE=^]^_:\
+    :CL=1000(#32!9)\E^L:\
+    :LR=(#32!9:GD=(9#1-!99$0#31!9$$9#22*!2#0!1)^]%t^_:
+.fi
+.ke
+
+.NH 3
+TERMCAP and GRAPHCAP
+
+    Every graphics terminal entry in the graphcap file should have a
+corresponding terminal capability entry in the termcap file.  When the user
+sets the terminal type with the \fBstty\fR task in the CL, the termcap entry
+tells whether or not the terminal supports vector graphics, and the value
+of the \fBstdgraph\fR environment variable is set to "none" for a non-graphics
+terminal, or to the graphcap name of the device for a graphics terminal.
+For a terminal to be recognized by the system as a graphics terminal the
+termcap entry must include the ":gd" capability.  If the graphcap name for
+the device is different than the termcap name then the form ":gd=gcname:"
+should be used.
+
+For example, the minimal termcap entry for the vt640 graphics terminal would
+be as follows.  Note that it makes no sense to set the terminal type to
+"vt100", since a standard vt100 does not support vector graphics.
+
+.ks
+.nf
+	vt640|Retrographics enhanced VT100:\
+	:gd:tc=vt100:
+.fi
+.ke
+
+The "gd" capability is not standard termcap, but will be ignored by non-IRAF
+programs which do not recognize the capability.
+
+.nh 2
+Graphics Kernel Interface
+
+    The graphics kernel interface (GKI) is the interface between GIO and the
+underlying graphics kernel or kernels.  The GKI is a data driven interface,
+i.e., GIO communicates with the graphics kernel via bidirectional streams
+of control instructions and data.  The functionality assumed by the GKI is
+simple enough to permit use of a variety of graphics kernels, e.g., the builtin
+GIO kernel for interactive graphics terminals, GKS, CORE, NSPP, and so on.
+To understand the level of functionality expected from the kernel we first
+summarize the functions the kernel is \fInot\fR expected to perform, i.e.,
+the functions performed by GIO before output to the kernel:
+
+.ls 4
+.ls o
+All WCS coordinate transformations and clipping at the viewport boundary.
+The kernel sees only NDC coordinates.
+.le
+.ls o
+Axis drawing and labeling.  GIO processes a \fBglabax\fR call into a
+sequence of polylines in NDC coordinates.
+.le
+.ls o
+Mark drawing.  GIO processes all mark drawing commands into polyline
+instructions.
+.le
+.ls o
+Move and draw commands.  GIO processes all absolute and relative move and draw
+commands into sequences of polyline instructions.
+.le
+.le
+
+
+The main functions of the kernel are the control and attribute set functions,
+set cursor, polyline, polymarker (GM_POINT only), text generation, fill area,
+cell array, and cursor read.  A kernel need not implement all such functions,
+but it must at least recognize and ignore the corresponding GKI instructions.
+The GKI kernel instructions are easily implemented for modern intelligent
+graphics terminals.  The fast kernel will let the terminal handle polyline
+drawing, point mode polymarker drawing, dashed lines, and character generation.
+
+The GKI format is a sequence of variable length binary control and
+output instructions.  Each instruction consists of the beginning of instruction
+sentinel (BOI), an integer binary opcode identifying the instruction,
+an integer giving the length of the instruction in metacode words,
+and an arbitrary number of parameter and data words.
+The BOI word aids in the detection of and recovery from botched instructions,
+e.g., if an interrupt occurs while writing an instruction.
+
+
+.ks
+.nf
+	 \fBfield\fR                          \fBdescription\fR
+
+	BOI		beginning of instruction (magic value = 100000B)
+	opcode		unique instruction identification code (1-27)
+	length		length of entire of instruction in metacode
+			    words (includes all four fields)
+	data		variable length part of instruction
+.fi
+
+.ce
+Figure 3. GKI Instruction Format
+.ke
+
+
+The instruction format chosen for GKI is basically a direct mapping of the
+required low level functions into binary opcodes.
+Various standard formats were considered and rejected,
+in particular the GKS VDM (virtual device metafile) format.
+GKS VDM turned out to be far to complex to be worth using at this level
+in the system.  The GKS VDI format might have been better suited,
+but I could not find any information describing this format
+(my understanding was that, although there are numerous implementations of VDI,
+there is no formal standard as yet).
+
+The GKI format may be extended at some point in the future to provide
+a binary instruction for each procedure in the GKS Fortran binding.
+This will make it possible for applications to use either GIO or GKS,
+provided a GKS kernel is available.  This will make it easier to
+import applications which are already written to use GKS (alternatively a
+mini-GKS might be built upon GIO, since the primitive functions are almost
+identical).  Since IRAF itself is transportable and it is desirable for IRAF
+applications to have full access to the IRAF i/o facilities, new IRAF
+applications are not being written with transport to another data reduction
+system in mind.  New IRAF applications will use only GIO whenever the
+facilities provided by GIO are adequate.  Applications which use only GIO
+will continue to be usable with any graphics kernel.
+
+.nh 3
+GKI Instructions
+
+    The GKI instruction stream transmitted between processes on the same or
+compatible machines will be a sequence of SPP short integer metacode words.
+The machine independent GKI metafile format will be the equivalent stream
+encoded as 16 bit twos complement signed integer metacode words, blocked 
+1440 words per block, with conversion between the internal and external
+metacode formats being provided by the IRAF MII (machine independent integer)
+interface (MII takes care of byte swapping, etc.).  GKI metafiles in MII
+format will be easily read and written by different machines, offloading most
+of the work to the graphics kernel on the reader machine.  The GKI instruction
+format is designed for maximum efficiency on modern minicomputers, i.e.,
+the internal format (SPP short integer) is an atomic datatype and no bit
+operations are required to generate or interpret metacode.
+
+NDC coordinates (0.0 to 1.0) will be represented in GKI as integers in the
+range 0-32767.  Character data will be packed one 7 bit ASCII character per
+metacode word.  Floating point is required only for certain output attributes,
+e.g., the linewidth and character height (size) scale factors.
+To avoid the problems of machine dependent floating point formats we shall
+represent the low precision real numbers by converting them to integer
+metacode words scaled according to the following relation:
+
+	I = int (R * 1E2)
+
+Specifications for the GKI metafile instructions follow.  The datatype and
+size of each field of the instruction is given in parenthesis.
+The datatype "p" denotes a coordinate pair (x,y) of type (m,m),
+where "m" denotes an NDC coordinate.
+
+The OPENWS instruction marks the start of an instruction stream or
+\fBmetafile\fR for a particular device.
+A subsequent CLOSEWS (or physical end of file) marks the end of a metafile.
+An OPENWS in APPEND mode requires that GIO recall the WCS defined when the
+device was last accessed.
+A physical file may consist of any number of independent metafiles.
+Although there is no explicit connection between OPENWS and screen clear
+(CLEARWS), a screen clear is implied for some devices when opened in
+new file mode.
+The MFTITLE instruction is optional and is provided only for documenting
+the contents of a metafile.
+
+
+.ks
+.nf
+			GKI_EOF = BOI  0 L
+		     GKI_OPENWS = BOI  1 L M N D
+		    GKI_CLOSEWS = BOI  2 L N D
+	       GKI_REACTIVATEWS = BOI  3 L
+	       GKI_DEACTIVATEWS = BOI  4 L
+		    GKI_MFTITLE = BOI  5 L N T
+		    GKI_CLEARWS = BOI  6 L
+		     GKI_CANCEL = BOI  7 L
+		      GKI_FLUSH = BOI  8 L
+		   GKI_POLYLINE = BOI  9 L N P
+		 GKI_POLYMARKER = BOI 10 L N P
+		       GKI_TEXT = BOI 11 L P N T
+		   GKI_FILLAREA = BOI 12 L N P
+	       GKI_PUTCELLARRAY = BOI 13 L LL UR NC NL P
+		  GKI_SETCURSOR = BOI 14 L CN POS
+		      GKI_PLSET = BOI 15 L LT LW CI
+		      GKI_PMSET = BOI 16 L MT MW CI
+		      GKI_TXSET = BOI 17 L UP SZ SP P HJ VJ F Q CI
+		      GKI_FASET = BOI 18 L FS CI
+		  GKI_GETCURSOR = BOI 19 L CN
+		GKI_CURSORVALUE = BOI 19 L CN POS KEY
+	       GKI_GETCELLARRAY = BOI 20 L LL UR NC NL
+		  GKI_CELLARRAY = BOI 20 L NP P
+		     GKI_ESCAPE = BOI 25 L FN N DC
+		     GKI_SETWCS = BOI 26 L N WCS
+		     GKI_GETWCS = BOI 27 L N
+.fi
+
+.ce
+The GKI Instruction Set
+.ke
+
+.nh 4
+Control Instructions
+
+    The NULL instruction is unique in that it consists of a single metacode
+word with value zero.  The BOI and length fields are omitted.  Any number
+of null words may be inserted between regular metacode instructions, e.g.,
+to pad a block of metacode to be written to an MII format metafile.
+The EOF instruction is used internally by GIO to stop metacode translation
+on a pseudofile stream, as if end of file had been encountered.
+
+The open workstation instruction should start a new frame unless the access
+mode is APPEND, in which case graphics is to be added to the last frame.
+An OPENWS implies an REACTIVATEWS.  CLOSEWS does little more than deactivate
+the workstation, since the last frame must in some sense remain open for
+APPEND mode to be possible.  Normal termination of the kernel process
+will or an open workstation in a mode other than append will cause the last
+frame to be terminated.
+
+
+.ls
+.tp 4
+GKI_EOF = BOI 0 L
+.ls
+.nf
+L(i)		3
+.fi
+.le
+
+
+.tp 6
+GKI_OPENWS = BOI 1 L M N D
+.ls
+.nf
+L(i)		5 + N
+M(i)		access mode (APPEND=4, NEW_FILE=5, TEE=6)
+N(i)		number of characters in field D
+D(Nc)		device name as in \fBgraphcap\fR file
+.fi
+.le
+
+
+.tp 5
+GKI_CLOSEWS = BOI 2 L N D
+.ls
+.nf
+L(i)		4 + N
+N(i)		number of characters in field D
+D(Nc)		device name as in \fBgraphcap\fR file
+.fi
+.le
+
+
+.tp 5
+GKI_REACTIVATEWS = BOI 3 L
+.ls
+.nf
+L(i)		3
+.fi
+.le
+
+
+.tp 5
+GKI_DEACTIVATEWS = BOI 4 L
+.ls
+.nf
+L(i)		3
+.fi
+.le
+
+
+.tp 5
+.rj (optional)
+GKI_MFTITLE = BOI 5 L N T
+.ls
+.nf
+L(i)		4 + N
+N(i)		number of characters in field T
+T(Nc)		title string identifying metafile
+.fi
+.le
+
+
+.tp 3
+GKI_CLEARWS = BOI 6 L
+.ls
+.nf
+L(i)		set to the constant 3 (no data fields)
+.fi
+.le
+
+
+.tp 3
+GKI_CANCEL = BOI 7 L
+.ls
+.nf
+L(i)		set to the constant 3 (no data fields)
+.fi
+.le
+
+
+.tp 3
+GKI_FLUSH = BOI 8 L
+.ls
+.nf
+L(i)		set to the constant 3 (no data fields)
+.fi
+.le
+.le
+
+.nh 4
+Output Instructions
+
+    All data points in the GKI output instructions have been transformed into
+NDC coordinates and clipped at the viewport boundary (if clipping is enabled).
+In the process GIO will translate any INDEF valued points by breaking large
+polylines into smaller polylines, hence the semantics of plotting polylines and
+polymarkers is quite simple at the graphics kernel level.
+
+CELLARRAY is processed into a series of one dimensional cell array instructions,
+one for each line in the two dimensional array supplied by the user.  Fewer or
+shorter lines will be output if clipping is necessary.  Arrays larger than 32767
+pixels may be output since each line is passed as a separate instruction.
+The maximum number of lines and columns in a cell array is 32767 and 32761,
+respectively (more lines can be input but they will not be resolved).
+The kernel is expected to scale cell arrays to fit the output device via some
+combination of pixel replication or subsampling, if there is not a one to one
+correspondence between cell array pixels and device pixels.
+
+.ls
+.tp 5
+GKI_POLYLINE = BOI 9 L N P
+.ls
+.nf
+L(i)		4 + N * 2
+N(i)		number of points in the polyline
+P(Np)		list of points (x,y pairs)
+.fi
+.le
+
+
+.tp 5
+GKI_POLYMARKER = BOI 10 L N P
+.ls
+.nf
+L(i)		4 + N * 2
+N(i)		number of points in the polymarker
+P(Np)		list of points (x,y pairs)
+.fi
+.le
+
+
+.tp 6
+GKI_TEXT = BOI 11 L P N T
+.ls
+.nf
+L(i)		6 + N
+P(p)		starting point of character string
+N(i)		number of characters in string T
+T(Nc)		string of N ASCII characters
+.fi
+.le
+
+
+.tp 5
+GKI_FILLAREA = BOI 12 L N P
+.ls
+.nf
+L(i)		4 + (N * 2)
+N(i)		number of points defining the polygon to be filled
+P(Np)		list of points (x,y pairs)
+.fi
+.le
+
+
+.tp 8
+GKI_PUTCELLARRAY = BOI 13 L LL UR NC NL P
+.ls
+.nf
+L(i)		9 + (N * M)
+LL(p)		coordinates of lower left corner of output area
+UR(p)		coordinates of upper right corner of output area
+NC(i)		number of columns in array
+NL(i)		number of lines in array
+P(NCNLi)	array of color indices (pixels) stored by row
+.fi
+.le
+
+
+.tp 5
+GKI_SETCURSOR = BOI 14 L CN POS
+.ls
+.nf
+L(i)		6
+CN(i)		cursor number
+POS(p)		new cursor position
+.fi
+.le
+.le
+
+.nh 4
+Set Attribute Instructions
+
+    The set polyline, polymarker, text, and fillarea instructions change
+the attributes used to generate graphics output.  These instructions need be
+issued only when one of the attributes in an instruction packet changes, i.e.,
+the kernel is assumed to remember the attributes while a device is open.
+
+.ls
+.tp 6
+GKI_PLSET = BOI 15 L LT LW CI
+.ls
+.nf
+L(i)		6
+LT(i)		linetype number
+LW(r)		linewidth scale factor
+CI(i)		polyline color index
+.fi
+.le
+
+
+.tp 6
+GKI_PMSET = BOI 16 L MT MW CI
+.ls
+.nf
+L(i)		6
+MT(i)		marktype (not used at present)
+MW(i)		marksize, NDC coords (not used at present)
+CI(i)		marker color index
+.fi
+.le
+
+
+.tp 9
+GKI_TXSET = BOI 17 L UP SZ SP P HJ VJ F Q CI
+.ls
+.nf
+L(i)		12
+UP(i)		character up vector (degrees)
+SZ(r)		character size scale factor
+SP(r)		character spacing
+P(i)		path (0,2=left,3=right,4=up,5=down)
+HJ(i)		horizontal justification
+		    (0=normal,1=center,2=left,3=right)
+VJ(i)		vertical justification
+		    (0=normal,1=center,6=top,7=bottom)
+F(i)		font (8=roman,9=greek,10=italic,11=bold)
+Q(i)		quality (0=normal,12=low,13=medium,14=high)
+CI(i)		text color index
+.fi
+.le
+
+
+.tp 5
+GKI_FASET = BOI 18 L FS CI
+.ls
+.nf
+L(i)		5
+FS(i)		fill style (0=clear,1=hollow,2=solid,3-6=hatch)
+CI(i)		fill area color index
+.fi
+.le
+.le
+
+
+The attributes for the output primitives are assumed to be set to their
+default values when OPENWS is issued.
+
+.nh 4
+Input Instructions
+
+    The primary input instruction is the cursor read instruction, used to read
+the cursor position in NDC coordinates.  The device cursor read may be either
+event driven or instantaneous.  If the cursor read is event driven a nonzero
+keystroke value may be returned, the range of possible keystroke values being
+device dependent.  The instantaneous type of cursor read is preferred at the
+GKI level since it offers the maximum flexibility (\fBclgcur\fR may then be
+used to provide an optional device independent keystroke driven cursor read).
+Devices which support both forms of cursor read may provide both as separate
+logical cursors.  The graphics kernel should return a null cursor value if
+the output device does not have a cursor.
+
+.ls
+.tp 6
+GKI_GETCURSOR = BOI 19 L CN
+.ls
+.nf
+L(i)		4
+CN(i)		cursor number
+.fi
+
+The kernel reads graphics cursor number CN and returns the keystroke value
+(if any) and the cursor position in NDC coordinates.  The cursor attributes
+are returned in the following format:
+
+	GKI_CURSORVALUE = BOI 19 L CN POS KEY
+
+where
+
+.nf
+	L(i)		7
+	CN(i)		cursor number
+	POS(r)		NDC coordinates of cursor
+	KEY(i)		keystroke value (>= 0 or EOF)
+.fi
+.le
+
+
+.tp 8
+GKI_GETCELLARRAY = BOI 20 L LL UR NC NL
+.ls
+.nf
+L(i)		9
+LL(p)		coordinates of lower left corner of input area
+UR(p)		coordinates of upper right corner of input area
+NC(i)		number of columns in output array
+NL(i)		number of lines in output array
+.fi
+
+The GETCELLARRAY instruction is the converse of the PUTCELLARRAY instruction.
+The cell array is returned in the following format:
+
+	GKI_CELLARRAY = BOI 20 L NP P
+
+where
+
+.nf
+	L(i)		4 + NP
+	NP(i)		number of pixels (0 if noread)
+	P(NPi)		array of pixels
+.fi
+.le
+
+
+(instruction codes 19-24 are reserved for future use)
+.le
+
+.nh 4
+Escape Instruction
+
+    The escape instruction is used to pass device dependent information or
+commands to the graphics kernel via GKI.  The graphics kernel will ignore
+unrecognized escape functions.  Function codes 1 through 100 are reserved
+for use by GIO.
+
+.ls
+.tp 5
+GKI_ESCAPE = BOI 25 L FN N DC
+.ls
+.nf
+L(i)		5 + N
+FN(i)		escape function code
+N(i)		number of escape data words
+DC(i)		escape data words
+.fi
+.le
+.le
+
+.nh 4
+Pseudo-GKI Instructions
+
+    Since the CL must be able to read the device cursor and convert NDC
+coordinates to WCS coordinates, the WCS must be passed to the CL when they
+are "fixed" to the device.  The most natural and efficient way to do this
+is via the GKI instruction stream, hence several additional instructions
+are used internally in GIO to communicate with the portion of GIO resident
+in the CL process.  These instructions are filtered out and executed by the
+CL process and their existence may therefore be ignored by the graphics kernels.
+
+The SETWCS instruction is used to pass WCS information to the CL process.
+The GETWCS instruction is used to recall the WCS for a device opened in APPEND
+mode (the WCS are returned in SETWCS format).  Since these instructions
+are passed only between two closely coupled processes on a single cpu,
+floating point numbers are passed in machine dependent format.
+The length of this instruction is machine dependent.
+Only the fields L and WCS are truely part of the instruction; the remaining
+fields are a binary copy of the GIO internal WCS structure.
+
+.ls
+.tp 6
+GKI_SETWCS = BOI 26 L N WCS
+.ls
+.nf
+L(i)		4 + 17 * sizeof (struct wcs)
+N(i)		length of WCS structure, words
+WCS		binary copy of the 17 WCS structures, transmitted
+		    in a single call to WRITE
+.fi
+.le
+
+
+.tp 5
+GKI_GETWCS = BOI 27 L N
+.ls
+.nf
+L(i)		4
+N(i)		maximum number of words to read
+.fi
+.le
+.le
+
+.nh 3
+Encoding GKI Instructions
+
+    The GKI instruction opcodes and fields are defined in the global include
+file lib$gki.h.  To avoid direct knowledge of the binary format of the GKI
+instructions, GIO uses a subpackage called GKI to encode the GKI instructions.
+The GKI procedures each encode and transmit a single GKI instruction on the
+output stream.  Although the GIO and GKI procedures have similar names, they
+should not be confused.  The GIO \fBgpline\fR, for example, performs conversion
+from a WCS to GKI coordinates with clipping at the viewport boundary, checking
+that the polyline attributes are up to date before transmitting the polyline
+instruction.  In contrast the GKI \fBgki_polyline\fR merely encodes and
+transmits the GKI_POLYLINE metacode instruction.
+
+The GKI procedures are self contained with the exception of the set attribute
+instructions, which reference attribute packet structures (argument \fIap\fR)
+defined in the include file gio.h.
+The GKI instruction encoding procedures are shown below.
+
+.ks
+.nf
+	     gki_openws (fd, device, mode)
+	    gki_closews (fd, device)
+       gki_reactivatews (fd, flags)
+       gki_deactivatews (fd, flags)
+	    gki_mftitle (fd, title)
+	    gki_clearws (fd)
+	     gki_cancel (fd)
+	      gki_flush (fd)
+	   gki_polyline (fd, points, npts)
+	 gki_polymarker (fd, points, npts)
+	       gki_text (fd, x, y, text)
+	   gki_fillarea (fd, points, npts)
+       gki_getcellarray (fd, m, nx, ny, x1,y1, x2,y2)
+       gki_putcellarray (fd, m, nx, ny, x1,y1, x2,y2)
+              gki_plset (fd, ap)
+              gki_pmset (fd, ap)
+	      gki_txset (fd, ap)
+              gki_faset (fd, ap)
+	  gki_setcursor (fd, x, y, cursor)
+	  gki_getcursor (fd, x, y, key, cursor)
+	     gki_escape (fd, fn, instruction, nwords)
+	     gki_setwcs (fd, wcsdata, len_wcsdata)
+	     gki_getwcs (fd, wcsdata, len_wcsdata)
+
+	     gki_fflush (fd)	# not GKI instruction; flushes GKI stream
+.fi
+.ke
+
+
+.nh 3
+Decoding GKI Instructions
+
+    The following additional procedures are provided for decoding and executing
+GKI metacode, e.g., in a graphics kernel.  In what follows, \fIinstruction\fR
+is a short integer array containing the encoded GKI instruction, and \fIdd\fR
+is the device driver table, i.e., array of \fBzlocpr\fR entry point addresses
+of the standard kernel procedures.
+
+
+.ks
+.nf
+	 stat = gki_fetch_next_instruction (fd, instruction_ptr)
+		gki_execute (instruction, dd)
+		gkp_install (dd, out_fd, verbose_output)
+.fi
+.ke
+
+
+The \fBfetch\fR procedure extracts the next instruction from the input metacode
+stream, returning a short integer pointer to the instruction as an output
+argument.  EOF is returned as the function value when end of file is detected.
+The \fBexecute\fR procedure decodes an instruction and calls a graphics device
+driver procedure to execute the instruction.  If the entry point address
+of the driver procedure is NULL \fBgki_execute\fR will ignore the corresponding
+GKI instruction.  The fields of the metacode instruction are passed to the
+driver procedure as distinct arguments, hence the device driver need not
+understand the GKI format.
+
+A standard kernel is provided for decoding GKI instructions, printing the
+decoded instructions in text form on the output stream.  The driver for this
+kernel is installed with \fBgkp_install\fR, setting the output file and
+verbose output flag in the process.
+
+.nh 3
+Example
+
+    To illustrate the use of GKI as well as the output of the GKI decoding
+kernel, consider the simple \fBgplotv\fR style plot of the following function:
+
+	y = x ** 2
+
+over the range
+
+	x = 1 to 5, y = 1 to 25
+
+The decoded GKI metacode produced by GIO to graph this function is
+shown below.  The "verbose" mode of output (shown) lists the values
+of the data points in the polyline, etc. output functions.  If verbose
+output is disabled only the statistics of the output polylines
+(computed by the decoder) will be printed.  All coordinates are printed
+in NDC units.  The redundant points appearing in the output metacode
+are expected to be filtered out by the kernel, which should not plot
+points separated by less than the device resolution in NDC units.
+
+
+.tp 4
+.nf
+open_workstation 'vt640', mode=new_file
+set_wcs nwords=352
+	 1 1. 5. 1. 25.  0.19 0.81 0.33 0.96  0 0 1
+set_polyline ltype=1, lwidth=2.00, color=1
+polyline np=3, xmin=0.19,xmax=0.19,xavg=0.19, ymin=0.33,ymax=0.37,yavg=0.34
+	0.188 0.334  0.188 0.334  0.188 0.367  
+set_text up=90, path=right, hjustify=center, vjustify=top, font=roman,
+	size=1.00, spacing=0.00, color=1, quality=normal
+text 0.19, 0.31, '1'
+polyline np=15, xmin=0.19,xmax=0.34,xavg=0.27, ymin=0.33,ymax=0.37,yavg=0.34
+	0.188 0.334  0.219 0.334  0.219 0.350  0.219 0.334  0.250 0.334  
+	0.250 0.350  0.250 0.334  0.281 0.334  0.281 0.350  0.281 0.334  
+	0.313 0.334  0.313 0.350  0.313 0.334  0.344 0.334  0.344 0.367  
+text 0.34, 0.31, '2'
+polyline np=15, xmin=0.34,xmax=0.50,xavg=0.43, ymin=0.33,ymax=0.37,yavg=0.34
+	0.344 0.334  0.375 0.334  0.375 0.350  0.375 0.334  0.406 0.334  
+	0.406 0.350  0.406 0.334  0.437 0.334  0.437 0.350  0.437 0.334  
+	0.469 0.334  0.469 0.350  0.469 0.334  0.500 0.334  0.500 0.367  
+text 0.50, 0.31, '3'
+polyline np=15, xmin=0.50,xmax=0.66,xavg=0.58, ymin=0.33,ymax=0.37,yavg=0.34
+	0.500 0.334  0.531 0.334  0.531 0.350  0.531 0.334  0.562 0.334  
+	0.562 0.350  0.562 0.334  0.593 0.334  0.593 0.350  0.593 0.334  
+	0.625 0.334  0.625 0.350  0.625 0.334  0.656 0.334  0.656 0.367  
+text 0.66, 0.31, '4'
+polyline np=15, xmin=0.66,xmax=0.81,xavg=0.74, ymin=0.33,ymax=0.37,yavg=0.34
+	0.656 0.334  0.687 0.334  0.687 0.350  0.687 0.334  0.718 0.334  
+	0.718 0.350  0.718 0.334  0.750 0.334  0.750 0.350  0.750 0.334  
+	0.781 0.334  0.781 0.350  0.781 0.334  0.812 0.334  0.812 0.367  
+text 0.81, 0.31, '5'
+polyline np=2, xmin=0.81,xmax=0.81,xavg=0.81, ymin=0.33,ymax=0.33,yavg=0.33
+	0.812 0.334  0.812 0.334  
+polyline np=77, xmin=0.78,xmax=0.81,xavg=0.81, ymin=0.33,ymax=0.96,yavg=0.65
+	0.812 0.334  0.812 0.334  0.796 0.334  0.812 0.334  0.812 0.360  
+	0.796 0.360  0.812 0.360  0.812 0.386  0.796 0.386  0.812 0.386  
+	0.812 0.412  0.796 0.412  0.812 0.412  0.812 0.438  0.779 0.438  
+	0.812 0.438  0.812 0.464  0.795 0.464  0.812 0.464  0.812 0.490  
+	0.795 0.490  0.812 0.490  0.812 0.516  0.795 0.516  0.812 0.516  
+	0.812 0.542  0.795 0.542  0.812 0.542  0.812 0.568  0.779 0.568  
+	0.812 0.568  0.812 0.594  0.795 0.594  0.812 0.594  0.812 0.620  
+	0.795 0.620  0.812 0.620  0.812 0.646  0.795 0.646  0.812 0.646  
+	0.812 0.672  0.795 0.672  0.812 0.672  0.812 0.698  0.779 0.698  
+	0.812 0.698  0.812 0.724  0.795 0.724  0.812 0.724  0.812 0.750  
+	0.795 0.750  0.812 0.750  0.812 0.776  0.795 0.776  0.812 0.776  
+	0.812 0.802  0.795 0.802  0.812 0.802  0.812 0.828  0.778 0.828  
+	0.812 0.828  0.812 0.854  0.795 0.854  0.812 0.854  0.812 0.880  
+	0.795 0.880  0.812 0.880  0.812 0.906  0.795 0.906  0.812 0.906  
+	0.812 0.932  0.795 0.932  0.812 0.932  0.812 0.958  0.778 0.958  
+	0.812 0.958  0.812 0.958  
+polyline np=15, xmin=0.19,xmax=0.22,xavg=0.19, ymin=0.33,ymax=0.44,yavg=0.38
+	0.188 0.334  0.188 0.334  0.204 0.334  0.188 0.334  0.188 0.360  
+	0.204 0.360  0.188 0.360  0.188 0.386  0.204 0.386  0.188 0.386  
+	0.188 0.412  0.204 0.412  0.188 0.412  0.188 0.438  0.221 0.438  
+set_text up=90, path=right, hjustify=right, vjustify=center, font=roman,
+	size=1.00, spacing=0.00, color=1, quality=normal
+text 0.19, 0.44, '5'
+polyline np=15, xmin=0.19,xmax=0.22,xavg=0.19, ymin=0.44,ymax=0.57,yavg=0.51
+	0.188 0.438  0.188 0.464  0.204 0.464  0.188 0.464  0.188 0.490  
+	0.204 0.490  0.188 0.490  0.188 0.516  0.204 0.516  0.188 0.516  
+	0.188 0.542  0.204 0.542  0.188 0.542  0.188 0.568  0.221 0.568  
+text 0.19, 0.57, '10'
+polyline np=15, xmin=0.19,xmax=0.22,xavg=0.19, ymin=0.57,ymax=0.70,yavg=0.64
+	0.188 0.568  0.188 0.594  0.204 0.594  0.188 0.594  0.188 0.620  
+	0.204 0.620  0.188 0.620  0.188 0.646  0.204 0.646  0.188 0.646  
+	0.188 0.672  0.204 0.672  0.188 0.672  0.188 0.698  0.221 0.698  
+text 0.19, 0.70, '15'
+polyline np=15, xmin=0.19,xmax=0.22,xavg=0.19, ymin=0.70,ymax=0.83,yavg=0.77
+	0.188 0.698  0.188 0.724  0.204 0.724  0.188 0.724  0.188 0.750  
+	0.204 0.750  0.188 0.750  0.188 0.776  0.204 0.776  0.188 0.776  
+	0.188 0.802  0.204 0.802  0.188 0.802  0.188 0.828  0.221 0.828  
+text 0.19, 0.83, '20'
+polyline np=15, xmin=0.19,xmax=0.22,xavg=0.19, ymin=0.83,ymax=0.96,yavg=0.90
+	0.188 0.828  0.188 0.854  0.204 0.854  0.188 0.854  0.188 0.880  
+	0.204 0.880  0.188 0.880  0.188 0.906  0.204 0.906  0.188 0.906  
+	0.188 0.932  0.204 0.932  0.188 0.932  0.188 0.958  0.221 0.958  
+text 0.19, 0.96, '25'
+polyline np=2, xmin=0.19,xmax=0.19,xavg=0.19, ymin=0.96,ymax=0.96,yavg=0.96
+	0.188 0.958  0.188 0.958  
+polyline np=65, xmin=0.19,xmax=0.81,xavg=0.50, ymin=0.92,ymax=0.96,yavg=0.95
+	0.188 0.958  0.188 0.958  0.188 0.925  0.188 0.958  0.219 0.958  
+	0.219 0.942  0.219 0.958  0.250 0.958  0.250 0.942  0.250 0.958  
+	0.281 0.958  0.281 0.941  0.281 0.958  0.313 0.958  0.313 0.941  
+	0.313 0.958  0.344 0.958  0.344 0.925  0.344 0.958  0.375 0.958  
+	0.375 0.941  0.375 0.958  0.406 0.958  0.406 0.941  0.406 0.958  
+	0.437 0.958  0.437 0.941  0.437 0.958  0.469 0.958  0.469 0.941  
+	0.469 0.958  0.500 0.958  0.500 0.925  0.500 0.958  0.531 0.958  
+	0.531 0.941  0.531 0.958  0.562 0.958  0.562 0.941  0.562 0.958  
+	0.593 0.958  0.593 0.941  0.593 0.958  0.625 0.958  0.625 0.941  
+	0.625 0.958  0.656 0.958  0.656 0.924  0.656 0.958  0.687 0.958  
+	0.687 0.941  0.687 0.958  0.718 0.958  0.718 0.941  0.718 0.958  
+	0.750 0.958  0.750 0.941  0.750 0.958  0.781 0.958  0.781 0.941  
+	0.781 0.958  0.812 0.958  0.812 0.924  0.812 0.958  0.812 0.958  
+set_text up=90, path=right, hjustify=center, vjustify=bottom, font=roman,
+	size=1.00, spacing=0.00, color=1, quality=normal
+text 0.50, 0.96, 'title'
+set_polyline ltype=1, lwidth=1.00, color=1
+polyline np=5, xmin=0.19,xmax=0.69,xavg=0.44, ymin=0.33,ymax=0.96,yavg=0.59
+	0.188 0.334  0.313 0.412  0.438 0.542  0.562 0.724  0.687 0.958  
+flush
+close_workstation 'vt640'
+.fi
+
+
+.nh 2
+Graphics Kernel Parameters
+
+    The translation from GKI codes to device codes should ideally be
+parameterized to permit variable device resolution, font substitution,
+and so on at translation time.  In general this is best handled by
+spooling the metacode and later processing it via an explicit call to
+a metacode translator program, using CL parameters to control the translation.
+Some control over translation may also be achieved by modifying the
+\fBgraphcap\fR entry for a device, provided the graphics kernel uses
+the graphics capability database.
+
+One of the most useful translation time parameters is the device resolution.
+On some devices, e.g. pen plotters, it is necessary to be able to change
+the device resolution at translation time to permit plotting of large vectors
+without loss of resolution.  Changing the device resolution is also a valuable
+technique for speeding up graphics when working remotely via a modem.
+
+.nh
+GKS Emulation
+
+    The basic graphics primitives provided by GIO (polyline, polymarker, etc.)
+are functionally identical to those provided by GKS (the Graphics Kernel
+System).  The basic drawing primitives of GKS are therefore easily emulated
+using GIO.  A subset of the Fortran binding of GKS has already been emulated,
+sufficient to run the NCAR utilities recently converted by NCAR for use with
+GKS.  In principle it should be possible to expand the GKS emulation to a
+full level 0b or 1b interface, although we have no plans to do so at present.