Initial commit

1 files changed, 671 insertions, 0 deletions

diff --git a/pkg/language/doc/cursors.hlp b/pkg/language/doc/cursors.hlp
new file mode 100644
index 00000000..2e04dd03
--- /dev/null
+++ b/pkg/language/doc/cursors.hlp
@@ -0,0 +1,671 @@
+.help cursors May93 language
+.ih
+NAME
+cursors -- cursor control for graphics and image display devices
+
+.nh
+Introduction
+
+    In IRAF, all cursor input is via the graphics cursor interface in the CL.
+The CL supports two types of cursors, the graphics cursor and the image
+display cursor, represented in the CL by the two parameter datatypes \fIgcur\fR
+and \fIimcur\fR.  To read either cursor from a task, the programmer declares
+one of the parameters of their task to be of type gcur or imcur, and then
+reads the value of the parameter.  The act of reading a cursor type parameter
+causes the physical device cursor to be read.  To make it possible for the
+user to read either cursor at any time, the CL provides two predefined global
+parameters also called \fIgcur\fR and \fIimcur\fR (or to be more precise,
+"cl.gcur" and "cl.imcur", since both parameters are local parameters of the
+\fIcl\fR task).
+
+Since the graphics cursors are interfaced as CL parameters, a cursor read is
+implied whenever a cursor type parameter is referenced in a CL expression.
+The simplest way to read a cursor is to use the "inspect" statement to print
+the value of the parameter, as in the following example.  Exactly the same
+thing happens when a program like \fIimplot\fR or \fIsplot\fR reads the cursor.
+
+.nf
+	cl> = gcur
+	0.5005035 0.4980621 1 k 
+.fi
+
+More complex accesses are occasionally useful, e.g.:
+
+	cl> print (gcur, > "curpos")
+
+writes the cursor value into a file, and
+
+	cl> = fscan (gcur, x, y)
+
+leaves the X and Y coordinates of the cursor in parameters X and Y.
+
+A cursor read returns a string value, as can be seen in the above example.
+The fields of the cursor value string are (from the left) the X and Y position
+of the cursor in world coordinates, the number of the world coordinate system
+to which the coordinates refer, and the key value, or character typed to
+terminate the cursor read.  If the key is a colon (":"), a fourth field
+will be added, namely a character string entered by the user after typing the
+colon key.  This feature is useful for passing arbitrary commands to programs
+via the cursor interface.
+
+A cursor read is not instantaneous.  A cursor read is initiated by reading a
+cursor type parameter, and terminated by typing any lower case or
+non-alphanumeric character on the keyboard.  The keyboard is used to
+terminate cursor reads from the image display as well as from a graphics
+terminal.  While the cursor read is in progress, i.e., while the CL is
+waiting for a key to be typed on the terminal, the CL is said to be in
+\fIcursor mode\fR.  Cursor mode reserves all of the upper case characters
+and digits for cursor mode commands.  Since the cursor mode commands are
+intercepted by cursor mode, they do not terminate a cursor read and are never
+seen by the program reading the cursor.
+
+The cursor mode commands are the major topic of discussion in the remainder
+of this document.  In brief, the cursor mode commands are used to zoom in
+on some portion of the graphics frame (e.g., to get a more accurate cursor
+position measurement), to roam about at high magnification, to replot the frame,
+to make a hardcopy on a batch plotter device, to save or restore the frame in
+a file, and so on.  In reading the rest of this document, take care not to get
+lost in the complexities of cursor mode, forgetting the essential simplicity
+of the cursor interface, namely that we are reading the cursor and returning
+the cursor coordinates to the caller.
+
+In the remainder of this document the discussion will focus on the graphics
+cursor to minimize confusion.  The same interface is however used to access
+both types of cursor, hence the discussion is relevant for the image display
+interface as well.
+
+.nh
+Overview
+.nh 2
+Invoking Cursor Mode
+
+    Many IRAF tasks produce a plot of some sort and then bring up a graphics
+cursor (e.g. a crosshair) and automatically leave the terminal in cursor mode.
+Alternatively, the user can invoke cursor mode from the CL by typing:
+
+	cl> = gcur
+
+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
+speed up drawing time you could set text quality to low and the
+graphics resolution to 200 points in X and 100 points in Y by adding
+the following \fBset\fR declaration to one's "login.cl" file:
+
+	set cminit = "xres=200; yres=150; txqual=low"
+
+An additional environment variable is provided for applications which generate
+very complex plots.  There is a fixed upper limit on the size of the cursor
+mode frame buffer, used to retain all the graphics instructions used to
+generate a plot.  If the buffer overflows the plot will come out correctly
+the first time, but part of the instructions used to generate the plot will be
+discarded, hence it will not be possible to regenerate the full plot in cursor
+mode.  If this happens the size of the cursor mode frame buffer may be
+increased, e.g.,
+
+	set cmbuflen = 512000
+
+would set the size of the frame buffer to 512K words, or 1 megabyte.
+This would be large enough to hold almost any plot.  A call to \fBgflush\fR
+may be required before the new buffer size takes effect.
+
+.nh 2
+Cursor Mode Help
+
+    While in cursor mode, help text may be obtained in at least two ways.
+Help on the cursor mode commands themselves, i.e. the topic of this
+document, is available with the command ":.help" or just ":.".  By convention
+help on an application task running cursor mode, e.g. \fBimplot\fR, is 
+available with the command "?".  All interactive IRAF graphics tasks are
+required to respond to the ? key with a summary of the keystrokes recognized
+by that task.
+
+.nh 2
+Cursor Mode Commands and Options
+
+    While in cursor mode, whether invoked by an IRAF task or interactively
+via the command "=gcur", three classes of commands are available.
+First, single, upper-case letters take actions such as roaming and zooming,
+redrawing axes after a zoom, and prompting for text annotation.
+Second, cursor mode options and more complicated commands may be entered
+after a ":.", for example sending a screen snapshot to a hardcopy plotter
+and changing text quality and orientation.  Third, all other commands,
+namely the lower case letters and most non-alphanumeric characters,
+are interpreted by the controlling task and will terminate a cursor read.
+Thus, if any keystroke is entered that is not shown below or handled by
+the governing application program, cursor mode exits and the keystroke and
+cursor coordinates are reported.
+
+Minimum match abbreviations are permitted for the cursor mode ":."
+command names.  Multiple commands may be given on one line, delimited by
+semicolons.
+
+The following upper-case commands are interpreted by the graphics system
+and may therefore be entered from the keyboard either in task mode or from
+"=gcur" (this is the same help panel you get from cursor mode by
+typing ":.help"):
+
+.nf
+    A 			draw and label the axes of current viewport
+    B			backup over last instruction in frame buffer
+    C			print the cursor position
+    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
+    =			short for ":.snap"
+    0			reset and redraw
+   1-9			roam
+.fi
+
+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.  Command
+lines which begin with a period, e.g., ":." are interpreted by the graphics
+system; any other command will terminate the cursor read.  If not running an
+IRAF task which interprets that other command, cursor mode will be
+terminated and the cursor value reported.
+
+.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
+    :.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
+
+.nh
+Advanced Usage
+.nh 2
+The Frame Buffer
+    
+    The concept of the \fIframe buffer\fR is essential to an understanding of
+cursor mode.  IRAF tasks output all graphics in the form of GKI 
+metacode instructions.  These instructions may be stored in a file if
+desired, or, if the task is run from the CL, they will usually be 
+stored automatically in the frame buffer.  This is a large storage area internal
+to the CL process, and is transparent to the user.  What is important is
+that after producing a plot on the screen, all or part of the information
+in the plot is still present in the frame buffer.  That means that it is
+possible to enter an interactive session with the plot, whether as a part of
+the task that produced the plot in the first place or after the task
+exits by typing "=gcur" from the CL.
+
+If one wishes to recall the last plot after the task which created it has
+exited, and the screen has since been cleared, the plot will still be in
+the frame buffer and can be redrawn by entering cursor mode and typing 0
+(the digit zero).  If the desired plot was not the last one plotted,
+hence is no longer in the frame buffer, it can still be recalled if it
+was saved earlier in a metacode file on disk.  The command ":.read fname"
+will refill the frame buffer from file "fname", and redraw the plot.
+
+All graphics instructions output since the last time the device screen was
+cleared reside in the frame buffer unless there is an extremely large amount
+of information in the plot, in which case only the last part of the plot
+will be saved (the frame buffer dynamically sizes itself to fit the frame,
+but there is a fixed upper limit on its size of about 100 Kb).
+
+.nh 2
+Filling and Writing the Frame Buffer
+
+    The graphics system will automatically clear the frame buffer whenever
+the screen is cleared when plotting.  For example, in a heavy interactive
+graphics session, the frame buffer will be filled and cleared many times,
+and at the end only the last screenfull will be left in the frame buffer.
+When reading a metacode file containing several frames with ":.read",
+all frames will be plotted in sequence, but only the last one will remain
+in the buffer when the sequence finishes.
+
+Some tasks have application-specific functions that append to, rather than
+overwrite the frame buffer.  For example, the "j" function in \fBimplot\fR
+plots another line from the image.  On the screen the previous data vectors
+are erased and the new ones drawn over.  However, if you then do a zoom or
+a reset screen, you will see EACH of the sets of data vectors drawn in
+succession (some people unfairly consider this to be a bug, but actually it
+is a highly desirable feature which we are justifiably proud of).  
+
+The contents of the frame buffer may be written to a metacode file
+with ":.write file".  By default the frame buffer is appended to the
+file if it already exists.  If you wish to "clobber" an existing file,
+use ":.write! file".  Also by default, the frame that is written is what
+you currently see on the screen, i.e., if you have zoomed in on a feature
+only what you see on the screen will be saved.  To write the full frame
+(the one you would see if you first did a "0"), use ":.write+ file".
+To overwrite an existing metacode file in full-frame mode, use ":.write!+ file".
+
+.nh 2
+Moving the Cursor and Modifying the Display Area
+
+    A number of special keystrokes are recognized for interactive
+display control.  These 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 often 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 a cursor read by the same factor.
+
+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 ("A") 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.  New axes may optionally be drawn
+every time the viewport changes after entry of the command ":.axes+".
+In cursor mode the viewport is the full display area of the output device,
+hence the tick mark labels of the drawn axes are drawn inside the viewport,
+on top of the data.
+
+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.
+Most of the upper-case commands involve moving the graphics cursor
+and/or re-displaying a different part of the plot.  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).  These keystrokes will only work if the terminal
+you are using permits positioning of the cursor under software control.
+
+The commands H, J, K, and L (upper case!) move the cursor left, down, up,
+and right (as in the VI text editor and in Forth/Camera graphics).
+The step size of each cursor motion can change in one of three ways.
+"F" increases the step size by a factor over the current step size each
+time it is used; "V" decreases it similarly.
+
+In practice the F/V speed keys are rarely used because the cursor positioning
+algorithm will automatically adjust the step size as you move the cursor.
+A large step size is used to cross the screen, then the step size is
+automatically decreased as you get close to the desired feature.
+Some practice is required to become adept at this, but soon it becomes
+natural and fast.
+
+Arrow keys, thumbwheels, etc., if present on a keyboard, may also be used
+for cursor motions.  However, moving the cursor this way does not
+automatically report the position to the graphics system, thus if the
+command "C" is given, you will not get a position report after each motion.  
+
+The numeric keypad of the terminal (if it has one) is used to roam about
+when the zoom factor is greater than one.  A numeric key must be escaped
+to use it to exit cursor mode, i.e., if the applications program reading
+the cursor recognizes the digit characters as commands.
+The directional significance of the numeric keys in roam mode is obvious
+if the terminal has a keypad, and is illustrated below.
+
+
+.nf
+	7   8   9	135 090 045
+
+	4   5   6	180 000 000
+
+	1   2   3      -135 -90 -45
+.fi
+
+
+Even if the terminal has a keypad, it may not be possible to use it for
+roam on some terminals.  If the keypad does not work, the normal numeric
+keys at the top of the keyboard will, after a glance at the keypad to
+see which digit to use.
+
+.nh 2
+Reporting and Marking the Cursor Position
+
+    To print the current cursor position in world coordinates without
+exiting cursor mode use the `C' keystroke.
+
+If the cursor mode option ":.markcur+" is set, the position of the cursor
+will be marked with a small plus sign when time cursor mode exits,
+returning the cursor position to the calling program.  This is useful
+when marking the positions of a large number of objects, to keep track
+of the objects already marked.  The cursor position will not be marked until
+cursor mode exits, i.e., no cursor mode command will cause the mark to be
+drawn.  The mark cursor option remains in effect until you explicitly turn
+it off with ":.markcur-" or by typing \fIgflush\fR.  The marks are drawn
+in the frame buffer, hence they will survive zoom and roam or screen reset
+(they can be erased with repeated B commands if desired).
+
+Some plots have more than one world coordinate system (WCS, the third value
+in the cursor value string).  Suppose you are in cursor mode and the frame
+contains two separate plots, or there is only one plot but the lower x-axis
+is in Angstroms while the upper one is in inverse centimeters.  By default
+the graphics system will automatically select the WCS (viewport) closest to
+the position of the cursor, returning a cursor position in that coordinate
+system.  If this is not what is desired, move the cursor to a position
+that belongs unambiguously to one of the coordinate systems and type "W".
+Subsequent cursor reads will refer to the coordinate system you have
+specified, regardless of the position of the cursor on the screen.
+When the frame is cleared the WCS "lock" will be cleared as well.
+
+.nh 2
+Annotating Plots
+
+    The "T" command will prompt you for a text string to be entered from the
+keyboard, followed by a RETURN.  The text will appear on the screen (and get
+stored in the frame buffer), normally located with its lower left corner at
+the current cursor position.  This command may be used in conjunction with
+the "D" command to draw a line from the text annotation to a feature of
+interest in the plot.  Notice that the text size is constant in cursor
+mode regardless of the current magnification.  In order that text entered
+with "T" will look as nearly the same as possible on a hardcopy snapshot
+as it does on the screen, you should set text quality to high.
+
+Text attributes are controlled by two command options.  Use ":.txqual" to
+set text quality to "normal" (the default), "low", "medium", or "high".
+Low-quality text plots the fastest, high-quality the slowest.  On terminals
+with hardware text generation such as the Retro-Graphics Enhanced VT100,
+low-quality characters may always come out 
+upright, even if the whole text string's up-vector is not at 90 degrees.
+
+Low-quality text sizes are also fixed on most devices, so in a hardcopy
+snapshot of a plot the text will not necessarily look the same as it did
+on the screen (in particular it may overwrite data vectors).
+With low-quality text other options such
+as "font=italic" will not work on most terminals (although they may come
+out correctly on a hardcopy device).  In general, set ":.txqual=h" if you are
+planning to get hardcopy output from a plot you are annotating.  Changing
+the text quality only applies to text entered with "T" AFTER the change;
+you cannot automatically set all text to high quality after you have 
+entered it.
+
+There are several ways to change the position of text relative to the
+cursor, its size, font, and orientation.  Use ":.txset" to change the
+text drawing parameters as follows:
+.nf
+
+    keyword	values					default
+
+    up		degrees counterclockwise, zero = +x	90
+    size	character size scale factor		1.0
+    path	left, right, up, down			right
+    hjustify	normal, center, left, right		left
+    vjustify	normal, center, top, bottom		bottom
+    font	roman, greek, italic, bold		roman
+    quality	normal, low, medium, high		normal
+    color	integers greater than one		1
+
+.fi
+The "up" keyword controls the orientation of the character and the whole
+text string.  A text string oriented at +45 degrees to the horizontal, 
+from left to right, would have "up=135".
+
+Character sizes are all specified relative to a base size characteristic
+of each plotting device.  The size is a linear magnification factor, so
+"size=2.0" results in a character with four times the area.
+
+Path is relative to the up vector; a string of characters consecutively
+underneath each other with the normal upright orientation would have 
+"up=90;path=down".
+
+The justify parameters refer to the placement of the entire text string
+relative to the current cursor position.  To center a text string horizontally
+over a spike in a plot, position the cursor to just above the spike and
+set "h=c;v=b".
+
+Font and quality were discussed above.  Setting the color will only have
+an effect on devices supporting it; if you have a color pen plotter, you
+must remember the current color setting, because there you cannot see it
+on the screen (":.show" will reveal it however).
+
+If you make a mistake or don't like the appearance of the text you entered,
+all is not lost.  Use the command "B" to back up over the last instruction
+and redraw (e.g. with "0") until you're ready to reenter the text.  If you
+back up one instruction too far (you lose some of the data vectors for
+instance) just type "U" to undo the last frame buffer edit, i.e. the backup.
+
+For example, to annotate a spectral line with "H-alpha", written sideways
+up the screen from the current position in italics:
+.nf
+
+	:.txqual high
+	:.txset up=180;font=italic
+	T
+	text: H-alpha
+
+.fi
+On the last line, cursor mode provided the "text: " prompt.  The
+format could have been shortened to "u=180;f=i".
+
+.nh 2
+Hardcopy Snapshots
+
+    There are two main ways to get a hardcopy of the frame buffer.  To 
+get a copy of what you see on the screen directly on a hardcopy plotter,
+simply use ":.snap plottername".  When you do so, you are actually sending
+the output down a buffered stream.  That is, you can do several ":.snap"'s
+before anything actually comes out on the plotter.  This is because many
+plotters use several pages worth of blank paper before and after the actual
+plot.  If you are planning to make a number of snapshots in succession,
+even if they are from different "=gcur" sessions, simply use ":.snap" for
+each one until you are done, then issue ":.gflush".  You can also flush
+graphics output to a plotter from the CL using the Language Package task
+\fBgflush\fR:
+
+.nf
+	cl> =gcur
+	...
+	:.snap versatec
+	...
+	:.snap versatec
+	<RETURN>
+	cl>
+	cl> gflush
+
+.fi
+
+Alternatively, you can use ":.write mcodefile" as discussed above, appending
+as many different frames as you wish, then later from the CL, send the
+metacode file to a plotter with one of the graphics kernels:
+
+.nf
+	cl> implot
+	...				(interactive session)
+	:.write file1.mc
+	<RETURN>
+	cl> stdplot file1.mc
+
+		or
+
+	cl> calcomp file1.mc		(etc.)
+
+.fi
+
+.nh 2
+Alternate Cursor Input
+
+    Any program which uses cursor input may be run non-interactively as well
+as in batch mode.  For example, suppose the task has a cursor type parameter
+called "coords".  In normal interactive use a hardware cursor read will
+occur every time the program reads the value of the "coords" parameter.
+To run the program in batch mode we must first prepare a list of cursor
+values in a text file, e.g., with the \fIrgcursor\fR or \fIrimcursor\fR tasks
+in the \fIlists\fR package.  We then run the task assigning the name of the
+cursor list file to the parameter "coords".  For example, to run the
+\fIapphot\fR task in batch, with the cursor list in the file "starlist":
+
+	cl> apphot arg1 arg2 ... argN coords=starlist &
+
+The program will then read successive cursor values from the starlist file,
+not knowing that the cursor values are coming from a text file rather than
+from actual cursor reads.
+
+A second mechanism is available for redirecting cursor input to the
+terminal.  This is most useful when working from a terminal that does not
+have graphics, or when debugging software.  To work this way one must
+first set the value of the environment variable \fIstdgcur\fR (for the
+graphics cursor) or \fIstdimcur\fR (for the image cursor).  Set the value
+to "text" to direct cursor reads to the terminal, e.g.:
+
+	cl> set stdgcur = text
+
+The cursor value will then be 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).
+
+.nf
+	cl> = gcur
+	gcur: 345.33 23.22 1 c
+	345.33 23.22 1 c
+	cl>
+.fi
+
+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.
+
+.nf
+	cl> = gcur
+	345.33 23.22 1 c
+	cl>
+.fi
+
+Redirecting cursor input to the terminal is useful when working from a
+non-graphics 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:
+
+.nf
+	cl> gcur = filename
+	cl> = gcur
+	345.33 23.22 1 c
+	cl>
+.fi
+
+.nh 2
+Examining the Status of the Graphics System
+
+    The command ":.show" writes out a page of information concerning the
+state of the graphics system.  This is an example of such a status report:
+
+.nf
+    Cursor Mode Parameters:
+
+	case	= YES
+	markcur = YES
+	page	= YES
+	axes	= NO
+	view	= full screen
+	keys	= ABCDEFGHIJKLMNOPQRSTUVWXYZ<>0123456789?:
+		->ABCDEFGHIJKLMNOPQRSTUVWXYZ<>0123456789?:
+
+
+    Graphics Kernel Status:
+
+	STDGRAPH: kernel=cl, device=vt640
+	    memory=9472 (8192fb+256sb+1024fio), frame=1114+0 words
+	    spool=yes, nopen=0, pid=0, in=0, out=0, redir=-6, wcs=0
+	    text size = 1., up=90, path=right, hj=left, vj=bottom, color=1
+
+	STDIMAGE:	disconnected
+	STDPLOT:	disconnected
+.fi
+
+The cursor mode parameters report the current values of the ":." command
+options; these options are in effect for all of three the standard graphics
+streams, i.e., STDGRAPH (the graphics terminal), STDIMAGE (the image display),
+and STDPLOT (batch plotters).
+
+The graphics kernel status reports the status of each of the three graphics
+streams.  These streams are independent and in principle any graphics device
+may be connected to any stream.  The \fIkernel\fR field gives the name of
+the kernel connected to that stream, if any.  The value "cl" refers to the
+\fIstdgraph\fR kernel, which is built into the CL, and which can only talk
+to graphics terminals.  Any other value is the filename of an external graphics
+kernel, running as a subprocess of the CL process.  The \fIdevice\fR field
+gives the name of the device named in the last "open workstation" command
+on that stream.  This is the device the stream is currently writing plots to.
+
+The significance of the remaining kernel status fields is described below.
+
+
+.nf
+	memory		- total memory used, chars
+	fb		- size of primary frame buffer, chars
+	sb		- size of scratch frame buffer (used by A)
+	fio		- size of the FIO buffer for the stream
+	frame		- amount of data in the frame + data in SB
+
+	spool		- enable spooling of graphics in frame buffer?
+	nopen		- open count (should be zero)
+	pid		- process id of kernel subprocess
+	in		- fd of process in, if subkernel
+	out		- fd of process out, if subkernel
+	redir		- redirection information for pseudofile i/o
+	wcs		- current WCS, zero if not locked with W
+
+	text size	- current text size relative to device's base size
+	up		- text up vector
+	path		- text character drawing path
+	hj		- horizontal justification
+	vj		- vertical justification
+	color		- index of current color attribute
+.fi
+
+
+This status report reflects only the information known to the CL.  The graphics
+subkernels, which are subprocesses of the CL, may themselves have subprocesses,
+sometimes on different nodes in the local network.
+
+.nh 2
+Initializing the Graphics System
+
+    The graphics system can normally be initialized by typing \fIgflush\fR.
+This will clear the frame buffer and disconnect all kernels, freeing memory
+and file descriptors, and reducing the subprocess count.  Shutting down a
+graphics subkernel automatically flushes any buffered graphics output.
+The CL automatically calls \fIgflush\fR during logout to shutdown the
+graphics system in an orderly fashion.
+.ih
+BUGS
+Despite the fact that the CL has graphics and image cursor access capabilities,
+there is no guarantee that one can access the cursor on a particular device.
+A \fIgraphcap\fR entry for the device is also required, as is a graphics kernel
+if the device is not a conventional graphics terminal (e.g., an image display).
+If all of these pieces are not in place, the system will abort the cursor
+read, complaining that it cannot find a termcap or graphcap entry for the
+device, or that it cannot open a connected subprocess (the subkernel).
+.ih
+SEE ALSO
+The GIO Reference Manual
+.endhelp