Graphical Devices
=================

The `g D' (`calc-graph-device') command sets the device name (or
"terminal name" in GNUPLOT lingo) to be used by `g p' commands on this
graph.  It does not affect the permanent default device name.  If you
enter a blank name, the device name reverts to the default.  Enter `?' 
to see a list of supported devices.

With a positive numeric prefix argument, `g D' instead sets the
default device name, used by all plots in the future which do not
override it with a plain `g D' command.  If you enter a blank line
this command shows you the current default.  The special name
`default' signifies that Calc should choose `x11' if the X window
system is in use (as indicated by the presence of a `DISPLAY'
environment variable), or otherwise `dumb' under GNUPLOT 3.0 and
later, or `postscript' under GNUPLOT 2.0.  This is the initial default
value.

The `dumb' device is an interface to "dumb terminals," i.e., terminals
with no special graphics facilities.  It writes a crude picture of the
graph composed of characters like `-' and `|' to a buffer called
`*Gnuplot Trail*', which Calc then displays.  The graph is made the
same size as the Emacs screen, which on most dumb terminals will be
80x24 characters.  The graph is displayed in an Emacs "recursive
edit"; type `q' or `M-# M-#' to exit the recursive edit and return to
Calc.  Note that the `dumb' device is present only in GNUPLOT 3.0 and
later versions.

The word `dumb' may be followed by two numbers separated by spaces.
These are the desired width and height of the graph in characters.
Also, the device name `big' is like `dumb' but creates a graph four
times the width and height of the Emacs screen.  You will then have to
scroll around to view the entire graph.  In the `*Gnuplot Trail*'
buffer, SPC, DEL, `<', and `>' are defined to scroll by one screenful
in each of the four directions.

With a negative numeric prefix argument, `g D' sets or displays the
device name used by `g P' (`calc-graph-print').  This is initially
`postscript'.  If you don't have a PostScript printer, you may decide
once again to use `dumb' to create a plot on any text-only printer.

The `g O' (`calc-graph-output') command sets the name of the output
file used by GNUPLOT.  For some devices, notably `x11', there is no
output file and this information is not used.  Many other "devices"
are really file formats like `postscript'; in these cases the output
in the desired format goes into the file you name with `g O'.  Type `g
O stdout RET' to set GNUPLOT to write to its standard output stream,
i.e., to `*Gnuplot Trail*'.  This is the default setting.

Another special output name is `tty', which means that GNUPLOT is
going to write graphics commands directly to its standard output,
which you wish Emacs to pass through to your terminal.  Tektronix
graphics terminals, among other devices, operate this way.  Calc does
this by telling GNUPLOT to write to a temporary file, then running a
sub-shell executing the command `cat tempfile >/dev/tty'.  On typical
Unix systems, this will copy the temporary file directly to the
terminal, bypassing Emacs entirely.  You will have to type `C-l' to
Emacs afterwards to refresh the screen.

Once again, `g O' with a positive or negative prefix argument sets the
default or printer output file names, respectively.  In each case you
can specify `auto', which causes Calc to invent a temporary file name
for each `g p' (or `g P') command.  This temporary file will be
deleted once it has been displayed or printed.  If the output file
name is not `auto', the file is not automatically deleted.

The default and printer devices and output files can be saved
permanently by the `m m' (`calc-save-modes') command.  The default
number of data points (see `g N') and the X geometry (see `g X') are
also saved.  Other graph information is *not* saved; you can save a
graph's configuration simply by saving the contents of the `*Gnuplot
Commands*' buffer.

If you are installing Calc you may wish to configure the default and
printer devices and output files for the whole system.  The relevant
Lisp variables are `calc-gnuplot-default-device' and `-output', and
`calc-gnuplot-print-device' and `-output'.  The output file names must
be either strings as described above, or Lisp expressions which are
evaluated on the fly to get the output file names.

Other important Lisp variables are `calc-gnuplot-plot-command' and
`calc-gnuplot-print-command', which give the system commands to
display or print the output of GNUPLOT, respectively.  These may be
`nil' if no command is necessary, or strings which can include `%s' to
signify the name of the file to be displayed or printed.  Or, these
variables may contain Lisp expressions which are evaluated to display
or print the output.

The `g x' (`calc-graph-display') command lets you specify on which X
window system display your graphs should be drawn.  Enter a blank line
to see the current display name.  This command has no effect unless
the current device is `x11'.

The `g X' (`calc-graph-geometry') command is a similar command for
specifying the position and size of the X window.  The normal value is
`default', which generally means your window manager will let you
place the window interactively.  Entering `800x500+0+0' would create
an 800-by-500 pixel window in the upper-left corner of the screen.

The buffer called `*Gnuplot Trail*' holds a transcript of the session
with GNUPLOT.  This shows the commands Calc has "typed" to GNUPLOT and
the responses it has received.  Calc tries to notice when an error
message has appeared here and display the buffer for you when this
happens.  You can check this buffer yourself if you suspect something
has gone wrong.

The `g C' (`calc-graph-command') command prompts you to enter any line
of text, then simply sends that line to the current GNUPLOT process.
The `*Gnuplot Trail*' buffer looks deceptively like a Shell buffer but
you can't type commands in it yourself.  Instead, you must use `g C'
for this purpose.

The `g v' (`calc-graph-view-commands') and `g V'
(`calc-graph-view-trail') commands display the `*Gnuplot Commands*'
and `*Gnuplot Trail*' buffers, respectively, in another window.  This
happens automatically when Calc thinks there is something you will
want to see in either of these buffers.  If you type `g v' or `g V'
when the relevant buffer is already displayed, the buffer is hidden
again.

One reason to use `g v' is to add your own commands to the
`*Gnuplot Commands*' buffer.  Press `g v', then use
`C-x o' to switch into that window.  For example, GNUPLOT has
`set label' and `set arrow' commands that allow you to
annotate your plots.  Since Calc doesn't understand these commands,
you have to add them to the `*Gnuplot Commands*' buffer
yourself, then use `g p' to replot using these new commands.  Note
that your commands must appear *before* the `plot' command.
To get help on any GNUPLOT feature, type, e.g., `g C help set label'.
You may have to type `g C RET' a few times to clear the
"press return for more" or "subtopic of ..." requests.
Note that Calc always sends commands (like `set nolabel') to
reset all plotting parameters to the defaults before each plot, so
to delete a label all you need to do is delete the `set label'
line you added (or comment it out with `#') and then replot
with `g p'.

You can use `g q' (`calc-graph-quit') to kill the GNUPLOT process that
is running.  The next graphing command you give will start a fresh
GNUPLOT process.  The word `Graph' appears in the Calc window's mode
line whenever a GNUPLOT process is currently running.  The GNUPLOT
process is automatically killed when you exit Emacs if you haven't
killed it manually by then.

The `g K' (`calc-graph-kill') command is like `g q' except that it
also views the `*Gnuplot Trail*' buffer so that you can see the
process being killed.  This is better if you are killing GNUPLOT
because you think it has gotten stuck.