This is the README file for YPLOT, a Yorick interface to PLPlot.

PREAMBLE
-------------------------------------------------------------------------
YPLOT is meant to be a useful tool in creating scientific plots of both
draft and publication quality very quickly and efficiently.
That said, it should be realised that most of this usefulness comes from
Yorick and PLPlot, so thanks to their respective creators and maintainers.
Most of what YPLOT can do is due to the fact that David Munroe wrote Yorick
to be extensible by linking external object files to the Yorick interpreter.
Thanks!

YPLOT facilities
-------------------------------------------------------------------------
At this stage YPLOT implements a subset of the (extensive) capabilities of
the PLPlot library. That said, most of the high level API is available
directly to the user, with some extra functions added for reading data
from files. More functions can easily be added on request or contribution.

So, YPLOT can do the following in the hands of even an inexperienced user:
o Access to all the capabilities of Yorick. Do all your data generation,
  interpretation and plotting from one package.
o Linear plots
o Log-log plots, with any variations of log and linear axes possible
o 3D surface and mesh plots (there is a difference, really ;-)
o 3D line and scatter 
o Grid lines
o Lots of symbols and stroked fonts to choose from, all scalable
o Full control over boxes drawn, captions, fonts and placement of labels
o Speed: A YPLOT plot finishes in about 3 times that of the corresponding
  compiled C version. Huh? Doesn't sound very fast, until you factor in the
  compiling time and development time (which can be VERY long if your C is
  not quite up to scratch. Like mine :-)
o Fast development due to the the interpreted nature of YPLOT
o Lots of output devices, including X11, Postscript, Laserjet printers, and
  PLPlot metafiles for later rendering.
o PLUS: a tutorial and reference manual that demonstrates most of YPLOT's
  capabilities with explanations every step of the way!

Note on Landscape and Portrait plotting
----------------------------------------------------------------------------
PLPlot was designed to plot in landscape mode. Period. (OK, so you can get
it to plot in Portrait mode, but this aspect ratio is still that of a
Landscape plot)

For that reason, I include my own hacks of the PLPlot drivers ps.c and
ljiip.c to enable you to compile PLPlot to produce Portrait Postscript and
Laserjet files. During the build stage, these files are compiled and linked
as part of the yplot command but are not part of the link to create the
yplotl command.  Thus if you prefer the vanilla landscape mode for Postscript
and Laserjet files use yplotl.


DEMOS
----------------------------------------------------------------------------
The doc subdirectory contains a few examples to show off YPLOT.
After installing, run these with eg.
yplot -batch demo1.i

Near the top of each of these files is a driver specification, of the form 
"xwin" or "ps" for the X11 or Postscript drivers. Change this to one of the
PLPlot devices according to what is available to you.  (See the file DEVICES
in this directory.)  Note that if you create a plplot metafile "plmeta", you
can change it to any of the other available devices using the plrender
command from the plplot package.  (plrender -h gives help with this command.)

Important Documentation
----------------------------------------------------------------------------
README   This file.
INSTALL  How to build and install yplot and yplotl.
DEVICES  Choices given by plrender command for all possible plplot output devices.
CHANGES  Important changes to the API
doc/*.i  yplot scripts for demos.
doc/ytut.[tex, dvi, ps]  Detailed tutorial for yplot.
yplot itself  While running yplot or yplotl interactively you can get help on
  all yplot and yorick commands by issuing help, commandname.
doc/yplot.doc  Listing generated by yorick mkdoc command of all yplot help.
info yorick gives extensive help on yorick
info plplot gives dated but useful information on plplot

Bugs and patches and support
---------------------------------------------------------------------------
"Correct them, send them, and don't expect any" ;-)

Seriously:
If you find any serious bugs, do the following:
o Try really hard to find out if it isn't your own fault.
o If you are able, try and correct the problem in either read.c, pplot.c or
  yplot_body.i or the Makefile.build (that's my only contribution actually)
o Send me a discription of the problem and any diffs (see man diff) you may
  come up with.
o I will try my best to solve the problem or incorporate your fix.

That said, YPLOT has been in daily use for some time at the SRU without any
and is considered quite stable.

If you would like to do any work on extending YPLOT, go ahead make my month!
Look at the files read.c, pplot.c and yplot.i for examples. It really isn't
very complicated, even I could understand it...

Please...
---------------------------------------------------------------------------
If you find YPLOT useful, please drop me an e-mail. It helps justify the
time I spent developing YPLOT when I should have been doing serious
research.

Conrad Steenberg <conrad@srl.caltech.edu>
20 February 1999
