This file contains a list of the major changes in PLPLOT.  It is best to look
through this file for new features, etc, until the new documentation is
complete.

*****************************************************************************
PLPLOT 4.99c changes
*****************************************************************************

o Added capability to have viewports greater than the display area.  In
this case the display becomes a window into the plot (i.e. the plot is
magnified).  The -mar, -jx, and -jy options of plrender were modified
to allow use of this.  Namely, specifying a negative argument for -mar
will enlarge the plot.  A "-mar -1 -jx 0 -jy 0" will result in the lower
left hand corner being plotted.  Probably -mar will be dropped from future
versions of plrender in favor of a more descriptive flag like "scl" (which
will have the opposite effect as mar).  In a GUI driver this will be
handled more naturally through zoom and pan menu/mouse operations.

o Added "install" target to makefile for installing into /usr/local/plplot.
See sys/unix/README.unix for more details.

o Eliminated SWITCH_TO_TEXT and SWITCH_TO_GRAPH metafile commands from both
driver and renderer.  These are really not necessary when a metafile is
being used and can be aggravating when using the xterm driver.  

o Added support for NEC SX-3 supercomputer, other minor fixes.

o Fixed name conflict for getdate() in ps.c on some systems.

*****************************************************************************
PLPLOT 4.99b changes
*****************************************************************************

A rather minor update, and the last one for a few weeks probably (I have
other committments). 

o Plrender now does page forward/backward operations immediately, for drivers
that can process the keystroke in a non-blocking fashion (for now only xwin
and amiga screen drivers).  This way the user can skip forward/backward at an
arbitrary speed if looking for a particular plot, without having to wait
for each page to actually finish plotting.

o Drivers _clear/_page commands all changed to _eop/_bop (end of page,
beginning of page), since that more accurately reflects what's going on now.
Interactive drivers needed their screen clear moved to the _bop function to
make the above-mentioned enhancement of plrender work.

o Amiga drivers partially finished.  Screen driver has been reconstructed
using capabilities of Amiga 2.0 OS, and is much improved.  Some menu options
as of yet unimplemented.  Other drivers (printer, IFF) still need some work.


*****************************************************************************
PLPLOT 4.99a changes
*****************************************************************************

-----------------------------------
Plrender
-----------------------------------

 * Inserted a hack for old metafiles with bad linewidth commands (WIDTH
 * commands in the body of the metafile are now ignored for metafiles version
 * 1993a and older).  WIDTH commands prior to the INIT on old metafiles are
 * still honored.
 *
 * Changed orient-setting code to switch on the basis of orient%2 and orient%4,
 * so that any value of orient gives valid output.
 *
 * Changed to a fatal error when unrecognized metafile input is encountered.
 *
 * Converted to new plplot command-line handling functions, resulting in a
 * considerable reduction in the amount of actual code.  Miscellaneous bugs
 * in file seeking fixed.  Extraneous page printed on a -p command
 * eliminated.  Many other small improvements.
 *
 * Support for polylines (even converts connected lines while reading into
 * polylines for better response), new color model support, event handler
 * support.  New events recognized allow seeking to arbitrary locations in
 * the file (absolute or relative), and backward.  Some old capabilities (no
 * longer useful) eliminated.  
 * 
 * Seeking: when using an appropriate output driver (e.g. xwin), user
 * keyboard input results in the following:
 *
 * <Backspace>	|
 * <Delete>	| Back page
 * <Page up>	|
 *
 * +<num><CR>	Seek forward <num> pages.
 * -<num><CR>	Seek backward <num> pages.
 *
 * <num><CR>	Seek to page <num>.
 *
 * Both <BS> and <DEL> are recognized for a back-page since the target
 * system may use either as its erase key.  <Page Up> is present on some
 * keyboards (different from keypad key).  Note that <Page Down> and
 * <Return> are recognized by the driver itself to advance the page.
 *
 * Illegal input is ignored.  When using the xterm driver, <backspace>,
 * <delete>, <page up>, <page down> either are ignored or don't function
 * properly.
 *
 * Fixed orientation code, previously it rotated plot in the wrong direction.
 *
 * Gave plrender an ID tag.

-----------------------------------
Main sources
-----------------------------------

ALL CODE:

 * Massive reorganization and clean up.  Main source code now isolated to
 * about two dozen files.  Routines of similar function are stored in the
 * same file, e.g. all routines to create viewports are now in plvpor.c.
 * All support for non-ANSI (K&R) C compilers removed!  


