README.release

PLplot Development Release 5.5.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the 
ongoing efforts of the community to improve the PLplot plotting 
package.  Development releases represent a "work in progress", and 
we expect to provide installments in the 5.5.x series every few weeks.  
The next full release will be 5.6.0.

     If you encounter a problem that is not already documented in the 
PROBLEMS file, then please send bug reports to PLplot developers via the 
mailing lists at http://sourceforge.net/mail/?group_id=2915 .

     Please see the license under which this software is distributed
(LGPL), and the disclaimer of all warrantees, given in the COPYING.LIB 
file.


INDEX

1. Build Instructions
2. Changes relative to PLplot 5.5.2
  2.1 API
  2.2 Drivers
    2.2.1 GCW (Gnome 2)
3. Changes relative to PLplot 5.3.1
  3.1 API
    3.1.1 Deprecated functions
    3.1.2 Unicode
    3.1.3 Extended cmap0 support
    3.1.4 The PlplotCanvas Widget for Gnome/GTK Applications
  3.2 Drivers
    3.2.1 PostScript
    3.2.2 GD (png, jpeg, gif)
    3.2.3 GCW (Gnome 2)
    3.2.4 AquaTerm (Mac OS X)
    3.2.5 Tk


1. Build Instructions

For detailed instructions on how to build and install PLplot from this
tarball, please read the INSTALL file.  The basic procedure is to execute
the following commands:

  ./configure
  make
  make install

     There are a variety of configuration options, and these are explained 
in the INSTALL document, and below as required.  In particular, if you 
want to install the PLplot Programmer's Reference Manual, please use:

  ./configure --with-prebuiltdoc

Note that it is often helpful to use the --with-pkg-config option if your
system has the pkg-config program (typically *nix systems).


2. Changes relative to PLplot 5.5.2 (our previous development release)


2.1 API

The deprecated functions plParseOpts, plHLS_RGB, and plRGB_HLS have been
temporarily restored into the API to make the resulting PLplot library
backward compatible with our last stable release (5.3.1).  However, since
these functions are deprecated, they will eventually be removed from the
API, and you should use plparseopts, plhlsrgb, and plrgbhls instead.
  	 
The soversion numbers for the different libraries in C, C++ and Fortran77,
as well as for the helper library libcsiro, are bumped to reflect the
addition of functions in the API since our last stable release (5.3.1).

Please see section 2.2.1 for changes in the GCW driver and PlplotCanvas
APIs.


2.2 Drivers


2.2.1 GCW (Gnome 2)

The GCW driver and associated PlplotCanvas widget have undergone
significant revisions since the previous release.  Please read the
PLplot Programmer's Reference Manual for a complete description of 
the current capabilities and publically available APIs.

     The specialized GCW and PlplotCanvas APIs are now contained in a
library named libplplotgnome2d.  To use this API, link your
programs against libplplotgnome2d instead of libplplotd.  This can 
most easily be achieved using pkg-config.  For example, to build foo.c
with libplplotgnome2d, use

  gcc foo.c -o foo `PKG_CONFIG_PATH=/usr/local/lib/pkgconfig \
  pkg-config --cflags --libs plplotd-gnome2`

     The specialized GCW and PlplotCanvas APIs have been streamlined
and enhanced, although no basic functionality has been removed.  Some 
methods were deleted because they were no longer required.  Others 
have had their argument list changed, or have been made private.  Some
GCW functions were determined to be best handled by existing 
command-line arguments.  In all cases, please consult the PLplot
Programmers Reference Manual for proper usage.

     By default, lines and shades are now rendered on a pixmap, which
has resulted in a significant speed increase.  To obtain the old
anti-aliased behaviour, use the "-nopixmap" command-line option.
Note that in both cases the fonts are antialiased, and so the results
generally look quite good.

     In standalone mode, the user-interface has a new feature that 
allows users to save plots to other file formats (ps, psc, png, jpg, 
gif).  There are some font size issues with png, jpg, and gif files, 
and occasional problems with colormaps, but these issues should 
be resolved soon.

     Dashed lines and hatched areas are now supported, as are plots in
portrait mode using the "-portrait" command-line option.  Nearly all of 
PLplot's command-line arguments are handled.

     The default page size has been changed to be consistent with the 
PostScript driver.

     Finally, the GCW driver and libplplotgnome2d library are now
automatically built if the required dependencies are available.


3. Changes Relative to PLplot 5.3.1 (our last stable release)


3.1 API


3.1.1 Deprecated functions