Additional changes, listed by file: 

 * scstubs.c:
 * Converted to string-integer equivalence method for C-Fortran string
 * passing.


 * sccont.c:
 * New front-end for contours from fortran.  Does amazingly little work now,
 * just defines an appropriate function evaluator and coordinate transformers
 * and calls the main contour function.


 * plwind.c:
 * Now holds all routines dealing with window specification.


 * plvpor.c:
 * Now holds all routines dealing with viewport generation.


 * pltick.c:
 * Now holds all functions dealing with tick generation, including error
 * bars.


 * plsym.c:
 * Now holds all routines dealing with PLPLOT symbols.


 * plstring.c:
 * Added to hold all functions that deal with PLPLOT strings.
 * Split off code to write a stroke font character into its own function for
 * clarity.  Changed character-decoding routine to use stream-dependent escape
 * character in text strings.


 * plstream.c:
 * Added to hold functions that primarily deal with manipulation of stream
 * quantities, through a pointer to a stream passed as an argument.  You may
 * also think of it as a driver utility library.  Eliminated negative
 * orientations.  Changed orient-setting code to switch on the basis of
 * orient%4, so that any value of orient give valid output.


 * plsdef.c:
 * Holds functions that modify plplot defaults.  These do not need direct
 * access to the stream data.  Changed references in error messages from
 * plstar to plinit.  Also changed behavior of size-setting routines (should
 * not affect user code).  Fixed data structure initializers to be
 * ANSI-conformant.


 * plpage.c:
 * Now holds all page-related functions.
 * Changed references in error messages from plstar to plinit.  Also changed
 * pladv to call grclr and grpage (instead of gradv, now gone).


 * plot3d.c:
 * Now holds all routines dealing with 3d plots (and hence has become rather
 * large).  A capability similar to that in the contour plotter (passing
 * in function evaluators instead of 2d arrays) is planned but not in this
 * version.


 * plline.c:
 * Now holds all routines dealing with line draws, including clipping and
 * dashed line support.  Polyline capability added.


 * plfont.c:
 * Added support for device-independent font files.


 * plfill.c:
 * Now holds all routines dealing with fills.


 * plcvt.c:
 * File for holding coordinate transformers (was: convert.c).


 * plctrl.c:
 * Added for the high level routines that don't result in something being
 * plotted ("control" routines) that don't need direct access to the stream
 * or dispatch table data.  Eliminated plbeg: it is now illegal to specify
 * the device by device number.


 * plcore.c:
 * Holds "core" routines -- includes routines from what was base.c, plstar.c,
 * some others.  The stream data and dispatch table are now local to this
 * file only.  Also added support for new color model, polyline support.
 * Added plscolbg() to modify background color.  Added plgver() for
 * retrieving plplot library version.  Eliminated gradv driver function.
 * Completely rewrote initialization routines.  Now plstar and plstart are
 * merely front-ends to plinit, which does all the initialization.  Added
 * plsdev for setting the device name, and plssub for setting the subpages.
 * Added plgpls for getting the current pls pointer, for offloading
 * stream-dependent code into other files.  Added plsesc/plgesc for
 * setting/getting the escape character for text strings (can be any of
 * [!#$%&*@^~], brackets not included).  Put in some checks for routines that
 * set family file parameters.  Eliminated some unused routines.  Added
 * plflush() function.


 * plcont.c:
 * Now holds all contouring routines.  The multiple contour functions have
 * been removed, since now a function is passed in instead of an array.
 * Through use of a suitable function evaluator and array evaluator, the same
 * contouring code can now be used from Fortran (with no transpose
 * necessary), C with C-like 2d arrays, C with 2d arrays stored as 1d, etc.
 * Replaced (void *) declaration for user data structures to (PLPointer), in
 * the spirit of Xt's XtPointer.  It was hoped that this would eliminate
 * certain warnings having to do with alignment (only showing up with all
 * warnings turned on), but it didn't.


 * plbox.c:
 * Now holds all box-related routines.


 * plargs.c:
 * Added code to parse command line arguments.  Accepts a data structure with
 * argument specification, syntax, description, mode flag, and function
 * handler (called if option is found).  Usable both to parse plplot command
 * flags and user command flags.  The latter is facilitated by input of user
 * routines to handle usage and help messages.  The plplot command line
 * parser removes all arguments it recognizes, allowing the user to detect
 * invalid input.  See plrender.c for a working example of usage of the case
 * of user command flags; the simpler case with no user command flags is
 * illustrated by any of the (C) example programs.  Changed the -bg flag to
 * accept a full-color argument in the form -bg rrggbb, with rr, gg, bb
 * corresponding to the background RGB values in hex.  Example: -bg FFFF00 to
 * get a yellow background.


 * plstubs.h:
 * Reduced stub routine definition to ONE set of defines through a clever
 * macro, FNAME.  Will work in principle for all systems.


-----------------------------------
Header Files
-----------------------------------

 * plstream.h:
 * Added to hold definition of PLStream data structure.  Included by all
 * files dealing with streams (and is included by driver.h).  Added to the
 * stream data structure: a device name, and the value of the escape
 * character.  Added function prototype for plgpls and some minor
 * documentation changes.


 * plplotio.h:
 * Added to handle any data structure definitions or function prototypes that
 * need access to stdio.h, so that plplot.h could remain free of this.


 * plplot.h:
 * Elimination of many function prototypes (and a few added), caused by many
 * routines becoming static in reorganization.  Added support data structures
 * and constant definitions for plplot options handling code.  Added function
 * prototypes for new functions and deleted a couple.  Eliminated case of
 * VOID == char since that should never be necessary with ANSI C.


 * plevent.h:
 * This file added for inclusion by all user-defined event handlers to be
 * used with plplot.  It contains constant definitions used to transmit
 * info on the event that occurred (e.g. keystroke definitions).


 * plcore.h:
 * Added this file for inclusion only by plcore.c.  It declares the plstream
 * data structure, and defines, declares, and initializes the dispatch
 * table data structure.


 * pdf.h:
 * Added prototypes for functions that support polyline read/writes.


 * metadefs.h:
 * Added support for polylines and new color model.  Changed PLPLOT_HEADER
 * and PLPLOT_VERSION to PLMETA_HEADER and PLMETA_VERSION so that plplot
 * could have its own distinct version number.


 * drivers.h:
 * Added this file for inclusion by all drivers, in lieu of what was
 * previously dispatch.h.  This now has only driver prototypes -- NO data
 * structure declarations.  Eliminated references to the xxx_adv (gradv)
 * driver functions.


-----------------------------------
Drivers
-----------------------------------

ALL DRIVERS:

 * All device coordinates are now expected to fit into a 16 bit address space
 * (reasonable, and good for performance).

 * Eliminated the gradv() driver calls, as these were made obsolete by
 * recent changes to plmeta and plrender.  Also eliminated page clear commands
 * from grtidy() -- plend now calls grclr() and grtidy() explicitly.

 * Changes to support new color model, polylines, and event handler support
 * (interactive devices only).  Type flag added to device definition to
 * indicate file-based or interactive.

 * Fixed orientation operation in several files and standardized certain
 * startup operations. Fixed bugs in various drivers.

 * Dummy function added for each non-active driver to eliminate warnings.


Additional changes, listed by file: 

 * xwin.c:
 * Fixed background color setting, for color and grayscale monitors.
 * Eliminated all multiple extraneous exposures during uncover or resize
 * operations.  The X driver refresh/resize works perfectly now as far as I
 * can tell.  Added refresh & resize capability.  Also reorganized
 * substantially, to be more along the lines of the new Motif driver.  Code
 * is about 2-3x more logical and flexible now.  Some operations are slower
 * now (e.g. dashed lines) because of the large virtual address space used
 * now.  Changed cursor to cross-hair for more accurate location retrieval
 * Added crude support to have mouse button 2 return cursor postition to
 * stdout.  Swapped background/foreground colors for monochrome X output.


 * xterm.c:
 * Fixed some long-standing bugs in switching between text and graphics
 * windows (didn't affect xterms, but did affect certain vt100/tek
 * emulators).


 * ps.c:
 * Eliminated the (atend) specification for BoundingBox, since this isn't
 * recognized by some programs; instead enough space is left for it and a
 * rewind and subsequent write is done from ps_tidy().  Familying is no
 * longer directly supported by the PS driver as a result.  The output done
 * by the @end function was eliminated to reduce aggravation when viewing
 * with ghostview.


 * plmeta.c:
 * Now writes out page offsets to metafile for seeking forward/backward
 * by plrender.


 * ljii.c:
 * Actually works now.


 * plbuf.c:
 * Routines for writing to and reading from a plot buffer, as well as
 * recreating an entire plot.  The driver need merely specify
 * pls->plbuf_enable = 1 for it to be used (it must of course handle the
 * expose/resize events itself).


 * null.c:
 * Null device driver, for use when you want the graphics to disappear into
 * the bit bucket.  Always appears as the last device.


-----------------------------------
Example programs
-----------------------------------

 * Added #include <stdlib.h> since the code needs to exit(1) on some errors.
 * Changed all C examples to initialize with new plinit() function, also
 * calls to PLPLOT command-line args parser added.  


-----------------------------------
Miscellaneous
-----------------------------------

Support for VMS has been suspended (perhaps permanently), since we don't use
it anymore and it's too much of a pain to support.  If anyone fixes the
makefile and verifies the package does work, however, we will include your
fixes with the release version.


*****************************************************************************
PLPLOT 4.0 changes
*****************************************************************************

Here are the biggest changes that have been made to PLPLOT, especially
those likely to affect the user.  Please see the PLPLOT docs for more
information. 

Some of the changes stem from the direction we want to take PLPLOT.  For
example, away from device dependence and use the metafile driver as our
main target.  This probably means offloading more intelligence into the
drivers in the future. 

Also, some very small files have been consolidated in order to speed
compilation and keep related routines together.


Changes from the 3.x strain by M. LeBrun
----------------------------------------

This version came originally from PLPLOT 2.6b.  In accomodating
the changes made in 3.0 (Tony's version), I had to break a few calls.
Namely, the following routines now have a different call syntax:

	plsxax plsyax plszax
	plgxax plgyax plgzax
	plmesh
	plot3d

Please see the documentation for the proper calls.  

You can now specify the argument types to PLPLOT calls in the more
generic fashion INT and FLOAT.

There have also been some new functions added and improvements made to
plrender. 


Major changes from PLPLOT 3.0.
------------------------------

The PLPLOT <-> driver interface completely rewritten.  Now a pointer
to a data structure containing all the PLPLOT "state" information for
a given data stream is passed into the driver.

Several new capabilities were added to the drivers.  This includes:

	aspect ratio scaling (see below)
	family files
	escape function
	multiple output streams

New drivers include:
	X-window
	metafile

Utilities:
	plrender	renders metafiles
	pltek		displays tektronix files

plrender has lots of options (see the docs).  In particular, the
family file output, margins, justification, and orientation flags
are fun to play with.
------------------------------------------------------------------------
A multiple output stream capability has been added.  The default
stream number is 0.  To start a new stream, call plsstrm(#) with #
set to stream number, then call plstar or plstart.  After that,
you can use this routine to switch between streams (simultaneous
plotting is not done).

------------------------------------------------------------------------
The character, sym, and tick mark lengths are no longer specified in
terms of the actual physical page dimensions by default, rather, a
virtual page size of 238 x 180 mm is used (not actual mm).  This is
to ensure the ratio of sym size and box length is independent of output
device.  For the old method of scaling, you can change back with
the call plspsc(1). (set physical scaling)

------------------------------------------------------------------------
There is a new function for specifying viewport with a given aspect
ratio -- plvpas().  This is sort of a combination of plvasp() and
plvpor(), in that you specify the corners (like plvpor) and the aspect
ratio.  The biggest box that fits within your specified box with the
given aspect ratio will be used.  Makes plvasp() and plvpor() (and plsvpa
to some extent) virtually obsolete.

------------------------------------------------------------------------
I implemented a function plsasp(aspect) to do global aspect ratio
scaling.  This never quite worked out the way I planned, and now I
recommend using plvpas instead.  I may still make plsasp() useful
in the future.

------------------------------------------------------------------------
Put in an 'escape' function in all the drivers.  I really just wanted to
add a new function to set the colors on the basis of rgb inputs.  But I
realized I'd be wanting to add support for raster operations in the future
to both the X and Amiga drivers, but no other ones.  Since it's a pain
adding a new function (even if a stub) to all the drivers and dispatch.c,
etc, I figured the escape function would be good.  You pass in the op-code
and a pointer to whatever data you want passed.

------------------------------------------------------------------------
The plcwin() and plgwin() calls are no longer supported.  Use pltext()
and plgra() instead.

------------------------------------------------------------------------
The pleop() and plbop() calls are no longer supported.  Use plclr()
and plpage() instead.

------------------------------------------------------------------------
plorient() and plselect() are no longer supported.  Use plsori(),
plsfnam(), plsfile() instead.

------------------------------------------------------------------------
Some new functions to set color, plrgb() and plhls().  The latter converts
color in hls values to rgb.  plrgb calls the gresc() function mentioned
above, and plhls() calls plrgb().  Also you can allocate a named color
(only works with X interface right now) with the plancol() routine.

------------------------------------------------------------------------
Put in family file support.  There is an option now to create a family of
files with each roughly of a given size.  Also each file is a complete
stand alone, and plrender can read a whole family like it is a single
logical file, and create a single output file or family output file. 

There are two new routines, plsfam() and plgfam(), for setting/getting
the parameters governing creation of family file sets.

Also changes were required to all drivers that support familying.  As far
as plplot is concerned, it's still just a single logical file.  The only
drivers I've put the familying into are the ps, tekf, and plmeta drivers.

------------------------------------------------------------------------
The ANSI/non-ANSI behavior of PLPLOT has changed again.  Now you need
to include plplot.h into your program to make sure you get the argument
types right (i.e. for ANSI compiler, a FLOAT really passes as a FLOAT
not a double).  Face it, we've had an ANSI standard for C for about 4
years now and ISO for 2, and vendors who don't comply should be boycotted.

All PLPLOT routines that accept a FLOAT as an argument now use an ANSI
style function declaration if PLSTDC is defined, to bypass the K&R style
promotion.  Eventually support for non-Standard C compilers will be
dropped. 

The analogous problem with ints is discussed in the GNU CC manual, under
'Known Causes of Trouble with GNU CC':

*** begin quote ***

Users often think it is a bug when GNU CC reports an error for code like this: 

    int foo (short);

    int foo (x)
    short x;
    (...)

The error message is correct; this code really is erroneous, because the
old-style non-prototype definition passes subword integers in their
promoted types.  In other words, the argument is really an int, not a
short.  The correct prototype is this:

    int foo (int);

*** end quote ***

------------------------------------------------------------------------
Some other magic being done in plplot.h includes redefinition of the
C-entry bindings (the installer can disable this but I don't recommend it). 
The point is that the C and Fortran namespaces on some systems clobber
each other, and there is no good solution except to change the C entry
names.  Each external call is prepended with a 'c_'.  So you must include
plplot.h and recompile any old programs that are to work with PLPLOT 4.0.

------------------------------------------------------------------------
Put in an alternate startup routine plstart(), that lets you specify device
name.  This makes the old plbeg() call obsolete.  See the pl_DevName entry
in the dispatch table (the second entry) for valid device names. 

------------------------------------------------------------------------
plfont.c:

Made font locating code to be much more intelligent, with 3 hardwired
locations, current directory, and $(HOME)/lib checked.  Locations
can be passed in from the makefile.

------------------------------------------------------------------------
plconf.c:

New, based on plcont.c and plcntr.c, for better Fortran interface.  Passes
grid arrays instead of function pointer for calculation of coordinate
transformation.  Also error handling changed. 

Also added fortran stub routines for the three new contour plotters: 

	plcon0 - simple contour plot, no transformation
	plcon1 - 1-d transformation, i.e. x(i), y(j).
	plcon2 - 2-d transformation, i.e. x(i,j), y(i,j)

as well as stub routines for plconf(), and three functions to handle
coordinate transformation (none, 1-d, 2-d).  Transformation functions
detect out-of-bounds coordinates and react intelligently (giving nearest
point and issuing a warning). 

------------------------------------------------------------------------
plccal.c:

  Improved interpolation algorithm to get rid of occasional contour crossing
  (especially for noisy data). 

------------------------------------------------------------------------
strtoint.f:

Changed string interface to be portable.  Each string is now a *char but
stored from fortran packed in an INTEGER*32.  The fortran stub packs the
string via 'strtoint', and the C routine unpacks via 'long_to_str'.

------------------------------------------------------------------------
System-independent makefile written in m4 for unix-like systems.  Compile
with m4 for desired system, e.g.

	m4 -DSUNOS makefile.m4 >makefile

Simplifies debugging & testing by creating symlinks between plplot/tmp and
all source & example files. 

------------------------------------------------------------------------
Reorganized directory structure.  New directories include:

docs/         examples/     fonts/        include/      lib/
src/          sys/          tmp/          utils/

Under src/, all source + directories stubc/ and stubf/.
Under sys/, amiga/  ctss/   dos/    os2/    unix/   vms/.
Under examples/, C/ and f77/.

So this way new systems can be supported without changing the top level dir
structure. 