plParseOpts, plHLS_RGB, and plRGB_HLS are now deprecated and will eventually
be removed from the API.  Use plparseopts, plhlsrgb, and plrgbhls instead
for all language interfaces.


3.1.2 Unicode

PLplot now supports unicode text.  The escape sequence for unicode
characters is

     #[nnn]

where nnn can be decimal or hexadecimal.  Escape sequences are also defined
to change fonts mid-string.

     There are known bugs for our unicode font implementation that are 
listed in a special section of the PROBLEMS file, but the current 
implementation is good enough so we turn on unicode support by default 
for the psc, ps, png, gif, jpeg, and gcw devices.  Although all examples 
look better with unicode fonts, the new PLplot unicode capabilities are 
especially demonstrated in examples x23 and x24.  (The latter example 
requires special fonts to be installed and at run time environment 
variables have to be set to access them;  see the self-documentation of 
the example 24 source code).  


3.1.3 Extended cmap0 support.

There have been many updates to cmap0 handling in the effort to wipe away 
all vestiges of the old 16 color limit.  The theoretical limit should now 
be 2^15 colors, since the metafile and tk drivers use a short for 
communication of the cmap0 index.  Should be *plenty* for the given 
application, i.e. fixing colors for lines, points, labels, and such.
 
     Since both the metafile & tk data stream formats have changed due to 
the change from U_CHAR -> short for cmap0 index representation, the format
versions have been upgraded.  If you see something like this:
 
  $ x02c -dev tk 
  Error: incapable of reading output of version 2005a. 
  plr_init: Please obtain a newer copy of plserver. 
  Command code: 1, byte count: 14 
  plr_process1: Unrecognized command code 0 
  ... 
 
then you know it's using the wrong version of plserver (in which case 
either you didn't install or your path is wrong). 

     The second example program (multiple bindings available) contains 
a demo of the expanded cmap0 capability.


3.1.4 The PlplotCanvas Widget for Gnome/GTK Applications

PlplotCanvas is a new widget for use in Gnome/GTK applications, and
is contained in the libplplotgnome2d library.  A specialzed API is
provided, and bindings are included for the C and Python programming 
languages.  Special example programs that demonstrate the use of 
PlplotCanvas in Gnome/GTK applications are provided for each 
language binding.


3.2 Drivers

Some of the drivers have undergone important revisions in order to provide
unicode support.  Several now present TrueType or PostScript fonts by
default, which produces higher-quality output than in the past: see the
examples from the GD (png) driver on the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html .


3.2.1 PostScript

The PostScript driver produces "publication quality" output files.  It
is unicode-enabled, and Type 1 PostScript fonts are used by default.  
Although the Type 1 symbol fonts have a significant number of 
mathemetical symbols available, some key special symbols (squares,
triangles) are missing.  Thus, by default, Hershey fonts are used to 
produce the symbols generated by calls to "plpoin" and "plsym", while 
PostScript fonts are used for calls to PLplot routines that plot text 
strings (e.g., "plmtex").  If you prefer a pure Hershey font environment, 
specify -drvopt text=0, and if you prefer a pure Postscript font 
environment, specify -drvopt hrshsym=0.


3.2.2 GD (png, jpeg, gif)

The GD driver is used to produce png, jpeg, and gif files.  It is 
unicode-enabled, and uses TrueType fonts by default.  The examples on 
the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html were produced using 
this driver.


3.2.3 GCW (Gnome 2)

GCW is a new driver for Gnome 2 that displays plots in a tabbed GTK 
window.  The driver is unicode-enabled, and uses TrueType fonts.  The 
GCW user interface supports zooming, and saves to a variety of output 
file formats (ps, psc, png, jpg, gif).  All of the relevant
command-line options for PLplot are supported.

     A separate library and specialized API are also provided, which
allow for a higher degree of interaction with the driver.  Bindings
are provided for the C and Python programming languages.


3.2.4 AquaTerm (Mac OS X)

AquaTerm is a new driver for Mac OS X that provides PLplot output in 
the AquaTerm graphics terminal program.  Aquaterm is a native Cocoa 
graphics terminal program for Mac OS X that provides a familiar look and 
feel to Mac users.  More details about AquaTerm and how to install it can 
be found at http://aquaterm.sourceforge.net/.

     The driver is unicode-enabled and uses default OS X fonts.

     To install the AquaTerm driver, use the options "--disable-dyndrivers" 
and "--disable-f77" during the configure step of the install process.
 

3.2.5 Tk

The plframe widget (and by extension, the Tk driver) now saves a plot using 
the correct aspect ratio, as represented by the actual window size.  For 
complicit output drivers only, e.g. png.