File: README.cumulated_release

package info (click to toggle)
plplot 5.15.0%2Bdfsg-19
links: PTS, VCS
area: main
in suites: bullseye
size: 31,312 kB
sloc: ansic: 79,707; xml: 28,583; cpp: 20,033; ada: 19,456; tcl: 12,081; f90: 11,431; ml: 7,276; java: 6,863; python: 6,792; sh: 3,274; perl: 828; lisp: 75; makefile: 50; sed: 34; fortran: 5
file content (17308 lines) | stat: -rw-r--r-- 845,903 bytes
parent folder | download | duplicates (4)
PLplot Release 5.15.0

This is a release of the PLplot plotting package. It represents the
ongoing best efforts (roughly ~50 commits since the last release) of
the PLplot development community to improve this package, and it is
the only version of PLplot that we attempt to support.  Releases in
the 5.x.y series should be available roughly two times per year.

Note that PLplot has been continuously developed since 1986 so it has
accumulated a lot of cruft since that time.  Therefore, we are now
slowing removing that cruft to improve the lot of both new users and
new members of the development team.  As a result virtually every
PLplot release has some backwards incompatibilities introduced to help
clean it up so please pay careful attention to the OFFICIAL NOTICES
FOR USERS below (and also in the various sections of
README.cumulated_release if you need backward incompatibility
information for several recent releases) where we document such
incompatibilities to make life easier for those who have prior
experience with older PLplot releases.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via our mailing lists (preferred for initial discussion of
issues) at <http://sourceforge.net/p/plplot/mailman/>. If it turns out
no quick resolution is possible via mailing-list discussion, then the
issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

This software is primarily distributed under the LGPL.  See the
Copyright file for all licensing details.
________________________________________________________________

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility
1.2 Remove typedefs for PL_NC_GENERIC_POINTER and PL_GENERIC_POINTER
1.3 Fix typedef for PLINT_NC_VECTOR

2. Improvements relative to the previous release

2.1 Bug fixes
2.2 Update PLplot to be consistent with modern free software
2.3 Rewrite the configuration of the INSTALL_RPATH target property
2.4 Rewrite the rpath configuration of traditionally built examples
2.5 Factor the PLplot export files
2.6 Introduce symbolic constants in our color-map routines
2.7 New implementation of the range checks for the validity of cmap0 and cmap1 user input
2.8 New implementation of the -bg command-line option
2.9 Implement ctest for the build system of the installed examples

3. PLplot testing
________________________________________________________________

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility

Our build system is implemented using CMake.  The minimum version of
CMake we currently allow is 3.13.2 on all platforms, and currently the
latest version of CMake that has been officially released is 3.14.4.

Note, that as of the time of this release we have the following
free distribution packaging support for modern CMake versions:

* Cygwin: 3.13.1 from <https://cygwin.com/cgi-bin2/package-grep.cgi>
* MinGW-w64/MSYS2: 3.14.4 from <http://repo.msys2.org/mingw/x86_64/>
* Fink: 3.11.0 from <http://pdb.finkproject.org/pdb/browse.php?name=cmake>
* MacPorts: 3.14.4 from <https://www.macports.org/ports.php?by=name&substr=cmake>
* Homebrew: 3.14.4 from <https://formulae.brew.sh/formula/cmake>
* Debian Testing: 3.13.4 (from <https://packages.debian.org/buster/cmake> where Testing = Buster is likely to become the official Debian Stable release of Debian in mid-2019, i.e., soon, see <https://en.wikipedia.org/wiki/Debian_version_history>).
* Other modern Linux distributions: likely 3.13.4 or greater since they typically package later versions of CMake than are available for Debian Stable.

It appears from the above table that binary packages for CMake for our
minimum allowed version (3.13.2) or later should be available soon or
immediately on most modern free software distributions.  However,
PLplot users of distributions that do not package 3.13.2 or later
(e.g., Cygwin and Fink) will need to build CMake 3.13.2 or later for
themselves before they build PLplot-5.15.0

This particular PLplot release has been comprehensively tested for
CMake-3.13.2 through 3.14.4 on a variety of platforms (see
<http://sourceforge.net/p/plplot/wiki/Testing_Reports> for details
of recent tests on all platforms).

Therefore, if the CMake version is within this range there is an
excellent chance that our build system will "just work" on all
platforms.  Furthermore, if later on you try CMake versions greater
than the latest version of CMake that is available at the time of this
PLplot release (3.14.4), our build system will likely continue to work
well because CMake has an excellent reputation for preserving
backwards compatibility.

1.2 Remove typedefs for PL_NC_GENERIC_POINTER and PL_GENERIC_POINTER

typedef PLPointer   PL_NC_GENERIC_POINTER;
typedef PLPointer   PL_GENERIC_POINTER;

were introduced as of 5.12.0 as the start of a plan that was almost
immediately abandoned.  So these typedefs were officially deprecated
in 5.13.0, and they are now being dropped as of this release.

This cruft-removal causes a backwards-incompatible change to our C API
that is of no concern for users who do not use PL_NC_GENERIC_POINTER
and PL_GENERIC_POINTER in their code.  However, for the remaining
users the solution must be to replace PL_NC_GENERIC_POINTER and
PL_GENERIC_POINTER by PLPointer everywhere in their code.

1.3 Fix typedef for PLINT_NC_VECTOR

This typedef (first defined as of 5.12.0) has been changed from

-typedef int *                 PLINT_NC_VECTOR;
+typedef PLINT *               PLINT_NC_VECTOR;

to fix an inconsistency that was incorrectly and inadvertently created
for 5.12.0 between this typedef and all other PLINT* typedefs.

For systems that provide the stdint.h header the PLINT typedef is

typedef int32_t        PLINT;

but for those systems that do not provide that header, this typedef is

typedef int            PLINT;

Therefore the above change to the typedef for PLINT_NC_VECTOR is
backwards-incompatible (requiring recompilation of user code but no
changes to that code to fix the problem) for users with systems that
(a) provide the stdint.h header, and (b) define int differently than
int32_t for those systems.
________________________________________________________________

2. Improvements relative to the previous release

2.1 Bug fixes

The bug fixes in this release are noted in the ~50 commit messages
collected in ChangeLog.release.

Commit plplot-5.14.0-8-gdb9d90d0b should be of particular note since
it finally makes results achieved with our qt device driver linked to
Qt5 similar to the high quality of results achieved with that same
device driver when it is linked to Qt4.

2.2 Update PLplot to be consistent with modern free software

This ongoing project is implemented by making sure PLplot passes all
[comprehensive
tests](<https://sourceforge.net/p/plplot/wiki/Testing_Reports) on the
Debian Testing platform which is a high-quality rolling release that
keeps up to date with modern free software development.  As a result
PLplot should be compatible with the following modern versions of free
software packages:

* CMake-3.13.2 through 3.14.4       (core, bindings, and device drivers)
* gcc 8.3.0			    (core)
* qhull 2015.2			    (optional core interpolation functionality)
* shapelib 1.4.1		    (optional core map functionality)
* swig 3.0.12 through 4.0.0	    (java, lua, octave, and python bindings)
* gnatmake/gdc/gfortran 8.3.0	    (ada, d, and fortran bindings)
* g++ 8.3.0			    (c++ binding and psttf and wxwidgets device drivers)
* pango 1.42.3, cairo 1.16.0	    (cairo device driver)
* openjdk 11.0.3		    (java binding)
* lua 5.3.5			    (lua binding)
* camlidl 1.05, ocaml 4.05	    (ocaml binding)
* octave 4.4.1	      		    (octave binding)
* python 3.7.3			    (python binding)
* Qt 5.11.3			    (qt binding and qt device driver)
* Tcl/Tk 8.6.9			    (tcl/tk binding and tk device driver)
* libx11 2:1.6.7		    (tk and xwin device drivers)
* wxWidgets 3.0.4		    (wxwidgets binding and device driver)

Notes for this table:

* The CMake versions used for testing were locally built rather than
  installed from Debian testing, see Section 1.1 for details.

* The Debian Testing package for swig 3.0.12 contains a swig fix from
  swig-4.0.0. That fix allows an Octave-4.4 binding to be built for
  PLplot.  If your swig-3 version does not have this fix, you should
  use Octave-4.2 until swig-4 is released.

* The swig-4.0.0 version used for testing was locally built since this
  version is not packaged for Debian Testing (yet).

* The Debian Testing package for lua 5.3.3 currently perpetuates
  [a serious bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=902238)
  for that particular upstream version.  The above good results for lua
  5.3.5 were generated with a locally built version of upstream 5.3.5
  that contains the essential fix for 5.3.3.

2.3 Rewrite the configuration of the INSTALL_RPATH target property

This change is important for those Unix users who install
PLplot dependencies (such as libLASi) in non-standard locations and
who use the traditional build of our installed examples rather than
the CMake-based build of those examples.

DT_RPATH and its more modern variant DT_RUNPATH are two ways on Unix
systems to inform the run-time loader of non-standard locations of
shared libraries that are needed by applications.  Therefore, the
details of how our build system configures use of the INSTALL_RPATH
target property (which controls DT_RPATH on old Unix systems such as
Debian Jessie and DT_RUNPATH on more modern Unix systems such as
Debian Testing) become important for the traditional build of
installed examples if any external library (e.g., libLASi) needed by
any PLplot component is installed in a non-standard location.  (Note
that CMake-based builds automatically take care of all rpath concerns
so our CMake-based core build and CMake-based build of the installed
examples automatically work fine regardless of where our external
libraries are installed or the INSTALL_RPATH target property set for
them.)

Our INSTALL_RPATH configuration worked fine for our traditional builds
of installed examples on DT_RPATH platforms such as Debian Jessie and
was extensively tested in that era with epa_built external libraries
that were installed in non-standard locations.  However, that
configuration did not work correctly for DT_RUNPATH platforms such as
Debian Testing since it was not always consistent with the following
additional constraint on the use of DT_RUNPATH that has been taken
from
<https://refspecs.linuxfoundation.org/elf/gabi4+/ch5.dynamic.html>:

  "The set of directories specified by a given DT_RUNPATH entry is
  used to find only the immediate dependencies of the executable or
  shared object containing the DT_RUNPATH entry. That is, it is used
  only for those dependencies contained in the DT_NEEDED entries of
  the dynamic structure containing the DT_RUNPATH entry, itself. One
  object's DT_RUNPATH entry does not affect the search for any other
  object's dependencies."

As a result PLplot's use of the new libLASi release (which necessarily
had to be built locally and with a non-standard install prefix) failed
for our traditional build.

To address this issue I (AWI) have completely rewritten our rpath
configuration logic for the INSTALL_RPATH property of installed
targets to (i) be consistent with the above additional DT_RUNPATH
constraint, and (ii) have that configuration done in a standardized
way for all our installed targets (executables, dll's (modules)
generated by swig, ordinary dll's, shared libraries and static
libraries).  The result of this work is a substantial reduction in the
number of lines of CMake logic in our build system (since virtually
all of the INSTALL_RPATH logic is now taken care of in the new
process_rpath function).

Note that this new logic always uses the transitive INSTALL_RPATH
method for the static build case and by default uses non-transitive
INSTALL_RPATH method for the shared library case (regardless of
whether the device drivers are dynamic or nondynamic).  And that
default for the shared library case works well for Debian Testing.
But if there are still some Unix platforms out there that only work
for the transitive INSTALL_RPATH method for the shared library case,
the user can choose that method by setting the
-DNON_TRANSITIVE_RPATH=OFF cmake option.  And as always if the user
(typically a binary package maintainer) specifies -DUSE_RPATH=OFF, the
INSTALL_RPATH target property (transitive or otherwise) will not be
set at all for installed targets with the result that DT_RPATH (old
Unix systems) and DT_RUNPATH (modern Unix systems) will not be set for
those targets.

N.B. in the rewritten INSTALL_RPATH logic the simplifying assumption
is made that in both the non-transitive and transitive rpath cases,
that all non-system library locations must be mentioned in the derived
DT_RPATH or DT_RUNPATH.  Of course, this assumption is only necessary
if the relevant libraries are shared so the result in the case where
the relevant library (whether external or internal) is static is the
non-standard location of that library is unnecessarily listed in the
resulting DT_RPATH or DT_RUNPATH.  So the result is the run-time
loader has to check a bit more before deciding that location
information is irrelevant so it adds slightly to start-up latency.
However, implementing a check whether external and internal libraries
are shared or not would so complicate our build system code and
therefore make it more fragile that I have decided to stick with using
this simplifying assumption.

2.4 Rewrite the rpath configuration of traditionally built examples

In this case, "traditionally built" refers to the traditional (GNU
make + pkg-config) build of the installed examples (including the
ocaml examples) AND the CMake-based builds of the ocaml examples in
the core build tree and the build tree for the installed examples.
(OCaml is a special case because there is no CMake official support
for this language so even for the CMake-based build of ocaml examples,
low-level CMake add_custom_command/target pairs must be used that are
very similar to the traditional build of the installed ocaml examples.

This change updated the somewhat sloppy transitive rpath method that
was used before for traditionally built examples to the rigorous
method I have implemented (see Section 2.3) recently for the case of
the INSTALL_RPATH property for installed targets.  That is, for the
non-transitive rpath case the traditionally built examples only refer
to the directory location of the "PLPLOT::" libraries that the plplot
examples in question depend on, and for the transitive case append the
INSTALL_RPATH locations for just the internal libraries that are
dependencies of the examples in question.  See the process_rpath
function in cmake/modules/plplot_functions.cmake for details.)

Note we use the same simplifying assumption mentioned in Section 2.3
to decide which library locations should be inserted in DT_RPATH or
DT_RUNPATH for traditionally built examples.

Note this more rigorous approach solved an ocaml rpath bug that was
exposed by the DT_RUNPATH Debian Testing platform.  So as far as I
know the combination of this change and the INSTALL_RPATH changes
described in section 2.3 eliminates the last known regression against
the good test results I achieved with the old sloppy rpath method on
the Debian Jessie platform with its old-fashioned but nevertheless
working DT_RPATH capability.

In sum, recent comprehensive tests on the Debian Testing platform
support the idea that our rewritten INSTALL_RPATH configuration for
installed targets and our rewritten rpath configuration for
traditionally built executables generates working DT_RUNPATH results
for the case where either/both PLplot libraries or external libraries
are installed in non-standard locations.  And presumably that good
result also holds true for generated DT_RPATH results since even quite
sloppy rpath configuration seems to have worked well in the past on
such systems (e.g., Debian Jessie).  However, if there are Unix
platforms still out there where the run-time loader (operating at run
time in contrast to the linker that operates at build time) errors out
by saying it cannot find a library for the present rpath methods, the
first thing the user should try is -DUSE_RPATH=ON (if they are not
using that default already) and the second thing they should try if
this trouble occurs for the shared build case is
-DNON_TRANSITIVE_RPATH=OFF.

2.5 Factor the PLplot export files

Packagers of binary versions of PLplot used in free software
distributions such as Debian and Fedora typically split the PLplot
installation into many different package components, and users of
those distributions have the option of only installing the subset of
those packages (and their dependencies) that they need.  However, the
CMake-based build system that is part of the examples package (which
contains source code for all our test examples) can currently only
build the examples if the user installs all binary components of
PLplot.

The current change is a large step toward removing that constraint.
This change factors the the two previous integrated PLplot export
files into two exported files per exported target (which can be an
installed library, module, or executable).  So if packagers distribute
these factored export files in the same binary packages which contain
the actual libraries, modules, or executables which are described by
the exported targets, then *any* CMake-based build systems for
software that depends on the PLplot installation can simply
interrogate that installation (using the if(TARGET ...)  command) to
see what subset of the PLplot targets have been installed and act
accordingly.

N.B. the CMake-based build system for the example source code that is
installed is a (large) example of such software.  But that software
has not yet been changed as described above so packagers will have to
wait until the next release before the source code for the appropriate
subset of the examples in that package can be built properly against
the subset of binary PLplot packages that have been installed by
users.

2.6 Introduce symbolic constants in our color-map routines

These new symbolic constants (in their C/C++ form) are

// Default number of colors for cmap0 and cmap1.
#define PL_DEFAULT_NCOL0    16
#define PL_DEFAULT_NCOL1    128
// minimum and maximum PLINT RGB values.
#define MIN_PLINT_RGB       0
#define MAX_PLINT_RGB       255
// minimum and maximum PLFLT cmap1 color index values.
#define MIN_PLFLT_CMAP1     0.
#define MAX_PLFLT_CMAP1     1.
// minimum and maximum PLFLT alpha values.
#define MIN_PLFLT_ALPHA     0.
#define MAX_PLFLT_ALPHA     1.

These constants should be defined for our core C "plplot" library and
all our different supported language bindings.  These symbolic
constants are used, for example, in our range checks for the validity
of cmap0 and cmap1 user input.

2.7 New implementation of the range checks for the validity of cmap0 and cmap1 user input

Instead of exiting when cmap0 or cmap1 user input is invalid, the
philosophy for the new implementation of cmap0 and cmap1 range
checking is to issue a warning message, substitute something
reasonable, and continue.  In addition, for the new implementation we
attempt to catch all invalid cmap0 or cmap1 user input rather than
just a subset of such cases.

2.8 New implementation of the -bg command-line option

The -bg command-line option is used to specify the RGB and (optional)
alpha values of the background.  The new implementation is much more
careful about checking for user input errors in both the RGB and alpha
values and follows the philosophy of warning and continuing with
reasonable default values when the user specifies an non-parsable or
invalid value for the RGB or alpha values of the background.

2.9 Implement ctest for the build system of the installed examples

Previously the ctest command was only configured for the CMake-based
build system of the core build of PLplot libraries and the source code
of the PLplot examples that appears in the PLplot source tree.  What
is changed now is the ctest command has also been configured for the
CMake-based build system of the installed source code for the PLplot
examples using in most cases common CMake logic as for the core build
case.  As a result, the ctest results in the two very different cases
cover the same tests.  In addition the same (good) ctest results have
been achieved for these two different builds confirming that all is
well with the core build of PLplot libraries and examples as well as
the installed binary version of PLplot libraries and corresponding
CMake-based build system for the installed source code for the PLplot
examples that is built against those installed libraries.
________________________________________________________________

3. PLplot testing

Comprehensive tests of this release are documented in
<https://sourceforge.net/p/plplot/wiki/Testing_Reports>.  In addition,
developers and users who have used the evolving git master tip
development version of PLplot for their plotting needs during this
release cycle have provided additional important testing of this
release of PLplot.
________________________________________________________________
PLplot Release 5.14.0

This is a release of the PLplot plotting package. It represents the
ongoing best efforts (roughly 150 commits since the last release) of
the PLplot development community to improve this package, and it is
the only version of PLplot that we attempt to support.  Releases in
the 5.x.y series should be available roughly two times per year.

Note that PLplot has been continuously developed since 1986 so it has
accumulated a lot of cruft since that time.  Therefore, we are now
slowing removing that cruft to improve the lot of both new users and
new members of the development team.  As a result virtually every
PLplot release has some backwards incompatibilities introduced to help
clean it up so please pay careful attention to the OFFICIAL NOTICES
FOR USERS below (and also in the various sections of
README.cumulated_release if you need backward incompatibility
information for several recent releases) where we document such
incompatibilities to make life easier for those who have prior
experience with older PLplot releases.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via our mailing lists (preferred for initial discussion of
issues) at <http://sourceforge.net/p/plplot/mailman/>. If it turns out
no quick resolution is possible via mailing-list discussion, then the
issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

This software is primarily distributed under the LGPL.  See the
Copyright file for all licensing details.
________________________________________________________________

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1  CMake version compatibility
1.2  Remove Fortran cruft
1.3  Remove Tcl/Tk cruft
1.4  Remove plmap cruft
1.5  Remove Perl/PDL examples
1.6  Remove all previously deprecated functions
1.7  Official deprecation of plshade1
1.8  Official deprecation of C++ cruft
1.9  plplot.org and www.plplot.org are now our official domains
1.10 We have removed the "sys" subdirectory from our source tree
1.11 Imported PLplot targets now must use the "PLPLOT::" prefix for the target name
1.12 Drop -single_module linking option that was previously forced for Mac OS X
1.13 Changed color interpolation for plscmap1l and plscmap1la

2. Improvements relative to the previous release

2.1  Bug fixes
2.2  Update control of Python version
2.3  Rewrite the build-system logic for determining PYQT_SIP_DIR and PYQT_SIP_FLAGS
2.4  Implement plStatic2dGrid
2.5  Replace use of the deprecated WIN32 and __WIN32__ macros by the _WIN32 macro
2.6  Difference report default device changed from psc to svg
2.7  Resolve the remaining difference report issues
2.8  Improve command-line parsing
2.9  Cleanup of plmap
2.10 wxwidgets development status
2.11 First step toward using best CMake-3 practices for our build system
2.12 Update PLplot to be consistent with modern free software
2.13 Rewrite documentation of PLplot testing
2.14 Configure the ps and psttf device drivers just like all other device drivers

3. PLplot testing
________________________________________________________________

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility

Our build system is implemented using CMake.  The minimum version of
CMake we allow is 3.7.2 on all platforms.

This particular PLplot release has been comprehensively tested for
CMake versions 3.7.2 through 3.13.1 on a variety of platforms (see
<http://sourceforge.net/p/plplot/wiki/Testing_Reports> for details
of recent tests on all platforms).

Therefore, if your CMake version is <= 3.13.1 and satisfies the above minimum
CMake version requirement there is an excellent chance that our build
system will work well.  Furthermore, if you try later CMake versions
as they are released during the life of this PLplot release, our build
system will likely continue to work well because CMake has an excellent
reputation for preserving backwards compatibility.  But if you get
build-system trouble for versions of CMake greater than 3.13.1, the
first thing you should try is CMake-3.13.1 which has been well-tested
by us.

1.2 Remove Fortran cruft

As of PLplot-5.12.0, a new Fortran binding was implemented using the
powerful capabilities of the Fortran 2003 iso_c_binding module which
was the replacement for the old binding that was implemented using a
combination of Fortran and C code.  The new binding is much simpler,
more consistent, and more standards-compliant than the old binding and
has some powerful new features (e.g., both single and double
precision Fortran floating-point arguments are accepted).  Therefore,
the new binding is necessarily backwards incompatible with the old
binding.  For PLplot-5.12.0 we implemented the CMake option
-DPL_DEPRECATED_fortran=ON to provide temporary deprecated access to
the old Fortran binding, and that form of backwards compatibility
continued to be provided for the PLplot-5.13.0 release.  However, it
appears our users are generally satisfied with the new binding, and we
no longer want to maintain or test that old binding.  So for this
release the old Fortran binding (and an old set of Fortran standard
examples that depended on it) has been completely removed from our
source tree.

1.3 Remove Tcl/Tk cruft

As of PLplot-5.12.0, a new Tcl binding was implemented that used the
"redacted" PLplot API where all dimension arguments for arrays are
dropped from argument lists since those data are redundant (already
supplied by the arrays themselves).  As a result of this change, Tcl
calls to the PLplot API in the old binding such as

$w cmd plline $nsize x y

now have to be replaced in the new binding by

$w cmd plline x y

and similarly for all other Tcl calls to the PLplot API that involve
array (tclmatrix) arguments.  The advantages of this new binding are
it is cleaner, it is safer (i.e., automatically self-consistent with
regard to array dimensions), and it makes our Tcl binding compatible
with the rest of our bindings.  (The only exception to this is our C++
binding which currently still uses simple C-style arrays and therefore
must use the non-redacted form of the PLplot API, but that may also
change in the future.)  However, the disadvantage of this change is
our new binding is obviously backwards-incompatible with the old
binding.  Therefore, for PLplot-5.12.0 we implemented the CMake option
-DUSE_NON_REDACTED_TCL_TK=ON to provide temporary deprecated access to
the old Tcl binding, and that form of backwards compatibility
continued to be provided for the PLplot-5.13.0 release.  However, it
appears our users are generally satisfied with the new binding, and we
no longer want to maintain or test that old binding.  So for this
release the old Tcl binding (and old versions of the Tcl standard
examples and Tk source code that depended on it) have been completely
removed from our source tree.

1.4 Remove plmap cruft

As of PLplot-5.9.10, a new version of plmap was implemented that used
shapefile format (accessed via shapelib) for maps.  In addition other
powerful map API (see the last page of standard example 19) that
depended on shapelib map data was implemented as well.  However, we
still made the old plmap implementation that depended on the
(undocumented) binary format of our *.map files available when the
user specified -DPL_DEPRECATED=ON, and this arrangement continued
through PLplot-5.13.0.  However, it appears our users are generally
satisfied with the new shapefile-based plmap functionality and we no
longer want to maintain or test that old plmap functionality based on
the *.map format.  So for this release that old plmap functionality
and associated *.map files have been completely removed from our
source tree.

1.5 Remove Perl/PDL examples

By historical accident and for just a limited time we actively
developed a set of standard examples written in Perl/PDL to help test
Doug Hunt's external PDL::Graphics::PLplot project.  But we have now
removed those examples from our project since we have long since
stopped testing PDL::Graphics::PLplot with those examples, and, in any
case, such examples should be part of the PDL::Graphics::PLplot package rather
than PLplot.

1.6 Remove all previously deprecated functions

We removed plParseInternalOpts, plSetInternalOpt, plclr, plpage, plcol,
plcontf, plP_gvpd, plP_gvpw, plotsh3d, plSetOpt, plrgb, plrgb1, plhls,
and plwid.  These functions were officially deprecated (i.e., only
accessible if the user specified the -DPL_DEPRECATED=ON cmake option)
as of the PLplot-5.9.10 release (and in some cases even before that
release) so it is long past the time to remove them.  We edited
the source tree files to remove all mentions of these functions (as well
as plParseOpts, plHLS_RGB, plRGB_HLS, and plarrows that had
been previously removed).  As a result

find . -type f |grep -v .git |xargs grep -E 'plParseInternalOpts|plSetInternalOpt|plclr|plpage|plcol|plcontf|plP_gvpd|plP_gvpw|plotsh3d|plSetOpt|plrgb|plrgb1|plhls|plwid' |grep -vE 'plcol0|plcol1|plcolorbar' |less

and

find . -type f |grep -v .git |xargs grep -E 'plParseOpts|plHLS_RGB|plRGB_HLS|plarrows' |less

now only find non-relevant hits or else hits for historical references
(e.g., change logs and release notes) to these functions.

1.7 Official deprecation of plshade1

The implementation of plStatic2dGrid (see 2.4) has made
the C routine plshade1 and its C++ wrapper pls->shade1 redundant.
Therefore, plshade1 and its C++ wrapper have now been officially
deprecated, i.e., only available if the CMake option -DPL_DEPRECATED=ON
is used.

1.8 Official deprecation of C++ cruft

The following C++ methods have been unofficially deprecated (via comments in the
code and lack of use in our C++ examples) for a long time:

// Previous function was inadvertently named plcol in old versions of
// plplot - this is maintained for backwards compatibility, but is best
// avoided in new code.  Use col1 method instead.
    void col( PLFLT c );
// Deprecated versions of methods which use PLINT instead of bool for logical arguments.
    void svect( const PLFLT *arrow_x, const PLFLT *arrow_y, PLINT npts, PLINT fill );
    void cpstrm( plstream &pls, PLINT flags );
    void plot3d( const PLFLT *x, const PLFLT *y, const PLFLT * const *z,
                 PLINT nx, PLINT ny, PLINT opt, PLINT side );
    void poly3( PLINT n, const PLFLT *x, const PLFLT *y, const PLFLT *z, const PLINT *draw, PLINT ifcc );
    void scmap1l( PLINT itype, PLINT npts, const PLFLT *intensity,
                  const PLFLT *coord1, const PLFLT *coord2, const PLFLT *coord3, const PLINT *alt_hue_path );

    void shade( const PLFLT * const *a, PLINT nx, PLINT ny,
                PLDEFINED_callback defined,
                PLFLT left, PLFLT right, PLFLT bottom, PLFLT top,
                PLFLT shade_min, PLFLT shade_max,
                PLINT sh_cmap, PLFLT sh_color, PLFLT sh_width,
                PLINT min_color, PLFLT min_width,
                PLINT max_color, PLFLT max_width,
                PLFILL_callback fill, PLINT rectangular,
                PLTRANSFORM_callback pltr, PLPointer pltr_data );

    void shades( const PLFLT * const *a, PLINT nx, PLINT ny, PLDEFINED_callback defined,
                 PLFLT xmin, PLFLT xmax, PLFLT ymin, PLFLT ymax,
                 const PLFLT * clevel, PLINT nlevel, PLFLT fill_width,
                 PLINT cont_color, PLFLT cont_width,
                 PLFILL_callback fill, PLINT rectangular,
                 PLTRANSFORM_callback pltr, PLPointer pltr_data );

    void shade( Contourable_Data& d, PLFLT xmin, PLFLT xmax,
                PLFLT ymin, PLFLT ymax, PLFLT shade_min, PLFLT shade_max,
                PLINT sh_cmap, PLFLT sh_color, PLFLT sh_width,
                PLINT min_color, PLFLT min_width,
                PLINT max_color, PLFLT max_width,
                PLINT rectangular,
                Coord_Xformer *pcxf );

    void fshade( PLFLT ( *f2eval )( PLINT, PLINT, PLPointer ),
                 PLPointer f2eval_data,
                 PLFLT ( *c2eval )( PLINT, PLINT, PLPointer ),
                 PLPointer c2eval_data,
                 PLINT nx, PLINT ny,
                 PLFLT left, PLFLT right, PLFLT bottom, PLFLT top,
                 PLFLT shade_min, PLFLT shade_max,
                 PLINT sh_cmap, PLFLT sh_color, PLFLT sh_width,
                 PLINT min_color, PLFLT min_width,
                 PLINT max_color, PLFLT max_width,
                 PLFILL_callback fill, PLINT rectangular,
                 PLTRANSFORM_callback pltr, PLPointer pltr_data );

    void spause( PLINT pause );

    void stripc( PLINT *id, const char *xspec, const char *yspec,
                 PLFLT xmin, PLFLT xmax, PLFLT xjump, PLFLT ymin, PLFLT ymax,
                 PLFLT xlpos, PLFLT ylpos,
                 PLINT y_ascl, PLINT acc,
                 PLINT colbox, PLINT collab,
                 const PLINT colline[], const PLINT styline[], const char *legline[],
                 const char *labx, const char *laby, const char *labtop );

    void xormod( PLINT mode, PLINT *status );

The above methods have now been officially deprecated, i.e., they will only
be accessible if a user sets -DPL_DEPRECATED=ON.

1.9 plplot.org and www.plplot.org are now our official domains

We have gone through the 3 steps in
<https://sourceforge.net/p/forge/documentation/Custom%20VHOSTs/> so that
plplot.org and www.plplot.org are now our official domains.

We have also gone through our source tree and replaced all instances
of plplot.sf.net and plplot.sourceforge.net with plplot.org.  As a
result the website that is generated and uploaded by this release will
use the official plplot.org domain for all internal references.  And
we have changed our official domain at sf.net/projects/plplot to
plplot.org as well.  We encourage all PLplot users to use that
official PLplot domain as well.

1.10 We have removed the "sys" subdirectory from our source tree

This used to contain special build systems for special ports of PLplot
to various platforms, but over the years our CMake-based build system
turned out to be a better build system than these specials or else for
the given platform the special build system had been unmaintained for
many years and was therefore essentially worthless.  The result has
been subdirectory after subdirectory has been removed from sys over
the years, and for this release the last such subdirectory (for the
so-called win-tk platform whose build system had not been maintained
for more than a decade) was removed from sys which allowed us to
remove sys as well.

1.11 Imported PLplot targets now must use the "PLPLOT::" prefix for the target name

This change is to conform to best CMake-3 practice.  See further details
in 2.11 below.

1.12 Drop -single_module linking option that was previously forced for Mac OS X

We imposed this Mac OS X linking option to address a linking issue
that occurred for CMake on that platform 12 (!) years ago.  We are
virtually positive from our google searches this linking issue no
longer exists so we have removed this option so that from now on
PLplot libraries and executables will be linked in a more standard way
on this platform.

1.13 Changed color interpolation for plscmap1l and plscmap1la

Previously these routines took control points for interpolating a new
colour map, but even if RGB coordinates were passed in, they were
converted to HLS coordinates and interpolated in HLS space. The new
behaviour of these routines is to interpolate in whichever space the
coordinates are passed in with.  In addition to this change in
semantics, there was a backwards-incompatible change in the
names of the members of the PLControlPt C struct in plplot.h.
So those users whose code refers to this C struct will need
to modify their code appropriately.
________________________________________________________________

2. Improvements relative to the previous release

2.1 Bug fixes

The bug fixes in this release are noted in the roughly 150 commit messages
collected in ChangeLog.release.

2.2 Update control of Python version

The build system now takes the following steps to search for a suitable
Python version.

* The build system searches for the PLPLOT_PYTHON_EXACT_VERSION version
  of Python where PLPLOT_PYTHON_EXACT_VERSION is specified by the
  user.  If this string is not specified by the user it defaults to
  "", and this exact search therefore always fails in this case.

* If that first exact search is a failure and the option FORCE_PYTHON2
  is not ON, the build system searches for PYTHON 3.

* If neither of the above two searches is a success, then the build
  system searches for Python 2.

2.3 Rewrite the build-system logic for determining PYQT_SIP_DIR and PYQT_SIP_FLAGS

For pyqt4 the pyqtconfig module useful for determining PYQT_SIP_DIR
and PYQT_SIP_FLAGS has been deprecated and has therefore already
completely disappeared from some software platforms (e.g.,
MinGW-w64/MSYS2).  Therefore, in this release we have replaced that
approach with an approach very similar to what we currently use for
pyqt5 (where the pyqtconfig module has never been available).

For both the pyqt4 and pyqt5 cases, PYQT_SIP_FLAGS is straightforward
to determine but determination of PYQT_SIP_DIR, the location where the
PyQT sip files are located, is not completely straightforward.  For
Linux, Cygwin, and MinGW-w64/MSYS2, we feel we have the correct HINTS
in place to find this directory for either the pyqt4 or pyqt5 cases,
but for other platforms users can specify the correct PYQT_SIP_DIR
directly and are invited to communicate that information to us so we
can update our HINTS appropriately.

2.4 Implement plStatic2dGrid

The 2D matrix arguments of plshade, plshades, plcont, plimage, plvect,
etc., for our C API and corresponding C++ API must currently be
organized as Iliffe column vectors (see
<https://en.wikipedia.org/wiki/Iliffe_vector>) containing pointers to
PLFLT row vectors.  And these matrices are normally in the C case
dynamically allocated with plAlloc2dGrid and freed with plFree2dGrid,
and in the C++ case the same thing is done with C++ wrappers for
plAlloc2dGrid and plFree2dGrid.  However, that dynamically allocated
approach does not allow our C and C++ users to call plshade, etc.,
with statically allocated 2D matrices.

Historically we have partially addressed that issue by implementing a
plshade1 variant of plshade that could be called with a statically
allocated 2D matrix.  Expanding that approach with plshades1, plcont1,
etc., variants is possible, but does considerably clutter our C and
C++ API.  So instead for this release we have implemented the
plStatic2dGrid C function and associated C++ wrapper which allows C
and C++ users to determine the Iliffe column vector corresponding to a
2D statically allocated array. The examples/c/x15c.c and
examples/c++/x15.cc standard examples demonstrate how to use this new
approach to call plshade using 2D data that have been statically
allocated, and although none of our examples illustrate these
additional possibilities, this same approach could also be used to
call plshades, etc., with 2D data that have been statically allocated.
And since this new approach completely supersedes plshade1, we have
officially deprecated that function and its C++ wrapper, see 1.7.

2.5 Replace use of the deprecated WIN32 and __WIN32__ macros by the _WIN32 macro

In our C and C++ source code we now detect non-Cygwin Windows platforms
using the recommended _WIN32 macro (supported by all modern versions
of compilers that work on Windows platforms) rather than the deprecated
WIN32 and __WIN32__ macros.

2.6 Difference report default device changed from psc to svg

We have made extensive changes to our three (CMake-based, CTest-based,
and legacy) test systems (see
<https://sourceforge.net/p/plplot/wiki/Testing_PLplot> for extensive
documentation of those test systems) to provide the user the freedom
(if they specify -DPLPLOT_TEST_DEVICE=<some test device name> to
choose any suitable PLplot device they like for the difference report
that is used to compare standard example results written for each
computer language that is supported by our bindings with the
corresponding C results.  Of course, many such devices are not
suitable for such difference tests because of a number of factors, but
in the past we used -dev psc for this purpose, but recently we also
found -dev svg was suitable.

Of course, both the svg and psc devices share the advantage of having
no external library dependencies and thus they are available
on all platforms.  However, the svg device has two notable advantages
over the psc device for the purposes of difference reports.

* The SVG XML format of the plot file output by the svg device file is
  fundamentally easier for humans to learn than PostScript (at least
  in this author's opinion) which makes it easier to debug rendering
  errors.

* The svg device is a modern PLplot device that implements
  alpha-channel transparency and gradients and which gives access to
  virtually all (unicode-accessible) glyphs installed on a platform
  while the psc device is an ancient PLplot device that because of the
  limitations of PostScript is missing the alpha-channel and gradient
  capabilities and which only gives access to an extremely limited
  number of glyphs.  Thus, when the svg device is used for
  comparisons, test_diff.sh compares one *good* plot file (with the
  exception of example 3 which is consistently missing some of its
  graphical elements for some reason which we will investigate later)
  result with another for all examples.  However, when the psc device
  is used for comparisons the difference test compares one garbage
  plot file with missing or incorrect elements with another for many
  of our standard examples.  This means the svg choice supplies a much
  stronger constraint on our language PLplot API consistency than the
  psc choice.

For these reasons we have adopted -DPLPLOT_TEST_DEVICE=svg as the default value, and it
turns out for that much more powerful test of PLplot we are currently getting perfect
difference report results (see 2.7).

2.7 Resolve the remaining difference report issues

For PLplot-5.13.0 the difference report (for the psc comparison device
used for that report) was perfect except for the following
long-standing OCaml issues:

ocaml
  Missing examples            :
  Differing graphical output  :  16 19 33
  Missing stdout              :
  Differing stdout

Those OCaml inconsistencies with the other languages have now been
fixed by the following steps:

* Implement the plmap* API for our OCaml binding and implement the
  "Exmoor" page for examples/ocaml/x19.ml using that new API to
  achieve consistency for this example.

* In examples/ocaml/x16.xml replace use of the high-level colorbar
  function (which set and restored color which interfered with
  consistency with the other languages) with plcolorbar to achieve
  consistency for this example.

* In examples/ocaml/x33.ml implement all pages concerning
  demonstrating the plcolorbar capability (page 5 onward) to achieve
  consistency for this example.

This change removed all differences for the -dev psc test device but
since this change we have also moved from that device to -dev svg and
we find we get a clean difference report in that more powerful test
case as well.

In sum, because of the OCaml binding and examples improvements we
obtained a perfect PostScript difference report for the first time in
7 years, i.e.,

ocaml
  Missing examples            :
  Differing graphical output  :
  Missing stdout              :
  Differing stdout

and similarly for all the other computer languages we support.  And
these perfect results have now been also demonstrated for the much
stronger test when using the svg device for the comparison.  Long may
this perfection continue!

2.8 Improve command-line parsing

2.8.1 Implement C demonstration of PL_PARSE_SKIP mode

The PL_PARSE_SKIP mode of plparsopts has been implemented for a long
time now in our core C library.  What this mode does is parse the
PLplot-relevant command-line options, skip those which it does not
recognize and return a revised argument list containing the skipped
command-line options that is suitable for further specialized
(non-PLplot) parsing.

To demonstrate this capability we have implemented a -pl_parse_skip
example option for examples/c/x01c.c such that we get the following
result illustrating the PL_PARSE_SKIP capability:

software@raven> examples/c/x01c -pl_parse_skip xxx -dev psc yyy -o testc.psc zzz
argv prior to call of plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/c/x01c
i =   1, argument = -pl_parse_skip
i =   2, argument = xxx
i =   3, argument = -dev
i =   4, argument = psc
i =   5, argument = yyy
i =   6, argument = -o
i =   7, argument = testc.psc
i =   8, argument = zzz
argv after call to plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/c/x01c
i =   1, argument = xxx
i =   2, argument = yyy
i =   3, argument = zzz
PLplot library version: 5.13.0

Note that the valgrind results for the above command and also a more typical
execution of this example,

software@raven> examples/c/x01c -dev psc -o test1c.psc
PLplot library version: 5.13.0

are perfect (i.e., 0 errors, no leaks are possible) with no
PostScript differences between the above two commands other
than the date stamp.

2.8.2 Fortran improvement in parsing the command line

Previously the Fortran parsing API consisted of just

function plparseopts(mode)
    integer :: plparseopts_brief !function type
    integer, intent(in) :: mode
    ....
end function plparseopts

which allowed parsing of just PLplot-related command-line options with
no direct access to the command-line options.

We have now added the following experimental parsing API to the above:

* dynamic length and size
function plget_arguments( argv )
    integer :: plget_arguments
    character(len=:), dimension(:), allocatable, intent(out) :: argv
    ....
end function plget_arguments
function plparseopts(argv, mode)
    integer :: plparseopts
    character(len=:), intent(inout), dimension(:), allocatable :: argv
    integer, intent(in) :: mode
    ....
end function plparseopts

* static length and dynamic size
function plget_arguments( argv, disambiguate )
    integer :: plget_arguments
    character(len=*), dimension(:), allocatable, intent(out) :: argv
    integer :: disambiguate
    ....
end function plget_arguments
function plparseopts(argv, mode, disambiguate)
    integer :: plparseopts_full !function type
    character(len=*), dimension(:), allocatable, intent(inout) :: argv
    integer, intent(in) :: mode
    integer :: disambiguate
    ....
end function plparseopts

* static length and size
function plget_arguments( nargv, argv )
    integer :: plget_arguments_impl !function type
    integer, intent(out) :: nargv
    character(len=*), dimension(0:), intent(out) :: argv
    ....
end function plget_arguments
function plparseopts(nargv, argv, mode)
    integer :: plparseopts_full !function type
    integer, intent(out) :: nargv
    character(len=*), dimension(0:), intent(inout) :: argv
    integer, intent(in) :: mode
    ....
end function plparseopts

The disambiguate variable of the static length and dynamic size
variants is required to distinguish between those variants and the
corresponding dynamic length and size variants.  The static length and
dynamic size and static length and size variants are deprecated, but
we include them for now because certain Fortran compilers (see below)
might have trouble with the dynamic length and size variant of the API
even though that is part of the Fortran 2003 (!) standard.

plget_arguments is a convenience function that exercises the rather
complex Fortran API for determining command-line arguments and returns
all the the command-line components in argv.  The three new variants
of plparseopts operate in a similar way to the C version of
plparseopts returning a modified form of argv that depends on which
mode is specified.

We tested these additions to the Fortran parsing API with
examples/x01f.f90, and Debian Testing gfortran version "Debian 8.2.0-9"

* If that source code is locally modified to change the
pl_parse_dynamic parameter from .false. to .true., and the x01f target
rebuilt then the following good results are  obtained:

software@merlin> examples/fortran/x01f xxx -dev svg yyy -o testf.svg zzz
 pl_parse_dynamic =  T
argv before call to plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/fortran/x01f
i =   1, argument = xxx
i =   2, argument = -dev
i =   3, argument = svg
i =   4, argument = yyy
i =   5, argument = -o
i =   6, argument = testf.svg
i =   7, argument = zzz
argv after call to plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/fortran/x01f
i =   1, argument = xxx
i =   2, argument = yyy
i =   3, argument = zzz
PLplot library version: 5.13.0

* If that source code is locally modified to drop the above change and set the
pl_parse_static_length parameter from .false. to .true., and the x01f target
rebuilt then the following good results are obtained:

software@raven> examples/fortran/x01f xxx -dev svg yyy -o testf.svg zzz
 pl_parse_static_length =  T
argv before call to plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/fortran/x01f
i =   1, argument = xxx
i =   2, argument = -dev
i =   3, argument = psc
i =   4, argument = yyy
i =   5, argument = -o
i =   6, argument = testf.psc
i =   7, argument = zzz
argv after call to plparseopts(..., PL_PARSE_SKIP)
i =   0, argument = examples/fortran/x01f
i =   1, argument = xxx
i =   2, argument = yyy
i =   3, argument = zzz
PLplot library version: 5.13.0

* If that source code is locally modified to drop the previous local
change and change the pl_parse_static parameter from .false. to
.true., and the x01f target rebuilt then the good results above
(except for the difference

 pl_parse_static_length =  T ==> pl_parse_static =  T

) continue to be obtained.

In all three test cases above, valgrind showed perfect results (0 errors with no leaks possible).

Note that when I tried these tests before with Debian Jessie (with gfortran-4.9.2) the first
test errored out with

"Fortran runtime error: Integer overflow when calculating the amount of memory to allocate"

We ascribe this error to a bug in gfortran-4.9.2 for the case of
character arrays that have both the length and size allocated.  So we
recommend that old version of gfortran should be avoided, and it
appears more modern gfortran, e.g., gfortran 8.2.0 tested above, will
not have issues if we drop the deprecated forms of plget_arguments and
plparseopts in favour of the first method where an array of character
strings of both dynamic length and size is allocated.  And that would
clear the way for following up by moving to uniform fortran arrays of
character strings that are dynamic in both length and size for our
entire Fortran API.  That follow up would be terrific since it moves
our Fortran API and corresponding examples out of the Fortran
character array dark ages.  However, there are other fortran compilers
(e.g., ifort, nagfor, absoft) we urgently need to test in the same way
with example 1 before we can go ahead and drop the above deprecated
functionality and do the suggested follow up.

2.9 Cleanup of plmap

We have removed old plmap functionality (see description of this
change in "1.4 Remove plmap cruft" above).  In addition as part of
fixing a wrap bug we substantially simplified the code.  And some
unused functions were also removed.

2.10 wxwidgets development status

This is a status report as of the release of PLplot-5.14.0 for the
"new" wxwidgets components (e.g., -dev wxwidgets, wxPLViewer
application, the wxwidgets binding, and wxPLplotDemo example
application that links to that binding) of PLplot.

Many bugs in the "new" wxwidgets components for this release (see the
ChangeLog for details) have been fixed.  However, despite this
excellent development progress at least two serious issues for -dev
wxwidgets still remain.

* wxPLViewer only displays the end result of each page plotted.

  Instead, it should immediately render that plot buffer as it is
  actively filled with PLplot commands.  That important change will
  supply the required interactivity for example 17 (rather than just
  plotting the end results for that one-page example) and make the -np
  (no pause) option work correctly (where you can see all plot pages
  as they are being plotted rather than just having a blank screen
  99.99% of the time followed by a "flash" of the final page result at
  the end of each page that is so short it is rarely visible).  Note,
  example 17 (without the -np option) and all examples including 17
  with the -np option do render correctly for the interactive xwin,
  tk, xcairo, and qtwidget devices so there should be no fundamental
  reason for this functionality to work incorrectly for -dev
  wxwidgets.

* AWI (Alan W. Irwin) and PR (Phil Rosenberg) have not yet decided on which of the
  -DPL_WXWIDGETS_IPC3=OFF or ON methods should be used to handle
  IPC (interprocess communication) between -dev wxwidgets and the
  wxPLViewer application.

  The -DPL_WXWIDGETS_IPC3=OFF case (developed by PR right when he
  started developing the "new" wxwidgets code) uses a relatively large
  circular buffer located in shared memory to efficiently transfer
  data from one process to the other with transfer progress checked
  periodically by a timed wait.  The majority of this code is a subset
  of code in an event-handling routine on the wxPLViewer side of
  transfers so it is not (yet) organized as a dedicated set of two
  routines (one to send one to receive) you call to transfer data as
  in the -DPL_WXWIDGETS_IPC3=ON case discussed below.  This method
  works well for all noninteractive examples for both Linux and
  Windows.  And in older tests (before the above fixes) for -locate
  mode of example 1 (that mode turns that normally noninteractive
  example into an interactive example) PR found this method succeeded
  on Windows while AWI found this method failed on Linux.

  AWI has recently found for the latest version of the "new" wxwidgets
  code (i.e., after all the above fixes were done) that interactive
  example still has problems, i.e., the display did not come on
  immediately so he had to mouse click on a particular part of the
  blank screen (over one of the hidden viewports) for a while to get
  the example to display properly on Linux for the
  -DPL_WXWIDGETS_IPC3=OFF case.

  The -DPL_WXWIDGETS_IPC3=ON case (developed by AWI long after PR had
  initiated the work on his "new" wxwidgets code) uses a 3-semaphore
  approach to transfer an arbitrarily large block bytes in an
  efficient way from one process to the other using a relatively small
  shared memory buffer with no timed waits.  This complete transfer is
  handled by just two function calls (transmitBytes on the
  transmitting side and receiveBytes on the receiving side).  Those
  two routines use two semaphores to control the transfer in the way
  described by the "Unnamed Semaphores Example" on page 73 and
  following of
  <http://man7.org/conf/lca2013/IPC_Overview-LCA-2013-printable.pdf>.
  In addition, transmitBytes acquires a third semaphore before this
  flow process starts and releases it after all bytes have been
  transmitted to make sure that if other threads call transmitBytes,
  they will just wait to acquire that third semaphore before
  proceeding with its data transfer.  So ordinarily there is absolutely no
  interference between data transfers that occur in different threads.
  However, there is at least one case (one thread transmitting bytes,
  a second thread waiting to transmit bytes, but with
  the first thread unable to regain process control for some reason (e.g.,
  some screw up in handling wxwidgets events) where the first thread
  will be unable to complete
  its transfer ==> deadlock.

  For -DPL_WXWIDGETS_IPC3=ON no such deadlocks have been observed on
  any platform for noninteractive examples, but PR discovered such
  deadlocks occurred on Windows when attempting to run the -locate
  mode of example 1, and AWI also had trouble for this case on Linux.
  But both these tests were done before all the recent wxwidgets fixes
  (which apparently had nothing to do with IPC), and AWI has recently
  discovered that interactive example now works well for the first
  time ever!  So an additional -DPL_WXWIDGETS_IPC3=ON test on Windows
  platforms for this interactive case should be done to see if
  whatever fixed -DPL_WXWIDGETS_IPC3=ON for the Linux case also fixes
  the Windows case.

  In sum, for noninteractive examples we should be fine on all
  platforms with either -DPL_WXWIDGETS_IPC3=ON or OFF.  And for the
  latest version of "new" wxwidgets we are also fine on Linux with
  -DPL_WXWIDGETS_IPC3=ON and the -locate mode of example 1.  But that
  interactive examples fails to work properly on Linux for
  -DPL_WXWIDGETS_IPC3=OFF.  And as far as I (AWI) am aware
  -DPL_WXWIDGETS_IPC3=OFF and ON have not been tested for the latest
  version of "new" wxwidgets on Windows.  Given this uncertain testing
  situation for the latest "new" wxwidgets code on Windows platform, I (AWI)
  have adopted -DPL_WXWIDGETS_IPC3=ON as the default on the assumption
  that the good noninteractive and interactive
  results in the Linux case for -DPL_WXWIDGETS_IPC3=ON will carry over
  to the Windows case when the latest version of the code is tested
  on that platform.  However, if a user runs into any trouble with this
  default choice on any platform, please also try -DPL_WXWIDGETS_IPC3=OFF
  and report back those two results to the plplot-general mailing list
  so we have a chance to replicate the issue and fix it.

Furthermore if either of these serious issues with "new" wxwidgets
affect you in a way you cannot work around, you should also try
-DOLD_WXWIDGETS=ON to see if that gives a better result (although that
old wxwidgets code is in deep maintenance mode so we are unlikely to
change any part of it going forward in case issues with it are
discovered).

By the way, we have tried -DOLD_WXWIDGETS=ON, on Linux (Debian
Testing), and the following good results were obtained: (i) The -np
option does work properly (all example plots seen as they are plotted
out rather than just the final page result) if you test it by building
the test_c_wxwidgets target, (ii) example 17 does plot "interactively"
(rather than plotting final results at the end of the page) if you try
"examples/c/x17c -dev wxwidgets", and (iii) "examples/c/x01c -locate
-dev wxwidgets" works properly, i.e., the display and cursor position
show *before* you make a choice of where to click the mouse button.
However, for these ultra-modern (version 3.0.4) Debian Testing
wxWidgets libraries (this -DOLD_WXWIDGETS=ON problem did not
show up for the old wxWidgets libraries I tested for Debian Jessie =
Oldstable) you have to randomly move the mouse to get long plots such
as "examples/c/x08c -dev wxwidgets" and "examples/c/x17c -dev
wxwidgets" results completely plotted.  So it appears that our "old"
code has exposed a bug in the Debian Testing wxwidgets libraries, but
that bug may not appear for other distributions so -DOLD_WXWIDGETS=ON
is certainly worth trying as a stop gap if there is some aspect of the
"new" wxwidgets PLplot code that is failing.

2.11 First step toward using best CMake-3 practices for our build system

Our CMake-based build system was originally designed more than a
decade ago for CMake-2 by a number of different PLplot developers, and
since then while maintaining this system I have taken full advantage
of CMake-3 backwards compatibility with CMake-2.  The result works
well for cmake-3.7.2 (our minimum allowed cmake version) through
cmake-3.13.1 (the latest version of CMake that has been released).
However, our build system does not follow best CMake-3 practices as
outlined in [this inspiring
article](https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/).

Motivated by that article as well as by comments on the CMake mailing
list, I have now taken the first step toward such best practices which
is to always use prefixed target names (with a prefix of "PLPLOT::")
for read-only use of targets that are installed by the core build
and which are correspondingly imported by the build of the installed examples.
Of course, those imported targets are not available to the core build (since it
builds these special targets before installing/exporting
them) so the only way to implement the same "PLPLOT::" prefix
for these special targets in the core build is to implement ALIASed
versions of all these targets in the core build whose names all
have the "PLPLOT::" prefix.  Both imported targets and ALIASed targets
can only be used by CMake commands which only read information about the target.
So for the sake of consistency, I changed
all read-only references to these special targets in the core build
by always using the "PLPLOT::" prefix for that case.  In addition
for CMake commands which write information to targets
I used the prefix ${WRITEABLE_TARGET} for the target name.
As a result of these changes all special targets for both build systems
had a prefixed target name where the prefix was "PLPLOT::" in the
read-only case and ${WRITEABLE_TARGET} otherwise.

For normal use ${WRITEABLE_TARGET} must be empty since otherwise it
changes the actual installed library and executable names which
completely messes up any non-trivial use of the installed PLplot such
as the installed examples build system.

However, the configure_library_build and configure_executable_build
functions (the functions that are used in the core build to uniformly
configure builds of all special targets) have also been updated so
that a non-empty ${WRITEABLE_TARGET} changes the special library and
executable names while the original PLPLOT::<original target name>
remains the same and is aliased to refer to those changed writeable
targets and corresponding changed names for executables and libraries.
Thus, the net result is the core build and corresponding tests of that
build work when ${WRITEABLE_TARGET} is non-empty.

Normally nobody would be particularly interested in prefixing the name
of all special PLplot libraries and executables in a way that only
works in the build tree.  However, there is one special case where
this capability is quite useful for developers, and that is when they
do a comprehensive test constrained just to the core-build
configurations with -DUSE_WRITEABLE_TARGET_TEST_PREFIX=ON (which is
the only case where a non-empty ${WRITEABLE_TARGET} is created).  If
that comprehensive test is a success (which proved to be the case in
this release cycle after a fair number of iterations), then the
developer knows that there are no unprefixed special targets left in
our build system (since they would refer to library or executable
names that don't exist) with the caveat that only CMake code that is
actually exercised by the above comprehensive test is checked this way
by this test.

N.B. The second and third big steps toward best CMake-3 practices are
in the initial planning stages.  Those steps which with luck will be
ready for the next release are the following:

* Replace all use of the completely unfocused include_directories
  command (that effects builds of all targets in that directory and
  below) with the the target_include_directories command which allows
  us to define *and export* header file locations for one focused
  target.

* Replace a grab-bag of ways to specify compile flags (some compiler options
  some specific -D definitions) and another grab bag of ways to specify
  compile definitions by calls
  to target_compile_options and target_compile_definitions that not only
  make these data available for the core target build but also the subset
  of these data that are typically needed for building against the corresponding
  imported targets.

In sum, we have made a good start toward updating our build system to
best CMake-3 practice for this release, and we plan to update it much
further in that regard for the next release.  The net result of all
these intrusive changes should be that our build system will be
subject to fewer subtle bugs.  And it should also be much easier to
maintain (e.g., during the coming expected advent of CMake-4 where several
deprecated CMake-2 commands such as the include_directories command
that we use now are likely to be dropped).

2.12 Update PLplot to be consistent with modern free software

This important series of changes occurred because the primary testing
platform for PLplot was changed from Debian Jessie (Debian 8) which
was more than 3 years out of date), to Debian Testing (currently
Debian Buster = Debian 10) which is a rolling release that keeps up to date
with modern free software development.

As a result of these changes, the PLplot core libraries, bindings, and device drivers
have now proven [via comprehensive tests](<https://sourceforge.net/p/plplot/wiki/Testing_Reports)
to be compatible with the following modern versions of free software packages:

* CMake-3.13.1	      		 (core, bindings, and device drivers)
* gcc 8.2.0			 (core)
* qhull 2015.2			 (optional core interpolation functionality)
* shapelib 1.4.1		 (optional core map functionality)
* swig 3.0.12			 (java, lua, octave, and python bindings)
* gnatmake/gdc/gfortran 8.2.0	 (ada, d, and fortran bindings)
* g++ 8.2.0			 (c++ binding and psttf and wxwidgets device drivers)
* pango 1.42.3, cairo 1.16.0	 (cairo device driver)
* openjdk 11.0.1		 (java binding)
* lua 5.3.5			 (lua binding)
* camlidl 1.05, ocaml 4.05	 (ocaml binding)
* octave 4.4.1	      		 (octave binding)
* python 3.6.7			 (python binding)
* Qt 5.11.2			 (qt binding and qt device driver)
* Tcl/Tk 8.6.8			 (tcl/tk binding and tk device driver)
* libx11 2:1.6.7		 (tk and xwin device drivers)
* wxWidgets 3.0.4		 (wxwidgets binding and device driver)

Notes for this table:

* The Debian Testing package for swig 3.0.12 contains a swig fix that should be
  generally released for swig-4 that allows PLplot to build an Octave-4.4 binding.
  If your swig-3 version does not have this fix, you should use Octave-4.2
  until swig-4 is released.

* The Debian Testing package for lua 5.3.3 currently perpetuates
  [a serious bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=902238)
  for that particular upstream version.  The above good results for lua
  5.3.5 were generated with a locally built version of upstream 5.3.5.

2.13 Rewrite documentation of PLplot testing

We have completely rewritten <https://sourceforge.net/p/plplot/wiki/Testing_Reports> which
documents how PLplot is tested.

2.14 Configure the ps and psttf device drivers just like all other device drivers

Previous to this change our build system configured the devices (i.e.,
the ps and psc devices) of the ps device driver together (i.e., the
CMake option DPLD_ps controlled both devices) but now it does that
individually (where DPLD_ps and DPLD_psc control the ps and psc
devices separately).  And similarly for the psttf and psttfc devices
of the psttf device driver.  Previous to this change, all other device
drivers configured their devices individually and now that the ps and
psttf device drivers are no longer anomalous in that regard, it has
allowed us to simplify our build system logic substantially for
anything having to do with the ps or psttf device drivers.
________________________________________________________________

3. PLplot testing

Comprehensive tests of this release are documented in
<https://sourceforge.net/p/plplot/wiki/Testing_Reports>.
In addition, developers and users who have used the git master tip
version for all their plotting needs during this release cycle have
provided additional important testing of this release of PLplot.
________________________________________________________________
PLplot Release 5.13.0

This is a release of the PLplot plotting package. It represents the
ongoing best efforts (roughly 100 commits since the last release) of
the PLplot development community to improve this package, and it is
the only version of PLplot that we attempt to support.  Releases in
the 5.x.y series should be available roughly two times per year.

Note that PLplot has been continuously developed since 1986 so it has
accumulated a lot of cruft since that time that we are now slowing
dealing with to improve the lot of both new users and new members of
the development team.  As a result virtually every PLplot release has
some backwards incompatibilities introduced to help clean it up so
please pay careful attention to the OFFICIAL NOTICES FOR USERS below
where we document such incompatibilities to make life easier
for those who have prior experience with older PLplot releases.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via our mailing lists (preferred for initial discussion of
issues) at <http://sourceforge.net/p/plplot/mailman/>. If it turns out
no quick resolution is possible via mailing-list discussion, then the
issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

This software is primarily distributed under the LGPL.  See the
Copyright file for all licensing details.
________________________________________________________________

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility
1.2 Notice of dropping our plan to introduce a generic C pointer with const attribute

2. Improvements relative to the previous release

2.1 Bug fixes
2.2 The Python binding and examples now work for both Python 2 and 3
2.3 Change the Fortran naming convention
2.4 Fix many "space in prefix" issues
2.5 Complete rewrite of IPC between -dev wxwidgets and wxPLViewer
2.6 Implement a new Windows GDI (wingdi) device driver
2.7 Implement new Python extension module to support pytkdemo
2.8 Fix OCaml inconsistencies for example 8
2.9 Improve the implementation of the OCaml binding

3. PLplot testing
________________________________________________________________

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility

Our build system is implemented using CMake.  The minimum version of
CMake we allow is 3.6.2 on all platforms.  (And it is likely we will
bump that minimum version to at least 3.7.2 for our next release.)

This particular PLplot release has been comprehensively tested for
CMake versions 3.6.2 through 3.9.1 on a variety of platforms (see
<http://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Testing%20Reports>).
So if your CMake version is <= 3.9.1 and satisfies the above minimum
CMake version requirement there is an excellent chance that our build
system will work well.  Furthermore, if you try later CMake versions
as they are released during the life of this PLplot release, our build
system will likely continue to work well because CMake has an excellent
reputation for preserving backwards compatibility.  But if you get
build-system trouble for versions of CMake greater than 3.9.1, the
first thing you should try is CMake-3.9.1 which has been well-tested
by PLplot builds.

1.2 Notice of dropping our plan to introduce a generic C pointer with const attribute

This plan (first mentioned in the 5.12.0 release notes) has been
dropped because the const attribute on generic pointers obviously
disallows users from using our generic pointer arguments to pass back
information from their callback routines.  As a result of this change
we have the following situation for our generic pointer arguments.

5.11.1 and before: PLPointer (typedef'd to void *) was our generic pointer argument

5.12.0: PLPointer was deprecated (in retrospect, not a good idea), and
PL_GENERIC_POINTER and PL_NC_GENERIC_POINTER were introduced with both
typedef'd to void *, but with the plan (since dropped) going forward
to typedef PL_GENERIC_POINTER as const void * (since the NC in the
name of PL_NC_GENERIC_POINTER is meant to signal non-const, that
implies when NC is dropped as in PL_GENERIC_POINTER that the type in
question has a const attribute similar to many other typedef pairs
with and without the const attribute that are defined in
include/plplot.h).

5.13.0.  Due to the change in plan, PLPointer is now preferred again,
and PL_GENERIC_POINTER and PL_NC_GENERIC_POINTER are officially
deprecated and are likely to be removed in the next release since they
were only introduced in non-deprecated form for one release.  All
three continue to be typedefed as void *.

________________________________________________________________

2. Improvements relative to the previous release

2.1 Bug fixes

The bug fixes in this release are noted in the roughly 100 commit messages
collected in ChangeLog.release.

2.2 The Python binding and examples now work for both Python 2 and 3

We have generalized our previous Python 2 binding and examples so they
work now with both Python 2 and 3.  The minimum versions of Python we
support are 2.7 for Python 2 and 3.4 for Python 3.  Our build system
finds Python 3 by default, but if the user prefers Python 2, they
can arrange that by using the cmake option -DFORCE_PYTHON2=ON.

We arrived at the Python 3 default choice because I (AWI) was having
trouble with corruption of the Python-generated file
bindings/python/Plframe.pyc fairly often with Python 2 while that
corruption has never happened with Python 3.  (This result is exactly
consistent with a Python developer's prediction when consulted about
that corruption bug that it was unlikely to occur for Python 3 because
that version was better maintained in general than Python 2.)

After our build system finds the Python executable, it then finds the
Python library and numpy versions that are consistent with whether
that Python executable corresponds to Python 2 or Python 3.

As a result of these changes we get perfect PostScript difference
reports between Python and C, i.e.,

python
  Missing examples            :
  Differing graphical output  :
  Missing stdout              :
  Differing stdout            :

for both Python 2 and 3.

2.3 Change the Fortran naming convention

Our Fortran binding and examples are written for the Fortran 2003
standard so the previous references in our build system, source code,
documentation, and even names of files and directories to "f95",
"F95", or Fortran 95 are all misnomers which we have addressed by
replacing essentially all occurrences of those with "fortran" or
"Fortran" as appropriate.  For example, our Fortran binding and
examples are now stored in the subdirectories bindings/fortran and
examples/fortran rather than bindings/f95 and examples/f95 that we
used before, and our build system enables our Fortran binding and
examples with the CMake variable ENABLE_fortran rather than the
ENABLE_f95 CMake variable that we used for this purpose before.

2.4 Fix many "space in prefix" issues

As a result of these fixes we can execute

scripts/comprehensive_test.sh --prefix "../comprehensive_test_disposeable blank"

from a source tree whose prefix has a space in it without any errors on Linux.

This is a successful comprehensive test of all components of PLplot
available on a fully loaded Linux platform where the prefixes for the
source, build, and install trees all contain spaces.  However, this
test does not test components of PLplot that are only available on
other platforms, and does not test the case where external libraries
that PLplot depends on have spaces in their full pathnames.  So this
"space" work is a large step in the right direction but is not
complete.

2.5 Complete rewrite of IPC between -dev wxwidgets and wxPLViewer

The inter-process communication (IPC) between -dev wxwidgets and
wxPLViewer was previously implemented using a circular shared memory
buffer with a mutex controlling access to that buffer.  That complex
IPC logic has now been completely rewritten in a much simpler way
using a three-semaphore approach.  One of those semaphores is used to
control the overall process of transmitting the bytes in either
direction between the two IPC partners via a shared memory buffer.
The remaining two semaphores are used to control the details of
sending bytes from -dev wxwidgets to wxPLViewer (or vice versa)
following the ideas described on page 73 and following of
<http://man7.org/conf/lca2013/IPC_Overview-LCA-2013-printable.pdf>.
However, the unnamed semaphores advocated at that site has been
replaced with named semaphores in our three-semaphore approach since
support for unnamed semaphores is not available on Mac OS X (and
likely other POSIX systems) or Windows and since all POSIX systems and
Windows support named semaphores.  Our tests show this new IPC
approach works well on Linux (and presumably all other POSIX
platforms) and Windows.  Also, we have found that it remains efficient
even when the shared memory buffer size is reduced by a factor of 100
(!) when compared with the corresponding buffer size used in the old
IPC approach.  Therefore, we have deprecated the old IPC approach and
plan to remove it (likely for the next release).  But for this release
that old IPC approach can still be accessed using the cmake option
-DPL_WXWIDGETS_IPC3=OFF.

2.6 Implement a new Windows GDI (wingdi) device driver

This implementation is based on the wingcc device driver, but unlike
that driver it does not use the deprecated plfreetype approach to
handle Unicode text.  Instead, it is a pure GDI driver which is not
currently Unicode-aware but which is a first step to a Unicode-aware
driver that uses the GDI+ API (along with the Uniscribe API to handle
Unicode text).  Because Microsoft has deprecated GDI+ and Uniscribe,
we also plan eventually to develop a device driver based on wingdi
which uses the Microsoft-recommendend Direct2D API (along with their
recommended DirectWrite API to handle Unicode text).

2.7 Implement new Python extension module to support pytkdemo

The pytkdemo example was previously supported by the hand-crafted
plplot_widget Python extension module, but that module had not been
maintained for a long time and was based on such old Python standards
that it did not work with Python3.  Therefore, I removed that
"plplot_widget" module and replaced it with the swig-generated
"Pltk_init" module which is really simple (since it is based on swig
wrapping of a small C routine that just calls Pltk_Init from the
plplottcltk library) and which is compatible with both Python3 and
Python2.

2.8 Fix OCaml inconsistencies for example 8

This change consisted of adding plsurf3dl (and plot3dcl) to the
ocaml binding, and using that new binding API to add an additional
page to examples/ocaml/x08.ml to make the result consistent
with the results from examples/c/x08c.c.  The PostScript
differences have now been reduced to

ocaml
  Missing examples            :
  Differing graphical output  :  16 19 33
  Missing stdout              :
  Differing stdout            :

i.e., the long-standing example 8 difference has now been removed from this report.

The above differences are the only ones left in our PostScript
difference report generated by, e.g., building the test_diff_psc
target.  So when these remaining differences are removed (with luck in
the next release cycle) using similar bindings/ocaml and
examples/ocaml changes as used in commit 45fdd53 to deal with the
example 8 case, we should finally have a clean overall PostScript
difference report after many years of living with the above issues.

2.9 Improve the implementation of the OCaml binding

Our build system implements the OCaml binding using a series of custom
commands and associated custom target.  Those custom commands have
been greatly improved with regards to consistency, dependencies, and
elimination of all space in prefix (see 2.4) issues.

In addition our build system now properly supports the OCaml binding
for the static build of PLplot.  Previously this support was
experimental (enabled only if the user specified
-DENABLE_ocaml_static=ON), and frankly did not work because this
capability was completely unmaintained.  For example, the list of
libraries to link was incomplete and contained the old "plplotd" name
for the PLplot library rather than the correct modern "plplot" name.
Also, the CMake logic that processed those libraries used the
<libname>_LIB_DEPENDS form of variables which are now deprecated by
CMake in favor of using the INTERFACE_LINK_LIBRARIES properties of
libraries.  Therefore, the build-system logic implementing the OCaml
binding for the static build case was completely rewritten taken all
these issues into account, and as a result the ENABLE_ocaml_static
option has now been removed because the OCaml bindings now work
without issues for the static build case.

________________________________________________________________

3. PLplot testing

Comprehensive tests of this release are documented in
<http://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Testing%20Reports>
and
<https://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Fortran%20Testing%20Reports>.
In addition, developers and users who have used the git master tip
version for all their plotting needs during this release cycle have
provided additional important testing of this release of PLplot.
________________________________________________________________
PLplot Release 5.12.0

This is a release of the PLplot plotting package. It represents the
ongoing best efforts of the PLplot development community (roughly 400
commits since the last release) to improve this package, and it is the
only version of PLplot that we attempt to support.  Releases in the
5.x.y series should be available several times per year.

Note that PLplot has been continuously developed since 1986 so it has
accumulated a lot of cruft since that time that we are now slowing
dealing with to improve the lot of both new users and new members of
the development team.  As a result virtually every PLplot release has
some backwards incompatibilities introduced to help clean it up so
please pay careful attention to the OFFICIAL NOTICES FOR USERS below
where we document such incompatibilities to make life easier
for those who have prior experience with older PLplot releases.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via our mailing lists (preferred for initial discussion of
issues) at <http://sourceforge.net/p/plplot/mailman/>. If it turns out
no quick resolution is possible via mailing-list discussion, then the
issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

This software is primarily distributed under the LGPL.  See the
Copyright file for the licensing details.
________________________________________________________________

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility
1.2 Backwards incompatibilities have been introduced for our C (and other) API
1.3 Backwards incompatibilities have been introduced for our Fortran binding
1.4 Backwards incompatibilities have been introduced for our Tcl/Tk bindings
1.5 Octal interpretation has been removed from numerical escape sequences in text
1.6 The rpath treatment has been changed for Mac OS X platforms
1.7 Notice of a backwards incompatibility for our C API that we plan for our next release

2. Improvements relative to the previous release

2.1 Bug fixes
2.2 Rewrite the CMake Ada language support
2.3 Rewrite the Fortran binding
2.4 Supply old Fortran binding and examples option
2.5 Backwards incompatibilities introduced by the new Fortran binding
2.6 Examples reworked for the -DPL_DOUBLE=OFF case
2.7 Changes to our Ada bindings and examples
2.8 Changes to our tclmatrix library
2.9 Backwards-incompatible changes to our Tcl/Tk bindings and examples
2.10 Substantial rewrite of the DocBook documentation
2.11 Default page size consistency
2.12 Updated D language support
2.13 Modernized build-system support for Qt4 and Qt5
2.14 Implemented support for pyqt5
2.15 Addressed -DPL_DOUBLE=OFF issues
2.16 Replaced "Lena" with "Chloe"
2.17 Removed trailing blanks on most text files in our source tree
2.18 Make our wxwidgets find module consistent with the official version for CMake-3.7.1
2.19 Introduction of two new generic pointer types to help protect against a planned future C API breakage
2.20 Introduction of additional self-describing names for the types of arguments used in our C API.
2.21 Implement submission of dashboards to the <my.cdash.org> cdash server
2.22 Substantial update and rename of the Python examples
2.23 Linux efficiency improvements for the wxwidgets device driver

3. PLplot testing
________________________________________________________________

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility

Our build system is implemented using CMake.  The minimum version of
CMake we allow is 3.0.2 on Linux and 3.6.2 on all other platforms.
(And it is likely we will bump those minimum versions to at least
3.7.0 for our next release.)

This particular PLplot release has been comprehensively tested for
CMake versions 3.0.2 through 3.7.0 on a variety of platforms (see
<http://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Testing%20Reports>).
So if your CMake version is <= 3.7.0 and satisfies the above minimum
CMake version requirement there is an excellent chance that our build
system will work well.  Furthermore, if you try later CMake versions
as they are released during the life of this PLplot release, our build
system might continue to work well because CMake has an excellent
reputation for preserving backwards compatibility.  But if you get
build-system trouble for versions of CMake greater than 3.7.0, the
first thing you should try is the well-tested CMake-3.7.0.

1.2 Backwards incompatibilities have been introduced for our C (and other) API

We recently discovered that the second (argv) argument of plparseopts
was changed by that routine so accordingly we have dropped the
inappropriate "const" attribute from the type of that argument.

The return type has been change from int to PLINT (which is normally
defined by "typedef int32_t PLINT;" for plparseopts, plsetopt,
plMergeOpts, plFindName, plGetCursor, and plTranslateCursor.

All these changes have been propagated to our language bindings where
appropriate.

1.3 Backwards incompatibilities have been introduced for our Fortran binding

The new implementation of the Fortran binding has introduced a
significant number of backwards incompatibilities.  See 2.5 below for
the details.

1.4 Backwards incompatibilities have been introduced for our Tcl/Tk bindings

Our Tcl/Tk bindings and examples now use only a redacted API, i.e.,
redundant array dimensions are removed from all argument lists.
See 2.9 for the details concerning this important Tcl/Tk change.

1.5 Octal interpretation has been removed from numerical escape sequences in text

The undocumented feature where leading 0's in numerical escape
sequences meant the whole number was interpreted as octal rather than
decimal has been removed, i.e., if the number string starts with 0x or
0X then the interpretation of the number is hexadecimal (as before),
but all other number strings starting with 0 are interpreted as
decimal rather than octal.  Thus, the decimal interpretation of
"#(0123)" and "#(123)" is now identical, and there are no errors
introduced by leading-zero decimal escape sequences such as "#(0855)".

1.6 The linking method has been changed for the Mac OS X platform

For this platform our build system previously used the default CMake
rpath-based linking method in the build tree, but in the installed
examples tree used the INSTALL_NAME_DIR linking method instead of the
rpath-based method.  For this release the build-tree linking method
uses the rpath-based linking method as before, but if USE_RPATH is ON
(the default) we also use the rpath-based linking method in the
installed examples tree.  This change makes our linking treatment on
Mac OS X similar to that on Linux with the side benefit that
DYLD_LIBRARY_PATH no longer has to be set in order to use a
traditional (Make + pkg-config) build of software against a set of
PLplot libraries that are installed in a non-standard location.
However, those who install PLplot libraries in standard locations
(typically just the downstream Mac OS X free software distributors of
PLplot such as Fink, MacPorts, and Homebrew) may prefer not to use
rpath-based methods for installed libraries.  Such users should
specify the old linking behaviour using -DUSE_RPATH=OFF.

1.7 Notice of a backwards incompatibility for our C API that we plan for our next release

In our next release as an aid toward achieving our goal of const
correctness for PLplot, we plan to distinguish between generic pointer
arguments to our C API that do and do not have the const attribute.
See 2.19 for a method of protecting yourself against that planned
future backwards incompatibility for our C API.
________________________________________________________________

2. Improvements relative to the previous release

2.1 Bug fixes

The bug fixes in this release are noted in the ~400 commit messages
collected in ChangeLog.release.

2.2 Rewrite the CMake Ada language support

The CMake-based Ada language support has been totally rewritten
based on the official CMake-3.4.0 language support that is used for
C++.  This rewrite should make the Ada language support much easier to
understand since the diff results comparing Ada and CMake-3.4 C++
language support are quite small if some Ada to CXX translations are
done with sed.  Also, it is considered to be a major advantage that
the new Ada language support is based on modern CMake language support
principles and infrastructure as opposed to whatever was available for
language support a decade ago when the old Ada language support was
implemented.

This new Ada language has been much more extensively tested than our
old Ada language support.  On Linux it is essentially perfect for our
Ada library and executable needs in the build tree and install tree.
On Mac OS X, our one report shows no problems in the build tree, but
there is a linking issue in the install-tree version of PLplot Ada
libraries that we have been unable to figure out.  Our one report for
Cygwin (the first time our old or new Ada language support has been
tested on any Windows platform) shows failure of our Ada
language support on that platform (fairly much as expected since we
don't understand what the Cygwin platform requires for CMake language
support) .

2.3 Rewrite the Fortran binding

The Fortran binding has been completely rewritten using the powerful
capabilities of the iso_c_binding module that is available for modern
Fortran.  There are several advantages to this rewritten binding.

(i) It is implemented using much more compact code with none
of the interfacing done in C (i.e., the plplotf95c library has
now been removed completely).

(ii) It is much easier to understand and maintain than the previous
effort.

(iii) Linking issues are simplified.  (nm --undefined-only shows that
the Fortran examples only need to be linked to libplplotf95 and not
libplplot)

(iv) Support for kind=plflt for those who just want to adopt in their
own code the same Fortran floating-point precision as in our C
libraries remains, but this is no longer necessary.  Instead, users
are encouraged to use either kind(1.0) or kind(1.0d0) for the
floating-point arguments in calls to PLplot routines, and our new
Fortran binding automatically does the appropriate conversions to the
floating-point precision of our C libraries using modern Fortran's
overloading mechanism.

N.B. plflt is now replaced in our examples by pl_test_flt, and that
latter parameter is made available by the plplot module as a
convenience to our Fortran developers to test that either kind(1.0) or
kind(1.0d0) works well for our examples regardless of the
floating-point precision used in our C libraries.  But users are
strongly discouraged from using this test parameter for their own code
because we make no guarantees concerning its value, and instead they
should make their own decision about whether to adopt kind(1.0) or
kind(1.0d0) for the floating-point arguments for a given call to a
PLplot routine.  See further remarks in examples/f95/README_precision.

(v) Once support for bindings/old_f95 and examples/old_f95 (see 2.4
below) has been dropped, the "c_" prefixes on our C API that were
required to avoid name clashes with the Fortran versions are no
longer required for that reason.  If it turns out no other
binding requires these prefixes then we potentially could
remove them which would be a welcome simplification.

We have achieved good test results (no build or run-time issues, no
PostScript differences between the Fortran and C results for our ~30
standard examples written in the two languages) for gfortran, ifort,
and nagfor with this new Fortran binding and examples.  In particular,
we feel it is significant there are no warning messages at all
generated by nagfor when we build the new Fortran binding and examples
with that compiler.  We had to make a significant number of changes to
achieve that goal to bring us into strict standards compliance consistent
with the claim made for that compiler that it is "valued by developers
all over the globe for its checking capabilities and detailed error
reporting" (see <https://www.nag.com/nag-compiler>).

One known gfortran downside of this new binding is it generates some ~50
"marked PRIVATE" warning messages when building the plplotf95 target
with the gfortran Fortran compiler.  A typical example of such a
warning message is

Warning: Symbol 'interface_plcont' at (1) is marked PRIVATE but has been given the binding label 'c_plcont'

It appears these warnings (which do not occur if using the ifort or
nagfor Fortran compilers) are due to a gfortran bug (see
<https://gcc.gnu.org/bugzilla/show_bug.cgi?id=49111> and
<https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64861>), i.e., they are
spurious warnings concerning completely valid use of the private
attribute for interface blocks describing C routines.  There appear to
be no known negative consequences of this gfortran bug other than the
spurious warnings themselves.  Until this gfortran bug is fixed, these
~50 "marked PRIVATE" warnings should just be ignored for those using
gfortran.

Another known gfortran downside of this new binding is it does not
build with gfortran 4.8.x or less, i.e., apparently the implementation
of the iso_c_binding module for those versions of gfortran is not good
enough to build our new Fortran binding.  However, our tests show
gfortran 4.9.2 does implement the iso_c_binding module well enough to
produce good results (other than the above spurious warnings).  So
4.9.2 is the minimum version of gfortran that we support with this new
binding, and if the user is temporarily stuck with an earlier version
of gfortran, see the next section.

2.4 Supply old Fortran binding and examples option

Because the new Fortran binding is not completely compatible with the
old one (see 2.5 below for the list of incompatibilities) and does not
build for gfortran versions less than 4.9.2, we have
supplied a -DPL_DEPRECATED_f95=ON CMake option (which defaults to
OFF) that uses a snapshot of the old Fortran binding and associated
Fortran examples rather than the new versions.

We have tested the new Fortran bindings and examples on several
different Fortran platforms accessible to us so it should normally
work well, but this option should be suitable for emergency conditions
where you just cannot get the new Fortran binding to work properly.
But in this case please let us know about those issues so we can fix
them.  Also, this -DPL_DEPRECATED_f95=ON option should extend the
length of time that the old Fortran 95 binding is available for new
PLplot releases, but that old binding will not be available
indefinitely so at some point (after discussions on the plplot-general
list concerning how many users are still using this option) the
-DPL_DEPRECATED_f95=ON option will be removed and user choices will be
reduced to either using an old PLplot version or modifying their
software for the incompatibilities mentioned below for the new Fortran
binding.  And if you start that modification process immediately, you
will likely get better help with it since we have just gone through
that process for the Fortran examples (which should be your first
guide concerning how to use the new Fortran binding).

2.5 Backwards incompatibilities introduced by the new Fortran binding

The rewritten Fortran binding does have a significant number of
backwards-incompatible API changes we have decided to introduce at
this time to improve consistency and simplicity as much as possible.
As always, the examples are your best documentation on how to
use this new Fortran API.  But for those experienced with the
old API, here is the list of changes.

(i) The new Fortran binding only maps C routines that have return
values to Fortran functions and C routines with no return values to
Fortran subroutines.  The strict application of this rule means that
plparseopts, plsetopt, and plGetCursor have been changed from
Fortran subroutines to Fortran functions.  This requires changes to
users' code similar to the following:

call plparseopts(...)

changed to

integer :: plplarseopts_rc
[...]
plparseopts_rc = plparseopts(...)

which will now allow our Fortran users to respond to error conditions
for plparseopts, plsetopt, and plGetCursor.

(ii) Only the redacted form of API (with all redundant dimension
arguments removed) is supported.  The following set of functions
has been affected by the strict application of this rule:

pllegend (drop redundant nlegend argument),

plpat (drop redundant nlin argument),

plsurf3dcl (drop redundant indexxmax argument),

plstyl (drop all overloaded versions other than the redacted one.  N.B. use
zero-sized arrays to indicate that plstyl should restore the default continuous
line style.)

(iii) Multiple arrays in a redacted argument list should have
consistent sizes for dimensions that are designed for the same
purpose.  This rule has been enforced for many years for most
languages where we provide bindings since if we take the size from an
array that is inconsistently smaller because of user error, then part
of the plot will be missing, and if we take the size from an array
that is inconsistently larger because of user error, then access
violations or memory management issues will be the result.  To warn of
such potential issues for the Fortran case we now generate a warning
when inconsistent array sizes are encountered.  For those cases which
generate such warnings because the calling routine provides static or
allocatable arrays which are larger than the subsets of the array
indices which have values assigned, it is straightforward to comply
with this consistency rule by taking the appropriate array slice in
the argument list, e.g., "text_colors(1:nlegend), text(1:nlegend)" in
the pllegend argument list.

The complete list of these adopted rules for consistently sized array
arguments for our Fortran binding are given at
bindings/f95/README_array_sizes.

(iv) Fortran logical arguments are strictly used for all cases where
the corresponding C argument is PLBOOL.  In order to comply strictly
with this rule, the list of functions whose arguments have changed
from integer to logical or functions where an extra signature with
integer argument rather than correct logical argument has been removed
is the following:

plarc (last argument),
plspal1 (last argument), and
plconfigtime (fifth argument).

(v) For those rare cases where the actual floating-point precision
cannot be automatically specified by the user via the precision of the
floating-point arguments which are used for a call to a subroutine or
function, then the only choice we supply is the double precision
(kind(1.0d0)) one regardless of the underlying precision of the C
plplot library.

The instances of this issue are the floating-point return value of the
function plrandd, floating-point elements of the defined type
PLGraphicsIn, floating-point arguments of Fortran callback functions
that are used as arguments for plstransform and pllabelfunc, and the
pre-defined floating-point parameters PL_NOTSET, PL_PI, and PL_TWOPI.
To see how each of these cases should be handled by users please
consult examples/f95/README_precision and the Fortran examples
in that directory.

(vi) The experimental and far from uniform support for the kind=plint and
kind=plunicode Fortran integer types has now been removed.  Instead,
ordinary default kind integers are used for the Fortran types
corresponding to the PLINT and PLUNICODE C types.

(vii) Support for a single integer argument for plstransform that is
unused is dropped because calling plstransform with no arguments
has exactly the same effect.

(viii) A rectangular logical argument for all variants of plshade and
plshades has been added to give the same control of this argument to
Fortran users that is currently available to C users.

(ix) The "defined" argument for all variants of plshade and plshades
that existed but was unused in the old Fortran binding has been
removed for the new binding.

(x) The old support for translating any "\n" characters in Fortran
character string arguments to "char(10)" has now been removed.
Instead, a user should use achar(10) (not char(10) which may not give
you the desired line feed character on certain platforms) to do this
job instead. So if the old character string argument was

"Heale\nDown"

that should be replaced by

"Heale"//achar(10)//"Down"

(Compare examples/old_f95/x19f.f90 with examples/f95/x19f.f90.)  The
net result of the achar(10) method is that the Fortran character
string is reliably on all platforms translated at the C level to
"Heale\nDown" (where in this case "\n" has a special character meaning
of linefeed unlike the Fortran case.  After that, how our device
drivers currently interpret that special C character for linefeed is
idiosyncratic to each of our device drivers.)

(xi) The index arguments (i.e., the last 3 arguments) of plot3dcl and
plsurf3dl have been changed from one-based indexing to zero-based
indexing to be consistent with C and also all our other bindings.

(xii) For the plimagefr signature without callback-related arguments
(i.e., no trailing xg, yg, tr, or callback arguments), we now use NULL
internally for the C callback following what is done (both in the old
and new binding) for the plshade and plshades signatures without
callback-related arguments.  In all these different cases, the C
library interprets the NULL callback as a signal to map the x and y
index ranges to the world coordinates xmin, xmax, ymin, and ymax
(which also appear in the argument lists for plshade, plshades, and
plimagefr) without recourse to a callback.  The old Fortran binding
used pltr0 rather than NULL for the plimagefr signature without
callback-related arguments.  In retrospect we feel this was an error
(since it meant xmin, xmax, ymin, and ymax were always ignored for the
old Fortran plimagefr case).  Note, this distinction does not matter
for our Fortran example 20 (the only place this particular signature
of plimagefr is used in our examples) since xmin, xmax, ymin, and ymax
correspond to the exact x and y ranges that pltr0 delivers.  But it
does matter for other uses of this plimagefr signature which is
why we are documenting this backwards incompatibility here.

(xiii) For the plcont and plvect signatures without callback-related
arguments (i.e., no trailing xg, yg, tr, or callback arguments), we
now use pltr0 internally for the callback rather than pltr0f (which
applies an offset of 1 unit in the way that input arguments were
interpreted compared to pltr0).  The idea behind pltr0f was
problematic since the index range being interpreted was always in the
C code and has nothing to do with Fortran indices.  In any case, this
is likely a "for the record" backwards incompatibility since these
particular signatures for plcont and plvect were not documented, and
were not used in any of our examples.

2.6 Examples reworked for the -DPL_DOUBLE=OFF case

N.B. Many of our supported languages do not currently work for
-DPL_DOUBLE=OFF so the changes below for many of our examples cannot
be tested for that case.  However, all these changes are worthwhile
style changes in their own right that have been thoroughly tested for
the (default) -DPL_DOUBLE=ON case.

* Example 29 has been changed for all our supported languages to be
  much more careful of adopted epoch to maximize the
  time-representation precision.  This is a good illustration of how
  to use epochs correctly for our users, and also allowed this example
  to give good results (as opposed to errors) for the -DPL_DOUBLE=OFF
  case.

* Example 31 has been changed for all our supported languages to use
  variables rather than constants for arguments of most calls
  (specifically all calls with floating-point arguments) to PLplot
  routines.  Use of variables rather than constants is generally
  better form in any case (via the self-description associated with
  well-chosen variable names), but this change also dealt with
  -DPL_DOUBLE=OFF errors for this example in a natural way for C, C++,
  and likely other languages as well.

* Example 33 has been changed for all our supported languages to
  replace the former scaling factor of 1.e-200 by 1.e-20.  This solved
  an issue with the -DPL_DOUBLE=OFF case where the former scaling
  factor underflowed, and those uniformly zeroed results in turn
  caused PLplot run-time errors.

2.7 Changes to our Ada bindings and examples

Using PLplot "traditional" and PLplot "standard" to name our two thick
user-visible Ada bindings has long been documented in our DocBook
documentation for our Ada bindings.  That is a good naming convention
since the names of these bindings nicely complement each other.  Our
existing Ada thick "PLplot_Traditional" binding implementation already
follows this naming convention, and we have now changed to this same
naming convention for our other thick binding by renaming it from
"PLplot" to "PLplot_Standard".  To keep backwards compatibility
(which has been tested by building and running our PLplot-5.11.1 Ada
examples against our latest Ada binding) we still provide
the deprecated "PLplot" name to be used in "with" and "use" statements
instead of the recommended "PLplot_Standard" name to access our
"standard" thick binding.

We have changed our Ada examples to be consistent with the above change.  In
addition, we have renamed the x??a.adb examples which depend on what
is now called our thick PLplot_Traditional binding to xtraditional??a.adb
and our xthick??a.adb examples (a egregious misnomer) which depend
on what is now called our thick PLplot_Standard binding to xstandard??a.adb.

We have made changes to our Ada bindings and examples so they now provide
the following report of complete consistency with the corresponding C results:

    adastandard
      Missing examples            :
      Differing graphical output  :
      Missing stdout              :
      Differing stdout            :
    adatraditional
      Missing examples            :
      Differing graphical output  :
      Missing stdout              :
      Differing stdout            :

2.8 Changes to our tclmatrix library

Implement vastly improved index slicing following the index slicing
rules used for Python.  Also implement vastly improved array
initialization and assignment for our tclmatrix library.
To see what is now possible, take a look at bindings/tcl/test_tclmatrix.tcl
and also the added instructions in examples/tcl/README.tcldemos for using
bindings/tcl/test_tclmatrix.tcl to test all these new tclmatrix capabilities.

2.9 Backwards-incompatible changes to our Tcl/Tk bindings and examples

Our Tcl/Tk bindings have been modified in a backwards-incompatible way
to use a redacted API.  That is, redundant array dimension information
has now been removed from all calls to PLplot routines.  So for
example, the call to plline from a Tcl/Tk environment has been changed
from

$w cmd plline $nsize x y

(where $nsize is the redundant size of the x and y arrays)

to

$w cmd plline x y

Note, this call returns TCL_ERROR if either x or y are of the wrong
type, or if x and y have inconsistent lengths.  So this new API is typically
more robust than our old API.  Of course, there are cases where users need to
collect information in x and y matrices of different sizes and only
plot a subset of that information.  For this case you should use the new
tclmatrix index slicing, matrix initialization, and matrix assignment capabilities
to create the same-sized x and y matrices you want to plot.

For (a rather contrived) example that plots a slice of xoriginal and
yoriginal corresponding to the third hundred values of xoriginal and the
second hundred values of yoriginal do the following:

matrix xoriginal f 500
matrix yoriginal f 1000

# for loop to define the 500 values of xoriginal
[...]
# for loop to define the 1000 values of yoriginal

# Use new index slice and matrix initialization capability
# to select the third hundred xoriginal values to plot:

matrix x f 100 = [xoriginal 200:300]

# Use new index slice and matrix assignment capability
# to select the second hundred yoriginal values to plot:

matrix y f 100
y : = [yoriginal 100:200]

$w cmd plline x y

Note that many PLplot calls do involve arrays so this new redacted API is largely
incompatible with the old API.  So for old applications we have
provided the -DUSE_NON_REDACTED_TCL_TK=ON cmake option to provide
access to a deprecated version of our Tcl/Tk bindings and examples
that is a snapshot of the relevant Tcl/Tk code before any of this
redacted API work had been done.

This -DUSE_NON_REDACTED_TCL_TK=ON option should extend the length of
time that the old non-redacted API is available with new PLplot
releases, but that deprecated API will not be available
indefinitely so at some point (after discussions on the plplot-general
list concerning how many users are still using this option) the
-DUSE_NON_REDACTED_TCL_TK=ON option will be removed and user choices
will be reduced to either using an old PLplot version or modifying
their Tcl/TK software for the incompatibilities mentioned above for
our new redacted API.  And if you start that modification process
immediately, you will likely get better help with it since we have
just gone through that process for our Tcl/Tk examples (which should
be your first guide concerning how to use the new redacted API for
Tcl/Tk).

2.10 Substantial rewrite of the DocBook documentation

The fundamental principle used for this rewrite is to rely heavily on
cross-references.  Most of these are internal to the DocBook
documentation, but some (such as references to our examples on our
website and platform-dependent build quirks documented in our wiki)
are external.  The result is much less repeating of material (which
substantially reduces maintenance issues) and use of the best source
of documentation in all cases.  For example, the simple and advanced
use of PLplot chapters previously contained large chunks of C code from the C
examples.  All that C code is gone and instead references to our
standard examples on our website are used instead.  The result is much
less C specific since the website user has ready access to the example
code in each of our supported languages.  Furthermore, the website
gives the expected plot results for the example.  Of course, the
downside of this new documentation approach is each section of the
DocBook documentation is much less self-contained.  But the advantages
of the new "cross-reference" documentation approach far outweigh that.

Here are the parts of the DocBook documentation that have been rewritten
with the new approach.

* The introduction has been rewritten to be consistent with
  modern PLplot.  For example, modern CMake-based build generic build
  instructions are given, and a reference to our wiki is given for
  those users who encounter platform-dependent build quirks.

* The simple and advanced use of PLplot chapters have been rewritten
  as referred to above.

* The chapters referring to drivers which implement file devices and
  interactive devices have been rewritten to be consistent with modern
  PLplot.  For example, the list of devices that was egregiously
  outdated has now been updated.

* The C chapter has been rewritten to be consistent with
  modern PLplot.  In particular, the new self-describing names for
  PLplot C argument types (see 2.19 and 2.20) are documented.

* The Fortran chapter has been rewritten to be consistent
  with modern PLplot, i.e., the new Fortran binding that has just been
  implemented.

* The tclmatrix subchapter of the Tcl chapter has been rewritten
  to be consistent with the recent tclmatrix changes (2.8).

* The previous chapter entitled "Notes for each Operating System that We Support"
  has now been dropped since this material is already covered
  in the introduction with reference to the wiki as appropriate
  for platform details (see above discussion of the introduction).

Here are some additional significant updates to our documentation that
(unlike the changes above) did not constitute a complete rewrite.

* The Ada chapter has been updated to be consistent with the
  recent Ada changes (2.7).

* The Tcl chapter as a whole has been updated to be
  consistent with the recent redacted API change (2.9).

* A number of documentation improvements have been made to the common
  API chapter.  For example, the new self-describing names for PLplot
  C argument types (see 2.19 and 2.20) are now used to document all
  arguments which makes it much simpler to document those arguments.
  Also, reference to those types now link to the appropriate part
  of the C chapter which describes the PLplot types.

* An important short paragraph of text was inserted in the simple
  usage, advanced usage, and common API chapters to clarify how the
  API for all our supported languages corresponds with the
  self-describing names for PLplot C argument types (see 2.19 and
  2.20).

2.11 Default page sizes

We now provide two default page sizes for our device drivers. One for
drivers which have real world pages (e.g. the postscript driver) which
is specified in mm and one for drivers which use pixel pages (e.g. the
Cairo or the interactive drivers). The mm page size is A4 as this is
the most commonly used metric paper size used. The pixel size is
approximately A5 when scaled using the default 90 dpi. This was chosen
as it has the same aspect ratio as the mm size, but fits comfortably
on most computer screens.  So far only the gd, cgm, and wxwidgets
device drivers use these defaults, but our eventual goal is that all
our device drivers will use these defaults for consistency between them.

2.12 Updated D language support

CMake-3.4.0 introduced a change in internal language support infrastructure.
Our D language support was changed so that it accommodated this change and
also still worked for older CMake versions.

2.13 Modernized build-system support for Qt4 and Qt5

The Qt4 support modernization consisted of moving from the old and rigid
QT4_WRAP_CPP method of applying moc to just qt.h and propagating those
results everywhere they were needed to the more flexible AUTOMOC approach
which allows us to choose (important!) what Qt header(s) to moc for each
library.  This same approach is now also used for the Qt5 case.

The Qt4 CMake support is a responsibility of CMake developers, but the
Qt5 CMake support is the responsibility of Qt5 developers and is
entirely different (except for AUTOMOC) from Qt4 support.  That
Qt5 CMake support is documented at <http://doc.qt.io/qt-5/cmake-manual.html>
and this PLplot release has moved from the deprecated qt5_use_modules method
to the latest method involving using aliased libraries called
Qt5::Svg, Qt5::Gui, and Qt5::PrintSupport in the appropriate
target_link_libraries command.

Our tests now show that as a result of these changes our build-system
support for Qt5 is now just as mature as for the Qt4 case.  Our tests
also show the Qt5 library has matured (as of Qt5 version 5.3.2 from
Debian Jessie) somewhat in that the character alignment issues that
plagued us before are now gone.  So there are no more ad hoc adjustments
of the character height to accommodate for the Qt5 character alignment bugs
so our qt device driver code now uses exactly the same code for Qt4
and Qt5.

Despite this encouraging recent alignment improvement, Qt5 is still
not nearly as mature as Qt4 according to our other tests.  For our qt
device driver linked to Qt5 and according to the
-DVALGRIND_ALL_TESTS=ON cmake option, results for the test_pdfqt
target show severe memory management issues (invalid reads, etc.) for
all standard examples other than 0, 1, 3, 5, 10, 12, 13, 24, and 31.
(Presumably these inter-example differences in Qt5 memory management
issues are due to the different ways these examples use the Qt
libraries and thus find the memory management issues in those
libraries or not.)  It is encouraging that there are no memory
management issues for some of our examples for qt linked to Qt5, but
when our qt device driver is linked to Qt4 instead (at least for the
Debian Jessie version 4.8.6) there are no memory management issues for
_any_ of the examples for the pdfqt device.  We have not had time to
make similar comprehensive valgrind tests for all our examples for other
qt devices, but spot checks with valgrind indicate a consistent pattern
of severe memory management issues with Qt5 that just don't occur
for Qt4.  Another memory-management issue that is likely related to Qt5
is we get a segfault when exiting from the pyqt5_example (which is
necessarily linked to Qt5) while we have no such issues with
pyqt4_example (that is necessarily linked to Qt4). A final issue
with Qt5 that we have noticed is our comprehensive test
of our qt device driver linked to Qt5 was twice (!) as slow as the
same test for our qt device driver linked to Qt4.

Because of these present Qt5 memory management and inefficiency
concerns, our build system currently prefers to use Qt4 if it can find
it, but automatically falls back to Qt5 otherwise.  If for some reason
a user wants to avoid Qt4, then only Qt5 will be searched for and used
if they specify -DPLPLOT_USE_QT5=ON.  (Note this important change in
the semantics of -DPLPLOT_USE_QT5=ON which in 5.11.1 was the only
(experimental) way users could link qt to Qt5.)

2.14 Implemented support for pyqt5

Because our build-system support for Qt5 has matured (although the Qt5
library has not matured yet in memory management and efficiency, see
comments above), we have also implemented support for pyqt5 when Qt5
is being used to link qt.  Our tests using the test_pyqt5_example show
this support for pyqt5 has matured (other than the segfault issue at
exit from this GUI which we attribute to memory management issues in
Qt5).  (Note our support for pyqt4 when Qt4 is being used to
link qt continues without known build or run-time issues.)

2.15 Addressed -DPL_DOUBLE=OFF issues

Our comprehensive tests of the single-precision version of the PLplot
libraries (built with -DPL_DOUBLE=OFF) demonstrated a substantial
number of issues that had accumulated since we last tested this
option.  Those issues have now all been solved so that PLplot users
can be reasonably confident again about using the -DPL_DOUBLE=OFF
option if they so desire.  However, it should be emphasized that the
-DPL_DOUBLE=ON case (which is the case users get by default) is the
case we test the most so that will almost always be the more reliable
option to use.

2.16 Replaced "Lena" with "Chloe"

The image we use to demonstrate and test our plimage capability has
been changed from "Lena" to "Chloe" because the licensing for the
former image (although used often as a test image by other software
projects) turns out to be not definite while the licensing for the
latter image is definite and gives us the freedom to modify and
redistribute that image.  Also, I like that image of Chloe who is a
cute "Westie" (West Highland White Terrier) that reminds me of one of
my all-time favourite TV shows "Hamish Macbeth".  :-)

2.17 Removed trailing blanks on most text files in our source tree

This was a massive and intrusive change to our source tree when we
first did this because years of neglect concerning this issue had left
trailing whitespace virtually everywhere which git constantly
complained about.  From now on, our developers are encouraged to run
scripts/remove_trailing_blanks.sh to deal with this issue before each
of their commits.  That script excludes all binary files following the
rules in .gitattributes concerning what constitutes a text file.  In
addition some text files are excluded from trailing-blank removal
because they involve text that should be immutable (e.g., licensing
text, test text) that has trailing blanks.  This script uses sed to do
the job so this script can only be run on systems that have sed
installed.

2.18 Make our wxwidgets find module consistent with the official version for CMake-3.7.1

That latest released version of the find module for wxwidgets is
actively maintained by the CMake developers so the latest version
available (from CMake-3.7.1) is likely to be the best version of this
find module. We therefore adopt that version (with one necessary line
change so we can use it for PLplot) for all our users regardless of
the CMake version they are using.

2.19 Introduction of two new generic pointer types to help protect against a planned future C API breakage

As a step toward our goal of achieving const correctness for PLplot we
have defined two new generic pointer types called PL_GENERIC_POINTER
and PL_NC_GENERIC_POINTER which are typedef'd and used in
include/plplot.h as the types for the generic pointers in our C API
with the former reserved for identifying generic pointer arguments
where the called routine guarantees to leave the object being pointed
to completely unchanged while the latter is used for those rare cases
when we cannot make that guarantee.  (NC stands for "non const".)  The
generic pointer type PLPointer is typedef'd in include/plplot.h for
those of our users who are still using it, but it is deprecated and
therefore unused in include/plplot.h.

The typedefs for these 3 generic pointers are currently the following:

typedef void * PL_NC_GENERIC_POINTER;
typedef void * PL_GENERIC_POINTER;
// Deprecated and only provided for backwards compatibility.
typedef PL_NC_GENERIC_POINTER  PLPointer;

So all the above is backwards compatible with prior releases which
just typedef'd and used

typedef void * PLPointer;

However, for our next release we plan to change PL_GENERIC_POINTER as follows:

typedef const void * PL_GENERIC_POINTER;

which will help improve our const correctness but which will also
introduce a substantial backwards incompatibility into our C API.

To protect yourself against this planned future backwards incompatibility we recommend
you do the following:

Change the types of all your void * or PLPointer arguments for our C
API to PL_GENERIC_POINTER or PL_NC_GENERIC_POINTER as documented for
each of our functions in include/plplot.h and also at
<http://plplot.sourceforge.net/docbook-manual/plplot-html-5.12.0/API.html>.
This change means when we update the PL_GENERIC_POINTER typedef as above,
a recompilation of your code will be all that is required to deal with this issue.

We also recommend you drop use of the deprecated PLPointer type since
we plan to stop providing a typedef for that type sometime in the future.

2.20 Introduction of additional self-describing names for the types of arguments used in our C API.

These new self-describing type name are defined (in include/plplot.h) as follows:

// typedefs that are typically used for passing scalar, vector, and
// matrix arguments to functions.  The NC attribute concerns pointers
// to mutable objects, where the objects are used for passing values
// that are either output only or both input and output.  Pointers whose
// name does not contain the NC attribute point to immutable objects
// which are strictly input and guaranteed to be unchanged by the function.
//

// Pointers to mutable scalars:
typedef PLINT *               PLINT_NC_SCALAR;
typedef PLBOOL *              PLBOOL_NC_SCALAR;
typedef PLUNICODE *           PLUNICODE_NC_SCALAR;
typedef char *                PLCHAR_NC_SCALAR;
typedef PLFLT *               PLFLT_NC_SCALAR;

// Pointers to mutable vectors:
typedef char *                PLCHAR_NC_VECTOR;
typedef PLFLT *               PLFLT_NC_VECTOR;

// Pointers to immutable vectors:
typedef const PLINT *         PLINT_VECTOR;
typedef const PLBOOL *        PLBOOL_VECTOR;
typedef const char *          PLCHAR_VECTOR;
typedef const PLFLT *         PLFLT_VECTOR;

// Pointers to mutable 2-dimensional matrices:
typedef char **               PLCHAR_NC_MATRIX;
typedef PLFLT **              PLFLT_NC_MATRIX;

// Pointers to immutable 2-dimensional matrices,
// (i.e., pointers to const pointers to const values):
typedef const char * const *  PLCHAR_MATRIX;
typedef const PLFLT * const * PLFLT_MATRIX;

// Callback-related typedefs
typedef void ( *PLMAPFORM_callback )( PLINT n, PLFLT_NC_VECTOR x, PLFLT_NC_VECTOR y );
typedef void ( *PLTRANSFORM_callback )( PLFLT x, PLFLT y, PLFLT_NC_SCALAR xp, PLFLT_NC_SCALAR yp, PL_GENEIC_POINTER data );
typedef void ( *PLLABEL_FUNC_callback )( PLINT axis, PLFLT value, PLCHAR_NC_VECTOR label, PLINT length, P_GENERIC_POINTER data );
typedef PLFLT ( *PLF2EVAL_callback )( PLINT ix, PLINT iy, PL_GENERIC_POINTER data );
typedef void ( *PLFILL_callback )( PLINT n, PLFLT_VECTOR x, PLFLT_VECTOR y );
typedef PLINT ( *PLDEFINED_callback )( PLFLT x, PLFLT y );

For this release we have only partially propagated the use of these
self-describing names for PLplot C argument types to our core C
library, device drivers, our bindings implemented in C, our C++
binding, and the C and C++ examples, but we plan to address that
propagation issue in the next release.  Meanwhile these type names are
extremely useful for helping to document our bindings and common API,
see 2.10.

2.21 Implement submission of dashboards to the <my.cdash.org> cdash server

CMake users who want to help with testing PLplot on Unix-like Windows
platforms such as Cygwin or MinGW-w64/MSYS2 or on the usual Unix
platforms such as Linux or Mac OS X can now submit dashboards (defined
as a collection of data associated with a given ctest run in a
standard form) to the <my.cdash.org> cdash server where it is publicly
displayed using a nice format at
<http://my.cdash.org/index.php?project=PLplot_git>.

Such dashboards should be submitted using, e.g.,

cmake -DBUILD_TEST=ON -DPLPLOT_BUILDNAME_SUFFIX:STRING="-shared library + dynamic devices" ....
#N.B. the all target must always be built before ctest is run
make -j4 all
ctest -j4 -D Experimental

The -DPLPLOT_BUILDNAME_SUFFIX:STRING option is not necessary, but the
string specified with that option is appended to the "Build Name"
field displayed by the cdash server so it helps PLplot users to
identify the broad configuration of the type of build that was used to
submit a dashboard.

If the user specifies the

--do_submit_dashboard yes

option for the bash script,

scripts/comprehensive_test.sh,

then the above tests to submit a dashboard will occur for each ctest
command (typically for (1) shared library + dynamic devices, (2)
shared library + nondynamic devices, and (3) static library +
nondynamic devices) that is run by that script and with
-DPLPLOT_BUILDNAME_SUFFIX:STRING automatically set appropriately for
each dashboard submission generated by the script.

2.22 Substantial update and rename of the Python examples

All python modules and scripts in example/python were converted to the
namespace form, e.g.,

from plplot import *

was replaced by

import plplot as <some namespace>

where "<some namespace>" is typically "w" for historical reasons.

This change removed the fundamental difference between the set of
well-maintained xw??.py standard examples and the original
badly-maintained and incomplete set of standard examples that were
called x??.py.  So we removed all those badly maintained versions and
renamed xw??.py as the corresponding x??.py.

This rename, some work on examples/python/pytkdemo, and a large amount
of generic work on bindings/python/Plframe.py to add the necessary
PLplot API to run the revitalized x??.py examples means
examples/python/pytkdemo (previously crippled by using the old buggy
version of the x??.py examples) is working reliably for the first time
ever.  In fact it is so reliable we routinely add the new
test_pytkdemo target to the dependencies of the generic
test_interactive target which is reserved for just running the
interactive test targets that are reliable.

2.23 Linux efficiency improvements for the wxwidgets device

The speed of the Linux wxwidgets device (N.B. note the
time required by wxPLViewer is not counted in any of these comparisons)
was not in a good state for PLplot-5.11.1; slowdowns of a factor of two
compared to the qtwidget and xcairo devices were typical while in some cases
the slowdown ranged up to two orders of magnitude!  That latter problem
turned out to be due to our use of the blocking /dev/random device
to choose the seed for the random names chosen for the shared memory
areas used for IPC between -dev wxwidgets and wxPLViewer, and the simple fix
(discovered quite recently) was to preferentially use the non-blocking
/dev/urandom instead!  In addition many other changes have been
made to both -dev wxwidgets and wxPLViewer to improve their joint
efficiency since the release of PLplot-5.11.1.  A recent detailed experiment
showing real times required to complete examples showed
the following count results for which of the three devices was the fastest
for each of the 27 standard examples that were run for this test:

qtwidget  10
xcairo    08
wxwidgets 09

In none of these 27 standard examples is -dev wxwidgets slower than
the best of the other two by a factor of two or more.  And -dev
wxwidgets is actually the best of the three devices for a 3rd of these
examples.  So -dev wxwidgets is clearly comparable in speed to the
other two for most of our examples.  However, the above 27 standard
examples did not include examples 8, 25, and 33 which all notoriously
have extremely large numbers of graphical elements.  I just ran
comparisons for examples 8 and 25 (because 33 takes too long even when
it is efficient), and in those two cases the wxwidgets slowdown factor
compared to the best of the other two devices is respectively 16 and
8!  So clearly there is still some large bottleneck in efficiency for the
combination of -dev wxwidgets and wxPLViewer that shows up
particularly strongly when there are large numbers of graphical
elements.  We hope to deal with that issue for our next release, but
clearly for this release Linux -dev wxwidgets users are going to be
much better off in the efficiency department than they were for
PLplot-5.11.1.
________________________________________________________________

3. PLplot testing

Comprehensive tests of this release are documented in
<http://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Testing%20Reports>
and
<https://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Fortran%20Testing%20Reports>.
In addition, developers and users who have used the git master tip
version for all their plotting needs during this release cycle have
provided additional important testing of this release of PLplot.
________________________________________________________________
PLplot Release 5.11.1

This is a release of the PLplot plotting package. It represents the
ongoing best efforts of the PLplot community to improve this package,
and it is the only version of PLplot that we attempt to support.
Releases in the 5.x.y series should be available several times per
year.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via our mailing lists (preferred for initial discussion of
issues) at <http://sourceforge.net/p/plplot/mailman/>. If it turns out
no quick resolution is possible via mailing-list discussion, then the
issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

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

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1 Minimum CMake version bump

2. Improvements relative to the previous release

2.1 Bug fixing!

2.2 Improve traditional build linking for nondynamic device drivers case

2.3 Comply with a NEW value for the CMake CMP0022 and CMP0023 policies

2.4 Comply with a NEW value for the CMake CMP0026 policy

2.5 Plot labels as date / time are now available for 3D plots

2.6 Comprehensive testing script improvements

2.7 Build system and file cleanup concerning retired devices

2.8 Many improvements and bug fixes for the new wxwidgets device

2.9 Substantially improved results for comprehensive testing of PLplot
on the Cygwin platform

2.10 Initial success of comprehensive testing of PLplot on the MSYS2
platform

3. PLplot comprehensive testing reports

________________________________________________________________

1. OFFICIAL NOTICES FOR USERS

1.1 Minimum CMake version bump

The minimum version of CMake has been bumped to 3.2.3 on all platforms
other than Cygwin and Linux where it has been bumped to 3.0.2 instead.

________________________________________________________________

2. Improvements relative to the previous release

2.1 Bug fixing!

Please consult the ChangeLog.release file for details concerning the
numerous bug fixes made for this release.

2.2 Improve traditional build linking for nondynamic device drivers case

For -DENABLE_DYNDRIVERS=OFF, the C and C++ code for the device drivers
becomes part of libplplot (as opposed to the -DENABLE_DYNDRIVERS=ON
case where the device drivers are independently built as dll's which
are dynamically loaded by libplplot).  Thus, -DENABLE_DYNDRIVERS=OFF
makes libplplot a mixed C and C++ library that requires linking using
all libraries that are required by the C++ compiler.  Which can get
complicated for the C, Fortran, D, Ada, Java, and OCaml examples.
CMake takes care of such linking issues automatically, and for the
traditional build of the installed examples we have replaced the
previous fragile and g++-specific scheme for determining the C++
compiler libraries with CMake's knowledge of those same libraries
for each C++ compiler supported by CMake.

2.3 Comply with a NEW value for the CMake CMP0022 and CMP0023 policies

All use of the deprecated LINK_INTERFACE_LIBRARIES has been replaced
by using either the PRIVATE (NON_TRANSITIVE=ON,
INTERFACE_LINK_LIBRARIES set to empty) or PUBLIC (NON_TRANSITIVE=OFF,
INTERFACE_LINK_LIBRARIES set to listed libraries)
target_link_libraries keywords.  The PRIVATE or PUBLIC keywords were
also appropriately propagated to our configured pkg-config files and
thus to our traditional build system for the installed examples.

2.4 Comply with a NEW value for the CMake CMP0026 policy

This NEW CMake policy means that location properties must no longer be
used to determine the filenames of executables, dll's, and libraries
for our CMake-based build system.  Instead, the same information must
be determined from CMake generator expressions.  Complying with this
policy makes our build system much less sensitive to potential
location bugs at generate time but has required intrusive but
well-tested changes to our CMake-based build system.

2.5 Plot labels as date / time are now available for 3D plots

The plbox3 function now supports the d suboption for xopt and yopt and
the e suboption (d is already used for something different for zopt)
for zopt to generate X, Y, or Z axis labels using date/time
formatting.  As in the 2D case (see standard example 29) call
the pltimefmt routine beforehand to control the date/time format that
is used.

2.6 Comprehensive testing script improvements

The principal improvement is to collect the most important information
concerning a given comprehensive test into a report tarball that helps
others to diagnose any problems turned up by the test or in the case of
complete test success provide enough information for a summary of the
test (see, for example, the tables below summarizing comprehensive
test success on various platforms).

2.7 Build system and file cleanup concerning retired devices

We have long since retired the gnome, gcw, gnome2, dg300, hpgl,
impress, linuxvga, ljii, ljiip, pbm, and tek device drivers.  This
(intrusive!) change removed all references to these from files (or
removes entire files if the file was only relevant to one of the
retired device drivers).  The only exception to this cleanup is our
DocBook documentation of devices which needs a complete rewrite
instead.

2.8 Many improvements and bug fixes for the new wxwidgets device

The new wxwidgets device is still being actively developed.  See the
ChangeLog.release file for the details of all such changes for this
release cycle.  The current status is this new version of the
wxwidgets device has no serious build or run-time issues.  However,
there are still known rendering issues with this device which can be
found at <http://sourceforge.net/p/plplot/bugs/search/?q=wxwidget> and
which we are in the process of fixing.  If any of these issues are an
important concern to our wxwidgets users for this release we suggest
they try the -DOLD_WXWIDGETS=ON option to access the old version of
the wxwidgets device.  We do sufficient maintenance of that old
wxwidgets device so that it passes comprehensive testing (see the
report below).  However, there are no plans to do further changes to
the old wxwidgets device driver other than minimal maintenance, and at
some point that old version of the wxwidgets device will be removed.

2.9 Substantially improved results for comprehensive testing of PLplot
on the Cygwin platform

See the detailed reports for 64-bit Cygwin below.  A substantial
amount of bug fixing for our build and test system during this release
cycle contributed to this 64-bit Cygwin success.  Because of this
success and because this platform provides almost every PLplot
soft prerequisite we highly recommend 64-bit Cygwin as a PLplot
platform with the caveat that the results depend on the Cygwin dll,
i.e., they are not pure Windows results.

We similarly expect that 32-bit Cygwin will be a good platform for
PLplot, but we have not comprehensively tested this platform yet.

2.10 Initial success of comprehensive testing of PLplot on the MSYS2
platform

Greg Jung reports that comprehensive testing of PLplot on
mingw-w64-x86_64/MSYS2 succeeds (see the detailed report below). This
derivative of the modern Cygwin platform allows use of posix MSYS2
tools to build pure (i.e., no dependence on the MSYS2 dll) Windows
applications and libraries using the mingw-w64-x86_64 toolchain and
the associated mingw64 software repository.  Although this repository
does not contain all the free software that is available for Cygwin,
it nevertheless does cover most of the PLplot prerequisites.  So we
can now highly recommend this platform for pure Windows builds of
PLplot using the mingw-w64-x86_64 toolchain.  Thanks, Greg!

We similarly expect that the mingw-w64-i686/MSYS2 platform
will also work well for pure Windows builds of PLplot using the
mingw-w64-i686 toolchain although we haven't comprehensively tested
this platform yet.

________________________________________________________________

3. PLplot comprehensive testing reports

These reports are in reverse chronological order and formatted in the
SourceForge markdown syntax for a table.

|||
---|---|---|---
Tester|Alan W. Irwin
Notes|(a), (b), (c), (d), (e), (k), (A)
Date|2015-08-07
PLplot commit|6747256
CMake version|3.0.2
Generator|\"Unix Makefiles\"
Platform|Debian wheezy = oldstable with system libraries
Pango/Cairo version|1.30.0/1.12.2
Qt version|4.8.2
WxWidgets version|2.8.12.1
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|No|Yes|No
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|No|Yes
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|No|Yes

|||
---|---|---|---
Tester|Alan W. Irwin
Notes|(a), (b), (c), (d), (e), (A)
Date|2015-07-30
PLplot commit|d64d9c6
CMake version|3.0.2
Generator|\"Unix Makefiles\"
Platform|Debian wheezy = oldstable with system libraries
Pango/Cairo version|1.30.0/1.12.2
Qt version|4.8.2
WxWidgets version|2.8.12.1
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|Yes|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes

|||
---|---|---|---
Tester|Greg Jung
Notes|(a), (e), (i), (j), (A), (B'), (E''''), (F'''), (G'), (H'''), (N)
Date|2015-07-30
PLplot commit|be85695
CMake version|3.2.3
Generator|\"MSYS Makefiles\"
Platform|mingw-w64-x86_64/MSYS2
Pango/Cairo version|1.37.1/1.14.2
Qt version|4.8.7
WxWidgets version|3.0.2-5
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No

|||
---|---|---|---
Tester|Greg Jung
Notes|(a), (e), (i), (A), (B'), (E''''), (F'''), (G'), (H''), (N)
Date|2015-07-30
PLplot commit|be85695
CMake version|3.2.3
Generator|\"Unix Makefiles\"
Platform|mingw-w64-x86_64/MSYS2
Pango/Cairo version|1.37.1/1.14.2
Qt version|4.8.7
WxWidgets version|Not applicable
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No

|||
---|---|---|---
Tester|Greg Jung
Notes|(a), (b), (e), (A), (B'), (D'), (E'''), (G'), (H'), (M)
Date|2015-07-11
PLplot commit|dd9f79e
CMake version|3.1.2
Generator|\"Unix Makefiles\"
Platform|Cygwin (64-bit)
Pango/Cairo version|1.36.8/1.12.18
Qt version|4.8.7
WxWidgets version|3.0.2
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No

|||
---|---|---|---
Tester|Arjen Markus
Notes|(a), (h), (A), (B'), (C'), (D), (D'), (E), (F'), (G), (H), (I), (J)
Date|2015-07-10
PLplot commit|32be1b9
CMake version|3.2.2
Generator|\"MSYS Makefiles\"
Platform|MinGW/MSYS
Pango/Cairo version|Not Applicable
Qt version|Not Applicable
WxWidgets version|Not Applicable
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
No||

|||
---|---|---|---
Tester|Arjen Markus
Notes|(a), (b), (e), (A), (B'), (D'), (E''), (G'), (H')
Date|2015-07-07
PLplot commit|ae0e9da
CMake version|3.1.2
Generator|\"Unix Makefiles\"
Platform|Cygwin (64-bit)
Pango/Cairo version|1.36.8/1.12.18
Qt version|4.8.7
WxWidgets version|2.8.12.1
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No

|||
---|---|---|---
Tester|Hazen Babcock
Notes|(a), (b), (e), (g), (A), (L)
Date|2015-04-13
PLplot commit|09dee003
CMake version|2.8.12.2
Generator|\"Unix Makefiles\"
Platform|Lubuntu 14.04.2 LTS with system libraries
Pango/Cairo version|1.36.3/1.13.1
Qt version|Not Applicable
WxWidgets version|Not Applicable
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|No|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|No

|||
---|---|---|---
Tester|Alan W. Irwin
Notes|(a), (b), (c), (d), (e), (f), (A), (K)
Date|2015-04-11
PLplot commit|99fe5f0
CMake version|3.0.2
Generator|\"MSYS Makefiles\"
Platform|MinGW-4.7.2/MSYS/Wine-1.6.1 with epa_built libraries
Pango/Cairo version|Not Applicable
Qt version|Not Applicable
WxWidgets version|Not Applicable
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|Yes|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes

|||
---|---|---|---
Tester|Alan W. Irwin
Notes|(a), (b), (c), (d), (e), (A)
Date|2015-03-29
PLplot commit|5f6e28f
CMake version|3.0.2
Generator|\"Unix Makefiles\"
Platform|Debian stable with epa_built libraries
Pango/Cairo version|1.35/1.12.14
Qt version|5.3.2
WxWidgets version|3.0.2
Shared libraries?|Dynamic drivers?
Yes|Yes
Yes|No
No|No
CMake-based build tree?|test_noninteractive?|test_interactive?|ctest?
Yes|Yes|Yes|Yes
CMake-based installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes
Traditional Installed examples?|test_noninteractive?|test_interactive
Yes|Yes|Yes

Testing notes where lower case notes concern configuration and build options while upper case notes concern limitations on testing due to platform constraints ("not available"), arbitrary constraints imposed by the tester to simplify testing ("not installed" or "ignored"), or working around PLplot issues for the platform ("disabled").
* (a) Testing done on 64-bit (x86-64, also known as x64, x86_64, and AMD64, ) hardware.
* (b) Used parallel make option (-j4) for all builds, installs, and test targets.
* (c) Suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.
* (d) Suitable compilers and bindings-related development packages have been installed on the system so there are no default bindings that are missing from this test.
* (e) Java, Python, Octave, Lua, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for the static PLplot libraries case.
* (f) For this MinGW/MSYS/Wine platform test the build_plplot_lite epa_build target was used which simplifies testing by excluding the qt, cairo, and wxwidgets devices from tests.  This was a \"lite\" test in other respects as well; i.e., the D, Java, OCaml, and Octave languages were not available on this platform.
* (g) This Lubuntu platform did not have Ada, Fortran, D, Java, or OCaml compilers installed and did not have development versions of Octave, Tcl/Tk, WxWidgets, Lua, shapelib, qhull, libLASi, or libharu installed.  Therefore corresponding components of PLplot were disabled and not tested.
* (h) This MinGW/MSYS platform with no epa_built libraries has very few PLplot soft prerequisites available so tests on this platform necessarily only apply to a small number of the PLplot components (i.e., just the mem, ntk, null, ps, svg, wingcc, and xfig device drivers and just the c++, f95, and tcl bindings).
* (i) CMake was hand-built to make it depend on Qt4 rather than Qt5 to help avoid Qt4/Qt5 MSYS2 package conflicts.
* (j) g++ (but not gcc) -DUNICODE option required to make wxwidgets device driver buildable.
* (k) wxwidgets-only interactive tests using -DOLD_WXWIDGETS=ON to comprehensively test the old wxwidgets device driver.
* (A) No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional \"upper-case\" notes (if any).
* (B) Interactive tests disabled to avoid run-time errors.
* (B') Interactive tests ignored.
* (C) Traditional build of installed tests disabled to avoid build errors.
* (C') pkg-config not available therefore traditional build of installed examples not tested.
* (C'') pkg-config was installed, but traditional build had to be disabled because of runtime errors.
* (D) libqhull not available.
* (D') shapelib not available.
* (E) Swig not available therefore Java, Python, Octave, and Lua bindings not tested.
* (E') Swig was installed but Java, Octave, and Lua not installed so those bindings not tested.
* (E'') Java not available and Octave ignored.
* (E''') Java not available, Octave ignored, and Numpy not installed so java, octave, and python bindings not tested.
* (E'''') Java and Octave not available so java and octave bindings not tested.
* (F) Tk/Itcl/Itk not installed therefore not tested.
* (F') X11 not available.  Therefore -dev tk and -dev tkwin not tested and Itcl/Itk not installed therefore not tested.
* (F'') X11 server was running, but was not picked up - DISPLAY variable?  Therefore, dev tk and -dev tkwin not tested and Itcl/Itk not installed therefore not tested.
* (F''') X11, Itcl, and Itk not available.  Therefore -dev xcairo, -dev tk, and -dev tkwin not tested and Itcl/Itk not tested.
* (G) Ada, D, and OCaml compilers not availables so Ada, D, and OCaml bindings not tested.
* (G') Ada disabled, D not available, and ocamlidl not available so Ada, D, and OCaml bindings not tested.
* (H) libharu, libLASi, wxwidgets not available so pdf, psttf, and wxwidgets device drivers not tested.
* (H') libharu not available so pdf device driver not tested.
* (H'') libharu and libLASi not available and wxwidgets ignored so pdf, psttf, and wxwidgets device drivers not tested.
* (H''') libharu and libLASi not available so pdf and psttf device drivers not tested.
* (I) libpango/libcairo not available therefore cairo devices not tested.
* (J) libQt not available therefore qt devices not tested.
* (K) Encountered intermittent (once only, repeat test did not have it) make.exe error: \"INTERNAL: Exiting with 1 jobserver tokens available; should be 4!\"  I attribute this error to the problematic make.exe parallel-build option on MSYS. (See \u003Chttps://sourceforge.net/p/mingw/bugs/1950/> for other unsolved classical MSYS parallel build flakiness.)  To work around this bug for the MinGW/MSYS platform should use the epa_build cmake option, -DNUMBER_PARALLEL_JOBS:STRING=1.  However, this workaround should not be necessary for the Cygwin or MinGW-w64/MSYS2 platforms.
* (L) For this Lubuntu system with Qt4.8.6 system libraries, severe memory management issues (including segfaults) occurred for all attempts to use qt devices.  Therefore, to complete this comprehensive test had to disable everything Qt related by using the script option
`--cmake_added_options \"DEFAULT_NO_QT_DEVICES=ON -DENABLE_qt=OFF\"`
* (M) gtk+-x11-2.0 development package not installed, therefore extXdrawable_demo test not run.
* (N) sip ignored so pyqt4 not tested.

________________________________________________________________
PLplot Release 5.11.0

This is a release of the PLplot plotting package. It represents the
ongoing best efforts of the PLplot community to improve this package,
and it is the only version of PLplot that we attempt to support.
Releases in the 5.x.0 series should be available several times per
year.

Comprehensive tests of this release are documented in
<http://sourceforge.net/p/plplot/wiki/Testing_PLplot#Testing%20Reports>.
In addition, developers and users who have used the git master tip
version during this release cycle have provided additional important
testing of this release of PLplot.

If you encounter a problem with this release that is not already
documented on our bug tracker, then please send bug reports to PLplot
developers via the mailing lists at
<http://sourceforge.net/p/plplot/mailman/> (preferred for initial
discussion of issues) and, if no quick resolution is possible, then
the issue should be placed on our bug tracker at
<http://sourceforge.net/p/plplot/bugs/>.

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

CONTENTS

1. OFFICIAL NOTICES FOR USERS

1.1 Backwards-incompatible change to the suffix for our library names

1.2 Backwards-incompatible API change for our f95 bindings

1.3 Backwards-incompatible change to our C++ API

1.4 Backwards-incompatible change to our CMake packaging


2. Improvements relative to the previous release

2.1 Update the parts of the build system that find Tcl-related software

2.2 Update epa_build configurations

2.3 Update the PLplot build system so that the Tcl/Tk/Itcl/Itk/Iwidgets

2.4 Make many minor build-system fixes so that comprehensive tests
finally work almost completely on MinGW/MSYS

2.5 Update api.xml to be consistent with our public API defined by plplot.h

2.6 Many plbuf improvements

2.7 plmeta/plrender now under active development

2.8 Add version macros

2.9 Implement experimental Qt5 support

2.10 Implement interactive capability for the wingcc device

2.11 Improve CMake packaging of PLplot

2.12 Add smoke binding for the qtwidget and extqt drivers

2.13 Add new mapping functionality for shapefiles

2.14 Removed a substantial number of "space in pathname" issues

2.15 Move from svn to git version control

2.16 Rewrite of wxwidgets
________________________________________________________________

1. OFFICIAL NOTICES FOR USERS


1.1 Backwards-incompatible change to the suffix for our library names

We have completely removed the CMake variable LIB_TAG from our build
system.  The effect of this change is the "d" suffix has been dropped
from our library names that had this suffix before (e.g, libplplotd
==> libplplot), dropped from the plplot pkg-config *.pc files used to
produce pkg-config results (e.g., plplotd.pc ==> plplot.pc), and
dropped from the directory name where the device driver dll's are
installed (i.e., $INSTALL_PREFIX/lib/plplot$PLPLOT_VERSION/driversd
==> $INSTALL_PREFIX/lib/plplot$PLPLOT_VERSION/drivers).  This "d"
suffix was a leftover from the days when we routinely built both
single-precision and double-precision forms of the PLplot library,
where the double-precision form was assigned the "d" suffix.  This
suffix was confusing (many users assumed it meant "debug" rather than
its actual meaning of "double precision"), did not normally
distinguish from the single-precision case since that case was rarely
built or tested, and was not uniformly applied to all our libraries
(because we produced single- and double-precision variants for only a
subset of our libraries).  Also, the single- or double-precision
variants of our library builds are only a small subset of the possible
build variations that can be produced with our build system so the
only safe and reliable way we can recommend for users to explore these
many different possible build variations is for them to use
independent build trees and install prefixes for each of the
variations rather than imposing a variety of easy-to-misinterpret
library, pkg-config, and driver install location suffixes.

1.2 Backwards-incompatible API change for our f95 bindings

We have renamed the following Fortran modules

plplot_types ==> plplot_graphics
plplot_flt ==> plplot_types

These name changes make sense since the new plplot_graphics module
defines just a graphics type and the new plplot_types module defines
fundamental real and integer types used by the PLplot API.

We highly recommend that users employ only the "use plplot" statement
in their fortran codes. Future name changes for the plplot module are
extremely unlikely (to say the least). Also, the plplot module "uses"
every other Fortran module we define and therefore makes all modules
for PLplot available to the user regardless of their name.  Thus, this
recommended "use" strategy should avoid any repercussions from the
above or future name changes for the modules that are "used" by the
plplot module.

1.3 Backwards-incompatible change to our C++ API

The plstream methods fill, tr0, tr1, tr2, and tr2p have been changed,
fixing a bug where the correct stream was not selected. This means
these functions are no longer static and can no longer be used as
callbacks in the shades method and its variants, the cont method, the
imagefr method, and the vect method. Instead a plcallback namespace
has been created which includes these methods as C-style
functions. Code which previously used the plstream methods above will
need to be recompiled and rebuilt using the plcallback versions (i.e.,
replace all plstream::fill callback use by plcallback::fill and
similarly for tr0, tr1, tr2, and tr2p).  Please see the documentation
for a full description.

1.4 Backwards-incompatible change to our CMake packaging

The "find_package(plplot)" command (as opposed to the previous
"include(export_plplot)") must now be used in CMake-based
build systems that need access to exported PLplot CMake packaging
information.  For additional information see 2.11 below.
________________________________________________________________

2. Improvements relative to the previous release


2.1 Update the parts of the build system that find Tcl-related software

The build system now checks extensively for the consistency of the
Tcl/Tk/Itcl/Itk/Iwidgets components that are found.

2.2 Update epa_build configurations

The epa_build subproject of PLplot design goal is to make it easy to
build PLplot dependencies on all platforms.  There has been a large
number of improvements in epa_build during this release cycle.  Those
include the following:

Get the wxwidgets (wxGTK) build to work properly on Linux including
its dependency on gtk+

Implement a libLASi build on Linux.

Update version 8.6 of Tcl/Tk, version 3 of Itcl/Itk, version 4
of Itcl/Itk, and versions 4.0 and 4.1 of Iwidgets so those
builds (which used to succeed only on Linux) now succeed for
both Linux and MinGW/MSYS.

2.3 Update the PLplot build system so that the Tcl/Tk/Itcl/Itk/Iwidgets
bindings and examples work on MinGW/MSYS

2.4 Make many minor build-system fixes so that comprehensive tests
finally work almost completely on MinGW/MSYS

2.5 Update api.xml to be consistent with our public API defined by plplot.h

This substantial improvement to our DocBook documentation for our
public API has been made possible by the "check" application written
by Hǎiliàng Wáng (see
https://github.com/hailiang/go-plplot/tree/master/c/check) which uses
gccxml to convert the API information in plplot.h into XML and
compares those results (names of functions in our public API, and for
each of those functions, number of arguments, names of arguments, and
types of arguments) with the corresponding information in api.xml.
The original report from the check_api_xml_consistency target (which
runs the check programme) showed ~150 inconsistencies between api.xml
and our public API including several functions in our public API that
were not documented at all in api.xml.  That number of inconsistencies
has now been reduced to zero which constitutes a substantial upgrade
in the quality of our API documentation.

2.6 Many plbuf improvements

We removed the disabled temporary file buffer code in plbuf.c to
improve code readability. (The temporary file buffer was superseded in
2006 when the much more efficient memory buffer approach was
implemented.) We improved plbuf efficiency in two additional ways; (1)
the rd_data_no_copy() internal function was implemented to avoid
needless memory allocation and copying in plbuf.c; and, (2), a
two-byte alignment is maintained in the plot buffer as most
architectures have better memory access performance with an even byte
alignment.  We implemented an experimental plot buffer import as a
PLESC operation to support wxwidget development.  We improved the plot
state save at the beginning of plot (BOP) in order to fix rendering
artifacts when plots were resized. We have improved the
text handling operations in the buffer; however, the cairo driver does
not correctly handle resizes, and it uses an alternate text
processing method that is currently disabled in the plot buffer.  We
corrected a bug in pattern fills, and the plot buffer now will only
contain the PLSTATE_FILL operation rather than both PLSTATE_FILL and
the individual LINE commands of the fill.  This was causing a line
doubling effect when plots were resized.

2.7 plmeta/plrender now under active development

The plmeta device driver is a useful idea which allows users to save
plots in a meta format which can then be read back in by plrender and
plotted with any PLplot device.

The plmeta/plrender code fell into disrepair many years ago, but now
it is being actively developed again.  We classify the new version of
this code as experimental so that we continue to disable it by default
(i.e., the user has to use the -DPLD_plmeta=ON cmake option in order
to try plmeta/plrender.)

So far we have implemented an experimental plot metafile input
function, plreadmetafile(), to provide an integrated read/write
capability into the core of PLplot.  In conjunction, we updated the
plmeta driver to support a transition to a new format.  A key change
is storing the raw string data used to represent text and plot symbols
into the metafile instead of the rendered characters.  We have
disabled the new features for this release in order to prevent
breaking compatibility with the existing format, but that should
change as development continues.

Implemented (using a new front end for plplot-test.sh) a
plmeta/plrender test to the test suite.  This is ignored when
-DPLD_plmeta=OFF (the default case).  When -DPLD_plmeta=ON the test
suite fails to work, but it is anticipated it will work once the new
plmeta/plrender features are enabled.

2.8 Add version macros

These macros are called PLPLOT_VERSION_MAJOR, PLPLOT_VERSION_MINOR,
and PLPLOT_VERSION_PATCH, and they should allow pure preprocessor
logic (as opposed to the running of a test programme that was required
previously) to distinguish between various PLplot versions from now
on.

2.9 Implement experimental Qt5 support

This can be chosen by the user by specifying the cmake option,
-DPLPLOT_USE_QT5=ON.  However, from our experience Qt5 is still (as of
version 5.3.2) too immature to be completely reliable consistent with
our historical experiences with Qt4.x.y where x < 6.  For example,
Qt5.x has long-standing character vertical alignment issues compared
to Qt4.8.x which we have semiempirically compensated in PLplot for the
PLPLOT_USE_QT5=ON case.  The resulting character alignment from this
workaround is OK (although not quite as good as for Qt4.8.x), but
nevertheless this workaround should not be required.  We have user
reports of bad rendering of PLplot qt device results for Qt-5.2.0, and
Qt5.3.0, and we have not even been able to epa_build Qt5.4.0 so
clearly those using -DPLPLOT_USE_QT5=ON have to be quite careful about what
Qt5 version they choose to try.  Finally, we have discovered (via
segfaults) that there are plend severe memory management issues
(invalid reads according to valgrind) for any version of Qt5 that is
epa_built on Debian stable including 5.3.2 regardless of what build
configuration was used including using a build configuration that is
virtually identical to that used for Debian packaging. These issues do
not appear for the Debian unstable binary package for Qt5.3.2.  One
hypothesis that explains these results is there is some incompatibility
between Qt5.3.2 and the Debian stable system libraries that epa_built
Qt5.3.2 depends on, but investigation continues.

2.10 Implement interactive capability for the wingcc device

Run

examples/c/x01c -dev wingcc -locate

to demonstrate what is possible.

2.11 Improve CMake packaging of PLplot

The fundamental improvement here is we use the standards documented in
<http://www.cmake.org/cmake/help/git-next/manual/cmake-packages.7.html>
to package PLplot as opposed to the non-standard way we packaged PLplot
before.  This change has allowed -DPLPLOT_USE_QT5=ON to work properly
when using exported PLplot CMake packaging information.

Also, we specifically have changed the install location of the
exported PLplot packages from

${DATA_DIR}/examples/cmake/modules
==>
${LIB_DIR}/cmake/plplot

which means (this is backwards incompatibility mentioned in 1.4 above)
CMake-based build systems (including the CMake-based build system for
the installed examples) must use "find_package(plplot)" as opposed to
"include(export_plplot)" to access the exported PLplot CMake packaging
information.

If $PREFIX (the install prefix set by the user) is not a standard
system location than one method to allow "find_package(plplot)" to
find the above location is to include $PREFIX/bin (which is probably
needed in any case) in the PATH.  Another possibility is to set the
CMAKE_PREFIX_PATH environment variable appropriately.  For a full list
of such possibilities, please consult the cmake documentation of
find_package.

2.12 Add smoke binding for the qtwidget and extqt drivers

From <https://techbase.kde.org/Development/Languages/Smoke> smoke can
be used as the basis for a number of language bindings, but this
particular smoke binding is only currently used by the external
cl-plplot software package
<https://common-lisp.net/project/cl-plplot/> which creates a Lisp
binding for PLplot.

2.13 Add new mapping functionality for shapefiles

This exciting new functionality gives PLplot users convenient access
to shapefile contour maps (e.g., of Exmoor National Park, U.K. as
demonstrated by example 19.05.)

2.14 Removed a substantial number of "space in pathname" issues

Since PLplot was originally developed on Unix where spaces in
pathnames are normally not used, there existed a lot of different
PLplot issues with blanks in pathnames that are typically used on
Windows.  A number of the most obvious of such issues have now been
fixed using a Windows test platform.  However, use of blanks is
pathnames is still probably not completely debugged, so if Windows
users run into any difficulties, the first thing they should try is to
use source-tree, build-tree, and install-tree prefixes without blanks.
And they should also try installing packages that PLplot depends on
with prefixes that do not include blanks.  If any of those changes
works (i.e., works around a blank-in-pathname bug for PLplot), please
inform us of that PLplot bug following the bug-report procedure stated
at the top of these release notes.

2.15 Move from svn to git version control

During this release cycle we have moved from svn to git for version
control.  A fairly large number of source-tree changes have been made
to support this change such as git control of file line endings (via
.gitattributes) and files that are outside git control (via
.gitignore), replacing svn commands with git commands in scripts/*.sh,
updating README.developers to document our new git workflow, creating
the historical_repository_conversions directory to document our
version control system updates (historically from cvs to svn and for
this current release cycle from svn to git), updating the website to
refer to git, etc.

2.16 Rewrite of wxwidgets

During this release cycle the wxwidgets device and binding have been
completely rewritten.  This new version is based on wxGCDC which
provides access to wxGraphicsContext but via a wxDC interface.  There
is only one backend (as opposed to the three backends of the old
wxwidgets) so the new approach is much easier to maintain.  PLplot
needs a substantial redesign to become thread safe.  Therefore the new
wxwidgets device driver uses a client-server model to communicate with
a wxPLViewer application to avoid thread-safety issues that occur when
wxwidgets viewing applications are integrated with the wxwidgets
device.  This whole design for new wxwidgets depends heavily on the
core plbuf capability.

Our substantial tests for the new wxwidgets device on Linux, Mac OS X,
and Windows show no build issues or substantial (e.g., segfaults)
run-time issues.  However, at run time there are still a number of
rendering issues (see <https://sourceforge.net/p/plplot/bugs/151/> for
a full list of the remaining rendering issues) so in case these or any
other issue with new wxwidgets turn out to be a showstopper for any user
we have implemented the CMake option -DOLD_WXWIDGETS=ON to provide
essentially the same old wxwidgets capability that was available for
PLplot-5.10.0.  But once all the issues in bug 151 are addressed we
plan to first deprecate -DOLD_WXWIDGETS=ON, and eventually remove it
completely.  So please try the new wxwidgets first and report any
issues you find in it beyond those already mentioned in bug 151
following the bug-report procedure stated at the top of these release
notes.

________________________________________________________________
PLplot Release 5.10.0
~~~~~~~~~~~~~~~~~~~~
This is a release of the PLplot plotting package. It represents the
ongoing best efforts of the PLplot community to improve this
package, and it is the only version of PLplot that we attempt
to support. Releases in the 5.x.y series should be available several
times per year.

If you encounter a problem that is not already documented in the
PROBLEMS file or on our bug tracker, then please send bug reports to
PLplot developers via the mailing lists at
<http://sourceforge.net/p/plplot/mailman/> (preferred for initial
discussion of issues) and, if no quick resolution is possible, then the
issue should be placed on our
bug tracker at <http://sourceforge.net/p/plplot/bugs/>.

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

INDEX

1. OFFICIAL NOTICES FOR USERS

2. Changes relative to the previous release

3. Tests made for the current release

4. Tests made for the prior release

1. OFFICIAL NOTICES FOR USERS

The distinction we made prior to 5.10.0 between stable and development
releases was essentially completely artificial and has now been
dropped.  In each case, the latest release was "stable" in the sense
that it was the PLplot team's best effort with substantial testing on
the computer platforms available to our test team.  And that tradition
continues for the release of 5.10.0.  Note we have bumped the minor
number in this release triplet compared to the previous 5.9.11 release
because from now on we want to reserve the patch number in that
triplet only for those (rare) releases that contain emergency fixes
compared to the previous release.  Note especially that 5.10.0 is not
that different from the prior release 5.9.11, and we don't ordinarily
require such emergency releases so our forthcoming release numbers are
likely to be 5.11.0, 5.12.0, etc.

2. Changes relative to the previous release

2.1 Update the parts of the build system that find Tcl-related software.

The build system now checks extensively for the consistency of the
Tcl/Tk/Itcl/Itk/Iwidgets components that are found.

2.2 Update the Tcl-related epa_build configurations.

The epa_build subproject of PLplot design goal is to make it easy to
build PLplot dependencies on all platforms.

Previously version 8.6 of Tcl/Tk and version 3 of Itcl/Itk, version 4
of Itcl/Itk, and versions 4.0 and 4.1 of Iwidgets could be epa_built
on Linux, but now the epa_build configuration files have been updated
so these builds also succeed on MinGW/MSYS.

2.3 Update the PLplot build system so that the Tcl/Tk/Itcl/Itk/Iwidgets
bindings and examples work on MinGW/MSYS.

2.4 Make many minor build-system fixes so that comprehensive tests (see
test summaries below) finally work almost completely on MinGW/MSYS.

2.5 Update api.xml to be consistent with our public API defined by plplot.h.

This substantial improvement to our DocBook documentation for our
public API has been made possible by the "check" application written
by Hǎiliàng Wáng (see
https://github.com/hailiang/go-plplot/tree/master/c/check) which uses
gccxml to convert the API information in plplot.h into XML and
compares those results (names of functions in our public API, and for
each of those functions, number of arguments, names of arguments, and
types of arguments) with the corresponding information in api.xml.
The original report from the check_api_xml_consistency target (which
runs the check programme) showed ~150 inconsistencies between api.xml
and our public API including several functions in our public API that
were not documented at all in api.xml.  That number of inconsistencies
has now been reduced to zero which constitutes a substantial upgrade
in the quality of our API documentation.

3. Tests made for the current release.

The "comprehensive tests" below refers to running
scripts/comprehensive_test.sh in default mode (i.e., not dropping any
tests).  For each of our three major configurations (shared
libraries/dynamic devices, shared libraries/nondynamic devices, and
static libraries/nondynamic devices) this test script runs ctest in
the build tree and runs the test_noninteractive and test_interactive
targets in the build tree, the installed examples tree configured with
a CMake-based build system for the examples, and an installed examples
tree configured with our traditional (Make + pkg-config) build system
for the examples.  Testers can run that script directly or there are
convenient options called -DCOMPREHENSIVE_PLPLOT_TEST_INTERACTIVE=ON
and -DCOMPREHENSIVE_PLPLOT_TEST_NONINTERACTIVE=ON for
epa_build (see cmake/epa_build/README) that automatically runs that
script for the build_plplot_lite case (The cairo, qt, and wxwidgets
device drivers are dropped) or the usual build_plplot case (no components
of PLplot dropped) for either/both the interactive and noninteractive
subsets of the tests.

Note that all tests mentioned below were successful ones unless
noted differently.

* Alan W. Irwin ran both interactive and noninteractive comprehensive
tests via epa_build of plplot (as opposed to plplot_lite) on a 64-bit
Debian Wheezy Linux platform on AMD-64 hardware.  That system has
virtually every relevant PLplot dependency either epa_built or
system-installed.  So these tests are virtually complete test of all
aspects of PLplot.

* Alan W. Irwin ran both interactive and noninteractive comprehensive
tests via epa_build of plplot_lite (as opposed to plplot) on a 64-bit
Debian Wheezy Linux platform on AMD-64 hardware.  These tests show
that the remaining components of PLplot work well when some important
components (i.e., cairo, qt, and wxwidgets device drivers) are
dropped.

* Alan W. Irwin ran both interactive and noninteractive comprehensive
tests of plplot_lite on 32-bit MinGW/MSYS/Wine for AMD-64 hardware.
(This test is only for plplot_lite since currently some of the
additional dependencies of plplot do not build on MinGW/MSYS/Wine.  It
is not clear whether this is due to a Wine issue or an epa_build
configuration issue for MinGW/MSYS.)  The language bindings and
examples tested were ada, c, c++, f95, lua, python, tcl, tk, itcl,
itk. and iwidgets.  The device drivers tested were ntk, pdf, ps, svg,
wingcc, and xfig.  So this test is less complete than the equivalent
Linux test above due to lack of PLplot dependencies on MinGW/MSYS.
But the epa_build project has already closed some of that dependency
gap for this platform (e.g., by providing builds of pkg-config, swig,
libagg, libharu, shapelib, libqhull, and everything Tcl-related), and
it is hoped it will close even more of that dependency gap in the
future.

The Wine version for this test was 1.6.1 which was built on Debian
Wheezy; the compiler was (MinGW) gcc-4.7.2; the Windows binary version
of CMake was downloaded from Kitware and was version 2.8.12.1; the
CMake generator was "MSYS Makefiles"; and the build command was "make"
(i.e., the MSYS version, not the MinGW version).

The above noninteractive comprehensive tests finished without issues.

In contrast the interactive comprehensive tests failed.  In
particular, all interactive tests for the shared library/dynamic
devices case for the build tree succeeded except for the
test_pltcl_standard_examples target which failed close to Tcl exit
from that particular test.  This failure near Tcl exit is similar to
the Tcl exit issue reported at
http://sourceforge.net/p/plplot/bugs/139/.  Because of this test
failure, the remaining configurations are untested on MinGW/MSYS/Wine
for the interactive case.

* Arjen Markus was unable to confirm the good noninteractive test
results obtained above for MinGW/MSYS using his Windows platform
consisting of MinGW-4.8.1 and MSYS on 64-bit
Windows 7, service pack 1 for AMD-64 hardware.  The long-standing MSYS
bug for parallel builds was worked around by using the epa_build
-DNUMBER_PARALLEL_JOBS:STRING=1 cmake option.  The build failure occurred
with an "undefined reference to `tclStubsPtr'" that occurred during
the course of the Itk epa_build.  It is not clear at this point if his
setup of epa_build (creating appropriate values for the

INSTALL_PREFIX
EPA_BUILD_SOURCE_PATH
CFLAGS
CXXFLAGS
FFLAGS
CMAKE_INCLUDE_PATH
CMAKE_LIBRARY_PATH
PATH
PKG_CONFIG_PATH
BUILD_COMMAND
GENERATOR_STRING

environment variables) or MinGW-4.8.1 (as opposed to MinGW-4.7.2 used
in the above successful test), or some other issue is causing failure
of the Itk build on this platform.

4. Tests made for the prior release

To remind the test team of the tests that were run for the
last release (5.9.11) here are the complete notes on
those tests from the previous release announcement.

Note that "comprehensive tests" below refers to running
scripts/comprehensive_test.sh in default mode (i.e., not dropping any
tests).  For each of our three major configurations (shared
libraries/dynamic devices, shared libraries/nondynamic devices, and
static libraries/nondynamic devices) this test script runs ctest in
the build tree and runs the test_noninteractive and test_interactive
targets in the build tree, the installed examples tree configured with
a CMake-based build system for the examples, and an installed examples
tree configured with our traditional (Make + pkg-config) build system
for the examples.

Note that all tests mentioned below were successful ones unless
noted differently.

* Alan W. Irwin ran comprehensive tests for a complete system build
environment on 64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran comprehensive tests for a limited (qt, cairo, wxwidgets,
and octave PLplot components were dropped) epa_build environment on
64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran comprehensive tests for an almost complete epa_build
environment (only the wxwidgets and octave components of PLplot were
dropped) on 64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran fairly comprehensive tests (i.e, for the shared
library/dynamic devices case run ctest and also the
test_noninteractive and test_interactive targets in the build tree)
for a quite limited (qt, cairo, wxwidgets, octave, Tcl/Tk, and Java
PLplot components were dropped) epa_build environment for 32-bit
MinGW/MSYS/Wine for AMD-64 hardware.  The Wine version was a release
candidate for Wine-1.6 that was built on Debian Wheezy Linux, the
compiler was gcc-4.7.2, the CMake generator was "MSYS Makefiles", and
the build command was "make" (i.e., the MSYS version, not the MinGW
version).  An attempt was made to extend this successful test result
to the installed examples built with the CMake-based build system, but
for that case the Ada examples all failed at run time with a return
code of 3 so no further attempt was made to widen the scope of these
MinGW/MSYS/Wine tests.

* Andrew Ross ran fairly comprehensive tests (i.e., for the shared
library/dynamic devices case use the test_noninteractive and
test_interactive targets in the build tree) for a complete system
build environment on 64-bit Debian unstable Linux for AMD-64 hardware.

* Andrew Ross ran comprehensive tests for a complete system build
environment on 64-bit Ubuntu Saucy (13.10) Linux for AMD-64 hardware.
The only issue was a segmentation fault on the c++ qt_example for
the nondynamic devices case only. This is reproducible on this
system, but not on other Linux platforms so may be specific to the
Ubuntu version of the Qt libraries. This is unlikely to affect most
users since the default is to use dynamically loaded devices.

* Andrew Ross ran limited tests with a limited number of nondynamic
devices (mem, null, psc, svg, xfig, xwin) and limited language
bindings (C / C++ / F95) for a CentOS 5.10 system with AMD64 hardware.
The build passed "make test_diff psc". The java version was too old
and java support had to be disabled. Ada support had to be
disabled due to a bug (now fixed). Cairo support also had to be
disabled due to too old a version of the library being installed.

* Andrew Ross ran limited tests for an epa_build environment on CentOS
5.10. The buildtools and plplot_lite targets were built (with
nondynamic devices), again after disabling java, ada and cairo support.
This build added support for tcl / tk bindings and the pdf and tk based
devices. The build passed make test_noninteractive in the install tree,
but failed make test_interactive due to missing rpath information for the
itcl and itk libraries. This bug can be worked around by setting
LD_LIBRARY_PATH to point to the libraries, in which case the interactive
test works fine.

* Arjen Markus ran a fairly comprehensive test (i.e., for the shared
library/dynamic devices case use the test_noninteractive target) for a
incomplete system build environment (the Ada, D, itcl/itk, Lua, ocaml,
octave, Java, and wxwidgets components of PLplot were dropped) on
64-bit Cygwin with gcc-4.8.2.  That platform was installed on top of
64-bit Windows 7, service pack 1 for AMD-64 hardware.  Java and
wxwidgets were dropped because of build errors for those on Cygwin
that have not been resolved yet.  The remaining components were
dropped due to lack of time to investigate them so far.  There was
close to complete success with the qt and cairo (aside from wincairo)
device drivers which is an excellent Windows result since those
device drivers add a lot of important capability to PLplot.

* Arjen Markus ran build tests and limited run-time tests (checking by
hand that some components of PLplot worked) for the shared
libraries/dynamic devices case for a limited build environment (the
qt, cairo, wxwidgets, pdf and the components mentioned above of PLplot
were dropped except for Java which was included in this test) on
32-bit MinGW.  That platform was installed on top of 64-bit Windows 7,
service pack 1 for AMD-64 hardware.  The compiler was gcc-4.7.0, the
CMake generator was "MinGW Makefiles", and the build command was
mingw32-make.

* Arjen Markus ran build tests and limited run-time tests (checking by
hand that some components of PLplot worked) for the shared
libraries/dynamic devices case for a limited build environment (the
same limitations as for his MinGW tests above) for MSVC/C++ 2010 and Intel
Fortran 2011 compilers on 64-bit Windows 7, service pack 1 for AMD-64
hardware.  In general, the CMake generator "NMake Makefiles" and
the corresponding build command "nmake" worked well for this platform.
The attempted use of Visual Studio generators combined with the
Visual Studio 2010 IDE available on that platform was more problematic.

* Phil Rosenberg ran build tests and limited run-time tests (checking
by hand that some components of PLplot worked) for the static
libraries/nondynamic devices case for a limited build environment
(virtually all PLplot components dropped other than C, C++ and
wxwidgets 2.8) for the Visual Studio 2008 IDE (with associated MSVC
compiler) on 32-bit Windows 7 for AMD-64 hardware.  The "Visual Studio
9 2008" generator yielded good results.

* Phil Rosenberg ran build tests and limited run-time tests (checking
by hand that some components of PLplot worked) for the static
libraries/nondynamic devices case for a limited build environment
(virtually all PLplot components dropped other than C, CXX, and
wxwidgets 3.0) for the Visual Studio 2012 IDE (with associated MSVC
compiler) on Windows 8 for AMD-64 hardware.  Both x86 and x64 builds
were tested.  The combination of "NMake Makefiles" generator and MSVC
compiler yielded good build results if CMake patches (available at
http://www.cmake.org/Bug/view.php?id=14587 and
http://www.cmake.org/Bug/view.php?id=14642) to allow use of
wxwidgets-3.0 were applied.  With those patches some run-time problems
with the use of Plplot's wxWidgetsApp with wxWidgets 3.0 were observed
in the examples, however plots embedded in wxWidgets apps seem to work
fine.  The "Visual Studio 11" and "Visual Studio 11 Win64" generators
had some additional issues which could be worked around but which
nevertheless indicated there are some CMake bugs for those generators
that need to be addressed.

* Jerry Bauck ran build tests of PLplot for the C core library, the
Ada, C++, Java, Lua, and Python bindings, and a fairly complete list
of device drivers (including qt and cairo) for PLplot on Mac OS X
Mountain Lion for AMD64 hardware.  Extremely narrow run-time tests of
the Ada examples were a success, but all the standard testing scripts
failed because for unknown reasons the lena.pgm file that is used in
conjunction with our standard example 20 was not properly copied by
our build and test system from the source tree to the correct
locations in the build tree.

* Felipe Gonzalez ran build tests of PLplot for the C core library and
the C++, Fortran 95, and OCaml-4.01.0 bindings on Mac OS X Mountain
Lion.  The report from Felipe stated the compiler suite used was
probably from MacPorts, and did not state anything about the hardware
type.
PLplot Release 5.9.11
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

If you encounter a problem that is not already documented in the
PROBLEMS file or on our bug tracker, then please send bug reports to
PLplot developers via the mailing lists at
<http://sourceforge.net/p/plplot/mailman/> (preferred for initial
discussion of issues) and, if no quick resolution is possible, on our
bug tracker at <http://sourceforge.net/p/plplot/bugs/>.

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

INDEX

1. OFFICIAL NOTICES FOR USERS SINCE 5.9.10 (the previous development release)

2. Tests made for release 5.9.11

3. Changes relative to PLplot 5.9.10 (the previous development release)

3.1 NUMERIC_INCLUDE_PATH ==> NUMPY_INCLUDE_PATH
3.2 Major overhaul of the build system and bindings for Tcl and friends
3.3 Substantial overhaul of the build system for the Qt-components of PLplot
3.4 The epa_build project has been implemented


4. OFFICIAL NOTICES FOR USERS SINCE 5.8.0 (the previous stable release)

5. Changes relative to PLplot 5.8.0 (the previous stable release)

5.1 All autotools-related files have now been removed
5.2 Build system bug fixes
5.3 Build system improvements
5.4 Implement build-system infrastructure for installed Ada bindings and
examples
5.5 Code cleanup
5.6 Date / time labels for axes
5.7 Alpha value support
5.8 New PLplot functions
5.9 External libLASi library improvements affecting our psttf device
5.10 Improvements to the cairo driver family
5.11 wxWidgets driver improvements
5.12 pdf driver improvements
5.13 svg driver improvements
5.14 Ada language support
5.15 OCaml language support
5.16 Perl/PDL language support
5.17 Update to various language bindings
5.18 Update to various examples
5.19 Extension of our test framework
5.20 Rename test subdirectory to plplot_test
5.21 Website support files updated
5.22 Internal changes to function visibility
5.23 Dynamic driver support in Windows
5.24 Documentation updates
5.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
5.26 get-drv-info now changed to test-drv-info
5.27 Text clipping now enabled by default for the cairo devices
5.28 A powerful qt device driver has been implemented
5.29 The PLplot API is now accessible from Qt GUI applications
5.30 NaN / Inf support for some PLplot functions
5.31 Various bug fixes
5.32 Cairo driver improvements
5.33 PyQt changes
5.34 Color Palettes
5.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
5.36 Make PLplot aware of LC_NUMERIC locale
5.37 Linear gradients have been implemented
5.38 Cairo Windows driver implemented
5.39 Custom axis labelling implemented
5.40 Universal coordinate transform implemented
5.41 Support for arbitrary storage of 2D user data
5.42 Font improvements
5.42 Alpha value support for plotting in memory.
5.43 Add a Qt device for in memory plotting.
5.44 Add discrete legend capability.
5.45 Add full bindings and examples for the D language.
5.46 The plstring and plstring3 functions have been added
5.47 The pllegend API has been finalized
5.48 Octave bindings now implemented with swig
5.49 Documentation redone for our swig-generated Python and Octave bindings
5.50 Support large polygons
5.51 Complete set of PLplot parameters now available for Fortran
5.52 The plarc function has been added
5.53 The format for map data used by plmap has changed
5.54 Python support for Numeric has been dropped
5.55 Backwards-incompatible API change to non-integer line widths
5.56 Improvements to the build system for the Cygwin case
5.57 The plcolorbar API has been finalized
5.58 Documentation of the new legend and color bar capabilities of PLplot
5.59 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)
5.60 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook
5.61 Implement experimental build_projects sub-project
5.62 Implement extremely simple "00" example
5.63 Convert to using the Allura form of SourceForge software
5.64 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems
5.65 Update f95 examples to take larger advantage of Fortran 95 capabilities
5.66 Substantial additions to the doxygen documentation
5.67 NUMERIC_INCLUDE_PATH ==> NUMPY_INCLUDE_PATH
5.68 Major overhaul of the build system and bindings for Tcl and friends
5.69 Substantial overhaul of the build system for the Qt-components of PLplot
5.70 The epa_build project has been implemented

1. OFFICIAL NOTICES FOR USERS SINCE 5.9.10 (the previous development release)

(5.9.11) Backwards-incompatible API change.  The numerical symbolic
constants that are #defined as macros in plplot.h have been
repropagated to the Python, Java, Lua, Octave, Fortran 95, and Tcl
language bindings using scripts.  Previously, this propagation was
done by hand in a piece-meal manner so use of the scripts has created
a number of changes in the PLplot symbolic constants for these
languages.  These changes are the addition of 25 symbolic constants
that were previously only available for C, no deletions of symbolic
constants, no changes to numerical values, but the following
backwards-incompatible name changes:

PLESC_PLFLTBUFFERING ==> PLESC_DOUBLEBUFFERING
PLESPLFLTBUFFERING_DISABLE ==> PLESC_DOUBLEBUFFERING_ENABLE
PLESPLFLTBUFFERING_ENABLE ==> PLESC_DOUBLEBUFFERING_ENABLE
PLESPLFLTBUFFERING_QUERY ==> PLESC_DOUBLEBUFFERING_QUERY

So those users who were using the symbolic constants on the left for
the above languages will have to change their source code or scripts
to use the constants on the right.  No changes in source code or
scripts should be required of other users.

(5.9.11) Backwards-incompatible API change.  The PLplot build system
and bindings for Tcl and friends have had a major overhaul, see below.
Part of this change was to split the former libplplottcltk into two
components.  The new libplplottcltk is now a pure Tcl/Tk extension
that can be linked to the stub versions of the Tcl/Tk libraries and
dynamically loaded from a tclsh or wish environment using the
appropriate "package require" command.  The new libplplottcltk_Main
library contains code (e.g., pltclMain and pltkMain) required by C
plotting applications (e.g., pltcl, plrender, and xtk0[124].c) that
link to libplplottcltk.

(5.9.11) Backwards-incompatible change.  Our Fortran 77 bindings
and examples have been completely removed because Fortran 95 is just a
much better language which we have been supporting for a long time,
and our judgement call based on user feedback we have received is
nobody is interested in plotting using strict Fortran 77 language
constructs any more.  However, if there is still some Fortran 77
source code out there that uses PLplot, typically the only change you
should have to do to port it to our Fortran 95 bindings is to place
the command "use plplot" as the first line of the source code of the
main routine.

(5.9.11) Deprecation.  The functionality of the AGG backend and
FreeType option in the wxwidgets device driver is provided (and in
some cases exceeded) by other backends and options that we have
implemented for this device driver.  The AGG backend and Freetype
option are therefore deprecated with the intention to remove them in a
future release.

2. Tests made for release 5.9.11

Note that "comprehensive tests" below refers to running
scripts/comprehensive_test.sh in default mode (i.e., not dropping any
tests).  For each of our three major configurations (shared
libraries/dynamic devices, shared libraries/nondynamic devices, and
static libraries/nondynamic devices) this test script runs ctest in
the build tree and runs the test_noninteractive and test_interactive
targets in the build tree, the installed examples tree configured with
a CMake-based build system for the examples, and an installed examples
tree configured with our traditional (Make + pkg-config) build system
for the examples.

Note that all tests mentioned below were successful ones unless
noted differently.

* Alan W. Irwin ran comprehensive tests for a complete system build
environment on 64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran comprehensive testsfor a limited (qt, cairo, wxwidgets,
and octave PLplot components were dropped) epa_build environment on
64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran comprehensive tests for an almost complete epa_build
environment (only the wxwidgets and octave components of PLplot were
dropped) on 64-bit Debian Wheezy Linux for AMD-64 hardware.

* Alan W. Irwin ran fairly comprehensive tests (i.e, for the shared
library/dynamic devices case run ctest and also the
test_noninteractive and test_interactive targets in the build tree)
for a quite limited (qt, cairo, wxwidgets, octave, Tcl/Tk, and Java
PLplot components were dropped) epa_build environment for 32-bit
MinGW/MSYS/Wine for AMD-64 hardware.  The Wine version was a release
candidate for Wine-1.6 that was built on Debian Wheezy Linux, the
compiler was gcc-4.7.2, the CMake generator was "MSYS Makefiles", and
the build command was "make" (i.e., the MSYS version, not the MinGW
version).  An attempt was made to extend this successful test result
to the installed examples built with the CMake-based build system, but
for that case the Ada examples all failed at run time with a return
code of 3 so no further attempt was made to widen the scope of these
MinGW/MSYS/Wine tests.

* Andrew Ross ran fairly comprehensive tests (i.e., for the shared
library/dynamic devices case use the test_noninteractive and
test_interactive targets in the build tree) for a complete system
build environment on 64-bit Debian unstable Linux for AMD-64 hardware.

* Andrew Ross ran comprehensive tests for a complete system build
environment on 64-bit Ubuntu Saucy (13.10) Linux for AMD-64 hardware.
The only issue was a segmentation fault on the c++ qt_example for
the nondynamic devices case only. This is reproducible on this
system, but not on other Linux platforms so may be specific to the
Ubuntu version of the Qt libraries. This is unlikely to affect most
users since the default is to use dynamically loaded devices.

* Andrew Ross ran limited tests with a limited number of nondynamic
devices (mem, null, psc, svg, xfig, xwin) and limited language
bindings (C / C++ / F95) for a CentOS 5.10 system with AMD64 hardware.
The build passed "make test_diff psc". The java version was too old
and java support had to be disabled. Ada support had to be
disabled due to a bug (now fixed). Cairo support also had to be
disabled due to too old a version of the library being installed.

* Andrew Ross ran limited tests for an epa_build environment on CentOS
5.10. The buildtools and plplot_lite targets were built (with
nondynamic devices), again after disabling java, ada and cairo support.
This build added support for tcl / tk bindings and the pdf and tk based
devices. The build passed make test_noninteractive in the install tree,
but failed make test_interactive due to missing rpath information for the
itcl and itk libraries. This bug can be worked around by setting
LD_LIBRARY_PATH to point to the libraries, in which case the interactive
test works fine.

* Arjen Markus ran a fairly comprehensive test (i.e., for the shared
library/dynamic devices case use the test_noninteractive target) for a
incomplete system build environment (the Ada, D, itcl/itk, Lua, ocaml,
octave, Java, and wxwidgets components of PLplot were dropped) on
64-bit Cygwin with gcc-4.8.2.  That platform was installed on top of
64-bit Windows 7, service pack 1 for AMD-64 hardware.  Java and
wxwidgets were dropped because of build errors for those on Cygwin
that have not been resolved yet.  The remaining components were
dropped due to lack of time to investigate them so far.  There was
close to complete success with the qt and cairo (aside from wincairo)
device drivers which is an excellent Windows result since those
device drivers add a lot of important capability to PLplot.

* Arjen Markus ran build tests and limited run-time tests (checking by
hand that some components of PLplot worked) for the shared
libraries/dynamic devices case for a limited build environment (the
qt, cairo, wxwidgets, pdf and the components mentioned above of PLplot
were dropped except for Java which was included in this test) on
32-bit MinGW.  That platform was installed on top of 64-bit Windows 7,
service pack 1 for AMD-64 hardware.  The compiler was gcc-4.7.0, the
CMake generator was "MinGW Makefiles", and the build command was
mingw32-make.

* Arjen Markus ran build tests and limited run-time tests (checking by
hand that some components of PLplot worked) for the shared
libraries/dynamic devices case for a limited build environment (the
same limitations as for his MinGW tests above) for MSVC/C++ 2010 and Intel
Fortran 2011 compilers on 64-bit Windows 7, service pack 1 for AMD-64
hardware.  In general, the CMake generator "NMake Makefiles" and
the corresponding build command "nmake" worked well for this platform.
The attempted use of Visual Studio generators combined with the
Visual Studio 2010 IDE available on that platform was more problematic.

* Phil Rosenberg ran build tests and limited run-time tests (checking
by hand that some components of PLplot worked) for the static
libraries/nondynamic devices case for a limited build environment
(virtually all PLplot components dropped other than C, C++ and
wxwidgets 2.8) for the Visual Studio 2008 IDE (with associated MSVC
compiler) on 32-bit Windows 7 for AMD-64 hardware.  The "Visual Studio
9 2008" generator yielded good results.

* Phil Rosenberg ran build tests and limited run-time tests (checking
by hand that some components of PLplot worked) for the static
libraries/nondynamic devices case for a limited build environment
(virtually all PLplot components dropped other than C, CXX, and
wxwidgets 3.0) for the Visual Studio 2012 IDE (with associated MSVC
compiler) on Windows 8 for AMD-64 hardware.  Both x86 and x64 builds
were tested.  The combination of "NMake Makefiles" generator and MSVC
compiler yielded good build results if CMake patches (available at
http://www.cmake.org/Bug/view.php?id=14587 and
http://www.cmake.org/Bug/view.php?id=14642) to allow use of
wxwidgets-3.0 were applied.  With those patches some run-time problems
with the use of Plplot's wxWidgetsApp with wxWidgets 3.0 were observed
in the examples, however plots embedded in wxWidgets apps seem to work
fine.  The "Visual Studio 11" and "Visual Studio 11 Win64" generators
had some additional issues which could be worked around but which
nevertheless indicated there are some CMake bugs for those generators
that need to be addressed.

* Jerry Bauck ran build tests of PLplot for the C core library, the
Ada, C++, Java, Lua, and Python bindings, and a fairly complete list
of device drivers (including qt and cairo) for PLplot on Mac OS X
Mountain Lion for AMD64 hardware.  Extremely narrow run-time tests of
the Ada examples were a success, but all the standard testing scripts
failed because for unknown reasons the lena.pgm file that is used in
conjunction with our standard example 20 was not properly copied by
our build and test system from the source tree to the correct
locations in the build tree.

* Felipe Gonzalez ran build tests of PLplot for the C core library and
the C++, Fortran 95, and OCaml-4.01.0 bindings on Mac OS X Mountain
Lion.  The report from Felipe stated the compiler suite used was
probably from MacPorts, and did not state anything about the hardware
type.

3. Changes relative to PLplot 5.9.10 (the previous development release)

3.1 NUMERIC_INCLUDE_PATH ==> NUMPY_INCLUDE_PATH

We have long since dropped support for the Numeric Python module and
are now exclusively using the numpy Python modules instead.
Therefore, we have changed the CMake variable name used in our build
system that holds the location of the numpy headers from the confusing
misnomer, NUMERIC_INCLUDE_PATH, to NUMPY_INCLUDE_PATH.  This change
only impacts PLplot users who in the past have used the cmake option
-DNUMERIC_INCLUDE_PATH to set the CMake variable NUMERIC_INCLUDE_PATH
to the location of the numpy header directory.  Note we discourage
that method since without that user intervention, the build system
uses python and numpy to find the location which should normally be
foolproof and not subject to the inconsistencies or errors possible
with setting the variable.  But if some users still insist on setting
the variable, that variable's name should now be NUMPY_INCLUDE_PATH.

3.2 Major overhaul of the build system and bindings for Tcl and friends

After years of neglect we have worked very hard in the release cycle
leading up to the release of 5.9.11 on our build system and code
interfacing Tcl and friends (Tk, Itcl, Itk, and Iwidgets) with PLplot.
The build system now does a much better job of finding a consistent
set of components for Tcl and friends.  For example, switching from
the system version of those components to a special build of those
components is typically a matter of simply putting tclsh from the
special build first on the PATH.  And after the components of Tcl and
friends are found, the build system does extensive checking to make
sure they are compatible with each other.  The plplottcktk library has
now been split (see remarks in the above OFFICIAL NOTICES for more
details).  Many bugs have been fixed, and all tests documented in
examples/tcl/README.tcldemos and examples/tk/README.tkdemos have now
been implemented as tests via the build system to help avoid any
regressions in the build system and bindings for Tcl and friends in
the future.

As a consequence of these activities the ntk device has been enabled
under Windows. The xwin and tkwin devices work under Cygwin.

3.3 Substantial overhaul of the build system for the Qt-components of PLplot

As a result of these improvements compiling and linking of our
Qt-related components just got a lot more rational, and the
long-standing memory management issues reported by valgrind for
examples/c++/qt_example for the non-dynamic devices case have been
resolved.

3.4 The epa_build project has been implemented

The goal of this project is to make builds of recent versions of
PLplot dependencies (and PLplot itself) much more convenient on all
platforms.  Once this goal is realized, it should make the full power
of PLplot (which depends on the existence and quality of its
dependencies) readily available on all platforms.  The epa_build
project uses the power of CMake (especially the ExternalProject_Add
command which is why we chose to use the prefix "epa_" in the name of
epa_build) to organize downloading, updating, configuring, building,
testing, and installing of any kind (not just those with CMake-based
build systems) of software project with full dependency support
between all the various builds.  For those users who are not
satisified with the PLplot dependencies on their systems, learn how to
use the epa_build project by consulting cmake/epa_build/README.

The epa_build project is in pretty good shape on Linux; epa_build
configurations work properly for build tools such as Tcl/Tk8.6, Itcl,
Itk, and Iwidgets and for regular packages such as pango (needed for
the cairo device driver), qt4_lite (needed for the qt device driver),
the wxwidgets software package (needed for the wxwidgets device
driver), and many smaller, but useful PLplot dependencies such as
shapelib, libqhull, and libharu.  The total build time is roughly an
hour for an ordinary PC which is not much of a price to pay to get
access to up-to-date versions of virtually all dependencies of PLplot.
In fact, the only known dependency of PLplot not currently covered by
epa_build is octave.  In principle, it should be straightforward to
add an epa_build configurations for octave and its many dependencies,
but that possibility has not been explored yet.

In principle, epa_build should work out of the box on Mac OS X
platforms, but we haven't tested on that platform yet.

Our testing for MinGW/MSYS and Cygwin shows the epa_build project is
still in fairly rough shape on Windows.  It is known that the "plplot"
case (PLplot with all its dependencies) fails in various ways on all
Windows platforms.  Those issues are being actively worked on.  Note,
however, that the "plplot_lite" case (PLplot with all the minor
dependencies but without Tcl etc., build tools and without the pango,
qt4_lite, and wxwidgets dependencies) has been shown to work on
MinGW/MSYS and should probably also work on Cygwin although we haven't
tested that specific case yet.

4. OFFICIAL NOTICES FOR USERS SINCE 5.8.0 (the previous stable release)

(5.9.11) Backwards-incompatible API change.  The numerical symbolic
constants that are #defined as macros in plplot.h have been
repropagated to the Python, Java, Lua, Octave, Fortran 95, and Tcl
language bindings using scripts.  Previously, this propagation was
done by hand in a piece-meal manner so use of the scripts has created
a number of changes in the PLplot symbolic constants for these
languages.  These changes are the addition of 25 symbolic constants
that were previously only available for C, no deletions of symbolic
constants, no changes to numerical values, but the following
backwards-incompatible name changes:

PLESC_PLFLTBUFFERING ==> PLESC_DOUBLEBUFFERING
PLESPLFLTBUFFERING_DISABLE ==> PLESC_DOUBLEBUFFERING_ENABLE
PLESPLFLTBUFFERING_ENABLE ==> PLESC_DOUBLEBUFFERING_ENABLE
PLESPLFLTBUFFERING_QUERY ==> PLESC_DOUBLEBUFFERING_QUERY

So those users who were using the symbolic constants on the left for
the above languages will have to change their source code or scripts
to use the constants on the right.  No changes in source code or
scripts should be required of other users.

(5.9.11) Backwards-incompatible API change.  The PLplot build system
and bindings for Tcl and friends have had a major overhaul, see below.
Part of this change was to split the former libplplottcltk into two
components.  The new libplplottcltk is now a pure Tcl/Tk extension
that can be linked to the stub versions of the Tcl/Tk libraries and
dynamically loaded from a tclsh or wish environment using the
appropriate "package require" command.  The new libplplottcltk_Main
library contains code (e.g., pltclMain and pltkMain) required by C
plotting applications (e.g., pltcl, plrender, and xtk0[124].c) that
link to libplplottcltk.

(5.9.11) Backwards-incompatible change.  Our Fortran 77 bindings
and examples have been completely removed because Fortran 95 is just a
much better language which we have been supporting for a long time,
and our judgement call based on user feedback we have received is
nobody is interested in plotting using strict Fortran 77 language
constructs any more.  However, if there is still some Fortran 77
source code out there that uses PLplot, typically the only change you
should have to do to port it to our Fortran 95 bindings is to place
the command "use plplot" as the first line of the source code of the
main routine.

(5.9.11) Deprecation.  The functionality of the AGG backend and
FreeType option in the wxwidgets device driver is provided (and in
some cases exceeded) by other backends and options that we have
implemented for this device driver.  The AGG backend and Freetype
option are therefore deprecated with the intention to remove them in a
future release.

(5.9.10) The minimum version of CMake has been bumped to 5.8.9.  This
change allows our build system to take advantage of CMake features
introduced in later versions of CMake.  Even more importantly it also
updates user's builds to the CMake policy conventions (important
backwards-incompatible changes in CMake behaviour introduced in later
versions of CMake) to the default CMake policy used for 5.8.9.

(5.9.10) The long deprecated support for the python Numeric package has been
dropped. This is no longer supported and is superseded by numpy. Support for
numpy has been the default in PLplot for a number of years so most users
should notice no difference.

(5.9.10) The current format for maps used by plmap has been deprecated in
favour of using shapefiles (a standard format widely used for GIS and with
suitable free data sources available). This requires the shapelib library
to be installed. If this library is not installed then by default no map
support will be available. Support for the old binary format is still
available by setting the cmake variable PL_DEPRECATED, however this
support will be removed in a future release of PLplot.

(5.9.10) Those who use the Python version of plgriddata will have to
change their use of this function for this release as follows (see
examples/xw21.py)

# old version (which overwrites preexisting zg in place):
zg = reshape(zeros(xp*yp),(xp,yp))
plgriddata(x, y, z, xg, yg, zg, alg, opt[alg-1])

# new version (which uses a properly returned newly created NumPy array
# as per the normal Python expectations):

zg = plgriddata(x, y, z, xg, yg, alg, opt[alg-1])

(5.9.10) Significant efforts have been made to ensure the PLplot code
is standards compliant and free from warnings. Compliance has been
tested using the gcc compiler suite -std, -pedantic and -W  flags. The
language standards adopted are
C: ISO C99 with POSIX.1-2001 base specification (required for a number
of C library calls)
C++: ISO C++ 1998 standard plus amendments
F95: Fortran 95 standard

Specifically, the following gcc / g++ / gfortran flags were used

CFLAGS='-O3 -std=c99 -pedantic -D_POSIX_C_SOURCE=200112L -Wall  \
-Wextra -Wmissing-prototypes -Wstrict-prototypes -Wnested-externs \
-Wconversion -Wshadow -Wcast-qual -Wcast-align -Wwrite-strings'

CXXFLAGS='-O3 -fvisibility=hidden -std=c++98 -pedantic -Wall -Wextra '

FFLAGS='-std=f95 -O3 -fall-intrinsics -fvisibility=hidden -pedantic \
-Wall -Wextra '

Note that the code is not yet quite standards compliant or warning free,
but this is our aim. We know that a number of common compilers do not
support these standards "out of the box", so we will continue to develop
and support workarounds to ensure that PLplot remains easily built on
a variety of platforms and compilers. Standards compliance should make
it easier to port to new systems in the future. Using aggressive
warnings flags will help to detect and eliminate errors or problems in
the libraries.

The gfortran -fall-intrinsics flag is required for a couple of
non-standard intrinsics which are used in the code. In the future
adopting the fortran 2003 or 2008 standard should allow this to be
removed.

Note: currently this code cleanup does not apply to code generated by
swig (octave, python, java, lua bindings) which gives a large number of
code warnings.

(5.9.10) For some years now we have had both FORTRAN 77 and Fortran 95
bindings, but to the best of our knowledge, there are no longer
any maintained FORTRAN 77 compilers left that do not also support
Fortran 95. (g77 for instance has not been maintained for several
years now. Its successor gfortran supports Fortran 95 and later standards
as well all g77's legacy features).

An important consequence is that we can not test the implementation for
compliance to the FORTRAN 77 standard.
Furthermore, we would prefer to concentrate all our Fortran
development effort on our f95 bindings and strongly encourage all our
Fortran users to use those bindings if they haven't switched from the
f77 version already. Therefore, as of this release we are deprecating
the f77 bindings and examples and plan no further support for them.
We signal this deprecation by disabling f77 by default (although our
users can still get access to these unsupported bindings and examples
for now by specifying the -DENABLE_f77=ON cmake option).

We plan to completely remove the f77 bindings and examples
two releases after this one.

(5.9.10) We have found that some distributions of the Windows
MinGW/gfortran compiler (i.e., MinGW/gfortran 4.6.1 and 4.6.2 from
http://www.equation.com) may cause a link error due to duplicate
symbols like __gfortran_setarg_. These errors can be suppressed by
adding the flag -Wl,--allow-multiple-define. It is very likely that
this is a bug in these distributions.

As building the libraries and the examples succeeds without any problem
if you use most other distributions of Windows MinGW/gfortran,
we have decided not to include this flag in our build system.

Distributions that are known to work:
- MinGW/gfortran-4.5 from http://www.equation.com,
- MinGW/gfortran-4.5.2-1 that is installed using the latest
  mingw-get-inst-20110802 automatic installer available at
  http://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst
- MinGW/gfortran-4.6.2 from tdm-gcc.tdragon.net

(Therefore it is not the 4.5.x versus 4.6.x version of MinGW/gfortran
as such that causes this problem.)

(5.9.9) This is a quick release to deal with two broken build issues
that were recently discovered for our Windows platform.  Windows users should
avoid 5.9.8 because of these problems for that release, and instead use
5.9.9 which has been heavily tested on a number of platforms including
Windows, see "Tests made for release 5.9.9" below.

(5.9.8) For unicode-aware devices we now follow what is done for the
Hershey font case for epsilon, theta, and phi.  This means the #ge,
#gh, and #gf escapes now give users the Greek lunate epsilon, the
ordinary Greek lower case theta, and the Greek symbol phi for Unicode
fonts just like has occurred since the dawn of PLplot history for the
Hershey font case.  Previously these legacy escapes were assigned to
ordinary Greek lower-case epsilon, the Greek symbol theta (= script
theta), and the ordinary Greek lower case phi for unicode fonts
inconsistently with what occurred for Hershey fonts.  This change gets
rid of this inconsistency, that is the #g escapes should give the best
unicode approximation to the Hershey glyph result that is possible for
unicode-aware devices.

In general we encourage users of unicode-aware devices who might
dislike the Greek glyph Hershey-lookalike choices they get with the
legacy #g escapes to use instead either PLplot unicode escapes (e.g.,
"#[0x03b5]" for ordinary Greek lower-case epsilon, see page 3 of
example 23) or better yet, UTF-8 strings (e.g., "ε") to specify
exactly what unicode glyph they want.

(5.9.8) The full set of PLplot constants have been made available to
our Fortran 95 users as part of the plplot module.  This means those
users will have to remove any parameter statements where they have
previously defined the PLplot constants (whose names typically start
with "PL_" for themselves.  For a complete list of the affected
constants, see the #defines in swig-support/plplotcapi.i which are
used internally to help generate the plplot module.  See also Index
item 5.51 below.

(5.9.8) There has been widespread const modifier changes in the API
for libplplotd and libplplotcxxd.  Those backwards-incompatible API
changes are indicated in the usual way by a soversion bump in those
two libraries which will force all apps and libraries that depend on
those two libraries to be rebuilt.

Specifically, we have changed the following arguments in the C library
(libplplotd) case

type * name1 ==> const type * name1
type * name2 ==> const type ** name2

and the following arguments in the C++ library (libplplotcxxd) case

type * name1 ==> const type * name1
type * name1 ==> const type * const * name2

where name1 is the name of a singly dimensioned array whose values are
not changed internally by the PLplot libraries and name2 is the name
of a doubly dimensioned array whose values are not changed internally
by the PLplot libraries.

The general documentation and safety justification for such const
modifier changes to our API is given in
http://www.cprogramming.com/tutorial/const_correctness.html.
Essentially, the above const modifier changes constitute our guarantee
that the associated arrays are not changed internally by the PLplot
libraries.

Although it is necessary to rebuild all apps and libraries that depend
on libplplotd and/or libplplotcxxd, that rebuild should be possible
with unchanged source code without build errors in all cases.  For C
apps and libraries (depending on libplplotd) there will be additional
build warnings due to a limitation in the C standard discussed at
http://c-faq.com/ansi/constmismatch.html unless all doubly dimensioned
arrays (but not singly dimensioned) are explicitly cast to (const type
**).  However, such source code changes will not be necessary to avoid
warning messages for the C++ (libplplotcxxd) change because of the
double use of const in the above "const type * const * name2" change.

(5.9.8) The plarc API has changed in release 5.9.8.  The plarc API now
has a rotation parameter which will eventually allow for rotated arcs.
PLplot does not currently support rotated arcs, but the plarc function
signature has been modified to avoid changing the API when this
functionality is added.

(5.9.6) We have retired the pbm driver containing the pbm (actually
portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey
font fallback), falls back to ugly software fills, doesn't support
alpha transparency, etc.  It also has a serious run-time issue with
example 2 (double free detected by glibc) which probably indicates
some fundamental issue with the 100 colors in cmap0 for that
example. For those who really need portable pixmap results, we suggest
using the ImageMagick convert programme, e.g., "convert
examples/x24c01.pngqt test.ppm" or "convert examples/x24c01.pngcairo
test.ppm" to produce good-looking portable pixmap results from our
best png device results.

(5.9.6) We have retired the linuxvga driver containing the linuxvga
interactive device.  This device is quite primitive, difficult to
test, and poorly maintained. It ignores unicode fonts (i.e., uses the
Hershey font fallback), falls back to ugly software fills, doesn't
support alpha transparency, etc.  It is Linux only, can only be run as
root, and svgalib (the library used by linuxsvga) is not supported by
some mainstream (e.g., Intel) chipsets.  All of these characteristics
make it difficult to even test this device much less use it for
anything serious.  Finally, it has had a well-known issue for years
(incorrect colors) which has never been fixed indicating nobody is
interested in maintaining this device.

(5.9.6) We have retired our platform support of djgpp that used to
reside in sys/dos/djgpp.  The developer (Andrew Roach) who used to
maintain those support files for djgpp feels that the djgpp platform
is no longer actively developed, and he no longer uses djgpp himself.

(5.9.6) We have changed plpoin results for ascii codes 92, 94, and 95
from centred dot, degree symbol, and centred dot glyphs to the correct
backslash, caret, and underscore glyphs that are associated with those
ascii indices.  This change is consistent with the documentation of
plpoin and solves a long-standing issue with backslash, caret, and
underscore ascii characters in character strings used for example by
pl[mp]tex.  Those who need access to a centred dot with plpoin should
use index 1.  The degree symbol is no longer accessible with plpoin,
but it is available in ordinary text input to PLplot as Hershey escape
"#(718)", where 718 is the Hershey index of the degree symbol, unicode
escape "#[0x00B0]" where 0x00B0 is the unicode index for the degree
symbol or direct UTF8 unicode string "°".

(5.9.6) We have retired the gcw device driver and the related gnome2
and pygcw bindings since these are unmaintained and there are good
replacements.  These components of PLplot were deprecated as of
release 5.9.3.  A good replacement for the gcw device is either the
xcairo or qtwidget device.  A good replacement for the gnome2 bindings
is the externally supplied XDrawable or Cairo context associated with
the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

(5.9.6) We have deprecated support for the python Numeric array
extensions. Numeric is no longer maintained and users of Numeric are
advised to migrate to numpy. Numpy has been the standard for PLplot
for some time. If numpy is not present PLplot will now disable python
by default. If you still require Numeric support in the short term
then set USE_NUMERIC to ON in cmake. The PLplot support for Numeric
will be dropped in a future release.

(5.9.5) We have removed pyqt3 access to PLplot and replaced it by
pyqt4 access to PLplot (see details below).

(5.9.5) The only method of specifying a non-default compiler (and
associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and
associated compiler options will not be supported until CMake bug 9220
is fixed, see discussion below of the soft-landing re-implementation
for details.

(5.9.5) We have retired the hpgl driver (containing the hp7470,
hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and
the tek driver (containing the conex, mskermit, tek4107, tek4107f,
tek4010, tek4010f, versaterm, vlt, and xterm devices).  Retirement
means we have removed the build options which would allow these
devices to build and install.  Recent tests have shown a number of
run-time issues (hpgl, impress, and ljii) or build-time issues (tek)
with these devices, and as far as we know there is no more user
interest in them. Therefore, we have decided to retire these devices
rather than fix them.

(5.9.4) We have deprecated the pbm device driver (containing the pbm
device) because glibc detects a catastrophic double free.

(5.9.3) Our build system requires CMake version 5.6.0 or higher.

(5.9.3) We have deprecated the gcw device driver and the related
gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on
the plfreetype approach for accessing unicode fonts which has known
issues (inconsistent text offsets, inconvenient font setting
capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally
supplied XDrawable or Cairo context associated with the xcairo device
and the extcairo device (see examples/c/README.cairo) instead. If you
still absolutely must use -dev gcw or the related gnome2 or pygcw
bindings despite the known problems, then they can still be accessed
by setting PLD_gcw, ENABLE_gnome2, and/or ENABLE_pygcw to ON.

(5.9.3) We have deprecated the gd device driver which implements the
png, jpeg, and gif devices.  This device driver is essentially
unmaintained. For example, it still depends on the plfreetype approach
for accessing unicode fonts which has known issues (inconsistent text
offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for
the JPEG format, we advise using the jpgqt device.  PNG is normally
considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and
then downgrading the results to the GIF format using the ImageMagick
"convert" application.  For those platforms where libgd (the
dependency of the gd device driver) is accessible while the required
dependencies of the cairo and/or qt devices are not accessible, you
can still use these deprecated devices by setting PLD_png, PLD_jpeg,
or PLD_gif to ON.

(5.9.3) We have re-enabled the tk, itk, and itcl components of PLplot
by default that were disabled by default as of release 5.9.1 due to
segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of
PLplot.

(5.9.2) We have set HAVE_PTHREAD (now called PL_HAVE_PTHREAD as of
release 5.9.8) to ON by default for all platforms other than Darwin.
Darwin will follow later once it appears the Apple version of X
supports it.

(5.9.1) We have removed our previously deprecated autotools-based
build system.  Instead, use the CMake-based build system following the
directions in the INSTALL file.

(5.9.1) We no longer support Octave-5.1.73 which has a variety of
run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results
with all our Octave examples for Octave-3.0.1. Also, that is the
recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only
version of Octave we support at this time.

(5.9.1) We have decided for consistency sake to change the PLplot
stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact
window limit values input by users using plwind. Previously to this
change, the stream variables and the values returned by plgvpw
reflected the internal slightly expanded range of window limits used
by PLplot so that the user's specified limits would be on the graph.
Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the
expanded ranges so most users results will be identical.  However, you
may notice some small changes to your plot results if you use these
stream variables directly (only possible in C/C++) or use plgvpw.

5. Changes relative to PLplot 5.8.0 (the previous stable release)

N.B. This release includes many code cleanups and fixes relative to
5.8.0 that are not mentioned in the list below.

5.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

5.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

5.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

5.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

5.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.5. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

5.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

5.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

5.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

5.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

5.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

5.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 5.8.4
and later. This backend produces antialiased output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

5.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

5.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

5.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

5.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

5.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

5.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

5.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

5.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigorous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

5.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

5.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

5.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

5.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

5.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

5.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

5.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

5.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

5.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

5.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

5.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

5.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make Fortran command line argument parsing work with shared libraries on Windows

5.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

5.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

5.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

5.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

5.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our color palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

5.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current color map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 5.

5.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

5.39 Custom axis labelling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labelling geographic coordinates in degrees North, South, East and
West.

5.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

5.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbitrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t structure of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

5.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

5.42 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

5.43 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

5.44 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage

5.45 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).

5.46 The plstring and plstring3 functions have been added

The plstring function largely supersedes plpoin and plsym
because many(!) more glyphs are accessible with plstring.  The glyph
is specified with a PLplot user string.  As with plmtex and plptex,
the user string can contain FCI escapes to determine the font, UTF-8
code to determine the glyph or else PLplot escapes for Hershey or
unicode text to determine the glyph.  Standard examples 4 and 26 use
plstring.

The plstring3 function largely supersedes plpoin3 for the same (access
to many more glyphs) reasons.  Standard example 18 uses plstring3.

5.47 The pllegend API has been finalized

The function pllegend allows users to create a discrete plot legend
with a plotted colored box, line, and/or line of symbols for each
annotated legend entry.  The pllegend function was first made
available for 5.9.7. Due to feedback from early adopters of pllegend,
we have now added substantially to the pllegend capabilities. and we
now believe pllegend is ready for prime time.  The pllegend
capabilities are documented in our DocBook documentation and
demonstrated in standard examples 4, 26, and 33.

N.B. The current set of changes required a backwards-incompatible
change to the pllegend API.  This requires users who tried this new
functionality for 5.9.7 to reprogramme their pllegend calls.  Since
the pllegend API was labelled experimental for 5.9.7, we will not be
bumping the soversions of the affected PLplot libraries.

5.48 Octave bindings now implemented with swig

Octave is a powerful platform that demands a first-class PLplot
solution, but we were finding it difficult to realize that goal
because we were running up against limitations of the previous
matwrap-generated Octave bindings.  Accordingly, a swig-generated
version of the Octave bindings has now been implemented that builds on
the prior matwrapped bindings effort but also extends it with, e.g.,
bindings for plstring, plstring3, pllegend, and plcolorbar.  These new
octave bindings (which now completely replace the prior matwrapped
bindings) make it possible to run examples 4, 18, 26, and 33 (all of
which have now have been updated to use those functions) and get
consistent results with the corresponding C examples.

Like the matwrapped bindings before it, the new swig-generated octave
bindings currently do not have a number of the PLplot functions
wrapped (e.g., "plmap") that are needed by standard example 19.
However, because of the power of swig we now have some confidence we
can solve this issue in the future.

5.49 Documentation redone for our swig-generated Python and Octave bindings

Through the docstring %feature, swig can generate documentation
strings for certain of the languages it supports (currently Python,
Octave, and Ruby).  We have now removed all such hand-crafted swig
documentation data from bindings/swig-support/plplotcapi.i and
replaced it with generated documentation in the file
bindings/swig-support/swig_documentation.i.  That file is generated
from doc/docbook/src/api.xml using the perl script
doc/docbook/bin/api2swigdoc.pl.  The build system Unix target
"check_swig_documentation" now runs that script and compares results
with bindings/swig-support/swig_documentation.i in the source tree to
make sure that latter file is consistent with any changes that might
have occurred in doc/docbook/src/api.xml.

The resulting Octave and Python user-documentation (obtained by 'help
<PLplot_command_name>' in Octave and 'print ("%s" %
<PLplot_command_name>.__doc__)' in Python is much more detailed than
what was available before using the hand-crafted documentation.  If we
ever decided to generate PLplot bindings for Ruby with swig, this
high-quality user-documentation would be available for that language
as well.

5.50 Support large polygons

Previous releases had an implicit limitation with respect to the
number of vertices in a polygon. This was due to the use of statically
defined arrays (to avoid allocating and freeing memory for each polygon
to be drawn). José Luis García Pallero found this limitation and
provided patches to eliminate this limitation. The strategy is
that for small polygons, the original statically defined arrays
are used and for large polygons new arrays are allocated and freed.
This strategy has been applied to all relevant source files.

5.51 Complete set of PLplot parameters now available for Fortran

The #defines in bindings/swig-support/plplotcapi.i (which are
consistent with those in include/plplot.h) define the complete set of
important PLplot constants (whose names typically start with "PL_").
We have implemented automatic methods of transforming that complete
set of #defines into Fortran parameters that can be used from either
Fortran 77 or Fortran 95.

For Fortran 77, the user must insert an

      include 'plplot_parameters.h'

statement in every function/subroutine/main programme where he expects
to use PLplot constants (whose names typically start with "PL_".  (See
examples/f77/*.fm4 for examples of this method).  When compiling he
must also insert the appropriate -I option to find this file (in
bindings/f77/ in the source tree and currently in
$prefix/lib/fortran/include/plplot$version in the install tree
although that install location may be subject to change).  Note, the
above method does not interfere with existing apps which have
necessarily been forced to define the needed PLplot constants for
themselves.  But for future f77 use, the above statement is
more convenient and much less subject to error than a whole bunch of
parameter statements for the required constants.

For Fortran 95, the complete set of parameters are made available as
part of the plplot module.  So access to this complete set of
parameters is automatic wherever the "use plplot" statement is used.
This is extremely convenient for new Fortran 95 apps that use PLplot,
but, in general, changes will have to be made for existing apps. (See
announcement XX above for the details).

5.52 The plarc function has been added

The plarc function allows drawing filled and outlined arcs in PLplot.
Standard example 3 uses plarc.

5.53 The format for map data used by plmap has changed

The format for map data used by plmap is now the shapefile format.
This is a widely used standard format and there are many sources of data
in this format. This replaces the custom binary format that PLplot used
to use. The support for reading shapefiles is provided by the shapelib
library, which is a new dependency for PLplot. If users do not have this
installed then, by default, they will not get any map capabilities with
PLplot. Support for the old format can still be enabled by setting the
PL_DEPRECATED cmake variable, but this support will be removed in a
subsequent PLplot release.

5.54 Python support for Numeric has been dropped

Support for the python Numeric package has been dropped. This has been
deprecated since 5.9.6. Numeric is no longer supported and is superseded
by numpy. Support for numpy has been the default in plplot for a number
of years so most users should notice no difference.

5.55 Backwards-incompatible API change to non-integer line widths

All functions which take line width arguments (plwidth, plshade*,
pllegend) now use PLFLT values for the line width. This allows device
drivers which are based on modern graphics libraries such as Qt4 and
pango/cairo to make full use (e.g., extremely fine line widths) of the
floating-point line width capabilities of those libraries.  The
replacement of plwid by plwidth, and the change in argument lists for
plshade* and pllegend constitute a backwards incompatible API change
from previous releases and the soname of libraries has been bumped
accordingly (which forces users to recompile PLplot).

5.56 Improvements to the build system for the Cygwin case

The Cygwin platform provides a full-featured Unix environment on
Windows.  CMake has recently been changed (at the request of Cygwin
developers) to emphasize the Unix aspects of the Cygwin platform and
deemphasize the Windows aspects of that platform.  It was argued this
change would tend to make CMake builds of software much more reliable
on Cygwin, and after some small but important changes to our
CMake-based build system to adjust for these recent CMake changes for
Cygwin, we have indeed confirmed that prediction for the PLplot case.
There are still some Cygwin platform issues left which are being
discussed on our Wiki at http://www.miscdebris.net/plplot_wiki/index.php?title=Setup_cygwin,
but some fundamental breakthroughs have also been made for the Cygwin case
that should interest all our Windows users.  For example, for the
first time ever we have been able to build our cairo and qt device
drivers on the Cygwin platform giving our Windows users convenient
access to the many high-quality PLplot devices that are available with
these two different device drivers.

5.57 The plcolorbar API has been finalized

The function plcolorbar allows users to create a color bar (an
annotated subplot representing a continuous range of colors within the
main plot and typically identifying certain colors with certain
numerical values using an axis).  The plcolorbar capabilities are
documented in our DocBook (and doxygen) documentation and demonstrated
in standard examples 16 and 33.

N.B. The previous two releases (5.9.8 and 5.9.9) contained
unadvertised experimental versions of plcolorbar.  Any PLplot user who
found and tried those capabilities will have to reprogramme their
plcolorbar calls to be compatible with the argument list of the latest
version.

5.58 Documentation of the new legend and color bar capabilities of PLplot

The pllegend and plcolorbar API has been documented in both doxygen
and DocBook forms.  In addition, the "advanced use" chapter of the
DocBook form of documentation now contains a section giving an
overview of pllegend and plcolorbar.

N.B. Although we feel the pllegend and plcolorbar API has now been
finalized with regard to the PLplot core developers own interests and
needs, we also realize that as more and more PLplot users take
advantage of these new PLplot capabilities there will likely be calls
to add additional features to pllegend or plcolorbar based on
additional experience with these powerful capabilities.  In general,
we would welcome such feature requests.

5.59 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)

This change should make PLplot much more relevant for D users
going forward.

See http://en.wikipedia.org/wiki/D_(programming_language)#History for
a discussion of the differences between these two variants of D.

5.60 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook

These modern backend tools (such as xmlto) replace the
deprecated/unmaintained SGML/DSSL tools we have used before.  For
developers this means generation of our DocBook generation is much
easier. much faster, and much less error-prone.  End users will notice
some improvements in the results (e.g., the table of Greek letters) as
well as some minor style changes.

5.61 Implement experimental build_projects sub-project

The idea here (see cmake/build_projects) is to automate the build of
all PLplot dependencies and the build and test of PLplot itself for
platforms (such as Linux enterprise distributions and all forms of
Windows platforms other than Cygwin) that do not come with modern
versions of PLplot soft dependencies such as Pango/Cairo and Qt.
This project is beginning to work properly for the Linux case, but
still needs lots of work for the Windows case.

5.62 Implement extremely simple "00" example

The point of this standard example is to give the users an extremely
simple tutorial example to help them to get started with 2D plotting
with PLplot.

5.63 Convert to using the Allura form of SourceForge software

We use sourceforge.net as our software hosting facility.  Early in
2013 Sourceforge updated essentially all their support software as
part of the so-called Allura project.  This made it necessary to make
some minor internal PLplot changes such as script changes and different URL's
in the website referring to SourceForge facilities.  The most important
change from the user perspective is the URL for the Allura form
of the svn repository that we use now:

http://svn.code.sf.net/p/plplot/code/trunk/

5.64 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems

The point of this change is to reduce overlinking and therefore
the problems caused by overlinking that are mentioned
at http://en.altlinux.org/UnderOverLinkProblems.

Non-transitive linking means link only to libraries that directly
resolve undefined symbols, i.e., do not link to a library just because
it is a dependency of a dependency.

5.65 Update f95 examples to take larger advantage of Fortran 95 capabilities

Previously our f95 examples tended to use legacy Fortran capabilities, but
that situation has substantially changed for this release.

5.66 Substantial additions to the doxygen documentation

One of the on-going documentation projects is to create doxygen
documentation of every single argument of the public API for PLplot.
A substantial increase in such documentation has been implemented
in this release cycle.

5.67 NUMERIC_INCLUDE_PATH ==> NUMPY_INCLUDE_PATH

We have long since dropped support for the Numeric Python module and
are now exclusively using the numpy Python modules instead.
Therefore, we have changed the CMake variable name used in our build
system that holds the location of the numpy headers from the confusing
misnomer, NUMERIC_INCLUDE_PATH, to NUMPY_INCLUDE_PATH.  This change
only impacts PLplot users who in the past have used the cmake option
-DNUMERIC_INCLUDE_PATH to set the CMake variable NUMERIC_INCLUDE_PATH
to the location of the numpy header directory.  Note we discourage
that method since without that user intervention, the build system
uses python and numpy to find the location which should normally be
foolproof and not subject to the inconsistencies or errors possible
with setting the variable.  But if some users still insist on setting
the variable, that variable's name should now be NUMPY_INCLUDE_PATH.

5.68 Major overhaul of the build system and bindings for Tcl and friends

After years of neglect we have worked very hard in the release cycle
leading up to the release of 5.9.11 on our build system and code
interfacing Tcl and friends (Tk, Itcl, Itk, and Iwidgets) with PLplot.
The build system now does a much better job of finding a consistent
set of components for Tcl and friends.  For example, switching from
the system version of those components to a special build of those
components is typically a matter of simply putting tclsh from the
special build first on the PATH.  And after the components of Tcl and
friends are found, the build system does extensive checking to make
sure they are compatible with each other.  The plplottcktk library has
now been split (see remarks in the above OFFICIAL NOTICES for more
details).  Many bugs have been fixed, and all tests documented in
examples/tcl/README.tcldemos and examples/tk/README.tkdemos have now
been implemented as tests via the build system to help avoid any
regressions in the build system and bindings for Tcl and friends in
the future.

5.69 Substantial overhaul of the build system for the Qt-components of PLplot

As a result of these improvements compiling and linking of our
Qt-related components just got a lot more rational, and the
long-standing memory management issues reported by valgrind for
examples/c++/qt_example for the non-dynamic drivers case have been
resolved.

5.70 The epa_build project has been implemented

The goal of this project is to make builds of recent versions of
PLplot dependencies (and PLplot itself) much more convenient on all
platforms.  Once this goal is realized, it should make the full power
of PLplot (which depends on the existence and quality of its
dependencies) readily available on all platforms.  The epa_build
project uses the power of CMake (especially the ExternalProject_Add
command which is why we chose to use the prefix "epa_" in the name of
epa_build) to organize downloading, updating, configuring, building,
testing, and installing of any kind (not just those with CMake-based
build systems) of software project with full dependency support
between all the various builds.  For those users who are not
satisified with the PLplot dependencies on their systems, learn how to
use the epa_build project by consulting cmake/epa_build/README.

The epa_build project is in pretty good shape on Linux; epa_build
configurations work properly for build tools such as Tcl/Tk8.6, Itcl,
Itk, and Iwidgets and for regular packages such as pango (needed for
the cairo device driver), qt4_lite (needed for the qt device driver),
the wxwidgets software package (needed for the wxwidgets device
driver), and many smaller, but useful PLplot dependencies such as
shapelib, libqhull, and libharu.  The total build time is roughly an
hour for an ordinary PC which is not much of a price to pay to get
access to up-to-date versions of virtually all dependencies of PLplot.
In fact, the only known dependency of PLplot not currently covered by
epa_build is octave.  In principle, it should be straightforward to
add an epa_build configurations for octave and its many dependencies,
but that possibility has not been explored yet.

In principle, epa_build should work out of the box on Mac OS X
platforms, but we haven't tested on that platform yet.

Our testing for MinGW/MSYS and Cygwin shows the epa_build project is
still in fairly rough shape on Windows.  It is known that the "plplot"
case (PLplot with all its dependencies) fails in various ways on all
Windows platforms.  Those issues are being actively worked on.  Note,
however, that the "plplot_lite" case (PLplot with all the minor
dependencies but without Tcl etc., build tools and without the pango,
qt4_lite, and wxwidgets dependencies) has been shown to work on
MinGW/MSYS and should probably also work on Cygwin although we haven't
tested that specific case yet.
PLplot Release 5.9.10
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

     If you encounter a problem that is not already documented in the
PROBLEMS file or on our bug tracker, then please send bug reports to PLplot
developers via the mailing lists at
http://sourceforge.net/mail/?group_id=2915 (preferred) or on our bug tracker
at http://sourceforge.net/tracker/?group_id=2915&atid=102915.

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

INDEX

OFFICIAL NOTICES FOR USERS

CHANGES

-1. Important changes we should have mentioned in previous release announcements.

-1.1 Add full bindings and examples for the D language.

0. Tests made for release 5.9.10

1. Changes relative to PLplot 5.9.9 (the previous development release)

1.1 The format for map data used by plmap has changed
1.2 Python support for Numeric has been dropped
1.3 Backwards-incompatible API change to non-integer line widths
1.4 Improvements to the build system for the Cygwin case
1.5 The plcolorbar API has been finalized
1.6 Documentation of the new legend and color bar capabilities of PLplot
1.7 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)
1.8 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook
1.9 Implement experimental build_projects sub-project
1.10 Implement extremely simple "00" example
1.11 Convert to using the Allura form of SourceForge software
1.12 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems
1.13 Update f95 examples to take larger advantage of Fortran 95 capabilities
1.14 Substantial additions to the doxygen documentation

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
2.36 Make PLplot aware of LC_NUMERIC locale
2.37 Linear gradients have been implemented
2.38 Cairo Windows driver implemented
2.39 Custom axis labelling implemented
2.40 Universal coordinate transform implemented
2.41 Support for arbitrary storage of 2D user data
2.42 Font improvements
2.42 Alpha value support for plotting in memory.
2.43 Add a Qt device for in memory plotting.
2.44 Add discrete legend capability.
2.45 Add full bindings and examples for the D language.
2.46 The plstring and plstring3 functions have been added
2.47 The pllegend API has been finalized
2.48 Octave bindings now implemented with swig
2.49 Documentation redone for our swig-generated Python and Octave bindings
2.50 Support large polygons
2.51 Complete set of PLplot parameters now available for Fortran
2.52 The plarc function has been added
2.53 The format for map data used by plmap has changed
2.54 Python support for Numeric has been dropped
2.55 Backwards-incompatible API change to non-integer line widths
2.56 Improvements to the build system for the Cygwin case
2.57 The plcolorbar API has been finalized
2.58 Documentation of the new legend and color bar capabilities of PLplot
2.59 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)
2.60 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook
2.61 Implement experimental build_projects sub-project
2.62 Implement extremely simple "00" example
2.63 Convert to using the Allura form of SourceForge software
2.64 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems
2.65 Update f95 examples to take larger advantage of Fortran 95 capabilities
2.66 Substantial additions to the doxygen documentation


OFFICIAL NOTICES FOR USERS

(5.9.10) The minimum version of CMake has been bumped to 2.8.9.  This
change allows our build system to take advantage of CMake features
introduced in later versions of CMake.  Even more importantly it also
updates user's builds to the CMake policy conventions (important
backwards-incompatible changes in CMake behaviour introduced in later
versions of CMake) to the default CMake policy used for 2.8.9.

(5.9.10) The long deprecated support for the python Numeric package has been
dropped. This is no longer supported and is superseded by numpy. Support for
numpy has been the default in PLplot for a number of years so most users
should notice no difference.

(5.9.10) The current format for maps used by plmap has been deprecated in
favour of using shapefiles (a standard format widely used for GIS and with
suitable free data sources available). This requires the shapelib library
to be installed. If this library is not installed then by default no map
support will be available. Support for the old binary format is still
available by setting the cmake variable PL_DEPRECATED, however this
support will be removed in a future release of PLplot.

(5.9.10) Those who use the Python version of plgriddata will have to
change their use of this function for this release as follows (see
examples/xw21.py)

# old version (which overwrites preexisting zg in place):
zg = reshape(zeros(xp*yp),(xp,yp))
plgriddata(x, y, z, xg, yg, zg, alg, opt[alg-1])

# new version (which uses a properly returned newly created NumPy array
# as per the normal Python expectations):

zg = plgriddata(x, y, z, xg, yg, alg, opt[alg-1])

(5.9.10) Significant efforts have been made to ensure the PLplot code
is standards compliant and free from warnings. Compliance has been
tested using the gcc compiler suite -std, -pedantic and -W  flags. The
language standards adopted are
C: ISO C99 with POSIX.1-2001 base specification (required for a number
of C library calls)
C++: ISO C++ 1998 standard plus amendments
F95: Fortran 95 standard

Specifically, the following gcc / g++ / gfortran flags were used

CFLAGS='-O3 -std=c99 -pedantic -D_POSIX_C_SOURCE=200112L -Wall  \
-Wextra -Wmissing-prototypes -Wstrict-prototypes -Wnested-externs \
-Wconversion -Wshadow -Wcast-qual -Wcast-align -Wwrite-strings'

CXXFLAGS='-O3 -fvisibility=hidden -std=c++98 -pedantic -Wall -Wextra '

FFLAGS='-std=f95 -O3 -fall-intrinsics -fvisibility=hidden -pedantic \
-Wall -Wextra '

Note that the code is not yet quite standards compliant or warning free,
but this is our aim. We know that a number of common compilers do not
support these standards "out of the box", so we will continue to develop
and support workarounds to ensure that PLplot remains easily built on
a variety of platforms and compilers. Standards compliance should make
it easier to port to new systems in the future. Using aggressive
warnings flags will help to detect and eliminate errors or problems in
the libraries.

The gfortran -fall-intrinsics flag is required for a couple of
non-standard intrinsics which are used in the code. In the future
adopting the fortran 2003 or 2008 standard should allow this to be
removed.

Note: currently this code cleanup does not apply to code generated by
swig (octave, python, java, lua bindings) which gives a large number of
code warnings.

(5.9.10) For some years now we have had both FORTRAN 77 and Fortran 95
bindings, but to the best of our knowledge, there are no longer
any maintained FORTRAN 77 compilers left that do not also support
Fortran 95. (g77 for instance has not been maintained for several
years now. Its successor gfortran supports Fortran 95 and later standards
as well all g77's legacy features).

An important consequence is that we can not test the implementation for
compliance to the FORTRAN 77 standard.
Furthermore, we would prefer to concentrate all our Fortran
development effort on our f95 bindings and strongly encourage all our
Fortran users to use those bindings if they haven't switched from the
f77 version already. Therefore, as of this release we are deprecating
the f77 bindings and examples and plan no further support for them.
We signal this deprecation by disabling f77 by default (although our
users can still get access to these unsupported bindings and examples
for now by specifying the -DENABLE_f77=ON cmake option).

We plan to completely remove the f77 bindings and examples
two releases after this one.

(5.9.10) We have found that some distributions of the Windows
MinGW/gfortran compiler (i.e., MinGW/gfortran 4.6.1 and 4.6.2 from
http://www.equation.com) may cause a link error due to duplicate
symbols like __gfortran_setarg_. These errors can be suppressed by
adding the flag -Wl,--allow-multiple-define. It is very likely that
this is a bug in these distributions.

As building the libraries and the examples succeeds without any problem
if you use most other distributions of Windows MinGW/gfortran,
we have decided not to include this flag in our build system.

Distributions that are known to work:
- MinGW/gfortran-4.5 from http://www.equation.com,
- MinGW/gfortran-4.5.2-1 that is installed using the latest
  mingw-get-inst-20110802 automatic installer available at
  http://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst
- MinGW/gfortran-4.6.2 from tdm-gcc.tdragon.net

(Therefore it is not the 4.5.x versus 4.6.x version of MinGW/gfortran
as such that causes this problem.)

(5.9.9) This is a quick release to deal with two broken build issues
that were recently discovered for our Windows platform.  Windows users should
avoid 5.9.8 because of these problems for that release, and instead use
5.9.9 which has been heavily tested on a number of platforms including
Windows, see "Tests made for release 5.9.9" below.

(5.9.8) For unicode-aware devices we now follow what is done for the
Hershey font case for epsilon, theta, and phi.  This means the #ge,
#gh, and #gf escapes now give users the Greek lunate epsilon, the
ordinary Greek lower case theta, and the Greek symbol phi for Unicode
fonts just like has occurred since the dawn of PLplot history for the
Hershey font case.  Previously these legacy escapes were assigned to
ordinary Greek lower-case epsilon, the Greek symbol theta (= script
theta), and the ordinary Greek lower case phi for unicode fonts
inconsistently with what occurred for Hershey fonts.  This change gets
rid of this inconsistency, that is the #g escapes should give the best
unicode approximation to the Hershey glyph result that is possible for
unicode-aware devices.

In general we encourage users of unicode-aware devices who might
dislike the Greek glyph Hershey-lookalike choices they get with the
legacy #g escapes to use instead either PLplot unicode escapes (e.g.,
"#[0x03b5]" for ordinary Greek lower-case epsilon, see page 3 of
example 23) or better yet, UTF-8 strings (e.g., "ε") to specify
exactly what unicode glyph they want.

(5.9.8) The full set of PLplot constants have been made available to
our Fortran 95 users as part of the plplot module.  This means those
users will have to remove any parameter statements where they have
previously defined the PLplot constants (whose names typically start
with "PL_" for themselves.  For a complete list of the affected
constants, see the #defines in swig-support/plplotcapi.i which are
used internally to help generate the plplot module.  See also Index
item 2.51 below.

(5.9.8) There has been widespread const modifier changes in the API
for libplplotd and libplplotcxxd.  Those backwards-incompatible API
changes are indicated in the usual way by a soversion bump in those
two libraries which will force all apps and libraries that depend on
those two libraries to be rebuilt.

Specifically, we have changed the following arguments in the C library
(libplplotd) case

type * name1 ==> const type * name1
type * name2 ==> const type ** name2

and the following arguments in the C++ library (libplplotcxxd) case

type * name1 ==> const type * name1
type * name1 ==> const type * const * name2

where name1 is the name of a singly dimensioned array whose values are
not changed internally by the PLplot libraries and name2 is the name
of a doubly dimensioned array whose values are not changed internally
by the PLplot libraries.

The general documentation and safety justification for such const
modifier changes to our API is given in
http://www.cprogramming.com/tutorial/const_correctness.html.
Essentially, the above const modifier changes constitute our guarantee
that the associated arrays are not changed internally by the PLplot
libraries.

Although it is necessary to rebuild all apps and libraries that depend
on libplplotd and/or libplplotcxxd, that rebuild should be possible
with unchanged source code without build errors in all cases.  For C
apps and libraries (depending on libplplotd) there will be additional
build warnings due to a limitation in the C standard discussed at
http://c-faq.com/ansi/constmismatch.html unless all doubly dimensioned
arrays (but not singly dimensioned) are explicitly cast to (const type
**).  However, such source code changes will not be necessary to avoid
warning messages for the C++ (libplplotcxxd) change because of the
double use of const in the above "const type * const * name2" change.

(5.9.8) The plarc API has changed in release 5.9.8.  The plarc API now
has a rotation parameter which will eventually allow for rotated arcs.
PLplot does not currently support rotated arcs, but the plarc function
signature has been modified to avoid changing the API when this
functionality is added.

(5.9.6) We have retired the pbm driver containing the pbm (actually
portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey
font fallback), falls back to ugly software fills, doesn't support
alpha transparency, etc.  It also has a serious run-time issue with
example 2 (double free detected by glibc) which probably indicates
some fundamental issue with the 100 colors in cmap0 for that
example. For those who really need portable pixmap results, we suggest
using the ImageMagick convert programme, e.g., "convert
examples/x24c01.pngqt test.ppm" or "convert examples/x24c01.pngcairo
test.ppm" to produce good-looking portable pixmap results from our
best png device results.

(5.9.6) We have retired the linuxvga driver containing the linuxvga
interactive device.  This device is quite primitive, difficult to
test, and poorly maintained. It ignores unicode fonts (i.e., uses the
Hershey font fallback), falls back to ugly software fills, doesn't
support alpha transparency, etc.  It is Linux only, can only be run as
root, and svgalib (the library used by linuxsvga) is not supported by
some mainstream (e.g., Intel) chipsets.  All of these characteristics
make it difficult to even test this device much less use it for
anything serious.  Finally, it has had a well-known issue for years
(incorrect colors) which has never been fixed indicating nobody is
interested in maintaining this device.

(5.9.6) We have retired our platform support of djgpp that used to
reside in sys/dos/djgpp.  The developer (Andrew Roach) who used to
maintain those support files for djgpp feels that the djgpp platform
is no longer actively developed, and he no longer uses djgpp himself.

(5.9.6) We have changed plpoin results for ascii codes 92, 94, and 95
from centred dot, degree symbol, and centred dot glyphs to the correct
backslash, caret, and underscore glyphs that are associated with those
ascii indices.  This change is consistent with the documentation of
plpoin and solves a long-standing issue with backslash, caret, and
underscore ascii characters in character strings used for example by
pl[mp]tex.  Those who need access to a centred dot with plpoin should
use index 1.  The degree symbol is no longer accessible with plpoin,
but it is available in ordinary text input to PLplot as Hershey escape
"#(718)", where 718 is the Hershey index of the degree symbol, unicode
escape "#[0x00B0]" where 0x00B0 is the unicode index for the degree
symbol or direct UTF8 unicode string "°".

(5.9.6) We have retired the gcw device driver and the related gnome2
and pygcw bindings since these are unmaintained and there are good
replacements.  These components of PLplot were deprecated as of
release 5.9.3.  A good replacement for the gcw device is either the
xcairo or qtwidget device.  A good replacement for the gnome2 bindings
is the externally supplied XDrawable or Cairo context associated with
the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

(5.9.6) We have deprecated support for the python Numeric array
extensions. Numeric is no longer maintained and users of Numeric are
advised to migrate to numpy. Numpy has been the standard for PLplot
for some time. If numpy is not present PLplot will now disable python
by default. If you still require Numeric support in the short term
then set USE_NUMERIC to ON in cmake. The PLplot support for Numeric
will be dropped in a future release.

(5.9.5) We have removed pyqt3 access to PLplot and replaced it by
pyqt4 access to PLplot (see details below).

(5.9.5) The only method of specifying a non-default compiler (and
associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and
associated compiler options will not be supported until CMake bug 9220
is fixed, see discussion below of the soft-landing re-implementation
for details.

(5.9.5) We have retired the hpgl driver (containing the hp7470,
hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and
the tek driver (containing the conex, mskermit, tek4107, tek4107f,
tek4010, tek4010f, versaterm, vlt, and xterm devices).  Retirement
means we have removed the build options which would allow these
devices to build and install.  Recent tests have shown a number of
run-time issues (hpgl, impress, and ljii) or build-time issues (tek)
with these devices, and as far as we know there is no more user
interest in them. Therefore, we have decided to retire these devices
rather than fix them.

(5.9.4) We have deprecated the pbm device driver (containing the pbm
device) because glibc detects a catastrophic double free.

(5.9.3) Our build system requires CMake version 2.6.0 or higher.

(5.9.3) We have deprecated the gcw device driver and the related
gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on
the plfreetype approach for accessing unicode fonts which has known
issues (inconsistent text offsets, inconvenient font setting
capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally
supplied XDrawable or Cairo context associated with the xcairo device
and the extcairo device (see examples/c/README.cairo) instead. If you
still absolutely must use -dev gcw or the related gnome2 or pygcw
bindings despite the known problems, then they can still be accessed
by setting PLD_gcw, ENABLE_gnome2, and/or ENABLE_pygcw to ON.

(5.9.3) We have deprecated the gd device driver which implements the
png, jpeg, and gif devices.  This device driver is essentially
unmaintained. For example, it still depends on the plfreetype approach
for accessing unicode fonts which has known issues (inconsistent text
offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for
the JPEG format, we advise using the jpgqt device.  PNG is normally
considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and
then downgrading the results to the GIF format using the ImageMagick
"convert" application.  For those platforms where libgd (the
dependency of the gd device driver) is accessible while the required
dependencies of the cairo and/or qt devices are not accessible, you
can still use these deprecated devices by setting PLD_png, PLD_jpeg,
or PLD_gif to ON.

(5.9.3) We have re-enabled the tk, itk, and itcl components of PLplot
by default that were disabled by default as of release 5.9.1 due to
segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of
PLplot.

(5.9.2) We have set HAVE_PTHREAD (now called PL_HAVE_PTHREAD as of
release 5.9.8) to ON by default for all platforms other than Darwin.
Darwin will follow later once it appears the Apple version of X
supports it.

(5.9.1) We have removed our previously deprecated autotools-based
build system.  Instead, use the CMake-based build system following the
directions in the INSTALL file.

(5.9.1) We no longer support Octave-2.1.73 which has a variety of
run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results
with all our Octave examples for Octave-3.0.1. Also, that is the
recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only
version of Octave we support at this time.

(5.9.1) We have decided for consistency sake to change the PLplot
stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact
window limit values input by users using plwind. Previously to this
change, the stream variables and the values returned by plgvpw
reflected the internal slightly expanded range of window limits used
by PLplot so that the user's specified limits would be on the graph.
Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the
expanded ranges so most users results will be identical.  However, you
may notice some small changes to your plot results if you use these
stream variables directly (only possible in C/C++) or use plgvpw.

CHANGES

0. Tests made for release 5.9.10

Comprehensive testing that showed no non-zero return codes or other
obvious run-time issues such as segfaults was done for the Debian
Wheezy platform.  These tests were done with the
scripts/comprehensive_test.sh which does 21 major tests.  Those tests
consist of seven tests (ctest, and "make test_noninteractive" and make
"test_interactive" results for the build tree, and "make
test_noninteractive" and make "test_interactive" results for both the
traditional and CMake-based build systems for the installed examples
tree) for each of our three major configurations (shared
libraries/dynamic devices, shared libraries/non-dynamic devices,
static libraries/non-dynamic devices).

More limited testing that showed no non-zero return codes or other
obvious run-time issues such as segfaults was done on a large number
of different platforms including the following:

Fedora with "Unix Makefiles" generator
Ubuntu with "Unix Makefiles" generator
Debian unstable with "Unix Makefiles" generator
Debian wheezy with "Ninja" generator
Wine version of Windows with "MSYS Makefiles" generator
Wine version of Windows with "MinGW Makefiles" generator
Wine version of Windows with "NMake Makefiles JOM" generator
Microsoft version of Windows with Cygwin and with "Unix Makefiles" generator
Microsoft version of Windows with "MinGW Makefiles" generator
Microsoft version of Windows with "MSYS Makefiles" generator
Microsoft version of Windows with "NMake Makefiles" generator

1. Changes relative to PLplot 5.9.9 (the previous development release)

N.B. This release includes many code cleanups and fixes relative to
5.9.9 that are not mentioned in the list below.

1.1 The format for map data used by plmap has changed

The format for map data used by plmap is now the shapefile format.
This is a widely used standard format and there are many sources of data
in this format. This replaces the custom binary format that PLplot used
to use. The support for reading shapefiles is provided by the shapelib
library, which is a new dependency for PLplot. If users do not have this
installed then, by default, they will not get any map capabilities with
PLplot. Support for the old format can still be enabled by setting the
PL_DEPRECATED cmake variable, but this support will be removed in a
subsequent PLplot release.

1.2 Python support for Numeric has been dropped

Support for the python Numeric package has been dropped. This has been
deprecated since 5.9.6. Numeric is no longer supported and is superseded
by numpy. Support for numpy has been the default in plplot for a number
of years so most users should notice no difference.

1.3 Backwards-incompatible API change to non-integer line widths

All functions which take line width arguments (plwidth, plshade*,
pllegend) now use PLFLT values for the line width. This allows device
drivers which are based on modern graphics libraries such as Qt4 and
pango/cairo to make full use (e.g., extremely fine line widths) of the
floating-point line width capabilities of those libraries.  The
replacement of plwid by plwidth, and the change in argument lists for
plshade* and pllegend constitute a backwards incompatible API change
from previous releases and the soname of libraries has been bumped
accordingly (which forces users to recompile PLplot).

1.4 Improvements to the build system for the Cygwin case

The Cygwin platform provides a full-featured Unix environment on
Windows.  CMake has recently been changed (at the request of Cygwin
developers) to emphasize the Unix aspects of the Cygwin platform and
deemphasize the Windows aspects of that platform.  It was argued this
change would tend to make CMake builds of software much more reliable
on Cygwin, and after some small but important changes to our
CMake-based build system to adjust for these recent CMake changes for
Cygwin, we have indeed confirmed that prediction for the PLplot case.
There are still some Cygwin platform issues left which are being
discussed on our Wiki at http://www.miscdebris.net/plplot_wiki/index.php?title=Setup_cygwin,
but some fundamental breakthroughs have also been made for the Cygwin case
that should interest all our Windows users.  For example, for the
first time ever we have been able to build our cairo and qt device
drivers on the Cygwin platform giving our Windows users convenient
access to the many high-quality PLplot devices that are available with
these two different device drivers.

1.5 The plcolorbar API has been finalized

The function plcolorbar allows users to create a color bar (an
annotated subplot representing a continuous range of colors within the
main plot and typically identifying certain colors with certain
numerical values using an axis).  The plcolorbar capabilities are
documented in our DocBook (and doxygen) documentation and demonstrated
in standard examples 16 and 33.

N.B. The previous two releases (5.9.8 and 5.9.9) contained
unadvertised experimental versions of plcolorbar.  Any PLplot user who
found and tried those capabilities will have to reprogramme their
plcolorbar calls to be compatible with the argument list of the latest
version.

1.6 Documentation of the new legend and color bar capabilities of PLplot

The pllegend and plcolorbar API has been documented in both doxygen
and DocBook forms.  In addition, the "advanced use" chapter of the
DocBook form of documentation now contains a section giving an
overview of pllegend and plcolorbar.

N.B. Although we feel the pllegend and plcolorbar API has now been
finalized with regard to the PLplot core developers own interests and
needs, we also realize that as more and more PLplot users take
advantage of these new PLplot capabilities there will likely be calls
to add additional features to pllegend or plcolorbar based on
additional experience with these powerful capabilities.  In general,
we would welcome such feature requests.

1.7 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)

This change should make PLplot much more relevant for D users
going forward.

See http://en.wikipedia.org/wiki/D_(programming_language)#History for
a discussion of the differences between these two variants of D.

1.8 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook

These modern backend tools (such as xmlto) replace the
deprecated/unmaintained SGML/DSSL tools we have used before.  For
developers this means generation of our DocBook generation is much
easier. much faster, and much less error-prone.  End users will notice
some improvements in the results (e.g., the table of Greek letters) as
well as some minor style changes.

1.9 Implement experimental build_projects sub-project

The idea here (see cmake/build_projects) is to automate the build of
all PLplot dependencies and the build and test of PLplot itself for
platforms (such as Linux enterprise distributions and all forms of
Windows platforms other than Cygwin) that do not come with modern
versions of PLplot soft dependencies such as Pango/Cairo and Qt.
This project is beginning to work properly for the Linux case, but
still needs lots of work for the Windows case.

1.10 Implement extremely simple "00" example

The point of this standard example is to give the users an extremely
simple tutorial example to help them to get started with 2D plotting
with PLplot.

1.11 Convert to using the Allura form of SourceForge software

We use sourceforge.net as our software hosting facility.  Early in
2013 Sourceforge updated essentially all their support software as
part of the so-called Allura project.  This made it necessary to make
some minor internal PLplot changes such as script changes and different URL's
in the website referring to SourceForge facilities.  The most important
change from the user perspective is the URL for the Allura form
of the svn repository that we use now:

http://svn.code.sf.net/p/plplot/code/trunk/

1.12 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems

The point of this change is to reduce overlinking and therefore
the problems caused by overlinking that are mentioned
at http://en.altlinux.org/UnderOverLinkProblems.

Non-transitive linking means link only to libraries that directly
resolve undefined symbols, i.e., do not link to a library just because
it is a dependency of a dependency.

1.13 Update f95 examples to take larger advantage of Fortran 95 capabilities

Previously our f95 examples tended to use legacy Fortran capabilities, but
that situation has substantially changed for this release.

1.14 Substantial additions to the doxygen documentation

One of the on-going documentation projects is to create doxygen
documentation of every single argument of the public API for PLplot.
A substantial increase in such documentation has been implemented
in this release cycle.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

N.B. This release includes many code cleanups and fixes relative to
5.8.0 that are not mentioned in the list below.

2.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialiased output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigorous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

2.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make Fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our color palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

2.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current color map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

2.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

2.39 Custom axis labelling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labelling geographic coordinates in degrees North, South, East and
West.

2.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

2.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbitrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t structure of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

2.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

2.42 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

2.43 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

2.44 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage

2.45 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).

2.46 The plstring and plstring3 functions have been added

The plstring function largely supersedes plpoin and plsym
because many(!) more glyphs are accessible with plstring.  The glyph
is specified with a PLplot user string.  As with plmtex and plptex,
the user string can contain FCI escapes to determine the font, UTF-8
code to determine the glyph or else PLplot escapes for Hershey or
unicode text to determine the glyph.  Standard examples 4 and 26 use
plstring.

The plstring3 function largely supersedes plpoin3 for the same (access
to many more glyphs) reasons.  Standard example 18 uses plstring3.

2.47 The pllegend API has been finalized

The function pllegend allows users to create a discrete plot legend
with a plotted colored box, line, and/or line of symbols for each
annotated legend entry.  The pllegend function was first made
available for 5.9.7. Due to feedback from early adopters of pllegend,
we have now added substantially to the pllegend capabilities. and we
now believe pllegend is ready for prime time.  The pllegend
capabilities are documented in our DocBook documentation and
demonstrated in standard examples 4, 26, and 33.

N.B. The current set of changes required a backwards-incompatible
change to the pllegend API.  This requires users who tried this new
functionality for 5.9.7 to reprogramme their pllegend calls.  Since
the pllegend API was labelled experimental for 5.9.7, we will not be
bumping the soversions of the affected PLplot libraries.

2.48 Octave bindings now implemented with swig

Octave is a powerful platform that demands a first-class PLplot
solution, but we were finding it difficult to realize that goal
because we were running up against limitations of the previous
matwrap-generated Octave bindings.  Accordingly, a swig-generated
version of the Octave bindings has now been implemented that builds on
the prior matwrapped bindings effort but also extends it with, e.g.,
bindings for plstring, plstring3, pllegend, and plcolorbar.  These new
octave bindings (which now completely replace the prior matwrapped
bindings) make it possible to run examples 4, 18, 26, and 33 (all of
which have now have been updated to use those functions) and get
consistent results with the corresponding C examples.

Like the matwrapped bindings before it, the new swig-generated octave
bindings currently do not have a number of the PLplot functions
wrapped (e.g., "plmap") that are needed by standard example 19.
However, because of the power of swig we now have some confidence we
can solve this issue in the future.

2.49 Documentation redone for our swig-generated Python and Octave bindings

Through the docstring %feature, swig can generate documentation
strings for certain of the languages it supports (currently Python,
Octave, and Ruby).  We have now removed all such hand-crafted swig
documentation data from bindings/swig-support/plplotcapi.i and
replaced it with generated documentation in the file
bindings/swig-support/swig_documentation.i.  That file is generated
from doc/docbook/src/api.xml using the perl script
doc/docbook/bin/api2swigdoc.pl.  The build system Unix target
"check_swig_documentation" now runs that script and compares results
with bindings/swig-support/swig_documentation.i in the source tree to
make sure that latter file is consistent with any changes that might
have occurred in doc/docbook/src/api.xml.

The resulting Octave and Python user-documentation (obtained by 'help
<PLplot_command_name>' in Octave and 'print ("%s" %
<PLplot_command_name>.__doc__)' in Python is much more detailed than
what was available before using the hand-crafted documentation.  If we
ever decided to generate PLplot bindings for Ruby with swig, this
high-quality user-documentation would be available for that language
as well.

2.50 Support large polygons

Previous releases had an implicit limitation with respect to the
number of vertices in a polygon. This was due to the use of statically
defined arrays (to avoid allocating and freeing memory for each polygon
to be drawn). José Luis García Pallero found this limitation and
provided patches to eliminate this limitation. The strategy is
that for small polygons, the original statically defined arrays
are used and for large polygons new arrays are allocated and freed.
This strategy has been applied to all relevant source files.

2.51 Complete set of PLplot parameters now available for Fortran

The #defines in bindings/swig-support/plplotcapi.i (which are
consistent with those in include/plplot.h) define the complete set of
important PLplot constants (whose names typically start with "PL_").
We have implemented automatic methods of transforming that complete
set of #defines into Fortran parameters that can be used from either
Fortran 77 or Fortran 95.

For Fortran 77, the user must insert an

      include 'plplot_parameters.h'

statement in every function/subroutine/main programme where he expects
to use PLplot constants (whose names typically start with "PL_".  (See
examples/f77/*.fm4 for examples of this method).  When compiling he
must also insert the appropriate -I option to find this file (in
bindings/f77/ in the source tree and currently in
$prefix/lib/fortran/include/plplot$version in the install tree
although that install location may be subject to change).  Note, the
above method does not interfere with existing apps which have
necessarily been forced to define the needed PLplot constants for
themselves.  But for future f77 use, the above statement is
more convenient and much less subject to error than a whole bunch of
parameter statements for the required constants.

For Fortran 95, the complete set of parameters are made available as
part of the plplot module.  So access to this complete set of
parameters is automatic wherever the "use plplot" statement is used.
This is extremely convenient for new Fortran 95 apps that use PLplot,
but, in general, changes will have to be made for existing apps. (See
announcement XX above for the details).

2.52 The plarc function has been added

The plarc function allows drawing filled and outlined arcs in PLplot.
Standard example 3 uses plarc.

2.53 The format for map data used by plmap has changed

The format for map data used by plmap is now the shapefile format.
This is a widely used standard format and there are many sources of data
in this format. This replaces the custom binary format that PLplot used
to use. The support for reading shapefiles is provided by the shapelib
library, which is a new dependency for PLplot. If users do not have this
installed then, by default, they will not get any map capabilities with
PLplot. Support for the old format can still be enabled by setting the
PL_DEPRECATED cmake variable, but this support will be removed in a
subsequent PLplot release.

2.54 Python support for Numeric has been dropped

Support for the python Numeric package has been dropped. This has been
deprecated since 5.9.6. Numeric is no longer supported and is superseded
by numpy. Support for numpy has been the default in plplot for a number
of years so most users should notice no difference.

2.55 Backwards-incompatible API change to non-integer line widths

All functions which take line width arguments (plwidth, plshade*,
pllegend) now use PLFLT values for the line width. This allows device
drivers which are based on modern graphics libraries such as Qt4 and
pango/cairo to make full use (e.g., extremely fine line widths) of the
floating-point line width capabilities of those libraries.  The
replacement of plwid by plwidth, and the change in argument lists for
plshade* and pllegend constitute a backwards incompatible API change
from previous releases and the soname of libraries has been bumped
accordingly (which forces users to recompile PLplot).

2.56 Improvements to the build system for the Cygwin case

The Cygwin platform provides a full-featured Unix environment on
Windows.  CMake has recently been changed (at the request of Cygwin
developers) to emphasize the Unix aspects of the Cygwin platform and
deemphasize the Windows aspects of that platform.  It was argued this
change would tend to make CMake builds of software much more reliable
on Cygwin, and after some small but important changes to our
CMake-based build system to adjust for these recent CMake changes for
Cygwin, we have indeed confirmed that prediction for the PLplot case.
There are still some Cygwin platform issues left which are being
discussed on our Wiki at http://www.miscdebris.net/plplot_wiki/index.php?title=Setup_cygwin,
but some fundamental breakthroughs have also been made for the Cygwin case
that should interest all our Windows users.  For example, for the
first time ever we have been able to build our cairo and qt device
drivers on the Cygwin platform giving our Windows users convenient
access to the many high-quality PLplot devices that are available with
these two different device drivers.

2.57 The plcolorbar API has been finalized

The function plcolorbar allows users to create a color bar (an
annotated subplot representing a continuous range of colors within the
main plot and typically identifying certain colors with certain
numerical values using an axis).  The plcolorbar capabilities are
documented in our DocBook (and doxygen) documentation and demonstrated
in standard examples 16 and 33.

N.B. The previous two releases (5.9.8 and 5.9.9) contained
unadvertised experimental versions of plcolorbar.  Any PLplot user who
found and tried those capabilities will have to reprogramme their
plcolorbar calls to be compatible with the argument list of the latest
version.

2.58 Documentation of the new legend and color bar capabilities of PLplot

The pllegend and plcolorbar API has been documented in both doxygen
and DocBook forms.  In addition, the "advanced use" chapter of the
DocBook form of documentation now contains a section giving an
overview of pllegend and plcolorbar.

N.B. Although we feel the pllegend and plcolorbar API has now been
finalized with regard to the PLplot core developers own interests and
needs, we also realize that as more and more PLplot users take
advantage of these new PLplot capabilities there will likely be calls
to add additional features to pllegend or plcolorbar based on
additional experience with these powerful capabilities.  In general,
we would welcome such feature requests.

2.59 The D bindings and examples have been converted from the
old version of D (D1) to the new version of D (D2)

This change should make PLplot much more relevant for D users
going forward.

See http://en.wikipedia.org/wiki/D_(programming_language)#History for
a discussion of the differences between these two variants of D.

2.60 The DocBook documentation for PLplot is now generated using modern
XML/XSL backend tools for DocBook

These modern backend tools (such as xmlto) replace the
deprecated/unmaintained SGML/DSSL tools we have used before.  For
developers this means generation of our DocBook generation is much
easier. much faster, and much less error-prone.  End users will notice
some improvements in the results (e.g., the table of Greek letters) as
well as some minor style changes.

2.61 Implement experimental build_projects sub-project

The idea here (see cmake/build_projects) is to automate the build of
all PLplot dependencies and the build and test of PLplot itself for
platforms (such as Linux enterprise distributions and all forms of
Windows platforms other than Cygwin) that do not come with modern
versions of PLplot soft dependencies such as Pango/Cairo and Qt.
This project is beginning to work properly for the Linux case, but
still needs lots of work for the Windows case.

2.62 Implement extremely simple "00" example

The point of this standard example is to give the users an extremely
simple tutorial example to help them to get started with 2D plotting
with PLplot.

2.63 Convert to using the Allura form of SourceForge software

We use sourceforge.net as our software hosting facility.  Early in
2013 Sourceforge updated essentially all their support software as
part of the so-called Allura project.  This made it necessary to make
some minor internal PLplot changes such as script changes and different URL's
in the website referring to SourceForge facilities.  The most important
change from the user perspective is the URL for the Allura form
of the svn repository that we use now:

http://svn.code.sf.net/p/plplot/code/trunk/

2.64 Use NON_TRANSITIVE linking by default for the shared libraries case for
all non-windows systems

The point of this change is to reduce overlinking and therefore
the problems caused by overlinking that are mentioned
at http://en.altlinux.org/UnderOverLinkProblems.

Non-transitive linking means link only to libraries that directly
resolve undefined symbols, i.e., do not link to a library just because
it is a dependency of a dependency.

2.65 Update f95 examples to take larger advantage of Fortran 95 capabilities

Previously our f95 examples tended to use legacy Fortran capabilities, but
that situation has substantially changed for this release.

2.66 Substantial additions to the doxygen documentation

One of the on-going documentation projects is to create doxygen
documentation of every single argument of the public API for PLplot.
A substantial increase in such documentation has been implemented
in this release cycle.


PLplot Release 5.9.9
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

     If you encounter a problem that is not already documented in the
PROBLEMS file or on our bugtracker, then please send bug reports to PLplot
developers via the mailing lists at
http://sourceforge.net/mail/?group_id=2915 (preferred) or on our bugtracker
at http://sourceforge.net/tracker/?group_id=2915&atid=102915.

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

INDEX

OFFICIAL NOTICES FOR USERS

CHANGES

-1. Important changes we should have mentioned in previous release announcements.

-1.1 Add full bindings and examples for the D language.

0. Tests made for release 5.9.9

1. Changes relative to PLplot 5.9.8 (the previous development release)

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
2.36 Make PLplot aware of LC_NUMERIC locale
2.37 Linear gradients have been implemented
2.38 Cairo Windows driver implemented
2.39 Custom axis labeling implemented
2.40 Universal coordinate transform implemented
2.41 Support for arbitrary storage of 2D user data
2.42 Font improvements
2.42 Alpha value support for plotting in memory.
2.43 Add a Qt device for in memory plotting.
2.44 Add discrete legend capability.
2.45 Add full bindings and examples for the D language.
2.46 The plstring and plstring3 functions have been added
2.47 The pllegend API has been finalized
2.48 Octave bindings now implemented with swig
2.49 Documentation redone for our swig-generated Python and Octave bindings
2.50 Support large polygons
2.51 Complete set of PLplot parameters now available for Fortran
2.52 The plarc function has been added

OFFICIAL NOTICES FOR USERS

(5.9.9) This is a quick release to deal with two broken build issues
that were recently discovered for our Windows platform.  Windows users should
avoid 5.9.8 because of these problems for that release, and instead use
5.9.9 which has been heavily tested on a number of platforms including
Windows, see "Tests made for release 5.9.9" below.

(5.9.8) For unicode-aware devices we now follow what is done for the
Hershey font case for epsilon, theta, and phi.  This means the #ge,
#gh, and #gf escapes now give users the Greek lunate epsilon, the
ordinary Greek lower case theta, and the Greek symbol phi for Unicode
fonts just like has occurred since the dawn of PLplot history for the
Hershey font case.  Previously these legacy escapes were assigned to
ordinary Greek lower-case epsilon, the Greek symbol theta (= script
theta), and the ordinary Greek lower case phi for unicode fonts
inconsistently with what occurred for Hershey fonts.  This change gets
rid of this inconsistency, that is the #g escapes should give the best
unicode approximation to the Hershey glyph result that is possible for
unicode-aware devices.

In general we encourage users of unicode-aware devices who might
dislike the Greek glyph Hershey-lookalike choices they get with the
legacy #g escapes to use instead either PLplot unicode escapes (e.g.,
"#[0x03b5]" for ordinary Greek lower-case epsilon, see page 3 of
example 23) or better yet, UTF-8 strings (e.g., "ε") to specify
exactly what unicode glyph they want.

(5.9.8) The full set of PLplot constants have been made available to
our Fortran 95 users as part of the plplot module.  This means those
users will have to remove any parameter statements where they have
previously defined the PLplot constants (whose names typically start
with "PL_" for themselves.  For a complete list of the affected
constants, see the #defines in swig-support/plplotcapi.i which are
used internally to help generate the plplot module.  See also Index
item 2.51 below.

(5.9.8) There has been widespread const modifier changes in the API
for libplplotd and libplplotcxxd.  Those backwards-incompatible API
changes are indicated in the usual way by a soversion bump in those
two libraries which will force all apps and libraries that depend on
those two libraries to be rebuilt.

Specifically, we have changed the following arguments in the C library
(libplplotd) case

type * name1 ==> const type * name1
type * name2 ==> const type ** name2

and the following arguments in the C++ library (libplplotcxxd) case

type * name1 ==> const type * name1
type * name1 ==> const type * const * name2

where name1 is the name of a singly dimensioned array whose values are
not changed internally by the PLplot libraries and name2 is the name
of a doubly dimensioned array whose values are not changed internally
by the PLplot libraries.

The general documentation and safety justification for such const
modifier changes to our API is given in
http://www.cprogramming.com/tutorial/const_correctness.html.
Essentially, the above const modifier changes constitute our guarantee
that the associated arrays are not changed internally by the PLplot
libraries.

Although it is necessary to rebuild all apps and libraries that depend
on libplplotd and/or libplplotcxxd, that rebuild should be possible
with unchanged source code without build errors in all cases.  For C
apps and libraries (depending on libplplotd) there will be additional
build warnings due to a limitation in the C standard discussed at
http://c-faq.com/ansi/constmismatch.html unless all doubly dimensioned
arrays (but not singly dimensioned) are explicitly cast to (const type
**).  However, such source code changes will not be necessary to avoid
warning messages for the C++ (libplplotcxxd) change because of the
double use of const in the above "const type * const * name2" change.

(5.9.8) The plarc API has changed in release 5.9.8.  The plarc API now
has a rotation parameter which will eventually allow for rotated arcs.
PLplot does not currently support rotated arcs, but the plarc function
signature has been modified to avoid changing the API when this
functionality is added.

(5.9.6) We have retired the pbm driver containing the pbm (actually
portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey
font fallback), falls back to ugly software fills, doesn't support
alpha transparency, etc.  It also has a serious run-time issue with
example 2 (double free detected by glibc) which probably indicates
some fundamental issue with the 100 colours in cmap0 for that
example. For those who really need portable pixmap results, we suggest
using the ImageMagick convert programme, e.g., "convert
examples/x24c01.pngqt test.ppm" or "convert examples/x24c01.pngcairo
test.ppm" to produce good-looking portable pixmap results from our
best png device results.

(5.9.6) We have retired the linuxvga driver containing the linuxvga
interactive device.  This device is quite primitive, difficult to
test, and poorly maintained. It ignores unicode fonts (i.e., uses the
Hershey font fallback), falls back to ugly software fills, doesn't
support alpha transparency, etc.  It is Linux only, can only be run as
root, and svgalib (the library used by linuxsvga) is not supported by
some mainstream (e.g., Intel) chipsets.  All of these characteristics
make it difficult to even test this device much less use it for
anything serious.  Finally, it has had a well-known issue for years
(incorrect colours) which has never been fixed indicating nobody is
interested in maintaining this device.

(5.9.6) We have retired our platform support of djgpp that used to
reside in sys/dos/djgpp.  The developer (Andrew Roach) who used to
maintain those support files for djgpp feels that the djgpp platform
is no longer actively developed, and he no longer uses djgpp himself.

(5.9.6) We have changed plpoin results for ascii codes 92, 94, and 95
from centred dot, degree symbol, and centred dot glyphs to the correct
backslash, caret, and underscore glyphs that are associated with those
ascii indices.  This change is consistent with the documentation of
plpoin and solves a long-standing issue with backslash, caret, and
underscore ascii characters in character strings used for example by
pl[mp]tex.  Those who need access to a centred dot with plpoin should
use index 1.  The degree symbol is no longer accessible with plpoin,
but it is available in ordinary text input to PLplot as Hershey escape
"#(718)", where 718 is the Hershey index of the degree symbol, unicode
escape "#[0x00B0]" where 0x00B0 is the unicode index for the degree
symbol or direct UTF8 unicode string "°".

(5.9.6) We have retired the gcw device driver and the related gnome2
and pygcw bindings since these are unmaintained and there are good
replacements.  These components of PLplot were deprecated as of
release 5.9.3.  A good replacement for the gcw device is either the
xcairo or qtwidget device.  A good replacement for the gnome2 bindings
is the externally supplied XDrawable or Cairo context associated with
the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

(5.9.6) We have deprecated support for the python Numeric array
extensions. Numeric is no longer maintained and users of Numeric are
advised to migrate to numpy. Numpy has been the standard for PLplot
for some time. If numpy is not present PLplot will now disable python
by default. If you still require Numeric support in the short term
then set USE_NUMERIC to ON in cmake. The PLplot support for Numeric
will be dropped in a future release.

(5.9.5) We have removed pyqt3 access to PLplot and replaced it by
pyqt4 access to PLplot (see details below).

(5.9.5) The only method of specifying a non-default compiler (and
associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and
associated compiler options will not be supported until CMake bug 9220
is fixed, see discussion below of the soft-landing re-implementation
for details.

(5.9.5) We have retired the hpgl driver (containing the hp7470,
hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and
the tek driver (containing the conex, mskermit, tek4107, tek4107f,
tek4010, tek4010f, versaterm, vlt, and xterm devices).  Retirement
means we have removed the build options which would allow these
devices to build and install.  Recent tests have shown a number of
run-time issues (hpgl, impress, and ljii) or build-time issues (tek)
with these devices, and as far as we know there is no more user
interest in them. Therefore, we have decided to retire these devices
rather than fix them.

(5.9.4) We have deprecated the pbm device driver (containing the pbm
device) because glibc detects a catastrophic double free.

(5.9.3) Our build system requires CMake version 2.6.0 or higher.

(5.9.3) We have deprecated the gcw device driver and the related
gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on
the plfreetype approach for accessing unicode fonts which has known
issues (inconsistent text offsets, inconvenient font setting
capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally
supplied XDrawable or Cairo context associated with the xcairo device
and the extcairo device (see examples/c/README.cairo) instead. If you
still absolutely must use -dev gcw or the related gnome2 or pygcw
bindings despite the known problems, then they can still be accessed
by setting PLD_gcw, ENABLE_gnome2, and/or ENABLE_pygcw to ON.

(5.9.3) We have deprecated the gd device driver which implements the
png, jpeg, and gif devices.  This device driver is essentially
unmaintained. For example, it still depends on the plfreetype approach
for accessing unicode fonts which has known issues (inconsistent text
offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for
the JPEG format, we advise using the jpgqt device.  PNG is normally
considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and
then downgrading the results to the GIF format using the ImageMagick
"convert" application.  For those platforms where libgd (the
dependency of the gd device driver) is accessible while the required
dependencies of the cairo and/or qt devices are not accessible, you
can still use these deprecated devices by setting PLD_png, PLD_jpeg,
or PLD_gif to ON.

(5.9.3) We have re-enabled the tk, itk, and itcl components of PLplot
by default that were disabled by default as of release 5.9.1 due to
segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of
PLplot.

(5.9.2) We have set HAVE_PTHREAD (now called PL_HAVE_PTHREAD as of
release 5.9.8) to ON by default for all platforms other than Darwin.
Darwin will follow later once it appears the Apple version of X
supports it.

(5.9.1) We have removed our previously deprecated autotools-based
build system.  Instead, use the CMake-based build system following the
directions in the INSTALL file.

(5.9.1) We no longer support Octave-2.1.73 which has a variety of
run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results
with all our Octave examples for Octave-3.0.1. Also, that is the
recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only
version of Octave we support at this time.

(5.9.1) We have decided for consistency sake to change the PLplot
stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact
window limit values input by users using plwind. Previously to this
change, the stream variables and the values returned by plgvpw
reflected the internal slightly expanded range of window limits used
by PLplot so that the user's specified limits would be on the graph.
Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the
expanded ranges so most users results will be identical.  However, you
may notice some small changes to your plot results if you use these
stream variables directly (only possible in C/C++) or use plgvpw.

CHANGES

-1. Important changes we should have mentioned in previous release announcements.

-1.1 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).


0. Tests made for release 5.9.9

* (Alan W. Irwin) The scripts/comprehensive_test.sh script was run for
  a fully loaded (all Linux bindings other than PDL, all Linux device
  drivers including our qt and cairo device drivers) Debian Squeeze
  Linux platform with no obvious build-time or run-time issues being
  found.  This script runs 7 major tests for each of our three
  principal build configurations (shared library/dynamic device
  drivers, shared libraries/nondynamic device drivers, static
  libraries/nondynamic device drivers). Those 7 tests are ctest and
  the test_noninteractive and test_interactive targets in the build
  tree, the test_noninteractive and test_interactive targets
  configured with CMake in the installed examples tree, and the
  traditional (MakeFile + pkg-config) test_noninteractive and
  test_interactive targets in the installed examples tree.

  These tests were done with OCaml disabled because of a segfault and
  a series of bad valgrind test results that occurred for OCaml
  3.11.2.  We have tentatively ascribed this issue to issues with the
  OCaml stack on that platform since this bad OCaml result contrasts
  with good OCaml results on other reported platforms.

  In addition to the scripts/comprehensive_test.sh result,
  comprehensive valgrind results were clean for all C examples for
  both -dev psc and -dev epsqt for the build-tree/shared
  library/dynamic device drivers case.  The first result verifies
  there are no core memory management issues for our C library and C
  examples for one of our simpler devices that has no external
  dependencies.  The second result shows in addition that there are no
  memory management issues for our epsqt device and the part of the
  Qt4 version 4.6.3 stack that it uses on this platform.

* (Andrew Ross) For one Ubuntu platform the test_noninteractive and
  test_interactive targets for the shared libraries and dynamic
  drivers case gave good results.  This was for a fully loaded
  platform including our qt and cairo device drivers.

* (Hezekiah M. Carty) scripts/comprehensive_test.sh failed on a Ubuntu
  Linux platform because of segfaults in the qt devices.  We
  have tentatively ascribed this issue to issues with the Qt4 stack of
  libraries on that platform since this bad qt result contrasts with
  the good qt result on the previous two Linux platforms.  When qt devices
  were ignored, clean valgrind results were obtained for OCaml-3.12.1 and
  OCaml-3.11.2 (in contrast to the results seen for OCaml-3.11.2 above).
  Testing with the comprehensive_test.sh script and qt devices disabled
  completed with good results.

* (Arjen Markus) MinGW/MSYS installed on a lightly loaded (at least
  compared to Linux tests) Windows XP system gives good results for
  the test_noninteractive target in the build tree for the shared
  library/dynamic device drivers case.

* (Arjen Markus) The combination of Microsoft Visual C/C++ version 9.0
  and Intel Fortran compilers installed on a lightly loaded Windows XP
  system gives good results for the "all" target for the shared
  library/dynamic device drivers case.  That target just builds the
  software.  In addition, some run-time testing was done by hand with
  no sign of any run-time trouble.

* (Jerry Bauck) Mac OS X 10.6.8 (Snow Leopard) platform with Ada
  bindings and good coverage of devices (e.g., qt and cairo) but
  lightly loaded with regard to non-Ada bindings give fairly good
  results for ctest and the test_noninteractive target for the shared
  library/dynamic device drivers case.  All tests passed including qt
  and cairo device driver tests, but when looking at detailed results
  some missing circular symbol issues were discovered for the pscairo
  results.  We don't understand this issue because the cairo devices
  give both superb and reliable results on our Linux platforms.  The
  cairo device driver depends on a subset (e.g., pango and cairo) of
  the GTK+ stack of libraries.  These results were obtained for GTK+
  version 2.18.5.

* (Werner Smekal) Mac OS X 10.7.1, XCode 4.1 platform that is lightly
  loaded (e.g., GTK+ but no Qt4) gave mixed results for ctest and the
  test_noninteractive target for the shared library/dynamic device
  drivers case.  The build worked without issues, and also everything
  but cairo devices at run time.  However, all cairo device results
  had major run-time errors (e.g., segfaults).  In this case the GTK+
  library was newer than we have tested before (version 2.24 from the
  Homebrew packaging effort as compared to 2.21 that gives such good
  results on Linux) so there may be a mismatch between our cairo
  device driver and this newer version of GTK+ that needs to be sorted
  out.

1. Changes relative to PLplot 5.9.8 (the previous development release)

No notable new features.  This is a bug fix release.  See the above
announcements.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

2.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make Fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our colour palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

2.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current colour map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

2.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

2.39 Custom axis labeling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labeling geographic coordinates in degrees North, South, East and
West.

2.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

2.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbitrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t structure of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

2.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

2.42 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

2.43 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

2.44 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage


2.45 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).

2.46 The plstring and plstring3 functions have been added

The plstring function largely supersedes plpoin and plsym
because many(!) more glyphs are accessible with plstring.  The glyph
is specified with a PLplot user string.  As with plmtex and plptex,
the user string can contain FCI escapes to determine the font, UTF-8
code to determine the glyph or else PLplot escapes for Hershey or
unicode text to determine the glyph.  Standard examples 4 and 26 use
plstring.

The plstring3 function largely supersedes plpoin3 for the same (access
to many more glyphs) reasons.  Standard example 18 uses plstring3.

2.47 The pllegend API has been finalized

The function pllegend allows users to create a discrete plot legend
with a plotted colored box, line, and/or line of symbols for each
annotated legend entry.  The pllegend function was first made
available for 5.9.7. Due to feedback from early adopters of pllegend,
we have now added substantially to the pllegend capabilities. and we
now believe pllegend is ready for prime time.  The pllegend
capabilities are documented in our DocBook documentation and
demonstrated in standard examples 4, 26, and 33.

N.B. The current set of changes required a backwards-incompatible
change to the pllegend API.  This requires users who tried this new
functionality for 5.9.7 to reprogramme their pllegend calls.  Since
the pllegend API was labelled experimental for 5.9.7, we will not be
bumping the soversions of the affected PLplot libraries.

2.48 Octave bindings now implemented with swig

Octave is a powerful platform that demands a first-class PLplot
solution, but we were finding it difficult to realize that goal
because we were running up against limitations of the previous
matwrap-generated Octave bindings.  Accordingly, a swig-generated
version of the Octave bindings has now been implemented that builds on
the prior matwrapped bindings effort but also extends it with, e.g.,
bindings for plstring, plstring3, pllegend, and plcolorbar.  These new
octave bindings (which now completely replace the prior matwrapped
bindings) make it possible to run examples 4, 18, 26, and 33 (all of
which have now have been updated to use those functions) and get
consistent results with the corresponding C examples.

Like the matwrapped bindings before it, the new swig-generated octave
bindings currently do not have a number of the PLplot functions
wrapped (e.g., "plmap") that are needed by standard example 19.
However, because of the power of swig we now have some confidence we
can solve this issue in the future.

2.49 Documentation redone for our swig-generated Python and Octave bindings

Through the docstring %feature, swig can generate documentation
strings for certain of the languages it supports (currently Python,
Octave, and Ruby).  We have now removed all such hand-crafted swig
documentation data from bindings/swig-support/plplotcapi.i and
replaced it with generated documentation in the file
bindings/swig-support/swig_documentation.i.  That file is generated
from doc/docbook/src/api.xml using the perl script
doc/docbook/bin/api2swigdoc.pl.  The build system Unix target
"check_swig_documentation" now runs that script and compares results
with bindings/swig-support/swig_documentation.i in the source tree to
make sure that latter file is consistent with any changes that might
have occurred in doc/docbook/src/api.xml.

The resulting Octave and Python user-documentation (obtained by 'help
<PLplot_command_name>' in Octave and 'print ("%s" %
<PLplot_command_name>.__doc__)' in Python is much more detailed than
what was available before using the hand-crafted documentation.  If we
ever decided to generate PLplot bindings for Ruby with swig, this
high-quality user-documentation would be available for that language
as well.

2.50 Support large polygons

Previous releases had an implicit limitation with respect to the
number of vertices in a polygon. This was due to the use of statically
defined arrays (to avoid allocating and freeing memory for each polygon
to be drawn). Jos Luis Garca Pallero found this limitation and
provided patches to eliminate this limitation. The strategy is
that for small polygons, the original statically defined arrays
are used and for large polygons new arrays are allocated and freed.
This strategy has been applied to all relevant source files.

2.51 Complete set of PLplot parameters now available for Fortran

The #defines in bindings/swig-support/plplotcapi.i (which are
consistent with those in include/plplot.h) define the complete set of
important PLplot constants (whose names typically start with "PL_").
We have implemented automatic methods of transforming that complete
set of #defines into Fortran parameters that can be used from either
Fortran 77 or Fortran 95.

For Fortran 77, the user must insert an

      include 'plplot_parameters.h'

statement in every function/subroutine/main programme where he expects
to use PLplot constants (whose names typically start with "PL_".  (See
examples/f77/*.fm4 for examples of this method).  When compiling he
must also insert the appropriate -I option to find this file (in
bindings/f77/ in the source tree and currently in
$prefix/lib/fortran/include/plplot$version in the install tree
although that install location may be subject to change).  Note, the
above method does not interfere with existing apps which have
necessarily been forced to define the needed PLplot constants for
themselves.  But for future f77 use, the above statement is
more convenient and much less subject to error than a whole bunch of
parameter statements for the required constants.

For Fortran 95, the complete set of parameters are made available as
part of the plplot module.  So access to this complete set of
parameters is automatic wherever the "use plplot" statement is used.
This is extremely convenient for new Fortran 95 apps that use PLplot,
but, in general, changes will have to be made for existing apps. (See
announcement XX above for the details).

2.52 The plarc function has been added

The plarc function allows drawing filled and outlined arcs in PLplot.
Standard example 3 uses plarc.


PLplot Release 5.9.8
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

     If you encounter a problem that is not already documented in the
PROBLEMS file or on our bugtracker, then please send bug reports to PLplot
developers via the mailing lists at
http://sourceforge.net/mail/?group_id=2915 (preferred) or on our bugtracker
at http://sourceforge.net/tracker/?group_id=2915&atid=102915.

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

Official Notices for Users.

(5.9.8) For unicode-aware devices we now follow what is done for the
Hershey font case for epsilon, theta, and phi.  This means the #ge,
#gh, and #gf escapes now give users the Greek lunate epsilon, the
ordinary Greek lower case theta, and the Greek symbol phi for Unicode
fonts just like has occurred since the dawn of PLplot history for the
Hershey font case.  Previously these legacy escapes were assigned to
ordinary Greek lower-case epsilon, the Greek symbol theta (= script
theta), and the ordinary Greek lower case phi for unicode fonts
inconsistently with what occurred for Hershey fonts.  This change gets
rid of this inconsistency, that is the #g escapes should give the best
unicode approximation to the Hershey glyph result that is possible for
unicode-aware devices.

In general we encourage users of unicode-aware devices who might
dislike the Greek glyph Hershey-lookalike choices they get with the
legacy #g escapes to use instead either PLplot unicode escapes (e.g.,
"#[0x03b5]" for ordinary Greek lower-case epsilon, see page 3 of
example 23) or better yet, UTF-8 strings (e.g., "ε") to specify
exactly what unicode glyph they want.

(5.9.8) The full set of PLplot constants have been made available to
our Fortran 95 users as part of the plplot module.  This means those
users will have to remove any parameter statements where they have
previously defined the PLplot constants (whose names typically start
with "PL_" for themselves.  For a complete list of the affected
constants, see the #defines in swig-support/plplotcapi.i which are
used internally to help generate the plplot module.  See also Index
item 2.51 below.

(5.9.8) There has been widespread const modifier changes in the API
for libplplotd and libplplotcxxd.  Those backwards-incompatible API
changes are indicated in the usual way by a soversion bump in those
two libraries which will force all apps and libraries that depend on
those two libraries to be rebuilt.

Specifically, we have changed the following arguments in the C library
(libplplotd) case

type * name1 ==> const type * name1
type * name2 ==> const type ** name2

and the following arguments in the C++ library (libplplotcxxd) case

type * name1 ==> const type * name1
type * name1 ==> const type * const * name2

where name1 is the name of a singly dimensioned array whose values are
not changed internally by the PLplot libraries and name2 is the name
of a doubly dimensioned array whose values are not changed internally
by the PLplot libraries.

The general documentation and safety justification for such const
modifier changes to our API is given in
http://www.cprogramming.com/tutorial/const_correctness.html.
Essentially, the above const modifier changes constitute our guarantee
that the associated arrays are not changed internally by the PLplot
libraries.

Although it is necessary to rebuild all apps and libraries that depend
on libplplotd and/or libplplotcxxd, that rebuild should be possible
with unchanged source code without build errors in all cases.  For C
apps and libraries (depending on libplplotd) there will be additional
build warnings due to a limitation in the C standard discussed at
http://c-faq.com/ansi/constmismatch.html unless all doubly dimensioned
arrays (but not singly dimensioned) are explicitly cast to (const type
**).  However, such source code changes will not be necessary to avoid
warning messages for the C++ (libplplotcxxd) change because of the
double use of const in the above "const type * const * name2" change.

(5.9.8) The plarc API has changed in release 5.9.8.  The plarc API now
has a rotation parameter which will eventually allow for rotated arcs.
PLplot does not currently support rotated arcs, but the plarc function
signature has been modified to avoid changing the API when this
functionality is added.

(5.9.6) We have retired the pbm driver containing the pbm (actually
portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey
font fallback), falls back to ugly software fills, doesn't support
alpha transparency, etc.  It also has a serious run-time issue with
example 2 (double free detected by glibc) which probably indicates
some fundamental issue with the 100 colours in cmap0 for that
example. For those who really need portable pixmap results, we suggest
using the ImageMagick convert programme, e.g., "convert
examples/x24c01.pngqt test.ppm" or "convert examples/x24c01.pngcairo
test.ppm" to produce good-looking portable pixmap results from our
best png device results.

(5.9.6) We have retired the linuxvga driver containing the linuxvga
interactive device.  This device is quite primitive, difficult to
test, and poorly maintained. It ignores unicode fonts (i.e., uses the
Hershey font fallback), falls back to ugly software fills, doesn't
support alpha transparency, etc.  It is Linux only, can only be run as
root, and svgalib (the library used by linuxsvga) is not supported by
some mainstream (e.g., Intel) chipsets.  All of these characteristics
make it difficult to even test this device much less use it for
anything serious.  Finally, it has had a well-known issue for years
(incorrect colours) which has never been fixed indicating nobody is
interested in maintaining this device.

(5.9.6) We have retired our platform support of djgpp that used to
reside in sys/dos/djgpp.  The developer (Andrew Roach) who used to
maintain those support files for djgpp feels that the djgpp platform
is no longer actively developed, and he no longer uses djgpp himself.

(5.9.6) We have changed plpoin results for ascii codes 92, 94, and 95
from centred dot, degree symbol, and centred dot glyphs to the correct
backslash, caret, and underscore glyphs that are associated with those
ascii indices.  This change is consistent with the documentation of
plpoin and solves a long-standing issue with backslash, caret, and
underscore ascii characters in character strings used for example by
pl[mp]tex.  Those who need access to a centred dot with plpoin should
use index 1.  The degree symbol is no longer accessible with plpoin,
but it is available in ordinary text input to PLplot as Hershey escape
"#(718)", where 718 is the Hershey index of the degree symbol, unicode
escape "#[0x00B0]" where 0x00B0 is the unicode index for the degree
symbol or direct UTF8 unicode string "°".

(5.9.6) We have retired the gcw device driver and the related gnome2
and pygcw bindings since these are unmaintained and there are good
replacements.  These components of PLplot were deprecated as of
release 5.9.3.  A good replacement for the gcw device is either the
xcairo or qtwidget device.  A good replacement for the gnome2 bindings
is the externally supplied XDrawable or Cairo context associated with
the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

(5.9.6) We have deprecated support for the python Numeric array
extensions. Numeric is no longer maintained and users of Numeric are
advised to migrate to numpy. Numpy has been the standard for PLplot
for some time. If numpy is not present PLplot will now disable python
by default. If you still require Numeric support in the short term
then set USE_NUMERIC to ON in cmake. The PLplot support for Numeric
will be dropped in a future release.

(5.9.5) We have removed pyqt3 access to PLplot and replaced it by
pyqt4 access to PLplot (see details below).

(5.9.5) The only method of specifying a non-default compiler (and
associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and
associated compiler options will not be supported until CMake bug 9220
is fixed, see discussion below of the soft-landing re-implementation
for details.

(5.9.5) We have retired the hpgl driver (containing the hp7470,
hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and
the tek driver (containing the conex, mskermit, tek4107, tek4107f,
tek4010, tek4010f, versaterm, vlt, and xterm devices).  Retirement
means we have removed the build options which would allow these
devices to build and install.  Recent tests have shown a number of
run-time issues (hpgl, impress, and ljii) or build-time issues (tek)
with these devices, and as far as we know there is no more user
interest in them. Therefore, we have decided to retire these devices
rather than fix them.

(5.9.4) We have deprecated the pbm device driver (containing the pbm
device) because glibc detects a catastrophic double free.

(5.9.3) Our build system requires CMake version 2.6.0 or higher.

(5.9.3) We have deprecated the gcw device driver and the related
gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on
the plfreetype approach for accessing unicode fonts which has known
issues (inconsistent text offsets, inconvenient font setting
capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally
supplied XDrawable or Cairo context associated with the xcairo device
and the extcairo device (see examples/c/README.cairo) instead. If you
still absolutely must use -dev gcw or the related gnome2 or pygcw
bindings despite the known problems, then they can still be accessed
by setting PLD_gcw, ENABLE_gnome2, and/or ENABLE_pygcw to ON.

(5.9.3) We have deprecated the gd device driver which implements the
png, jpeg, and gif devices.  This device driver is essentially
unmaintained. For example, it still depends on the plfreetype approach
for accessing unicode fonts which has known issues (inconsistent text
offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for
the JPEG format, we advise using the jpgqt device.  PNG is normally
considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and
then downgrading the results to the GIF format using the ImageMagick
"convert" application.  For those platforms where libgd (the
dependency of the gd device driver) is accessible while the required
dependencies of the cairo and/or qt devices are not accessible, you
can still use these deprecated devices by setting PLD_png, PLD_jpeg,
or PLD_gif to ON.

(5.9.3) We have re-enabled the tk, itk, and itcl components of PLplot
by default that were disabled by default as of release 5.9.1 due to
segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of
PLplot.

(5.9.2) We have set HAVE_PTHREAD (now called PL_HAVE_PTHREAD as of
release 5.9.8) to ON by default for all platforms other than Darwin.
Darwin will follow later once it appears the Apple version of X
supports it.

(5.9.1) We have removed our previously deprecated autotools-based
build system.  Instead, use the CMake-based build system following the
directions in the INSTALL file.

(5.9.1) We no longer support Octave-2.1.73 which has a variety of
run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results
with all our Octave examples for Octave-3.0.1. Also, that is the
recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only
version of Octave we support at this time.

(5.9.1) We have decided for consistency sake to change the PLplot
stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact
window limit values input by users using plwind. Previously to this
change, the stream variables and the values returned by plgvpw
reflected the internal slightly expanded range of window limits used
by PLplot so that the user's specified limits would be on the graph.
Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the
expanded ranges so most users results will be identical.  However, you
may notice some small changes to your plot results if you use these
stream variables directly (only possible in C/C++) or use plgvpw.

INDEX

-1. Important changes we should have mentioned in previous release announcements.

-1.1 Add full bindings and examples for the D language.

0. Tests made for release 5.9.8

1. Changes relative to PLplot 5.9.7 (the previous development release)

1.1 The plstring and plstring3 functions have been added
1.2 The pllegend API has been finalized
1.3 Octave bindings now implemented with swig
1.4 Documentation redone for our swig-generated Python and Octave bindings
1.5 Support large polygons
1.6 Complete set of PLplot parameters now available for Fortran

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
2.36 Make PLplot aware of LC_NUMERIC locale
2.37 Linear gradients have been implemented
2.38 Cairo Windows driver implemented
2.39 Custom axis labeling implemented
2.40 Universal coordinate transform implemented
2.41 Support for arbitrary storage of 2D user data
2.42 Font improvements
2.42 Alpha value support for plotting in memory.
2.43 Add a Qt device for in memory plotting.
2.44 Add discrete legend capability.
2.45 Add full bindings and examples for the D language.
2.46 The plstring and plstring3 functions have been added
2.47 The pllegend API has been finalized
2.48 Octave bindings now implemented with swig
2.49 Documentation redone for our swig-generated Python and Octave bindings
2.50 Support large polygons
2.51 Complete set of PLplot parameters now available for Fortran
2.52 The plarc function has been added

-1. Important changes we should have mentioned in previous release announcements.

-1.1 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).


0. Tests made for release 5.9.8

See
http://www.miscdebris.net/plplot_wiki/index.php?title=Testing_PLplot#Testing_Reports
for a summary table of all testing done for PLplot-5.9.8.


1. Changes relative to PLplot 5.9.7 (the previous development release)

1.1 The plstring and plstring3 functions have been added

The plstring function largely supersedes plpoin and plsym
because many(!) more glyphs are accessible with plstring.  The glyph
is specified with a PLplot user string.  As with plmtex and plptex,
the user string can contain FCI escapes to determine the font, UTF-8
code to determine the glyph or else PLplot escapes for Hershey or
unicode text to determine the glyph.  Standard examples 4 and 26 use
plstring.

The plstring3 function largely supersedes plpoin3 for the same (access
to many more glyphs) reasons.  Standard example 18 uses plstring3.

1.2 The pllegend API has been finalized

The function pllegend allows users to create a discrete plot legend
with a plotted colored box, line, and/or line of symbols for each
annotated legend entry.  The pllegend function was first made
available for 5.9.7. Due to feedback from early adopters of pllegend,
we have now added substantially to the pllegend capabilities. and we
now believe pllegend is ready for prime time.  The pllegend
capabilities are documented in our docbook documentation and
demonstrated in standard examples 4, 26, and 33.

N.B. The current set of changes required a backwards-incompatible
change to the pllegend API.  This requires users who tried this new
functionality for 5.9.7 to reprogramme their pllegend calls.  Since
the pllegend API was labelled experimental for 5.9.7, we will not be
bumping the soversions of the affected PLplot libraries.

1.3 Octave bindings now implemented with swig

Octave is a powerful platform that demands a first-class PLplot
solution, but we were finding it difficult to realize that goal
because we were running up against limitations of the previous
matwrap-generated Octave bindings.  Accordingly, a swig-generated
version of the Octave bindings has now been implemented that builds on
the prior matwrapped bindings effort but also extends it with, e.g.,
bindings for plstring, plstring3, pllegend, and plcolorbar.  These new
octave bindings (which now completely replace the prior matwrapped
bindings) make it possible to run examples 4, 18, 26, and 33 (all of
which have now have been updated to use those functions) and get
consistent results with the corresponding C examples.

Like the matwrapped bindings before it, the new swig-generated octave
bindings currently do not have a number of the PLplot functions
wrapped (e.g., "plmap") that are needed by standard example 19.
However, because of the power of swig we now have some confidence we
can solve this issue in the future.

1.4 Documentation redone for our swig-generated Python and Octave bindings

Through the docstring %feature, swig can generate documentation
strings for certain of the languages it supports (currently Python,
Octave, and Ruby).  We have now removed all such hand-crafted swig
documentation data from bindings/swig-support/plplotcapi.i and
replaced it with generated documentation in the file
bindings/swig-support/swig_documentation.i.  That file is generated
from doc/docbook/src/api.xml using the perl script
doc/docbook/bin/api2swigdoc.pl.  The build system Unix target
"check_swig_documentation" now runs that script and compares results
with bindings/swig-support/swig_documentation.i in the source tree to
make sure that latter file is consistent with any changes that might
have occurred in doc/docbook/src/api.xml.

The resulting Octave and Python user-documentation (obtained by 'help
<PLplot_command_name>' in Octave and 'print ("%s" %
<PLplot_command_name>.__doc__)' in Python is much more detailed than
what was available before using the hand-crafted documentation.  If we
ever decided to generate PLplot bindings for Ruby with swig, this
high-quality user-documentation would be available for that language
as well.

1.5 Support large polygons

Previous releases had an implicit limitation with respect to the
number of vertices in a polygon. This was due to the use of statically
defined arrays (to avoid allocating and freeing memory for each polygon
to be drawn). Jos Luis Garca Pallero found this limitation and
provided patches to eliminate this limitation. The strategy is
that for small polygons, the original statically defined arrays
are used and for large polygons new arrays are allocated and freed.
This strategy has been applied to all relevant source files.

1.6 Complete set of PLplot parameters now available for Fortran

The #defines in bindings/swig-support/plplotcapi.i (which are
consistent with those in include/plplot.h) define the complete set of
important PLplot constants (whose names typically start with "PL_").
We have implemented automatic methods of transforming that complete
set of #defines into Fortran parameters that can be used from either
Fortran 77 or Fortran 95.

For Fortran 77, the user must insert an

      include 'plplot_parameters.h'

statement in every function/subroutine/main programme where he expects
to use PLplot constants (whose names typically start with "PL_".  (See
examples/f77/*.fm4 for examples of this method).  When compiling he
must also insert the appropriate -I option to find this file (in
bindings/f77/ in the source tree and currently in
$prefix/lib/fortran/include/plplot$version in the install tree
although that install location may be subject to change).  Note, the
above method does not interfere with existing apps which have
necessarily been forced to define the needed PLplot constants for
themselves.  But for future f77 use, the above statement is
more convenient and much less subject to error than a whole bunch of
parameter statements for the required constants.

For Fortran 95, the complete set of parameters are made available as
part of the plplot module.  So access to this complete set of
parameters is automatic wherever the "use plplot" statement is used.
This is extremely convenient for new Fortran 95 apps that use PLplot,
but, in general, changes will have to be made for existing apps. (See
announcement XX above for the details).

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

2.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our colour palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

2.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current colour map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

2.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

2.39 Custom axis labeling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labeling geographic coordinates in degrees North, South, East and
West.

2.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

2.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbtrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t stucture of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

2.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

2.42 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

2.43 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

2.44 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage


2.45 Add full bindings and examples for the D language.

As of release 5.9.5 we added full bindings and examples for the D
language.  The results for the D examples are generally consistent
with the corresponding C examples which helps to verify the D
bindings.

Since the release of 5.9.5 it has come to our attention that the
version of gdc supplied with several recent versions of Ubuntu has a
very serious bug on 64-bit systems (see
https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955) which
causes several of the plplot D examples to crash. If this affects you,
you are recommended to disable the d bindings or switch to an
alternative d compiler (the Digital Mars compiler is reported to be
good).

2.46 The plstring and plstring3 functions have been added

The plstring function largely supersedes plpoin and plsym
because many(!) more glyphs are accessible with plstring.  The glyph
is specified with a PLplot user string.  As with plmtex and plptex,
the user string can contain FCI escapes to determine the font, UTF-8
code to determine the glyph or else PLplot escapes for Hershey or
unicode text to determine the glyph.  Standard examples 4 and 26 use
plstring.

The plstring3 function largely supersedes plpoin3 for the same (access
to many more glyphs) reasons.  Standard example 18 uses plstring3.

2.47 The pllegend API has been finalized

The function pllegend allows users to create a discrete plot legend
with a plotted colored box, line, and/or line of symbols for each
annotated legend entry.  The pllegend function was first made
available for 5.9.7. Due to feedback from early adopters of pllegend,
we have now added substantially to the pllegend capabilities. and we
now believe pllegend is ready for prime time.  The pllegend
capabilities are documented in our docbook documentation and
demonstrated in standard examples 4, 26, and 33.

N.B. The current set of changes required a backwards-incompatible
change to the pllegend API.  This requires users who tried this new
functionality for 5.9.7 to reprogramme their pllegend calls.  Since
the pllegend API was labelled experimental for 5.9.7, we will not be
bumping the soversions of the affected PLplot libraries.

2.48 Octave bindings now implemented with swig

Octave is a powerful platform that demands a first-class PLplot
solution, but we were finding it difficult to realize that goal
because we were running up against limitations of the previous
matwrap-generated Octave bindings.  Accordingly, a swig-generated
version of the Octave bindings has now been implemented that builds on
the prior matwrapped bindings effort but also extends it with, e.g.,
bindings for plstring, plstring3, pllegend, and plcolorbar.  These new
octave bindings (which now completely replace the prior matwrapped
bindings) make it possible to run examples 4, 18, 26, and 33 (all of
which have now have been updated to use those functions) and get
consistent results with the corresponding C examples.

Like the matwrapped bindings before it, the new swig-generated octave
bindings currently do not have a number of the PLplot functions
wrapped (e.g., "plmap") that are needed by standard example 19.
However, because of the power of swig we now have some confidence we
can solve this issue in the future.

2.49 Documentation redone for our swig-generated Python and Octave bindings

Through the docstring %feature, swig can generate documentation
strings for certain of the languages it supports (currently Python,
Octave, and Ruby).  We have now removed all such hand-crafted swig
documentation data from bindings/swig-support/plplotcapi.i and
replaced it with generated documentation in the file
bindings/swig-support/swig_documentation.i.  That file is generated
from doc/docbook/src/api.xml using the perl script
doc/docbook/bin/api2swigdoc.pl.  The build system Unix target
"check_swig_documentation" now runs that script and compares results
with bindings/swig-support/swig_documentation.i in the source tree to
make sure that latter file is consistent with any changes that might
have occurred in doc/docbook/src/api.xml.

The resulting Octave and Python user-documentation (obtained by 'help
<PLplot_command_name>' in Octave and 'print ("%s" %
<PLplot_command_name>.__doc__)' in Python is much more detailed than
what was available before using the hand-crafted documentation.  If we
ever decided to generate PLplot bindings for Ruby with swig, this
high-quality user-documentation would be available for that language
as well.

2.50 Support large polygons

Previous releases had an implicit limitation with respect to the
number of vertices in a polygon. This was due to the use of statically
defined arrays (to avoid allocating and freeing memory for each polygon
to be drawn). Jos Luis Garca Pallero found this limitation and
provided patches to eliminate this limitation. The strategy is
that for small polygons, the original statically defined arrays
are used and for large polygons new arrays are allocated and freed.
This strategy has been applied to all relevant source files.

2.51 Complete set of PLplot parameters now available for Fortran

The #defines in bindings/swig-support/plplotcapi.i (which are
consistent with those in include/plplot.h) define the complete set of
important PLplot constants (whose names typically start with "PL_").
We have implemented automatic methods of transforming that complete
set of #defines into Fortran parameters that can be used from either
Fortran 77 or Fortran 95.

For Fortran 77, the user must insert an

      include 'plplot_parameters.h'

statement in every function/subroutine/main programme where he expects
to use PLplot constants (whose names typically start with "PL_".  (See
examples/f77/*.fm4 for examples of this method).  When compiling he
must also insert the appropriate -I option to find this file (in
bindings/f77/ in the source tree and currently in
$prefix/lib/fortran/include/plplot$version in the install tree
although that install location may be subject to change).  Note, the
above method does not interfere with existing apps which have
necessarily been forced to define the needed PLplot constants for
themselves.  But for future f77 use, the above statement is
more convenient and much less subject to error than a whole bunch of
parameter statements for the required constants.

For Fortran 95, the complete set of parameters are made available as
part of the plplot module.  So access to this complete set of
parameters is automatic wherever the "use plplot" statement is used.
This is extremely convenient for new Fortran 95 apps that use PLplot,
but, in general, changes will have to be made for existing apps. (See
announcement XX above for the details).

2.52 The plarc function has been added

The plarc function allows drawing filled and outlined arcs in PLplot.
Standard example 3 uses plarc.


PLplot Release 5.9.7
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

     If you encounter a problem that is not already documented in the
PROBLEMS file or on our bugtracker, then please send bug reports to PLplot
developers via the mailing lists at
http://sourceforge.net/mail/?group_id=2915 (preferred) or on our bugtracker
at http://sourceforge.net/tracker/?group_id=2915&atid=102915.

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

Official Notices for Users.

I. As of release 5.9.1 we have removed our previously deprecated
autotools-based build system.  Instead, use the CMake-based build system
following the directions in the INSTALL file.

II. As of release 5.9.1 we no longer support Octave-2.1.73 which has a
variety of run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results with all
our Octave examples for Octave-3.0.1. Also, that is the recommended stable
version of Octave at http://www.gnu.org/software/octave/download.html so
that is the only version of Octave we support at this time.

III. As of release 5.9.1 we have decided for consistency sake to change the
PLplot stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact window
limit values input by users using plwind. Previously to this change, the
stream variables and the values returned by plgvpw reflected the internal
slightly expanded range of window limits used by PLplot so that the user's
specified limits would be on the graph.  Two users noted this slight
difference, and we agree with them it should not be there. Note that
internally, PLplot still uses the expanded ranges so most users results will
be identical.  However, you may notice some small changes to your plot
results if you use these stream variables directly (only possible in C/C++)
or use plgvpw.

IV. As of release 5.9.2 we have set HAVE_PTHREAD to ON by default for all
platforms other than Darwin.  Darwin will follow later once it appears the
Apple version of X supports it.

V. As of release 5.9.3 our build system requires CMake version 2.6.0 or
higher.

VI. As of release 5.9.3 we have deprecated the gcw device driver and the
related gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on the
plfreetype approach for accessing unicode fonts which has known issues
(inconsistent text offsets, inconvenient font setting capabilities, and
incorrect rendering of CTL languages).  To avoid these issues we advise
using the xcairo device and the externally supplied XDrawable or Cairo
context associated with the xcairo device and the extcairo device (see
examples/c/README.cairo) instead. If you still absolutely must use -dev gcw
or the related gnome2 or pygcw bindings despite the known problems, then
they can still be accessed by setting PLD_gcw, ENABLE_gnome2, and/or
ENABLE_pygcw to ON.
N.B. This announcement has been superseded by the subsequent retirement
of gcw, gnome2, and pygcw, see announcement XVII.

VII. As of release 5.9.3 we have deprecated the gd device driver which
implements the png, jpeg, and gif devices.  This device driver is
essentially unmaintained. For example, it still depends on the plfreetype
approach for accessing unicode fonts which has known issues (inconsistent
text offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for the
JPEG format, we advise using the jpgqt device.  PNG is normally considered a
better raster format than GIF, but if you absolutely require GIF format, we
advise using the pngcairo or pngqt devices and then downgrading the results
to the GIF format using the ImageMagick "convert" application.  For those
platforms where libgd (the dependency of the gd device driver) is accessible
while the required dependencies of the cairo and/or qt devices are not
accessible, you can still use these deprecated devices by setting PLD_png,
PLD_jpeg, or PLD_gif to ON.

VIII. As of release 5.9.3 we have re-enabled the tk, itk, and itcl components
of PLplot by default that were disabled by default as of release 5.9.1 due
to segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of PLplot.

IX. As of release 5.9.4 we have deprecated the pbm device driver (containing
the pbm device) because glibc detects a catastrophic double free.

X. As of release 5.9.5 we have removed pyqt3 access to PLplot and
replaced it by pyqt4 access to PLplot (see details below).

XI. As of release 5.9.5 the only method of specifying a non-default compiler
(and associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and associated
compiler options will not be supported until CMake bug 9220 is fixed, see
discussion below of the soft-landing re-implementation for details.

XII. As of release 5.9.5 we have retired the hpgl driver (containing the
hp7470, hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and the
tek driver (containing the conex, mskermit, tek4107, tek4107f, tek4010,
tek4010f, versaterm, vlt, and xterm devices).  Retirement means we have
removed the build options which would allow these devices to build and
install.  Recent tests have shown a number of run-time issues (hpgl,
impress, and ljii) or build-time issues (tek) with these devices, and as far
as we know there is no more user interest in them. Therefore, we have
decided to retire these devices rather than fix them.

XIII. As of release 5.9.6 we have retired the pbm driver containing the pbm
(actually portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey font
fallback), falls back to ugly software fills, doesn't support alpha
transparency, etc.  It also has a serious run-time issue with example 2
(double free detected by glibc) which probably indicates some fundamental
issue with the 100 colours in cmap0 for that example. For those who really
need portable pixmap results, we suggest using the ImageMagick convert
programme, e.g., "convert examples/x24c01.pngqt test.ppm" or "convert
examples/x24c01.pngcairo test.ppm" to produce good-looking portable pixmap
results from our best png device results.

XIV. As of release 5.9.6 we have retired the linuxvga driver
containing the linuxvga interactive device.  This device is quite
primitive, difficult to test, and poorly maintained. It ignores
unicode fonts (i.e., uses the Hershey font fallback), falls back to
ugly software fills, doesn't support alpha transparency, etc.  It is
Linux only, can only be run as root, and svgalib (the library used by
linuxsvga) is not supported by some mainstream (e.g., Intel) chipsets.
All of these characteristics make it difficult to even test this
device much less use it for anything serious.  Finally, it has had a
well-known issue for years (incorrect colours) which has never been
fixed indicating nobody is interested in maintaining this device.

XV. As of release 5.9.6 we have retired our platform support of djgpp
that used to reside in sys/dos/djgpp.  The developer (Andrew Roach)
who used to maintain those support files for djgpp feels that the
djgpp platform is no longer actively developed, and he no longer uses
djgpp himself.

XVI. As of release 5.9.6 plpoin results for ascii codes 92, 94, and 95
are changed from centred dot, degree symbol, and centred dot glyphs to
the correct backslash, caret, and underscore glyphs that are
associated with those ascii indices.  This change is consistent with
the documentation of plpoin and solves a long-standing issue with
backslash, caret, and underscore ascii characters in character strings
used for example by pl[mp]tex.  Those who need access to a centred dot
with plpoin should use index 1.  The degree symbol is no longer
accessible with plpoin, but it is available in ordinary text input to
PLplot as Hershey escape "#(718)", where 718 is the Hershey index of
the degree symbol, unicode escape "#[0x00B0]" where 0x00B0 is the
unicode index for the degree symbol or direct UTF8 unicode string "°".

XVII. As of release 5.9.6 we have retired the gcw device driver and
the related gnome2 and pygcw bindings since these are unmaintained and
there are good replacements.  These components of PLplot were
deprecated as of release 5.9.3.  A good replacement for the gcw device
is either the xcairo or qtwidget device.  A good replacement for the
gnome2 bindings is the externally supplied XDrawable or Cairo context
associated with the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

XVIII. As of release 5.9.6 we have deprecated support for the python
Numeric array extensions. Numeric is no longer maintained and users
of Numeric are advised to migrate to numpy. Numpy has been the standard
for PLplot for some time. If numpy is not present PLplot will now
disable python by default. If you still require Numeric support in the
short term then set USE_NUMERIC to ON in cmake. The PLplot support
for Numeric will be dropped in a future release.

XVIV. It has come to our attention that the version of gdc supplied with
several recent versions of Ubuntu has a very serious bug on 64-bit
systems (see https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955)
which causes several of the plplot D examples to crash. If this
affects you, you are recommended to disable the d bindings or switch to
an alternative d compiler (the Digital Mars compiler is reported to
be good).

INDEX

0. Tests made for release 5.9.7

1. Changes relative to PLplot 5.9.6 (the previous development release)

1.1 Alpha value support for plotting in memory.
1.2 Add a Qt device for in memory plotting.
1.3 Add discrete legend capability.


2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
2.36 Make PLplot aware of LC_NUMERIC locale
2.37 Linear gradients have been implemented
2.38 Cairo Windows driver implemented
2.39 Custom axis labeling implemented
2.40 Universal coordinate transform implemented
2.41 Support for arbitrary storage of 2D user data
2.42 Font improvements
2.42 Alpha value support for plotting in memory.
2.43 Add a Qt device for in memory plotting.
2.44 Add discrete legend capability.


0. Tests made for release 5.9.7

See
http://www.miscdebris.net/plplot_wiki/index.php?title=Testing_PLplot#Testing_Reports
for a summary table of all testing done for PLplot-5.9.7.

1. Changes relative to PLplot 5.9.6 (the previous development release)

1.1 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

1.2 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

1.3 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

2.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our colour palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

2.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current colour map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

2.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

2.39 Custom axis labeling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labeling geographic coordinates in degrees North, South, East and
West.

2.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

2.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbtrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t stucture of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

2.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

2.42 Alpha value support for plotting in memory.

The function plsmema() was added to the PLplot API. This allows the user
to supply a RGBA formatted array that PLplot can use to do in memory
plotting with alpha value support. At present only the memcairo device
is capable of using RGBA formatted memory. The mem device, at least
for the time being, only supports RGB formatted memory and will exit
if the user attempts to give it RGBA formatted memory to plot in.

2.43 Add a Qt device for in memory plotting.

A new device called memqt has been added for in memory plotting using
Qt. This device is the Qt equivalent of the memcairo device.

2.44 Add discrete legend capability.

A new routine called pllegend has been added to our core C API.
(N.B. This is an experimental API that may be subject to further
change as we gain more experience with it.)  This routine creates a
discrete plot legend with a plotted box, line, and/or line of symbols
for each annotated legend entry. The arguments of pllegend provide
control over the location and size of the legend within the current
subpage as well as the location and characteristics of the elements
(most of which are optional) within that legend. The resulting legend
is clipped at the boundaries of the current subpage


PLplot Release 5.9.6
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.0.

     If you encounter a problem that is not already documented in the
PROBLEMS file or on our bugtracker, then please send bug reports to PLplot
developers via the mailing lists at
http://sourceforge.net/mail/?group_id=2915 (preferred) or on our bugtracker
at http://sourceforge.net/tracker/?group_id=2915&atid=102915.

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

Official Notices for Users.

I. As of release 5.9.1 we have removed our previously deprecated
autotools-based build system.  Instead, use the CMake-based build system
following the directions in the INSTALL file.

II. As of release 5.9.1 we no longer support Octave-2.1.73 which has a
variety of run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results with all
our Octave examples for Octave-3.0.1. Also, that is the recommended stable
version of Octave at http://www.gnu.org/software/octave/download.html so
that is the only version of Octave we support at this time.

III. As of release 5.9.1 we have decided for consistency sake to change the
PLplot stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact window
limit values input by users using plwind. Previously to this change, the
stream variables and the values returned by plgvpw reflected the internal
slightly expanded range of window limits used by PLplot so that the user's
specified limits would be on the graph.  Two users noted this slight
difference, and we agree with them it should not be there. Note that
internally, PLplot still uses the expanded ranges so most users results will
be identical.  However, you may notice some small changes to your plot
results if you use these stream variables directly (only possible in C/C++)
or use plgvpw.

IV. As of release 5.9.2 we have set HAVE_PTHREAD to ON by default for all
platforms other than Darwin.  Darwin will follow later once it appears the
Apple version of X supports it.

V. As of release 5.9.3 our build system requires CMake version 2.6.0 or
higher.

VI. As of release 5.9.3 we have deprecated the gcw device driver and the
related gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on the
plfreetype approach for accessing unicode fonts which has known issues
(inconsistent text offsets, inconvenient font setting capabilities, and
incorrect rendering of CTL languages).  To avoid these issues we advise
using the xcairo device and the externally supplied XDrawable or Cairo
context associated with the xcairo device and the extcairo device (see
examples/c/README.cairo) instead. If you still absolutely must use -dev gcw
or the related gnome2 or pygcw bindings despite the known problems, then
they can still be accessed by setting PLD_gcw, ENABLE_gnome2, and/or
ENABLE_pygcw to ON.
N.B. This announcement has been superseded by the subsequent retirement
of gcw, gnome2, and pygcw, see announcement XVII.

VII. As of release 5.9.3 we have deprecated the gd device driver which
implements the png, jpeg, and gif devices.  This device driver is
essentially unmaintained. For example, it still depends on the plfreetype
approach for accessing unicode fonts which has known issues (inconsistent
text offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for the
JPEG format, we advise using the jpgqt device.  PNG is normally considered a
better raster format than GIF, but if you absolutely require GIF format, we
advise using the pngcairo or pngqt devices and then downgrading the results
to the GIF format using the ImageMagick "convert" application.  For those
platforms where libgd (the dependency of the gd device driver) is accessible
while the required dependencies of the cairo and/or qt devices are not
accessible, you can still use these deprecated devices by setting PLD_png,
PLD_jpeg, or PLD_gif to ON.

VIII. As of release 5.9.3 we have re-enabled the tk, itk, and itcl components
of PLplot by default that were disabled by default as of release 5.9.1 due
to segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of PLplot.

IX. As of release 5.9.4 we have deprecated the pbm device driver (containing
the pbm device) because glibc detects a catastrophic double free.

X. As of release 5.9.5 we have removed pyqt3 access to PLplot and
replaced it by pyqt4 access to PLplot (see details below).

XI. As of release 5.9.5 the only method of specifying a non-default compiler
(and associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and associated
compiler options will not be supported until CMake bug 9220 is fixed, see
discussion below of the soft-landing re-implementation for details.

XII. As of release 5.9.5 we have retired the hpgl driver (containing the
hp7470, hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and the
tek driver (containing the conex, mskermit, tek4107, tek4107f, tek4010,
tek4010f, versaterm, vlt, and xterm devices).  Retirement means we have
removed the build options which would allow these devices to build and
install.  Recent tests have shown a number of run-time issues (hpgl,
impress, and ljii) or build-time issues (tek) with these devices, and as far
as we know there is no more user interest in them. Therefore, we have
decided to retire these devices rather than fix them.

XIII. As of release 5.9.6 we have retired the pbm driver containing the pbm
(actually portable pixmap) file device. This device is quite primitive and
poorly maintained. It ignores unicode fonts (i.e., uses the Hershey font
fallback), falls back to ugly software fills, doesn't support alpha
transparency, etc.  It also has a serious run-time issue with example 2
(double free detected by glibc) which probably indicates some fundamental
issue with the 100 colours in cmap0 for that example. For those who really
need portable pixmap results, we suggest using the ImageMagick convert
programme, e.g., "convert examples/x24c01.pngqt test.ppm" or "convert
examples/x24c01.pngcairo test.ppm" to produce good-looking portable pixmap
results from our best png device results.

XIV. As of release 5.9.6 we have retired the linuxvga driver
containing the linuxvga interactive device.  This device is quite
primitive, difficult to test, and poorly maintained. It ignores
unicode fonts (i.e., uses the Hershey font fallback), falls back to
ugly software fills, doesn't support alpha transparency, etc.  It is
Linux only, can only be run as root, and svgalib (the library used by
linuxsvga) is not supported by some mainstream (e.g., Intel) chipsets.
All of these characteristics make it difficult to even test this
device much less use it for anything serious.  Finally, it has had a
well-known issue for years (incorrect colours) which has never been
fixed indicating nobody is interested in maintaining this device.

XV. As of release 5.9.6 we have retired our platform support of djgpp
that used to reside in sys/dos/djgpp.  The developer (Andrew Roach)
who used to maintain those support files for djgpp feels that the
djgpp platform is no longer actively developed, and he no longer uses
djgpp himself.

XVI. As of release 5.9.6 plpoin results for ascii codes 92, 94, and 95
are changed from centred dot, degree symbol, and centred dot glyphs to
the correct backslash, caret, and underscore glyphs that are
associated with those ascii indices.  This change is consistent with
the documentation of plpoin and solves a long-standing issue with
backslash, caret, and underscore ascii characters in character strings
used for example by pl[mp]tex.  Those who need access to a centred dot
with plpoin should use index 1.  The degree symbol is no longer
accessible with plpoin, but it is available in ordinary text input to
PLplot as Hershey escape "#(718)", where 718 is the Hershey index of
the degree symbol, unicode escape "#[0x00B0]" where 0x00B0 is the
unicode index for the degree symbol or direct UTF8 unicode string "°".

XVII. As of release 5.9.6 we have retired the gcw device driver and
the related gnome2 and pygcw bindings since these are unmaintained and
there are good replacements.  These components of PLplot were
deprecated as of release 5.9.3.  A good replacement for the gcw device
is either the xcairo or qtwidget device.  A good replacement for the
gnome2 bindings is the externally supplied XDrawable or Cairo context
associated with the xcairo device and the extcairo device (see
examples/c/README.cairo).  A good replacement for pygcw is our new
pyqt4 bindings for PLplot.

XVIII. As of release 5.9.6 we have deprecated support for the python
Numeric array extensions. Numeric is no longer maintained and users
of Numeric are advised to migrate to numpy. Numpy has been the standard
for PLplot for some time. If numpy is not present PLplot will now
disable python by default. If you still require Numeric support in the
short term then set USE_NUMERIC to ON in cmake. The PLplot support
for Numeric will be dropped in a future release.

XVIV. It has come to our attention that the version of gdc supplied with
several recent versions of Ubuntu has a very serious bug on 64-bit
systems (see https://bugs.launchpad.net/ubuntu/+source/gdc-4.2/+bug/235955)
which causes several of the plplot D examples to crash. If this
affects you, you are recommended to disable the d bindings or switch to
an alternative d compiler (the Digital Mars compiler is reported to
be good).

INDEX

0. Tests made for release 5.9.6

1. Changes relative to PLplot 5.9.5 (the previous development release)

1.1 Make PLplot aware of LC_NUMERIC locale
1.2 Linear gradients have been implemented
1.3 Cairo Windows driver implemented
1.4 Custom axis labeling implemented
1.5 Universal coordinate transform implemented
1.6 Support for arbitrary storage of 2D user data
1.7 Font improvements


2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Re-implementation of a "soft landing" when a bad/missing compiler is
detected
2.36 Make PLplot aware of LC_NUMERIC locale
2.37 Linear gradients have been implemented
2.38 Cairo Windows driver implemented
2.39 Custom axis labeling implemented
2.40 Universal coordinate transform implemented
2.41 Support for arbitrary storage of 2D user data
2.42 Font improvements


0. Tests made for release 5.9.6

See
http://www.miscdebris.net/plplot_wiki/index.php?title=Testing_PLplot#Testing_Reports
for a summary table of all testing done for PLplot-5.9.6.

1. Changes relative to PLplot 5.9.5 (the previous development release)

1.1 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our colour palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

1.2 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current colour map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

1.3 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

1.4 Custom axis labeling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labeling geographic coordinates in degrees North, South, East and
West.

1.5 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

1.6 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbtrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t stucture of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

1.7 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake is now the only supported build system. It has been tested on
Linux / Unix, Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already available in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an official PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in PLplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in PLplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
PLplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared PLplot library is built.

2.24 Documentation updates

The DocBook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for PLplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplot's color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplot's color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on Linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2.36 Make PLplot aware of LC_NUMERIC locale

For POSIX-compliant systems, locale is set globally so any external
applications or libraries that use the PLplot library or any external
libraries used by the PLplot library or PLplot device drivers could
potentially change the LC_NUMERIC locale used by PLplot to anything those
external applications and libraries choose. The principal consequence of
such choice is the decimal separator could be a comma (for some locales)
rather than the period assumed for the "C" locale.  For previous versions of
PLplot a comma decimal separator would have lead to a large number of
errors, but this issue is now addressed with a side benefit that our plots
now have the capability of displaying the comma (e.g., in axis labels) for
the decimal separator for those locales which require that.

If you are not satisfied with the results for the default PLplot locale set
by external applications and libraries, then you can now choose the
LC_NUMERIC locale for PLplot by (a) specifying the new -locale command-line
option for PLplot (if you do not specify that option, a default locale is
chosen depending on applications and libraries external to PLplot (see
comments above), and (b) setting an environment variable (LC_ALL,
LC_NUMERIC, or LANG on Linux, for example) to some locale that has been
installed on your system.  On Linux, to find what locales are installed, use
the "locale -a" option. The "C" locale is always installed, but usually
there is also a principal locale that works on a platform such as
en_US.UTF8, nl_NL.UTF8, etc.  Furthermore, it is straightforward to build
and install any additional locale you desire.  (For example, on Debian Linux
you do that by running "dpkg-reconfigure locales".)

Normally, users will not use the -locale option since the period
decimal separator that you get for the normal LC_NUMERIC default "C"
locale used by external applications and libraries is fine for their needs.
However, if the resulting decimal separator is not what the user
wants, then they would do something like the following to (a) use a period
decimal separator for command-line input and plots:

LC_ALL=C examples/c/x09c -locale -dev psc -o test.psc -ori 0.5

or (b) use a comma decimal separator for command-line input and plots:

LC_ALL=nl_NL.UTF8 examples/c/x09c -locale -dev psc -o test.psc -ori 0,5

N.B. in either case if the wrong separator is used for input (e.g., -ori 0,5
in the first case or -ori 0.5 in the second) the floating-point conversion
(using atof) is silently terminated at the wrong separator for the locale,
i.e., the fractional part of the number is silently dropped.  This is
obviously not ideal, but on the other hand there are relatively few
floating-point command-line options for PLplot, and we also expect those who
use the -locale option to specifically ask for a given separator for plots
(e.g., axis labels) will then use it for command-line input of
floating-point values as well.

Certain critical areas of the PLplot library (e.g., our colour palette file
reading routines and much of the code in our device drivers) absolutely
require a period for the decimal separator.  We now protect those critical
areas by saving the normal PLplot LC_NUMERIC locale (established with the
above -locale option or by default by whatever is set by external
applications or libraries), setting the LC_NUMERIC "C" locale, executing the
critical code, then restoring back to the normal PLplot LC_NUMERIC locale.
Previous versions of PLplot did not have this protection of the critical
areas so were vulnerable to default LC_NUMERIC settings of external
applications that resulted in a comma decimal separator that did not work
correctly for the critical areas.

2.37 Linear gradients have been implemented

The new plgradient routine draws a linear gradient (based on the
current colour map 1) at a specified angle with the x axis for a
specified polygon.  Standard examples 25 and 30 now demonstrate use of
plgradient.  Some devices use a software fallback to render the
gradient.  This fallback is implemented with plshades which uses a
series of rectangles to approximate the gradient. Tiny alignment
issues for those rectangles relative to the pixel grid may look
problematic for transparency gradients.  To avoid that issue, we try
to use native gradient capability whenever that is possible for any of
our devices.  Currently, this has been implemented for our svg, qt,
and cairo devices.  The result is nice-looking smooth transparency
gradients for those devices, for, e.g., example 30, page 2.

2.38 Cairo Windows driver implemented

A cairo Windows driver has been implemented. This provides an
interactive cairo driver for Windows similar to xcairo on Linux.
Work to improve its functionality is ongoing.

2.39 Custom axis labeling implemented

Axis text labels can now be customized using the new plslabelfunc function.
This allows a user to specify what text should be draw at a given position
along a plot axis.  Example 19 has been updated to illustrate this function's
use through labeling geographic coordinates in degrees North, South, East and
West.

2.40 Universal coordinate transform implemented

A custom coordinate transformation function can be set using plstransform.
This transformation function affects all subsequent plot function calls which
work with plot window coordinates.  Testing and refinement of this support is
ongoing.

2.41 Support for arbitrary storage of 2D user data

This improvement courtesy of David MacMahon adds support for arbitrary
storage of 2D user data.  This is very similar to the technique employed
by some existing functions (e.g. plfcont and plfshade) that use "evaluator"
functions to access 2D user data that is stored in an arbtrary format.
The new approach extends the concept of a user-supplied (or predefined)
"evaluator" function to a group of user-supplied (or predefined) "operator"
functions.  The operator functions provide for various operations on the
arbitrarily stored 2D data including: get, set, +=, -=, *=, /=, isnan,
minmax, and f2eval.

To facilitate the passing of an entire family of operator functions (via
function pointers), a plf2ops_t structure is defined to contain a
pointer to each type of operator function.  Predefined operator
functions are defined for several common 2D data storage techniques.
Variables (of type plf2ops_t) containing function pointers for these
operator functions are also defined.

New variants of functions that accept 2D data are created.  The new
variants accept the 2D data as two parameters: a pointer to a plf2ops_t
structure containing (pointers to) suitable operator functions and a
PLPointer to the actual 2D data store.  Existing functions that accept
2D data are modified to simply pass their parameters to the
corresponding new variant of the function, along with a pointer to the
suitable predefined plf2ops_t stucture of operator function pointers.

The list of functions for which new variants are created is:
c_plimage, c_plimagefr, c_plmesh, c_plmeshc, c_plot3d, c_plot3dc,
c_plot3dcl, c_plshade1, c_plshades, c_plsurf3d, and c_plsurf3dl, and
c_plgriddata.  The new variants are named the same as their
corresponding existing function except that the "c_" prefix is changed
to "plf" (e.g. the new variant of c_plmesh is called plfmesh).

Adds plfvect declaration to plplot.h and changes the names (and only the
names) of some plfvect arguments to make them slightly clearer.  In
order to maintain backwards API compatibility, this function and the
other existing functions that use "evaluator" functions are NOT changed
to use the new operator functions.

Makes plplot.h and libplplot consistent vis-a-vis pltr0f and pltr2d.
Moves the definitions of pltr2f (already declared in plplot.h) from the
sccont.c files of the FORTRAN 77 and Fortran 95 bindings into plcont.c.
Removes pltr0f declaration from plplot.h.

Changes x08c.c to demonstrate use of new support for arbitrary storage
of 2D data arrays.  Shows how to do surface plots with the following
four types of 2D data arrays:

1) PLFLT z[nx][ny];
2) PLfGrid2 z;
3) PLFLT z[nx*ny]; /* row major order */
4) PLFLT z[nx*ny]; /* column major order */

2.42 Font improvements

We have added the underscore to the Hershey glyphs (thanks to David
MacMahon) and slightly rearranged the ascii index to the Hershey
indices so that plpoin now generates the complete set of printable
ascii characters in the correct order for the Hershey fonts (and therefore
the Type1 and TrueType fonts as well).

We have improved how we access TrueType and Type1 fonts via the Hershey
font index (used by plpoin, plsym, and the Hershey escape sequences in pl*tex
commands).  We have added considerably to the Hershey index to Unicode index
translation table both for the compact and extended Hershey indexing scheme,
and we have adopted the standard Unicode to Type1 index translation tables
from http://unicode.org/Public/MAPPINGS/VENDORS/ADOBE/.

We have also dropped the momentary switch to symbol font that was
implemented in the PLplot core library.  That switch was designed to partially
compensate for the lack of symbol glyphs in the standard Type1 fonts.  That
was a bad design because it affected TrueType font devices as well as
the desired Type1 font devices.  To replace this bad idea we now
change from Type1 standard fonts to the Type1 Symbol font (and vice
versa) whenever there is a glyph lookup failure in the Type1 font
device drivers (ps and pdf).


PLplot Release 5.9.5
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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 warranties, given in the COPYING.LIB
file.


Official Notices for Users.

I. As of release 5.9.1 we have removed our previously deprecated
autotools-based build system.  Instead, use the CMake-based build system
following the directions in the INSTALL file.

II. As of release 5.9.1 we no longer support Octave-2.1.73 which has a
variety of run-time issues in our tests of the Octave examples on different
platforms. In contrast our tests show we get good run-time results with all
our Octave examples for Octave-3.0.1. Also, that is the recommended stable
version of Octave at http://www.gnu.org/software/octave/download.html so
that is the only version of Octave we support at this time.

III. As of release 5.9.1 we have decided for consistency sake to change the
PLplot stream variables plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and
plsc->vpwyma and the results returned by plgvpw to reflect the exact window
limit values input by users using plwind. Previously to this change, the
stream variables and the values returned by plgvpw reflected the internal
slightly expanded range of window limits used by PLplot so that the user's
specified limits would be on the graph.  Two users noted this slight
difference, and we agree with them it should not be there. Note that
internally, PLplot still uses the expanded ranges so most users results will
be identical.  However, you may notice some small changes to your plot
results if you use these stream variables directly (only possible in C/C++)
or use plgvpw.

IV. As of release 5.9.2 we have set HAVE_PTHREAD to ON by default for all
platforms other than Darwin.  Darwin will follow later once it appears the
Apple version of X supports it.

V. As of release 5.9.3 our build system requires CMake version 2.6.0 or
higher.

VI. As of release 5.9.3 we have deprecated the gcw device driver and the
related gnome2 and pygcw bindings since these are essentially unmaintained.
For example, the gcw device and associated bindings still depends on the
plfreetype approach for accessing unicode fonts which has known issues
(inconsistent text offsets, inconvenient font setting capabilities, and
incorrect rendering of CTL languages).  To avoid these issues we advise
using the xcairo device and the externally supplied XDrawable or Cairo
context associated with the xcairo device and the extcairo device (see
examples/c/README.cairo) instead. If you still absolutely must use -dev gcw
or the related gnome2 or pygcw bindings despite the known problems, then
they can still be accessed by setting PLD_gcw, ENABLE_gnome2, and/or
ENABLE_pygcw to ON.

VII. As of release 5.9.3 we have deprecated the gd device driver which
implements the png, jpeg, and gif devices.  This device driver is
essentially unmaintained. For example, it still depends on the plfreetype
approach for accessing unicode fonts which has known issues (inconsistent
text offsets, inconvenient font setting capabilities, and incorrect
rendering of CTL languages).  To avoid these issues for PNG format, we
advise using the pngcairo or pngqt devices.  To avoid these issues for the
JPEG format, we advise using the jpgqt device.  PNG is normally considered a
better raster format than GIF, but if you absolutely require GIF format, we
advise using the pngcairo or pngqt devices and then downgrading the results
to the GIF format using the ImageMagick "convert" application.  For those
platforms where libgd (the dependency of the gd device driver) is accessible
while the required dependencies of the cairo and/or qt devices are not
accessible, you can still use these deprecated devices by setting PLD_png,
PLD_jpeg, or PLD_gif to ON.

VIII. As of release 5.9.3 we have reenabled the tk, itk, and itcl components
of PLplot by default that were disabled by default as of release 5.9.1 due
to segfaults.  The cause of the segfaults was a bug (now fixed) in how
pthread support was implemented for the Tk-related components of PLplot.

IX. As of release 5.9.4 we have deprecated the pbm device driver (containing
the pbm device) because glibc detects a catastrophic double free.

X. As of release 5.9.5 we have removed pyqt3 access to PLplot and
replaced it by pyqt4 access to PLplot (see details below).

XI. As of release 5.9.5 the only method of specifying a non-default compiler
(and associated compiler options) that we support is the environment
variable approach, e.g.,

export CC='gcc -g -fvisibility=hidden'
export CXX='g++ -g -fvisibility=hidden'
export FC='gfortran -g -fvisibility=hidden'

All other CMake methods of specifying a non-default compiler and associated
compiler options will not be supported until CMake bug 9220 is fixed, see
discussion below of the soft-landing reimplementation for details.

XII. As of release 5.9.5 we have retired the hpgl driver (containing the
hp7470, hp7580, and lj_hpgl devices), the impress driver (containing the imp
device), the ljii driver (containing the ljii and ljiip devices), and the
tek driver (containing the conex, mskermit, tek4107, tek4107f, tek4010,
tek4010f, versaterm, vlt, and xterm devices).  Retirement means we have
removed the build options which would allow these devices to build and
install.  Recent tests have shown a number of run-time issues (hpgl,
impress, and ljii) or build-time issues (tek) with these devices, and as far
as we know there is no more user interest in them. Therefore, we have
decided to retire these devices rather than fix them.

INDEX

1. Changes relative to PLplot 5.9.4 (the previous development release)

1.1 PyQt changes
1.2 Color Palettes
1.3 Reimplementation of a "soft landing" when a bad/missing compiler is
detected

1.1 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

1.2 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplots color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplots color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on linux).

1.3 Reimplementation of a "soft landing" when a bad/missing compiler is
detected.

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device
2.10 Improvements to the cairo driver family.
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements
2.33 PyQt changes
2.34 Color Palettes
2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected.


2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

2.24 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2.33 PyQt changes

Years ago we got a donation of a hand-crafted pyqt3 interface to PLplot
(some of the functions in plplot_widgetmodule.c in bindings/python) and a
proof-of-concept example (prova.py and qplplot.py in examples/python), but
this code did not gain any developer interest and was therefore not
understood or maintained. Recently one of our core developers has
implemented a sip-generated pyqt4 interface to PLplot (controlled by
plplot_pyqt4.sip in bindings/qt_gui/pyqt4) that builds without problems as a
python extension module, and a good-looking pyqt4 example (pyqt4_example.py
in examples/python) that works well.  Since this pyqt4 approach is
maintained by a PLplot developer it appears to have a good future, and we
have therefore decided to concentrate on pyqt4 and remove the pyqt3 PLplot
interface and example completely.

2.34 Color Palettes

Support has been added to PLplot for user defined color palette files.
These files can be loaded at the command line using the -cmap0 or
-cmap1 commands, or via the API using the plspal0 and plspal1 commands.
The commands cmap0 / plspal0 are used to load cmap0 type files which
specify the colors in PLplots color table 0. The commands cmap1 /
plspal1 are used to load cmap1 type files which specify PLplots color
table 1. Examples of both types of files can be found in either the
plplot-source/data directory or the PLplot installed directory
(typically /usr/local/share/plplotx.y.z/ on linux).

2.35 Reimplementation of a "soft landing" when a bad/missing compiler is
detected.

The PLplot core library is written in C so our CMake-based build system will
error out if it doesn't detect a working C compiler.  However all other
compiled languages (Ada, C++, D, Fortran, Java, and OCaml) we support are
optional.  If a working compiler is not available, we give a "soft landing"
(give a warning message, disable the optional component, and keep going).
The old implementation of the soft landing was not applied consistently (C++
was unnecessarily mandatory before) and also caused problems for ccmake (a
CLI front-end to the cmake application) and cmake-gui (a CMake GUI front-end
to the cmake application) which incorrectly dropped languages as a result
even when there was a working compiler.

We now have completely reimplemented the soft landing logic.  The result
works well for cmake, ccmake, and cmake-gui.  The one limitation of this new
method that we are aware of is it only recognizes either the default
compiler chosen by the generator or else a compiler specified by the
environment variable approach (see Official Notice XII above).  Once CMake
bug 9220 has been fixed (so that the OPTIONAL signature of the
enable_language command actually works without erroring out), then our
soft-landing approach (which is a workaround for bug 9220) will be replaced
by the OPTIONAL signature of enable_language, and all CMake methods of
specifying compilers and compiler options will automatically be recognized
as a result.



PLplot Release 5.9.4
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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 warranties, given in the COPYING.LIB
file.


Notices for Users.

I. This is the official notice that our deprecated autotools-based build
system has been removed as of release 5.9.1.  Instead, use the CMake-based
build system following the directions in the INSTALL file.

II. This is official notice that we (as of 5.9.1) no longer support
Octave-2.1.73 which has a variety of run-time issues in our tests of the
Octave examples on different platforms.  In contrast our tests show we get
good run-time results with all our Octave examples for Octave-3.0.1. Also,
that is the recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only version
of Octave we support at this time.

III. This is official notice that the PLplot team have decided (as of release
5.9.1) for consistency sake to change the PLplot stream variables
plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and plsc->vpwyma and the results
returned by plgvpw to reflect the exact window limit values input by users
using plwind. Previously to this change, the stream variables and the values
returned by plgvpw reflected the internal slightly expanded range of window
limits used by PLplot so that the user's specified limits would be on the
graph.  Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the expanded
ranges so most users results will be identical.  However, you may notice
some small changes to your plot results if you use these stream variables
directly (only possible in C/C++) or use plgvpw.

IV. This is official notice that (as of release 5.9.2) we have set
HAVE_PTHREAD to ON by default for all platforms other than Darwin.  Darwin
will follow later once it appears the Apple version of X supports it.

V. This is official notice that (as of release 5.9.3) our  build system
requires CMake version 2.6.0 or higher.

VI. This is official notice that (as of release 5.9.3) we have deprecated
the gcw device driver and the related gnome2 and pygcw bindings since these
are essentially unmaintained. For example, the gcw device and associated
bindings still depends on the plfreetype approach for accessing unicode
fonts which has known issues (inconsistent text offsets, inconvenient font
setting capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally supplied
XDrawable or Cairo context associated with the xcairo device and the
extcairo device (see examples/c/README.cairo) instead. If you still
absolutely must use -dev gcw or the related gnome2 or pygcw bindings despite
the known problems, then they can still be accessed by setting PLD_gcw,
ENABLE_gnome2, and/or ENABLE_pygcw to ON.

VII. This is official notice that (as of release 5.9.3) we have deprecated
the gd device driver which implements the png, jpeg, and gif devices.  This
device driver is essentially unmaintained. For example, it still depends on
the plfreetype approach for accessing unicode fonts which has known issues
(inconsistent text offsets, inconvenient font setting capabilities, and
incorrect rendering of CTL languages).  To avoid these issues for PNG
format, we advise using the pngcairo or pngqt devices.  To avoid these
issues for the JPEG format, we advise using the jpgqt device.  PNG is
normally considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and then
downgrading the results to the GIF format using the ImageMagick "convert"
application.  For those platforms where libgd (the dependency of the gd
device driver) is accessible while the required dependencies of the cairo
and/or qt devices are not accessible, you can still use these deprecated
devices by setting PLD_png, PLD_jpeg, or PLD_gif to ON.

VIII. This is official notice that the tk, itk, and itcl components of
PLplot have been reenabled again by default (as of release 5.9.3) after
being disabled by default as of release 5.9.1 due to segfaults.  The cause
of the segfaults was a bug (now fixed) in how pthread support was
implemented for the Tk-related components of PLplot.

INDEX

1. Changes relative to PLplot 5.9.3 (the previous development release)

1.1 Various bug fixes
1.2 Cairo driver improvements


2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device.
2.10 Improvements to the cairo driver family.
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions
2.31 Various bug fixes
2.32 Cairo driver improvements

1. Changes relative to PLplot 5.9.3 (the previous development release)

1.1 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

1.2 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device.

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

2.24 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a new qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse (or hitting
<return> to be consistent with other PLplot interactive devices) to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overall sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity. Qt-4.5
(the version we used for most of our tests) has some essential SVG
functionality so we recommend that version (downloadable from
http://www.qtsoftware.com/downloads for Linux, Mac OS X, and Windows) for
svgqt.  One of our developers found that pdfqt was orders of magnitude
slower than the other qt devices for Qt-4.4.3 on Ubuntu 8.10 installed on a
64 bit box.  That problem was completely cured by moving to the downloadable
Qt-4.5 version.  However, we have also had good Qt-4.4.3 pdfqt reports on
other platforms.  One of our developers also found that all first pages of
examples were black for just the qtwidget device for Qt-4.5.1 on Mac OS X.
From the other improvements we see in Qt-4.5.1 relative to Qt-4.4.3 we
assume this black first page for qtwidget problem also exists for Qt-4.4.3,
but we haven't tested that combination.

In sum, Qt-4.4.3 is worth trying if it is already installed on your machine,
but if you run into any difficulty with it please switch to Qt-4.5.x (once
Qt-4.5.x is installed all you have to do is to put the 4.5.x version of
qmake in your path, and cmake does the rest).  If the problem persists for
Qt-4.5, then it is worth reporting a qt bug.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2.31 Various bug fixes

Various bugs in the 5.9.3 release have been fixed including:

- Include missing file needed for the aqt driver on Mac OS X
- Missing library version number for nistcd
- Fixes for the qt examples with dynamic drivers disabled
- Fixes to several tcl examples so they work with plserver
- Fix pkg-config files to work correctly with Debug / Release build types set
- Make fortran command line argument parsing work with shared libraries on Windows

2.32 Cairo driver improvements

Improvements to the cairo driver to give better results for bitmap
formats when used with anti-aliasing file viewers.


PLplot Release 5.9.3
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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 warranties, given in the COPYING.LIB
file.


Notices for Users.

I. This is the official notice that our deprecated autotools-based build
system has been removed as of release 5.9.1.  Instead, use the CMake-based
build system following the directions in the INSTALL file.

II. This is official notice that we (as of 5.9.1) no longer support
Octave-2.1.73 which has a variety of run-time issues in our tests of the
Octave examples on different platforms.  In contrast our tests show we get
good run-time results with all our Octave examples for Octave-3.0.1. Also,
that is the recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only version
of Octave we support at this time.

III. This is official notice that the PLplot team have decided (as of release
5.9.1) for consistency sake to change the PLplot stream variables
plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and plsc->vpwyma and the results
returned by plgvpw to reflect the exact window limit values input by users
using plwind. Previously to this change, the stream variables and the values
returned by plgvpw reflected the internal slightly expanded range of window
limits used by PLplot so that the user's specified limits would be on the
graph.  Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the expanded
ranges so most users results will be identical.  However, you may notice
some small changes to your plot results if you use these stream variables
directly (only possible in C/C++) or use plgvpw.

IV. This is official notice that (as of release 5.9.2) we have set
HAVE_PTHREAD to ON by default for all platforms other than Darwin.  Darwin
will follow later once it appears the Apple version of X supports it.

V. This is official notice that (as of release 5.9.3) our  build system
requires CMake version 2.6.0 or higher.

VI. This is official notice that (as of release 5.9.3) we have deprecated
the gcw device driver and the related gnome2 and pygcw bindings since these
are essentially unmaintained. For example, the gcw device and associated
bindings still depends on the plfreetype approach for accessing unicode
fonts which has known issues (inconsistent text offsets, inconvenient font
setting capabilities, and incorrect rendering of CTL languages).  To avoid
these issues we advise using the xcairo device and the externally supplied
XDrawable or Cairo context associated with the xcairo device and the
extcairo device (see examples/c/README.cairo) instead. If you still
absolutely must use -dev gcw or the related gnome2 or pygcw bindings despite
the known problems, then they can still be accessed by setting PLD_gcw,
ENABLE_gnome2, and/or ENABLE_pygcw to ON.

VII. This is official notice that (as of release 5.9.3) we have deprecated
the gd device driver which implements the png, jpeg, and gif devices.  This
device driver is essentially unmaintained. For example, it still depends on
the plfreetype approach for accessing unicode fonts which has known issues
(inconsistent text offsets, inconvenient font setting capabilities, and
incorrect rendering of CTL languages).  To avoid these issues for PNG
format, we advise using the pngcairo or pngqt devices.  To avoid these
issues for the JPEG format, we advise using the jpgqt device.  PNG is
normally considered a better raster format than GIF, but if you absolutely
require GIF format, we advise using the pngcairo or pngqt devices and then
downgrading the results to the GIF format using the ImageMagick "convert"
application.  For those platforms where libgd (the dependency of the gd
device driver) is accessible while the required dependencies of the cairo
and/or qt devices are not accessible, you can still use these deprecated
devices by setting PLD_png, PLD_jpeg, or PLD_gif to ON.

VIII. This is official notice that the tk, itk, and itcl components of
PLplot have been reenabled again by default (as of release 5.9.3) after
being disabled by default as of release 5.9.1 due to segfaults.  The cause
of the segfaults was a bug (now fixed) in how pthread support was
implemented for the Tk-related components of PLplot.

INDEX

1. Changes relative to PLplot 5.9.2 (the previous development release)

1.1 libnistcd (a.k.a. libcd) now built internally for -dev cgm
1.2 get-drv-info now changed to test-drv-info
1.3 Text clipping now enabled by default for the cairo devices
1.4 A powerful qt device driver has been implemented
1.5 The PLplot API is now accessible from Qt GUI applications
1.6 NaN / Inf support for some PLplot functions

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device.
2.10 Improvements to the cairo driver family.
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates
2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm
2.26 get-drv-info now changed to test-drv-info
2.27 Text clipping now enabled by default for the cairo devices
2.28 A powerful qt device driver has been implemented
2.29 The PLplot API is now accessible from Qt GUI applications
2.30 NaN / Inf support for some PLplot functions

1. Changes relative to PLplot 5.9.2 (the previous development release)

1.1 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

1.2 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

1.3 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

1.4 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overal sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity.
Qt-4.5 has some essential SVG functionality so we recommend that
version (downloadable from http://www.qtsoftware.com/downloads for Linux,
Mac OS X, and Windows) for svgqt.  Qt-4.5 is the version we have used for
most of our testing, but limited testing for Qt-4.4 indicates that version
should be fine for qt devices other than svgqt.

1.5 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

1.6 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, qt, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device.

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

2.24 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.

2.25 libnistcd (a.k.a. libcd) now built internally for -dev cgm

CGM format is a long-established (since 1987) open standard for vector
graphics that is supported by w3c (see http://www.w3.org/Graphics/WebCGM/).
PLplot has long had a cgm device driver which depended on the (mostly)
public domain libcd library that was distributed in the mid 90's by National
Institute of Standards and Technology (NIST) and which is still available
from http://www.pa.msu.edu/ftp/pub/unix/cd1.3.tar.gz.  As a convenience
to our -dev cgm users, we have brought that
source code in house under lib/nistcd and now build libnistcd routinely
as part of our ordinary builds.  The only changes we have made to the
cd1.3 source code is visibility changes in cd.h and swapping the sense of
the return codes for the test executables so that 0 is returned on success
and 1 on failure.  If you want to test libnistcd on your platform,
please run

make test_nistcd

in the top-level build tree.  (That tests runs all the test executables
that are built as part of cd1.3 and compares the results that are generated
with the *.cgm files that are supplied as part of cd1.3.)

Two applications that convert and/or display CGM results on Linux are
ralcgm (which is called by the ImageMagick convert and display applications)
and uniconvertor.

Some additional work on -dev cgm is required to implement antialiasing and
non-Hershey fonts, but both those should be possible using libnistcd according
to the text that is shown by lib/nistcd/cdtext.cgm and lib/nistcd/cdexp1.cgm.

2.26 get-drv-info now changed to test-drv-info

To make cross-building much easier for PLplot we now configure the *.rc
files that are used to describe our various dynamic devices rather than
generating the required *.rc files with get-drv-info.  We have changed the
name of get-drv-info to test-drv-info.  That name is more appropriate
because that executable has always tested dynamic loading of the driver
plug-ins as well as generating the *.rc files from the information gleaned
from that dynamic loading.  Now, we simply run test-drv-info as an option
(defaults to ON unless cross-building is enabled) and compare the resulting
*.rc file with the one configured by cmake to be sure the dynamic device
has been built correctly.

2.27 Text clipping now enabled by default for the cairo devices

When correct text clipping was first implemented for cairo devices, it was
discovered that the libcairo library of that era (2007-08) did that clipping
quite inefficiently so text clipping was disabled by default.  Recent tests
of text clipping for the cairo devices using libcairo 1.6.4 (released in
2008-04) shows text clipping is quite efficient now.  Therefore, it is now
enabled by default.  If you notice a significant slowdown for some libcairo
version prior to 1.6.4 you can use the option -drvopt text_clipping=0 for
your cairo device plots (and accept the improperly clipped text results that
might occur with that option).  Better yet, use libcairo 1.6.4 or later.

2.28 A powerful qt device driver has been implemented

Thanks to the efforts of Alban Rochel of the QSAS team, we now have a qt
device driver which delivers the following 9 (!) devices: qtwidget, bmpqt,
jpgqt, pngqt, ppmqt, tiffqt, epsqt, pdfqt, and svgqt. qtwidget is an
elementary interactive device where, for now, the possible interactions
consist of resizing the window and right clicking with the mouse to control
paging.  The qtwidget overall size is expressed in pixels. bmpqt, jpgqt,
pngqt, ppmqt, and tiffqt are file devices whose overal sizes are specified
in pixels and whose output is BMP (Windows bitmap), JPEG, PNG, PPM (portable
pixmap), and TIFF (tagged image file format) formatted files. epsqt, pdfqt,
svgqt are file devices whose overall sizes are specified in points (1/72 of
an inch) and whose output is EPS (encapsulated PostScript), PDF, and SVG
formatted files.  The qt device driver is based on the powerful facilities
of Qt4 so all qt devices implement variable opacity (alpha channel) effects
(see example 30).  The qt devices also use system unicode fonts, and deal
with CTL (complex text layout) languages automatically without any
intervention required by the user.  (To show this, try qt device results
from examples 23 [mathematical symbols] and 24 [CTL languages].)

Our exhaustive Linux testing of the qt devices (which consisted of detailed
comparisons for all our standard examples between qt device results and the
corresponding cairo device results) indicates this device driver is mature,
but testing on other platforms is requested to confirm that maturity.
Qt-4.5 has some essential SVG functionality so we recommend that
version (downloadable from http://www.qtsoftware.com/downloads for Linux,
Mac OS X, and Windows) for svgqt.  Qt-4.5 is the version we have used for
most of our testing, but limited testing for Qt-4.4 indicates that version
should be fine for qt devices other than svgqt.

2.29 The PLplot API is now accessible from Qt GUI applications

This important new feature has been implemented by Alban Rochel of the QSAS
team as a spin-off of the qt device driver project using the extqt device
(which constitutes the tenth qt device).  See examples/c++/README.qt_example
for a brief description of a simple Qt example which accesses the PLplot API
and which is built in the installed examples tree using the pkg-config
approach. Our build system has been enhanced to configure the necessary
plplotd-qt.pc file.

2.30 NaN / Inf support for some PLplot functions

Some PLplot now correctly handle Nan or Inf values in the data to be plotted.
Line plotting (plline etc) and image plotting (plimage, plimagefr) will
now ignore NaN / Inf values. Currently some of the contour plotting / 3-d
routines do not handle NaN / Inf values. This functionality will
depend on whether the language binding used supports NaN / Inf values.


PLplot Release 5.9.2
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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 warranties, given in the COPYING.LIB
file.


Notices for Users.

I. This is the official notice that our deprecated autotools-based build
system has been removed as of release 5.9.1.  Instead, use the CMake-based
build system following the directions in the INSTALL file.

II. This is official notice that the tk, itk, and itcl components of PLplot
have been disabled by default as of 5.9.1.  We reluctantly took this step
for these venerable PLplot components because we found segfaults with most
of our Tk-related interactive tests for this release which we have been, as
yet, unable to address. For now, if you want to try these components of
PLplot to help us debug the problem, you must specifically use the cmake
options -DENABLE_tk=ON -DENABLE_itk=ON -DENABLE_itcl=ON to build and install
these components.

III. This is official notice that we (as of 5.9.1) no longer support
Octave-2.1.73 which has a variety of run-time issues in our tests of the
Octave examples on different platforms.  In contrast our tests show we get
good run-time results with all our Octave examples for Octave-3.0.1. Also,
that is the recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only version
of Octave we support at this time.

IV.  This is official notice that the PLplot team have decided (as of
release 5.9.1) for consistency sake to change the PLplot stream variables
plsc->vpwxmi, plsc->vpwxma, plsc->vpwymi, and plsc->vpwyma and the results
returned by plgvpw to reflect the exact window limit values input by users
using plwind. Previously to this change, the stream variables and the values
returned by plgvpw reflected the internal slightly expanded range of window
limits used by PLplot so that the user's specified limits would be on the
graph.  Two users noted this slight difference, and we agree with them it
should not be there. Note that internally, PLplot still uses the expanded
ranges so most users results will be identical.  However, you may notice
some small changes to your plot results if you use these stream variables
directly (only possible in C/C++) or use plgvpw.

INDEX

1. Changes relative to PLplot 5.9.1 (the previous development release)

1.1 Extension of our test framework

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device.
2.10 Improvements to the cairo driver family.
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Extension of our test framework
2.20 Rename test subdirectory to plplot_test
2.21 Website support files updated
2.22 Internal changes to function visibility
2.23 Dynamic driver support in Windows
2.24 Documentation updates


1. Changes relative to PLplot 5.9.1 (the previous development release)

1.1 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device.

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (examples 1-31 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors.  Some of the Tcl examples (example 21) require Tcl version 8.5 for
proper support for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Extension of our test framework

The standard test suite for PLplot now carries out a comparison of the
stdout output (especially important for example 31 which tests most of our
set and get functions) and PostScript output for different languages as a
check.  Thanks to the addition of example 31, the inclusion of examples 14
and 17 in the test suite and other recent extensions of the other
examples we now have rigourous testing in place for almost the entirety
of our common API.  This extensive testing framework has already helped
us track down a number of bugs, and it should make it much easier for us
to maintain high quality for our ongoing PLplot releases.

2.20 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.21 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.22 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.23 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

2.24 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.


PLplot Release 5.9.1
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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 warranties, given in the COPYING.LIB
file.

Notices for Users.

I. This is the official notice that our deprecated autotools-based build
system has now been removed.  Instead, use the CMake-based build system
following the directions in the INSTALL file.

II. This is official notice that the tk, itk, and itcl components of PLplot
have been disabled by default for this release.  We reluctantly take this
step for these venerable PLplot components because we found segfaults with
most of our Tk-related interactive tests for this release.  We hope these
issues are addressed before our next release so that the tk, itk, and itcl
components of PLplot can be enabled by default again.  For now, if you want
to try these components of PLplot to help us debug the problem, you must
specifically use the cmake options -DENABLE_tk=ON -DENABLE_itk=ON
-DENABLE_itcl=ON to build and install these components.

III. This is official notice that the python version of gnome2 has been
temporarily disabled by default until we can figure out a

RuntimeError: maximum recursion depth exceeded

error that has been introduced for it (e.g., when running
plplotcanvas_animation.py in the installed examples/python directory).  If
you wish to experiment with this component of PLplot use the
-DENABLE_pygcw=ON option.

examples/c/plplotcanvas_animation (when built in the install tree for the
default ENABLE_gnome2=ON case) works fine.  So do all the standard examples
in the installed examples/python tree.  So this issue appears to be confined
just to the python version of gnome2.

IV. This is official notice that we no longer support Octave-2.1.73 which
has a variety of run-time issues in our tests of the Octave examples on
different platforms.  In contrast our tests show we get good run-time
results with all our Octave examples for Octave-3.0.1. Also, that is the
recommended stable version of Octave at
http://www.gnu.org/software/octave/download.html so that is the only version
of Octave we support at this time.

V.  This is official notice that the PLplot team have decided for
consistency sake to change the PLplot stream variables plsc->vpwxmi,
plsc->vpwxma, plsc->vpwymi, and plsc->vpwyma and the results returned by
plgvpw to reflect the exact window limit values input by users using plwind.
Previously to this change, the stream variables and the values returned by
plgvpw reflected the internal slightly expanded range of window limits used
by PLplot so that the user's specified limits would be on the graph.  Two
users noted this slight difference, and we agree with them it should not be
there. Note that internally, PLplot still uses the expanded ranges so most
users results will be identical.  However, you may notice some small changes
to your plot results if you use these stream variables directly (only
possible in C/C++) or use plgvpw.

INDEX

1. Changes relative to PLplot 5.9.0 (the previous development release)
1.1 New PLplot functions
1.2 Improvements to the cairo driver family.
1.3 wxWidgets driver improvements
1.4 pdf driver improvements
1.5 svg driver improvements
1.6 Ada language support
1.7 OCaml language support
1.8 Perl/PDL language support
1.9 Update to various language bindings
1.10 Update to various examples
1.11 Rename test subdirectory to plplot_test
1.12 Website support files updated
1.13 Internal changes to function visibility
1.14 Dynamic driver support in Windows
1.15 Documentation updates

2. Changes relative to PLplot 5.8.0 (the previous stable release)
2.1 All autotools-related files have now been removed
2.2 Build system bug fixes
2.3 Build system improvements
2.4 Implement build-system infrastructure for installed Ada bindings and
examples
2.5 Code cleanup
2.6 Date / time labels for axes
2.7 Alpha value support
2.8 New PLplot functions
2.9 External libLASi library improvements affecting our psttf device.
2.10 Improvements to the cairo driver family.
2.11 wxWidgets driver improvements
2.12 pdf driver improvements
2.13 svg driver improvements
2.14 Ada language support
2.15 OCaml language support
2.16 Perl/PDL language support
2.17 Update to various language bindings
2.18 Update to various examples
2.19 Rename test subdirectory to plplot_test
2.20 Website support files updated
2.21 Internal changes to function visibility
2.22 Dynamic driver support in Windows
2.23 Documentation updates

1. Changes relative to PLplot 5.9.0 (the previous development release)

1.1 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator (based
on the original Mersenne Twister 1997 code) within the library. plrandd will
return a PLFLT random number in the range 0.0-1.0. plseed will allow the
random number generator to be seeded.

1.2 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

1.3 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

1.4 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

1.5 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

1.6 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

1.7 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

1.8 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

1.9 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

1.10 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (example 1-30 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors. The standard test suite for PLplot using ctest now carries out a
comparison of the postscript output for different languages as a check. Some
of the Tcl examples (example 21) require Tcl version 8.5 for proper support
for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

1.11 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

1.12 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

1.13 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

1.14 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

1.15 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.

2. Changes relative to PLplot 5.8.0 (the previous stable release)

2.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

2.2 Build system bug fixes

Various fixes include the following:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

2.3 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

2.4 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

2.5 Code cleanup

The PLplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using PLplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

2.6 Date / time labels for axes

PLplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

N.B. Our reliance on C library POSIX time routines to (1) convert from
broken-down time to time-epoch, (2) to convert from time-epoch to
broken-down time, and (3) to format results with strftime have proved
problematic for non-C languages which have time routines of variable
quality.  Also, it is not clear that even the POSIX time routines are
available on Windows. So we have plans afoot to implement high-quality
versions of (1), (2), and (3) with additional functions to get/set the epoch
in the PLplot core library itself.  These routines should work on all C
platforms and should also be uniformly accessible for all our language
bindings.

WARNING.....  Therefore, assuming these plans are implemented, the present
part of our date/time PLplot API that uses POSIX time routines will be
changed.

2.7 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

2.8 New PLplot functions

An enhanced version of plimage, plimagefr has been added. This allows images
to be plotted using coordinate transformation, and also for the dynamic range
of the plotted values to be altered. Example 20 has been modified to
demonstrate this new functionality.

To ensure consistent results in example 21 between different platforms and
language bindings PLplot now includes a small random number generator within
the library. plrandd will return a PLFLT random number in the range 0.0-1.0.
plseed will allow the random number generator to be seeded.

2.9 External libLASi library improvements affecting our psttf device.

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.

2.10 Improvements to the cairo driver family.

Jonathan Woithe improved the xcairo driver so that it can optionally be
used with an external user supplied X Drawable. This enables a nice
separation of graphing (PLplot) and window management (Gtk, etc..). Doug
Hunt fixed the bugs that broke the memcairo driver and it is now fully
functional. Additionally, a new extcairo driver was added that will plot
into a user supplied cairo context.

2.11 wxWidgets driver improvements

Complete reorganization of the driver code. A new backend was added, based
on the wxGraphicsContext class, which is available for wxWidgets 2.8.4
and later. This backend produces antialized output similar to the
AGG backend but has no dependency on the AGG library. The basic wxDC
backend and the wxGraphicsContext backend process the text output
on their own, which results in much nicer plots than with the standard
Hershey fonts and is much faster than using the freetype library. New
options were introduced in the wxWidgets driver:
 - backend: Choose backend: (0) standard, (1) using AGG library,
                            (2) using wxGraphicsContext
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - text: Use own text routines (text=0|1)
 - freetype: Use FreeType library (freetype=0|1)
The option "text" changed its meaning, since it enabled the FreeType library
support, while now the option enables the driver's own text routines.

Some other features were added:
 * the wxWidgets driver now correctly clears the background (or parts of it)
 * transparency support was added
 * the "locate mode" (already availale in the xwin and tk driver) was
   implemented, where graphics input events are processed and translated
   to world coordinates

2.12 pdf driver improvements

The pdf driver (which is based on the haru library http://www.libharu.org)
processes the text output now on its own. So far only the Adobe Type1
fonts are supported. TrueType font support will follow. Full unicode
support will follow after the haru library will support unicode strings. The
driver is now able to produce A4, letter, A5 and A3 pages. The Hershey font
may be used only for symbols. Output can now be compressed, resulting in
much smaller file sizes.
Added new options:
 - text: Use own text routines (text=0|1)
 - compress: Compress pdf output (compress=0|1)
 - hrshsym: Use Hershey symbol set (hrshsym=0|1)
 - pagesize: Set page size (pagesize=A4|letter|A3|A5)

2.13 svg driver improvements

This device driver has had the following improvements: schema for generated
file now validates properly at http://validator.w3.org/ for the
automatically detected document type of SVG 1.1; -geometry option now works;
alpha channel transparency has been implemented; file familying for
multipage examples has been implemented; coordinate scaling has been
implemented so that full internal PLplot resolution is used; extraneous
whitespace and line endings that were being injected into text in error have
now been removed; and differential correction to string justification is now
applied.

The result of these improvements is that our SVG device now gives the
best-looking results of all our devices.  However, currently you must be
careful of which SVG viewer or editor you try because a number of them have
some bugs that need to be resolved.  For example, there is a librsvg bug in
text placement (http://bugzilla.gnome.org/show_bug.cgi?id=525023) that
affects all svg use within GNOME as well as the ImageMagick "display"
application.  However, at least the latest konqueror and firefox as well as
inkscape and scribus-ng (but not scribus!) give outstanding looking results
for files generated by our svg device driver.

2.14 Ada language support

We now have a complete Ada bindings implemented for PLplot. We also have a
complete set of our standard examples implemented in Ada which give results
that are identical with corresponding results for the C standard examples.
This is an excellent test of a large subset of the Ada bindings. We now
enable Ada by default for our users and request widespread testing of this
new feature.

2.15 OCaml language support

Thanks primarily to Hezekiah M. Carty's efforts we now have a complete OCaml
bindings implemented for PLplot. We also have a complete set of our standard
examples implemented in OCaml which give results that are identical with
corresponding results for the C standard examples. This is an excellent test
of a large subset of the OCaml bindings. We now enable OCaml by default for
our users and request widespread testing of this new feature.

2.16 Perl/PDL language support

Thanks to Doug Hunt's efforts the external Perl/PDL module,
PDL::Graphics::PLplot version 0.46 available at
http://search.cpan.org/dist/PDL-Graphics-PLplot has been brought up to date
to give access to recently added PLplot API.  The instructions for how to
install this module on top of an offical PDL release are given in
examples/perl/README.perldemos. Doug has also finished implementing a
complete set of standard examples in Perl/PDL which are part of PLplot and
which produce identical results to their C counterparts if the above updated
module has been installed.  Our build system tests the version of
PDL::Graphics::PLplot that is available, and if it is not 0.46 or later, the
list of Perl/PDL examples that are run as part of our standard tests is
substantially reduced to avoid examples that use the new functionality.  In
sum, if you use PDL::Graphics::PLplot version 0.46 or later the full
complement of PLplot commands is available to you from Perl/PDL, but
otherwise not.

2.17 Updates to various language bindings

A concerted effort has been made to bring all the language bindings up to
date with recently added functions. Ada, C++, f77, f95, Java, OCaml, Octave,
Perl/PDL, Python, and Tcl now all support the common PLplot API (with the
exception of the mapping functions which are not yet implemented for all
bindings due to technical issues.) This is a significant step forward for
those using languages other than C.

2.18 Updates to various examples

To help test the updates to the language bindings the examples have been
thoroughly checked. Ada, C, C++, f77, f95, and OCaml now contain a full set
of non-interactive tests (example 1-30 excluding 14 and 17). Java, Octave,
Python and Tcl are missing example 19 because of the issue with the mapping
functions. The examples have also been checked to ensure consistent results
between different language bindings. Currently there are still some minor
differences in the results for the tcl examples, probably due to rounding
errors. The standard test suite for PLplot using ctest now carries out a
comparison of the postscript output for different languages as a check. Some
of the Tcl examples (example 21) require Tcl version 8.5 for proper support
for NaNs.

Also new is an option for the plplot_test.sh script to run the examples
using a debugging command. This is enabled using the --debug option. The
default it to use the valgrind memory checker. This has highlighted at
least one memory leaks in plplot which have been fixed. It is not part
of the standard ctest tests because it can be _very_ slow for a complete
set of language bindings and device drivers.

2.19 Rename test subdirectory to plplot_test

This change was necessary to quit clashing with the "make test" target which
now works for the first time ever (by executing ctest).

2.20 Website support files updated

Our new website content is generated with PHP and uses CSS (cascaded style
sheets) to implement a consistent style.  This new approach demanded lots of
changes in the website support files that are used to generate and upload
our website and which are automatically included with the release.

2.21 Internal changes to function visibility

The internal definitions of functions in plplot have been significantly
tidied up to allow the use of the -fvisibility=hidden option with newer
versions of gcc. This prevents internal functions from being exported
to the user where possible. This extends the existing support for this
on windows.

2.22 Dynamic driver support in Windows

An interface based on the ltdl library function calls was established
which allows to open and close dynamic link libraries (DLL) during
run-time and call functions from these libraries. As a consequence
drivers can now be compiled into single DLLs separate from the core
plplot DLL also in Windows. The cmake option ENABLE_DYNDRIVERS is now
ON by default for Windows if a shared plplot library is built.

2.23 Documentation updates

The docbook documentation has been updated to include many of the
C-specific functions (for example plAlloc2dGrid) which are not part
of the common API, but are used in the examples and may be helpful
for plplot users.



PLplot Release 5.9.0
~~~~~~~~~~~~~~~~~~~~
This is a development release of PLplot. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development
releases in the 5.9.x series will be available every few months. The next
stable release will be 5.10.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.

N.B. This is the official notice that our deprecated autotools-based build
system has now been removed.  Instead, use the CMake-based build system
following the directions in the INSTALL file.

INDEX

1. Changes relative to PLplot 5.8.0 (the previous stable release)

1.1 All autotools-related files have now been removed
1.2 Date / time labels for axes
1.3 Code cleanup
1.4 Bug fixes
1.5 Alpha value support
1.6 Build system improvements
1.7 Implement build-system infrastructure for installed Ada bindings and
examples
1.8 WxWidgets driver improvements
1.9 External libLASi library improvements affecting our psttf device.


1.1 All autotools-related files have now been removed

CMake (with the exception of a special build script for the DJGPP platform)
is now the only supported build system. It has been tested on Linux / Unix,
Mac OS-X and Windows platforms.

1.2 Date / time labels for axes

Plplot now allows date / time labels to be used on axes. A new option
('d') is available for the xopt and yopt arguments to plbox which
indicates that the axis should be interpreted as a date / time. Similarly
there is a new range of options for plenv to select date / time labels.
The time format is seconds since the epoch (usually 1 Jan 1970). This
format is commonly used on most systems. The C gmtime routine can be
used to calculate this for a given date and time. The format for the
labels is controlled using a new pltimefmt function, which takes a
format string. All formatting is done using the C strftime function.
See documentation for available options on your platform. Example 29
demonstrates the new capabilities.

1.3 Code cleanup

The plplot source code has been cleaned up to make consistent use of
(const char *) and (char *) throughout. Some API functions have changed
to use const char * instead of char * to make it clear that the strings
are not modified by the function. The C and C++ examples have been updated
consistent with this. These changes fix a large number of warnings
with gcc-4.2. Note: this should not require programs using plplot to be
recompiled as it is not a binary API change.

There has also been some cleanup of include files in the C++ examples
so the code will compile with the forthcoming gcc-4.3.

1.4 Bug fixes

Various fixes including:

Ctest will now work correctly when the build tree path includes symlinks.

Dependencies for swig generated files fixed so they are not rebuilt every
time make is called.

Various dependency fixes to ensure that parallel builds (using make -j)
work under unix.

1.5 Alpha value support

PLplot core has been modified to support a transparency or alpha value
channel for each color in color map 0 and 1. In addition a number of new
functions were added the PLplot API so that the user can both set and query
alpha values for color in the two color maps. These functions have the same
name as their non-alpha value equivalents, but with a an "a" added to the
end. Example 30 demonstrates some different ways to use these functions
and the effects of alpha values, at least for those drivers that support alpha
values. This change should have no effect on the device drivers that do not
currently support alpha values. Currently only the cairo, gd, wxwidgets and
aquaterm drivers support alpha values. There are some limitations with the gd
driver due to transparency support in the underlying libgd library.

1.6 Build system improvements

We now transform link flag results delivered to the CMake environment by
pkg-config into the preferred CMake form of library information.  The
practical effect of this improvement is that external libraries in
non-standard locations now have their rpath options set correctly for our
build system both for the build tree and the install tree so you don't have
to fiddle with LD_LIBRARY_PATH, etc.

1.7 Implement build-system infrastructure for installed Ada bindings and
examples

Install source files, library information files, and the plplotada library
associated with the Ada bindings.  Configure and install the pkg-config file
for the plplotada library.  Install the Ada examples and a configured Makefile
to build them in the install tree.

1.8 WxWidgets driver improvements

A number of small bug fixes. New functionality includes menu options to
save the current plot in different formats.

1.9 External libLASi library improvements affecting our psttf device.

Our psttf device depends on the libLASi library. libLASi-1.1.0 has just been
released at http://sourceforge.net/svn/?group_id=187113 .  We recommend
using this latest version of libLASi for building PLplot and the psttf
device since this version of libLASi is more robust against glyph
information returned by pango/cairo/fontconfig that on rare occasions is not
suitable for use by libLASi.


PLplot Release 5.8.0
~~~~~~~~~~~~~~~~~~~~

This is a stable release of PLplot. It represents the ongoing efforts of the
community to improve the PLplot plotting package. Development releases in the
5.9.x series will be available every few months. The next stable release will
be 5.10.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 warranties, given in the COPYING.LIB
file.

N.B. This is the official notice that our deprecated autotools-based build
system is scheduled for removal starting with the 5.9.0 release.  The reason
for this decision is the PLplot developers and users are happy with our
CMake-based build system (see below), and nobody has been willing to spend
time maintaining our old autotools-based build system.

Note for Windows users:
The same holds for the old Windows build system in sys/win32/msdev. This
build system is much less flexible than the CMake-based system. It also
lacks a larger number of important features - freetype text, language
bindings and so on. With the 5.9.0 release the source distribution will
no longer contain this directory. Hence you should switch to the new
build system described below.

Note for gfortran users of our f95 bindings: gfortran version 4.2.1 or later
is a requirement, see fortran 95 bindings remarks below.

Note for OS-X users:
The Octave bindings no longer work for Octave 2.1.73. Work is ongoing to
try and solve this problem.


INDEX

1. Changes relative to PLplot 5.7.4
  1.1 Drivers
    1.1.1 cairo devices
    1.1.2 plmeta/plrender
  1.2 Fortran 95 bindings
  1.3 plmtex3/plptex3
  1.4 Octave 2.9

2. Changes relative to PLplot 5.6.1
  2.1 CVS to Subversion conversion
  2.2 CMake build system
  2.3 Plot Buffering
  2.4 Updated INSTALL/README
  2.5 malloc/calloc clean up
  2.6 Documentation
  2.7 Additions to the PLplot API
  2.8 Language bindings
    2.8.1 ADA language binding
    2.8.2 wxwidgets applications bindings
    2.8.3 Python bindings
    2.8.4 Fortran 95 bindings
    2.8.5 Octave 2.9
  2.9 Updated examples
  2.10 Drivers
    2.10.1 psttf
    2.10.2 svg
    2.10.3 wxwidgets
    2.10.4 pdf
    2.10.5 gd, wingcc (freetype)
    2.10.6 cairo
    2.10.7 pstex
    2.10.8 plmeta (and plrender application to render plmeta results).


1. Changes relative to PLplot 5.7.4 (the previous development release)

1.1 Drivers
   1.1.1 cairo devices
     The xwinttf driver has been renamed xcairo. In addition most of the
     other devices that are theoretically possible with Cairo have been
     implemented. These are a PostScript device (pscairo), a PNG device
     (pngcairo), a PDF device (pdfcairo), an SVG device (svgcairo), and a
     memory device (memcairo). The cairo device driver is still considered
     experimental as a whole. Known issues include improper text rendering
     with svgcairo and memcairo not working at all so those two devices are
     disabled by default.  The pngcairo, pscairo, and xcairo devices appear
     to work without problems and also give outstanding-looking antialiased
     and hinted results so are enabled by default. The pdfcairo device
     appears to work reasonably well so is enabled by default although it is
     not as mature as the other Cairo devices that are enabled.

   1.1.2 plmeta/plrender
     The combination of the plmeta device and the plrender application
     that renders plmeta results is unmaintained and has some known issues
     with strings, aspect ratio changes, and fonts.  Therefore, the plmeta
     device is now not enabled by default, and must be specifically enabled
     by the user using the -DPLD_plmeta=ON cmake option.  Furthermore,
     plrender is not built or installed and the plrender man page is not
     installed unless the plmeta device is specifically enabled.

1.2 Fortran 95 bindings

    Equivalance statements in our F95 bindings were causing problems for
    one fortran 95 compiler so we have dropped those equivalence statements
    and use the transfer intrinsic instead.  However, for gfortran that
    intrinsic was only implemented for version 4.2.1 so that is the
    minimum version requirement for gfortran now if you attempt to build
    the f95 bindings.  Note, earlier versions of gfortran build the f77
    bindings with no problems.

1.3  plmtex3/plptex3

    These two functions, which were added in release 5.7.3, had a number
    of bugs. These have hopefully been cleaned up. Example 28 demonstrates
    how to use these functions. The functions and the example have now been
    implemented for most language bindings.

1.4 Octave 2.9

    Octave 2.9 has a number of significant differences from version 2.1.
    The octave language bindings have been updated to work with this new
    version since the latest 2.9.x release is now the "recommended" choice
    by the octave developers. Note that all the low-level plplot functions
    work as expected. The higher level functions which replace the default
    octave / gnuplot plotting commands mostly work as for version 2.1. They
    do not (yet) replicate the new and more Matlab-like functionality in
    the latest 2.9.x releases of Octave.

    Note: As a result of the compatibilty code for octave 2.1 and lower the
    octave bindings will generate spurious warnings about obsolete built-in
    variables when using octave 2.9. These can be silenced using the command
        warning("off","Octave:built-in-variable-assignment");
    before using the plplot bindings. This is not enabled by default as it
    would also turn off genuine warnings in your own code which you might
    want to fix.


2. Changes relative to PLplot 5.6.1 (the previous stable release)

2.1 CVS to Subversion conversion

   PLplot now uses the Subversion (svn) version control system. Records of
all the changes and release tags have been preserved from the CVS repository.

2.2 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated and is scheduled for removal as
of the 5.9.0 release. The switch to CMake was made due its superior support
for Windows platforms and its relative simplicity compared to autotools on
Unix. To use CMake to configure and build PLplot follow the directions at
http://www.miscdebris.net/plplot_wiki/.

2.3 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

2.4 Updated INSTALL/README

   The INSTALL and README files have been updated. They now include detailed
instructions for building plplot using the new CMake build system on Linux
and Windows.

2.5 malloc/calloc clean up

   Checks have been added to many (all?) of the calls to calloc and malloc in
the PLplot core. The purpose of the check is to verify that the memory
requested was actually allocated prior to attempting to use it.

2.6 Documentation

   The API section has been expanded to include information about how to call
the functions from Fortran95, Java, Perl/PDL and Python. Since array dimension
information is typically redundant in these languages it is dropped in many
of the relevant function. Additionally, some of the Perl/PDL function calls
have a different argument order than their C equivalent. This section has also
been expanded to include a list of which examples each function is used in
(if any).

   The Fortran95 documentation has been updated.

2.7 Additions to the PLplot API

   The functions plptex3 and plmtex3 have been added to the PLplot API. These
allow the user to draw text in "3D" on the 3D plots. plptex3 is the 3D
equivalent of plptex and plmtex3 is the 3D equivalent of plmtex. Their
use is demonstrated by example 28.

2.8 Language bindings
  2.8.1 ADA
       Jerry Bauck has donated bindings to the ADA programming language.
    These bindings have been included into the CMake build system,
    and should be generated automatically if you have an ADA compiler and
    you specify the cmake option -DENABLE_ada=ON. The ADA bindings are now
    considered complete and the current focus is on implementing all of the
    examples in ADA to help test the bindings.  Until that work is completed
    these bindings should be considered experimental.

  2.8.2 wxwidgets applications bindings
       The wxWidgets bindings provide an interface to the PLplot API and a
    simple widget to be used in a wxWidgets application. The class
    'wxPLplotstream' inherited from the PLplot class 'plstream' allows access
    to the complete PLplot API. 'wxPLplotWindow' is a simple wxWidget which
    takes care of some preparatory work for convenient use of the PLplot
    Library within a wxWidgets application.

  2.8.3 Python bindings
    The Python bindings have been updated to use numpy rather than the now
    deprecated Numeric python numeric library.

  2.8.4 Fortran 95 bindings
    Equivalance statements in our F95 bindings were causing problems for
    one fortran 95 compiler so we have dropped those equivalence statements
    and use the transfer intrinsic instead.  However, for gfortran that
    intrinsic was only implemented for version 4.1.2 so that is the
    minimum version requirement for gfortran now if you attempt to build
    the f95 bindings.  Note, earlier versions of gfortran build the f77
    bindings with no problems.

  2.8.5 Octave 2.9
    Octave 2.9 has a number of significant differences from version 2.1.
    The octave language bindings have been updated to work with this new
    version since the latest 2.9.x release is now the "recommended" choice
    by the octave developers. Note that all the low-level plplot functions
    work as expected. The higher level functions which replace the default
    octave / gnuplot plotting commands mostly work as for version 2.1. They
    do not (yet) replicate the new and more Matlab-like functionality in
    the latest 2.9.x releases of Octave.

    Note: As a result of the compatibilty code for octave 2.1 and lower the
    octave bindings will generate spurious warnings about obsolete built-in
    variables when using octave 2.9. These can be silenced using the command
        warning("off","Octave:built-in-variable-assignment");
    before using the plplot bindings. This is not enabled by default as it
    would also turn off genuine warnings in your own code which you might
    want to fix.

2.9 Updated examples

   The examples have been checked over to make sure that they all work
and to make them more consistent across different programming languages.

2.10 Drivers
  2.10.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  2.10.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  2.10.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antialiasing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antialiasing turned off. In addition the antialiasing code can
    now handle filled polygons and window resizing.

  2.10.4 pdf
    A basic version of a pdf driver was added to the latest PLplot release.
    This driver is based on the libharu library
    (http://libharu.sourceforge.net/). At present only the Hershey fonts are
    used and there is no support for pdf or TrueType fonts. Compression of the
    pdf output is not enabled and the paper size can't be chosen. All these
    issues will be addressed in later releases.

  2.10.5 gd, wingcc (freetype)
    Improved anti-aliasing routines have been added to PLplot's freetype
    font rendering engine. The gd and wingcc drivers have been modified in
    turn to take advantage of these new routines, leading to improved text
    rendering.

  2.10.6 cairo
    This is a family of drivers that use the Cairo graphics library to
    render text and graphics. The graphics and the text are both
    anti-aliased which yields some outstanding-looking results. This driver
    is unicode enabled, and Truetype fonts are used by default. Most of the
    devices that are theoretically possible with Cairo have been
    implemented. These are an X device (xcairo), a PostScript device
    (pscairo), a PNG device (pngcairo, a PDF device (pdfcairo), an SVG
    device (svgcairo), and a memory device (memcairo). The cairo device
    driver is still considered experimental as a whole. Known issues include
    improper text rendering with svgcairo and memcairo not working at all so
    those two devices are disabled by default.  The pngcairo, pscairo, and
    xcairo devices appear to work without problems and also give
    outstanding-looking antialiased and hinted results so are enabled by
    default. The pdfcairo device appears to work reasonable well so is
    enabled by default although it is not as mature as the other three cairo
    devices that are enabled.

  2.10.7 pstex driver
       This Latex driver has now been resurrected from years of neglect and
    aside from bounding box issues seems to be working well.  Should be
    useful for Latex enthusiasts.

  2.10.8 plmeta driver
    The combination of the plmeta device and the plrender application that
    renders plmeta results is unmaintained and has some known issues with
    strings, aspect ratio changes, and fonts.  Therefore, the plmeta device
    is now not enabled by default, and must be specifically enabled by the
    user using the -DPLD_plmeta=ON cmake option. Furthermore, plrender is
    not built or installed and the plrender man page is not installed unless
    the plmeta device is specifically enabled.


PLplot Release 5.8.0-RC1
~~~~~~~~~~~~~~~~~~~~~~~~

This is a stable release of PLplot. It represents the ongoing efforts of the
community to improve the PLplot plotting package. Development releases in the
5.9.x series will be available every few months. The next stable release will
be 5.10.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 warranties, given in the COPYING.LIB
file.

N.B. This is the official notice that our deprecated autotools-based build
system is scheduled for removal starting with the 5.9.0 release.  The reason
for this decision is the PLplot developers and users are happy with our
CMake-based build system (see below), and nobody has been willing to spend
time maintaining our old autotools-based build system.

Note for Windows users:
The same holds for the old Windows build system in sys/win32/msdev. This
build system is much less flexible than the CMake-based system. It also
lacks a larger number of important features - freetype text, language
bindings and so on. With the 5.9.0 release the source distribution will
no longer contain this directory. Hence you should switch to the new
build system described below.

Note for gfortran users of our f95 bindings: gfortran version 4.1.2 or later
is a requirement, see fortran 95 bindings remarks below.

INDEX

1. Changes relative to PLplot 5.7.4
  1.1 Drivers
    1.1.1 cairo devices
    1.1.2 plmeta/plrender
  1.2 Fortran 95 bindings
  1.3 plmtex3/plptex3
  1.4 Octave 2.9

2. Changes relative to PLplot 5.6.1
  2.1 CVS to Subversion conversion
  2.2 CMake build system
  2.3 Plot Buffering
  2.4 Updated INSTALL/README
  2.5 malloc/calloc clean up
  2.6 Documentation
  2.7 Additions to the PLplot API
  2.8 Language bindings
    2.8.1 ADA language binding
    2.8.2 wxwidgets applications bindings
    2.8.3 Python bindings
    2.8.4 Fortran 95 bindings
    2.8.5 Octave 2.9
  2.9 Updated examples
  2.10 Drivers
    2.10.1 psttf
    2.10.2 svg
    2.10.3 wxwidgets
    2.10.4 pdf
    2.10.5 gd, wingcc (freetype)
    2.10.6 cairo
    2.10.7 pstex
    2.10.8 plmeta (and plrender application to render plmeta results).


1. Changes relative to PLplot 5.7.4 (the previous development release)

1.1 Drivers
   1.1.1 cairo devices
     The xwinttf driver has been renamed xcairo. In addition most of the
     other devices that are theoretically possible with Cairo have been
     implemented. These are a PostScript device (pscairo), a PNG device
     (pngcairo), a PDF device (pdfcairo), an SVG device (svgcairo), and a
     memory device (memcairo). The cairo device driver is still considered
     experimental as a whole. Known issues include improper text rendering
     with svgcairo and memcairo not working at all so those two devices are
     disabled by default.  The pngcairo, pscairo, and xcairo devices appear
     to work without problems and also give outstanding-looking antialiased
     and hinted results so are enabled by default. The pdfcairo device
     appears to work reasonably well so is enabled by default although it is
     not as mature as the other Cairo devices that are enabled.

   1.1.2 plmeta/plrender
     The combination of the plmeta device and the plrender application
     that renders plmeta results is unmaintained and has some known issues
     with strings, aspect ratio changes, and fonts.  Therefore, the plmeta
     device is now not enabled by default, and must be specifically enabled
     by the user using the -DPLD_plmeta=ON cmake option.  Furthermore,
     plrender is not built or installed and the plrender man page is not
     installed unless the plmeta device is specifically enabled.

1.2 Fortran 95 bindings

    Equivalance statements in our F95 bindings were causing problems for
    one fortran 95 compiler so we have dropped those equivalence statements
    and use the transfer intrinsic instead.  However, for gfortran that
    intrinsic was only implemented for version 4.1.2 so that is the
    minimum version requirement for gfortran now if you attempt to build
    the f95 bindings.  Note, earlier versions of gfortran build the f77
    bindings with no problems.

1.3  plmtex3/plptex3

    These two functions, which were added in release 5.7.3, had a number
    of bugs. These have hopefully been cleaned up. Example 28 demonstrates
    how to use these functions. The functions and the example have now been
    implemented for most language bindings.

1.4 Octave 2.9

    Octave 2.9 has a number of significant differences from version 2.1.
    The octave language bindings have been updated to work with this new
    version since the latest 2.9.x release is now the "recommended" choice
    by the octave developers. Note that all the low-level plplot functions
    work as expected. The higher level functions which replace the default
    octave / gnuplot plotting commands mostly work as for version 2.1. They
    do not (yet) replicate the new and more Matlab-like functionality in
    the latest 2.9.x releases of Octave.

    Note: As a result of the compatibilty code for octave 2.1 and lower the
    octave bindings will generate spurious warnings about obsolete built-in
    variables when using octave 2.9. These can be silenced using the command
        warning("off","Octave:built-in-variable-assignment");
    before using the plplot bindings. This is not enabled by default as it
    would also turn off genuine warnings in your own code which you might
    want to fix.


2. Changes relative to PLplot 5.6.1 (the previous stable release)

2.1 CVS to Subversion conversion

   PLplot now uses the Subversion (svn) version control system. Records of
all the changes and release tags have been preserved from the CVS repository.

2.2 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated and is scheduled for removal as
of the 5.9.0 release. The switch to CMake was made due its superior support
for Windows platforms and its relative simplicity compared to autotools on
Unix. To use CMake to configure and build PLplot follow the directions at
http://www.miscdebris.net/plplot_wiki/.

2.3 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

2.4 Updated INSTALL/README

   The INSTALL and README files have been updated. They now include detailed
instructions for building plplot using the new CMake build system on Linux
and Windows.

2.5 malloc/calloc clean up

   Checks have been added to many (all?) of the calls to calloc and malloc in
the PLplot core. The purpose of the check is to verify that the memory
requested was actually allocated prior to attempting to use it.

2.6 Documentation

   The API section has been expanded to include information about how to call
the functions from Fortran95, Java, Perl/PDL and Python. Since array dimension
information is typically redundant in these languages it is dropped in many
of the relevant function. Additionally, some of the Perl/PDL function calls
have a different argument order than their C equivalent. This section has also
been expanded to include a list of which examples each function is used in
(if any).

   The Fortran95 documentation has been updated.

2.7 Additions to the PLplot API

   The functions plptex3 and plmtex3 have been added to the PLplot API. These
allow the user to draw text in "3D" on the 3D plots. plptex3 is the 3D
equivalent of plptex and plmtex3 is the 3D equivalent of plmtex. Their
use is demonstrated by example 28.

2.8 Language bindings
  2.8.1 ADA
       Jerry Bauck has donated bindings to the ADA programming language.
    These bindings have been included into the CMake build system,
    and should be generated automatically if you have an ADA compiler and
    you specify the cmake option -DENABLE_ada=ON. The ADA bindings are now
    considered complete and the current focus is on implementing all of the
    examples in ADA to help test the bindings.  Until that work is completed
    these bindings should be considered experimental.

  2.8.2 wxwidgets applications bindings
       The wxWidgets bindings provide an interface to the PLplot API and a
    simple widget to be used in a wxWidgets application. The class
    'wxPLplotstream' inherited from the PLplot class 'plstream' allows access
    to the complete PLplot API. 'wxPLplotWindow' is a simple wxWidget which
    takes care of some preparatory work for convenient use of the PLplot
    Library within a wxWidgets application.

  2.8.3 Python bindings
    The Python bindings have been updated to use numpy rather than the now
    deprecated Numeric python numeric library.

  2.8.4 Fortran 95 bindings
    Equivalance statements in our F95 bindings were causing problems for
    one fortran 95 compiler so we have dropped those equivalence statements
    and use the transfer intrinsic instead.  However, for gfortran that
    intrinsic was only implemented for version 4.1.2 so that is the
    minimum version requirement for gfortran now if you attempt to build
    the f95 bindings.  Note, earlier versions of gfortran build the f77
    bindings with no problems.

  2.8.5 Octave 2.9
    Octave 2.9 has a number of significant differences from version 2.1.
    The octave language bindings have been updated to work with this new
    version since the latest 2.9.x release is now the "recommended" choice
    by the octave developers. Note that all the low-level plplot functions
    work as expected. The higher level functions which replace the default
    octave / gnuplot plotting commands mostly work as for version 2.1. They
    do not (yet) replicate the new and more Matlab-like functionality in
    the latest 2.9.x releases of Octave.

    Note: As a result of the compatibilty code for octave 2.1 and lower the
    octave bindings will generate spurious warnings about obsolete built-in
    variables when using octave 2.9. These can be silenced using the command
        warning("off","Octave:built-in-variable-assignment");
    before using the plplot bindings. This is not enabled by default as it
    would also turn off genuine warnings in your own code which you might
    want to fix.

2.9 Updated examples

   The examples have been checked over to make sure that they all work
and to make them more consistent across different programming languages.

2.10 Drivers
  2.10.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  2.10.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  2.10.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antialiasing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antialiasing turned off. In addition the antialiasing code can
    now handle filled polygons and window resizing.

  2.10.4 pdf
    A basic version of a pdf driver was added to the latest PLplot release.
    This driver is based on the libharu library
    (http://libharu.sourceforge.net/). At present only the Hershey fonts are
    used and there is no support for pdf or TrueType fonts. Compression of the
    pdf output is not enabled and the paper size can't be chosen. All these
    issues will be addressed in later releases.

  2.10.5 gd, wingcc (freetype)
    Improved anti-aliasing routines have been added to PLplot's freetype
    font rendering engine. The gd and wingcc drivers have been modified in
    turn to take advantage of these new routines, leading to improved text
    rendering.

  2.10.6 cairo
    This is a family of drivers that use the Cairo graphics library to
    render text and graphics. The graphics and the text are both
    anti-aliased which yields some outstanding-looking results. This driver
    is unicode enabled, and Truetype fonts are used by default. Most of the
    devices that are theoretically possible with Cairo have been
    implemented. These are an X device (xcairo), a PostScript device
    (pscairo), a PNG device (pngcairo, a PDF device (pdfcairo), an SVG
    device (svgcairo), and a memory device (memcairo). The cairo device
    driver is still considered experimental as a whole. Known issues include
    improper text rendering with svgcairo and memcairo not working at all so
    those two devices are disabled by default.  The pngcairo, pscairo, and
    xcairo devices appear to work without problems and also give
    outstanding-looking antialiased and hinted results so are enabled by
    default. The pdfcairo device appears to work reasonable well so is
    enabled by default although it is not as mature as the other three cairo
    devices that are enabled.

  2.10.7 pstex driver
       This Latex driver has now been resurrected from years of neglect and
    aside from bounding box issues seems to be working well.  Should be
    useful for Latex enthusiasts.

  2.10.8 plmeta driver
    The combination of the plmeta device and the plrender application that
    renders plmeta results is unmaintained and has some known issues with
    strings, aspect ratio changes, and fonts.  Therefore, the plmeta device
    is now not enabled by default, and must be specifically enabled by the
    user using the -DPLD_plmeta=ON cmake option. Furthermore, plrender is
    not built or installed and the plrender man page is not installed unless
    the plmeta device is specifically enabled.


PLplot Release 5.7.4
~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot. It represents the ongoing
efforts of the community to improve the PLplot plotting package. Development
releases in the 5.7.x series will be available every few months. The next
stable release will be 5.8.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. Changes relative to PLplot 5.7.3
  1.1 CVS to Subversion conversion
  1.2 Drivers
    1.2.1 xwinttf -> xcairo
  1.3 Ada bindings
  1.4 Python bindings
  1.5 Fortran95 Documentation

2. Changes relative to PLplot 5.6.1
  2.1 CVS to Subversion conversion
  2.2 CMake build system
  2.3 Plot Buffering
  2.4 Updated INSTALL/README
  2.5 malloc/calloc clean up
  2.6 Documentation
  2.7 Additions to the PLplot API
  2.8 Language bindings
    2.8.1 Experimental ADA language binding
    2.8.2 wxwidgets applications bindings
  2.9 Updated examples
  2.10 Drivers
    2.10.1 psttf
    2.10.2 svg
    2.10.3 wxwidgets
    2.10.4 pdf
    2.10.5 gd, wingcc (freetype)
    2.10.6 cairo
    2.10.7 pstex
  2.11 Python bindings
  2.12 Fortran95 Documentation


1. Changes relative to PLplot 5.7.3 (the previous development release)

1.1 CVS to Subversion conversion

   PLplot now uses the Subversion (svn) version control system. Records of
all the changes and release tags have been preserved from the CVS repository.

1.2 Drivers
   1.2.1 xwinttf -> xcairo
        The xwinttf driver has been renamed xcairo. In addition most of the
     the other output devices that Cairo supports are now supported. These
     include a postscript driver (pscairo), a PDF driver (pdfcairo), a
     SVG driver (svgcairo), a PNG driver (pngcairo) and a memory driver
     (memcairo). This driver is still considered experimental. Known issues
     include improper text rendering with the SVG driver and the memory
     driver does not work at all.

1.3 Ada bindings

    The ADA bindings are now considered complete and the current focus is on
implementing all of the examples in ADA.

1.4 Python bindings

    The Python bindings have been updated to use numpy rather than the now
deprecated Numeric python numeric library. If you need to revert to the old
Numeric support, then you should specify the cmake option -DHAVE_NUMPY=OFF.

1.5 Fortran95 documentation

    The Fortran95 documentation has been updated.


2. Changes relative to PLplot 5.6.1 (the previous stable release)

2.1 CVS to Subversion conversion

   PLplot now uses the Subversion (svn) version control system. Records of
all the changes and release tags have been preserved from the CVS repository.

2.2 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated. The switch to CMake was made due
its superior support for Windows platforms and its relative simplicity
compared to autotools. CMake 2.4.5 is the minimum required version of cmake.
Finding swig has been improved such that it should now be found as long as
it is in your path.

2.3 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

2.4 Updated INSTALL/README

   The INSTALL and README files have been updated. They now include detailed
instructions for building plplot using the new CMake build system on linux
and windows.

2.5 malloc/calloc clean up

   Checks have been added to many (all?) of the calls to calloc and malloc in
the PLplot core. The purpose of the check is to verify that the memory
requested was actually allocated prior to attempting to use it.

2.6 Documentation

   The API section has been expanded to include information about how to call
the functions from Fortran95, Java, Perl/PDL and Python. Since array dimension
information is typically redundant in these languages it is dropped in many
of the relevant function. Additionally, some of the Perl/PDL function calls
have a different argument order than their C equivalent. This section has also
been expanded to include a list of which examples each function is used in
(if any).

2.7 Additions to the PLplot API

   The functions plptex3 and plmtex3 have been added to the PLplot API. These
allow the user to draw text in "3D" on the 3D plots. plptex3 is the 3D
equivalent of plptex and plmtex3 is the 3D equivalent of plmtex.

2.8 Language bindings
  2.8.1 ADA
       Jerry Bauck has donated bindings to the ADA programming language.
    These are considered experimental in nature and the API is subject to
    change.  These bindings have been included into the CMake build system,
    and should be generated automatically if you have an ADA compiler and
    you specify the cmake option -DENABLE_ada=ON.  Four standard examples
    have been completed and work on a complete set of examples is ongoing.

  2.8.2 wxwidgets applications bindings
       The wxWidgets bindings provide an interface to the PLplot API and a
    simple widget to be used in a wxWidgets application. The class
    'wxPLplotstream' inherited from the PLplot class 'plstream' allows access
    to the complete PLplot API. 'wxPLplotWindow' is a simple wxWidget which
    takes care of some preparational work for convenient use of the PLplot
    Library within a wxWidgets application.

2.9 Updated examples

   The examples have been checked over to make sure that they all work
and to make them more consistent across different programming languages.

2.10 Drivers
  2.10.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  2.10.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  2.10.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antializing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antializing turned off. In addition the antializing code can
    now handle filled polygons and window resizing.

  2.10.4 pdf
    A basic version of a pdf driver was added to the latest PLplot release.
    This driver is based on the libharu library
    (http://libharu.sourceforge.net/). At present only the hershey fonts are
    used and there is no support for pdf or ttf fonts. Compression of the pdf
    output is not enabled and the paper size can't be chosen. All these issues
    will be addressed in later releases.

  2.10.5 gd, wingcc (freetype)
    Improved anti-aliasing routines have been added to plplot's freetype
    font rendering engine. The gd and wingcc drivers have been modified in
    turn to take advantage of these new routines, leading to improved text
    rendering.

  2.10.6 cairo
       This is a family of drivers that use the Cairo graphics library to
    render text and graphics. The graphics and the text are both
    anti-aliased. It is unicode enabled and Truetype fonts are used by
    default. Most of the the output devices that Cairo supports are
    supported. These include a X windows driver (xcairo), a postscript
    driver (pscairo), a PDF driver (pdfcairo), a SVG driver (svgcairo), a
    PNG driver (pngcairo) and a memory driver (memcairo). This driver is
    still considered experimental. Known issues include improper text
    rendering with the SVG driver and the memory driver does not work at
    all.

  2.10.7 pstex driver
       This Latex driver has now been resurrected from years of neglect and
    aside from bounding box issues seems to be working well.  Should be
    useful for Latex enthusiasts.

1.4 Python bindings

    The Python bindings have been updated to use numpy rather than the now
deprecated Numeric python numeric library.

1.5 Fortran95 documentation

    The Fortran95 documentation has been updated.


PLplot Release 5.7.3
~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot. It represents the ongoing
efforts of the community to improve the PLplot plotting package. Development
releases in the 5.7.x series will be available every few months. The next
stable release will be 5.8.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. Changes relative to PLplot 5.7.2
  1.1 CMake build system
  1.2 malloc/calloc clean up
  1.3 Documentation
  1.4 Additions to the PLplot API
  1.5 Language bindings
    1.5.1 Experimental ADA language binding
    1.5.2 wxwidgets applications bindings
  1.6 Drivers
    1.6.1 xwinttf
    1.6.2 pstex

2. Changes relative to PLplot 5.6.1
  2.1 CMake build system
  2.2 Plot Buffering
  2.3 Updated INSTALL/README
  2.4 malloc/calloc clean up
  2.5 Documentation
  2.6 Additions to the PLplot API
  2.7 Language bindings
    2.7.1 Experimental ADA language binding
    2.7.2 wxwidgets applications bindings
  2.8 Updated examples
  2.9 Drivers
    2.9.1 psttf
    2.9.2 svg
    2.9.3 wxwidgets
    2.9.4 pdf
    2.9.5 gd, wingcc (freetype)
    2.9.6 xwinttf
    2.9.7 pstex


1. Changes relative to PLplot 5.7.2 (the previous development release)

1.1 CMake build system

   Finding swig has been improved such that it should now be found as long
as it is in your path.

1.2 malloc/calloc clean up

   Checks have been added to many (all?) of the calls to calloc and malloc in
the PLplot core. The purpose of the check is to verify that the memory
requested was actually allocated prior to attempting to use it.

1.3 Documentation

   The API section has been expanded to include information about how to call
the functions from Fortran95, Java, Perl/PDL and Python. Since array dimension
information is typically redundant in these languages it is dropped in many
of the relevant function. Additionally, some of the Perl/PDL function calls
have a different argument order than their C equivalent. This section has also
been expanded to include a list of which examples each function is used in
(if any).

1.4 Additions to the PLplot API

   The functions plptex3 and plmtex3 have been added to the PLplot API. These
allow the user to draw text in "3D" on the 3D plots. plptex3 is the 3D
equivalent of plptex and plmtex3 is the 3D equivalent of plmtex.

1.5 Language bindings
  1.5.1 ADA
       Jerry Bauck has donated bindings to the ADA programming language.
    These are considered experimental in nature and the API is subject to
    change.  These bindings have been included into the CMake build system,
    and should be generated automatically if you have an ADA compiler and
    you specify the cmake option -DENABLE_ada=ON.  Four standard examples
    have been completed and work on a complete set of examples is ongoing.

  1.5.2 wxwidgets applications bindings
       The wxWidgets bindings provide an interface to the PLplot API and a
    simple widget to be used in a wxWidgets application. The class
    'wxPLplotstream' inherited from the PLplot class 'plstream' allows access
    to the complete PLplot API. 'wxPLplotWindow' is a simple wxWidget which
    takes care of some preparational work for convenient use of the PLplot
    Library within a wxWidgets application.

1.6 Drivers

  1.6.1 xwinttf driver
       This is a new driver for X Windows that uses Cairo for rendering
    graphics and Pango for rendering text. The graphics and the text are both
    anti-aliased. It is unicode enabled and Truetype fonts are used by
    default.

  1.6.2 pstex driver
       This Latex driver has now been resurrected from years of neglect and
    aside from bounding box issues seems to be working well.  Should be
    useful for Latex enthusiasts.

2. Changes relative to PLplot 5.6.1 (the previous stable release)

2.1 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated. The switch to CMake was made due
its superior support for Windows platforms and its relative simplicity
compared to autotools. CMake 2.4.5 is the minimum required version of cmake.
Finding swig has been improved such that it should now be found as long as
it is in your path.

2.2 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

2.3 Updated INSTALL/README

   The INSTALL and README files have been updated. They now include detailed
instructions for building plplot using the new CMake build system on linux
and windows.

2.4 malloc/calloc clean up

   Checks have been added to many (all?) of the calls to calloc and malloc in
the PLplot core. The purpose of the check is to verify that the memory
requested was actually allocated prior to attempting to use it.

2.5 Documentation

   The API section has been expanded to include information about how to call
the functions from Fortran95, Java, Perl/PDL and Python. Since array dimension
information is typically redundant in these languages it is dropped in many
of the relevant function. Additionally, some of the Perl/PDL function calls
have a different argument order than their C equivalent. This section has also
been expanded to include a list of which examples each function is used in
(if any).

2.6 Additions to the PLplot API

   The functions plptex3 and plmtex3 have been added to the PLplot API. These
allow the user to draw text in "3D" on the 3D plots. plptex3 is the 3D
equivalent of plptex and plmtex3 is the 3D equivalent of plmtex.

2.7 Language bindings
  2.7.1 ADA
       Jerry Bauck has donated bindings to the ADA programming language.
    These are considered experimental in nature and the API is subject to
    change.  These bindings have been included into the CMake build system,
    and should be generated automatically if you have an ADA compiler and
    you specify the cmake option -DENABLE_ada=ON.  Four standard examples
    have been completed and work on a complete set of examples is ongoing.

  2.7.2 wxwidgets applications bindings
       The wxWidgets bindings provide an interface to the PLplot API and a
    simple widget to be used in a wxWidgets application. The class
    'wxPLplotstream' inherited from the PLplot class 'plstream' allows access
    to the complete PLplot API. 'wxPLplotWindow' is a simple wxWidget which
    takes care of some preparational work for convenient use of the PLplot
    Library within a wxWidgets application.

2.8 Updated examples

   The examples have been checked over to make sure that they all work
and to make them more consistent across different programming languages.

2.9 Drivers
  2.9.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  2.9.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  2.9.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antializing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antializing turned off. In addition the antializing code can
    now handle filled polygons and window resizing.

  2.9.4 pdf
    A basic version of a pdf driver was added to the latest PLplot release.
    This driver is based on the libharu library
    (http://libharu.sourceforge.net/). At present only the hershey fonts are
    used and there is no support for pdf or ttf fonts. Compression of the pdf
    output is not enabled and the paper size can't be chosen. All these issues
    will be addressed in later releases.

  2.9.5 gd, wingcc (freetype)
    Improved anti-aliasing routines have been added to plplot's freetype
    font rendering engine. The gd and wingcc drivers have been modified in
    turn to take advantage of these new routines, leading to improved text
    rendering.

  2.9.6 xwinttf driver
       This is a new driver for X Windows that uses Cairo for rendering
    graphics and Pango for rendering text. The graphics and the text are both
    anti-aliased. It is unicode enabled and Truetype fonts are used by
    default.

  2.9.7 pstex driver
       This Latex driver has now been resurrected from years of neglect and
    aside from bounding box issues seems to be working well.  Should be
    useful for Latex enthusiasts.


PLplot Release 5.7.2
~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot. It represents the ongoing
efforts of the community to improve the PLplot plotting package. Development
releases in the 5.7.x series will be available every few months. The next full
release will be 5.8.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. Changes relative to PLplot 5.7.1
  1.1 CMake build system
  1.2 Updated INSTALL/README
  1.3 Updated examples
  1.4 Drivers
    1.4.1 pdf
    1.4.2 gd, wingcc (freetype)

2. Changes relative to PLplot 5.6.1
  2.1 CMake build system
  2.2 Plot Buffering
  2.3 Drivers
    2.3.1 psttf
    2.3.2 svg
    2.3.3 wxwidgets

1. Changes relative to PLplot 5.7.1 (the previous development release)

1.1 CMake build system

   CMake 2.4.5 is the now minimum required version of cmake. A lot of work
has been done to improve this build system, particularly for Windows
platforms.

1.2 Updated INSTALL/README

   The INSTALL and README files have been updated. They now include detailed
instructions for building plplot using the new CMake build system on linux
and windows.

1.3 Updated examples

   The examples have been checked over to make sure that they all work
and to make them more consistent across different programming languages.

1.4 Drivers
  1.4.1 pdf
    A basic version of a pdf driver was added to the latest PLplot release.
    This driver is based on the libharu library
    (http://libharu.sourceforge.net/). At present only the hershey fonts are
    used and there is no support for pdf or ttf fonts. Compression of the pdf
    output is not enabled and the paper size can't be chosen. All these issues
    will be addressed in later releases.

  1.4.2 gd, wingcc (freetype)
    Improved anti-aliasing routines have been added to plplot's freetype
    font rendering engine. The gd and wingcc drivers have been modified in
    turn to take advantage of these new routines, leading to improved text
    rendering.


2. Changes relative to PLplot 5.6.1 (the previous stable release)

2.1 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated. The switch to CMake was made due
its superior support for Windows platforms and its relative simplicity
compared to autotools.

2.2 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

2.3 Drivers
  2.3.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  2.3.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  2.3.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antializing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antializing turned off. In addition the antializing code can
    now handle filled polygons and window resizing.


PLplot Release 5.7.1
~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot. It represents the ongoing
efforts of the community to improve the PLplot plotting package. Development
releases in the 5.7.x series will be available every few months. The next full
release will be 5.8.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. Changes relative to PLplot 5.6.1
  1.1 CMake build system
  1.2 Plot Buffering
  1.3 Drivers
    1.3.1 psttf
    1.3.2 svg
    1.3.3 wxwidgets


1. Changes relative to PLplot 5.6.1 (the previous stable release)

1.1 CMake build system

   PLplot now uses the CMake build system (www.cmake.org) and the older
autotools build system has been deprecated. The switch to CMake was made due
its superior support for Windows platforms and its relative simplicity
compared to autotools.

1.2 Plot Buffering

   PLplot core has been modified to buffer plot commands in memory rather than
via a unix pipe or temporary file. Testing has shown that there is 20-30%
improvement in plotting performance (i.e. speed). This is likely to be system
dependent and some may see a much larger benefit. This also resolves a problem
with some windows platforms where the temporary files were not getting deleted.

1.3 Drivers
  1.3.1 psttf
    This device driver now requires LASi version 1.0.6 or 1.0.5pl.  See
    http://www.unifont.org/lasi/ for instructions (depending on installed
    version of FreeType library) on which to choose.

  1.3.2 svg
    This is a new device driver that creates Scalable Vector Graphics files
    (http://www.w3.org/Graphics/SVG/). SVG is a XML language describing
    graphics that is supported directly or via plug-ins in most modern web
    browsers. The driver is off by default as its text handling has not been
    perfected.

  1.3.3 wxwidgets
    This driver has been updated a great deal. The most important improvements
    have been to the antializing part of the driver. It is now about 4 times
    faster than it was, and is nearly comparable in speed to the driver
    with the antializing turned off. In addition the antializing code can
    now handle filled polygons and window resizing.



PLplot Bug Fix Release 5.6.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This release corrects a number of outstanding issues with plplot that were
discovered subsequent to the 5.6.0 release. It represents the ongoing efforts
of the community to improve the PLplot plotting package. Development releases
in the 5.7.x series will be available every few months. The next full release
will be 5.8.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. Changes relative to PLplot 5.6.0
  1.1 API
    1.1.1 f95
  1.2 Drivers
    1.2.1 psttf
    1.2.2 pstex


1. Changes relative to PLplot 5.6.0 (the previous stable release)

1.1 Fortran 95

A lot of work was done to correct a number of outstanding issues with
Fortran 95 interface. All of plplot API is now available to f95 users and
a complete set of examples was created to demonstrate how to use plplot with
a f95. In its current form it is known to work with gfortran compiler. Due
to limitations in the current version of libtool it not possible to use both
a f77 and a f95 compiler to build plplot. If you desire both interfaces the
recommended approach is to compile the f77 interface with your f95 compiler,
which can be done by setting the FC and F77 environment variables at the
configuration stage.

- The API is defined via a module, so that the compiler can now check
  the argument types.
- It is now possible to pass arrays as assumed-shape arrays. This
  means: less arguments and less chances for interface errors.
- The module also defines specific parameters to describe PLplot
  options. This way, you can use symbolic names instead of
  numbers.
- The floating-point type PLFLT is now available as a KIND parameter,
  making it possible to use the same code for single and double
  precision applications - simply declare all real variables
  using the KIND facility and link with the corresponding version of
  the PLplot library.

More information is found in bindings/f95/readme_f95.txt


1.2 Drivers

1.2.1 psttf

This is a postscript driver that supports TrueType fonts. This allows access
to a far greater range of fonts and characters than is possible using Type 1
postscript fonts.

The driver requires the LASi (v1.0.5), pango and pangoft2 libraries to work.
The pango and pangoft2 libraries are widely distributed with most Linux
distributions and give the psttf driver full complex text layout (CTL)
capability (see http://plplot.sourceforge.net/examples/demo24.php for an
example of this capability).  The LASi library is not part of most
distributions at this time. The source code can be downloaded from
http://www.unifont.org/lasi/. The library is small and easy to build and
install.  Make sure you use LASi-1.0.5.  The psttf device driver uses new
capabilities in this version of LASi and no longer works with LASi-1.0.4.

This driver is now enabled by default.

1.2.2 pstex

Permanently disable the autotools build of pstex.  Other PostScript devices
(either ps or psttf) appear to give better solutions so there doesn't seem
to be much purpose in maintaining this currently broken device.



PLplot Development Release 5.6.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a stable release of PLplot. It represents the ongoing efforts of the
community to improve the PLplot plotting package. Development releases in the
5.7.x series will be available every few months. The next full release will
be 5.8.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.3
  2.1 API
    2.1.1 PLBOOL
  2.2 Drivers
    2.2.1 psttf
    2.2.2 wingcc
    2.2.3 wxwidgets
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 psttf
    3.2.3 GD (png, jpeg, gif)
    3.2.4 GCW (Gnome 2)
    3.2.5 AquaTerm (Mac OS X)
    3.2.6 Tk
    3.2.7 wxwidgets
4. Notes on Autotools
  4.1 Autotools versions
  4.2 cf/bootstrap.sh output

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.3 (the previous development release)


2.1 API


2.1.1 PLBOOL

The java interface was reworked to use the PLBOOL type.

2.1.2 Fortran 95

The language bindings have been extended to Fortran 95. While it is
possible to use the F77 bindings in a program that uses the Fortran 95
features (as Fortran 95 is almost 100% compatible with FORTRAN 77),
there are a few aspects specific to this newer standard that made
it worthwhile to support Fortran 95 explicitly:

- The API is defined via a module, so that the compiler can now check
  the argument types.
- It is now possible to pass arrays as assumed-shape arrays. This
  means: less arguments and less chances for interface errors.
- The module also defines specific parameters to describe PLplot
  options. This way, you can use symbolic names instead of
  numbers.
- The floating-point type PLFLT is now available as a KIND parameter,
  making it possible to use the same code for single and double
  precision applications - simply declare all real variables
  using the KIND facility and link with the corresponding version of
  the PLplot library.

More information is found in bindings/f95/readme_f95.txt


2.2 Drivers


2.2.1 psttf

Initial version of a postscript driver that supports TrueType fonts.
This allows access to a far greater range of fonts and characters than
is possible using purely postscript fonts.

The driver requires the LASi, pango and pangoft2 libraries to work.
The pango and pangoft2 libraries are widely distributed with most
Linux distributions at least. The LASi library is not part of most
distributions at this time. The source code can be downloaded from
http://eyegene.ophthy.med.umich.edu/lasi/. The library is small and
easy to build and install.

This driver is disabled by default. To try it you will need to add
the --enable-psttf --enable-psttfc options when running configure.

2.2.2 wingcc

Performance improvements have been implemented.

2.2.3 wxwidgets

Major upgrade that eliminated a number of bugs and added support for unicode
fonts.

2.2.4 win32

Support for UNICODE and anti-aliasing fonts added


3. Changes Relative to PLplot 5.3.1 (the previous 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 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 given 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 psttf

An initial version of a new PostScript driver that has all the functionality
of the current postscript driver and also handles TrueType fonts.


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 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 specialized API, which allows interaction with the driver,
is provided in libplplotgnome2d.  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.


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.


3.2.6 wxwidgets

This is a device driver that runs on the wxWidgets cross-platform GUI (see
http://www.wxwidgets.org/) that has been donated by Werner Smekal. The driver
is unicode-enabled. It currently provides a limited GUI but additional
capabilities are being developed.


4. Note on the Autotools that were used for this release

4.1 Autotools versions

autoconf (GNU Autoconf) 2.59
Written by David J. MacKenzie and Akim Demaille.

automake (GNU automake) 1.9.6
Written by Tom Tromey <tromey@redhat.com>.

ltmain.sh (GNU libtool) 1.5.22 (1.1220.2.365 2005/12/18 22:14:06)

4.2 cf/bootstrap.sh output

Running aclocal (GNU automake) 1.9.6... done
Running autoheader (GNU Autoconf) 2.59... done
Running libtoolize (GNU libtool) 1.5.22... done
Running automake (GNU automake) 1.9.6... done
Running autoconf (GNU Autoconf) 2.59... done
Regenerating libltdl/aclocal+configure... done



PLplot Development Release 5.5.4
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.3
  2.1 API
    2.1.1 PlplotCanvas
    2.1.2 FCI
  2.2 Drivers
    2.2.1 GCW (Gnome 2)
    2.2.2 wxwidgets
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
    3.2.6 wxwidgets


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.3 (the previous development release)


2.1 API


2.1.1 PlplotCanvas

PlplotCanvas method wrappers for PLplot functions have dropped
the prefix "pl" from the function name.  For example, the
method plplot_canvas_plline is now plplot_canvas_line.


2.1.2 FCI

Backwards incompatible API change (with respect to 5.5.3, but not with
respect to 5.3.1 since this involves a new feature within the 5.5.x
development releases).  PL_FCI_MARK changed from 0x10000000 to 0x80000000.
This should only affect users who have been inserting absolute FCI (font
characterization integer) changes within their strings to change the font in
mid-string.

2.2 Drivers


2.2.1 GCW (Gnome 2)

Performance improvements have been implemented.

2.2.2 wxwidgets

Initial version of a device to run on the wxWidgets cross-platform GUI (see
http://www.wxwidgets.org/) has been donated by Werner Smekal.  Most examples
work out of the box, but some (e.g., a segfault for example 8) currently
have problems.  More development of this immature device driver is planned.

3. Changes Relative to PLplot 5.3.1 (the previous 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 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 given 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 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 specialized API, which allows interaction with the driver,
is provided in libplplotgnome2d.  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.

3.2.6 wxwidgets

Initial version of a device to run on the wxWidgets cross-platform GUI (see
http://www.wxwidgets.org/) has been donated by Werner Smekal.  Most examples
work out of the box, but some (e.g., a segfault for example 8) currently
have problems.  More development of this immature device driver is planned.




PLplot Development Release 5.5.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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, and the
disclaimer of all warrantees, given in the COPYING.LIB file.


INDEX

1. Build Instructions
2. Changes Relative to PLplot 5.5.1
  2.1 API
  2.2 Drivers
3. Changes Relative to PLplot 5.3.1
  3.1 API
    3.1.1 Unicode
    3.1.2 Extended cmap0 support
  3.2 Drivers
    3.2.1 PostScript
    3.2.2 GD (png, jpeg, gif)
    3.2.3 GCW "Gnome Canvas Widget"
    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 (which is required for
documentation on any new feature since PLplot 5.3.1), you must 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 our last development release, PLplot 5.5.1

Progress toward our next major release with documentation improvements and a
substantial number of minor tweaks and bug fixes.

2.1 API

No change.


2.2 Drivers

No change.


3. Changes Relative to our last stable release, PLplot 5.3.1


3.1 API


3.1.1 Unicode

PLplot now allows unicode text, and this is detailed in the PLplot
Programmers Reference Manual in the section on "Setting Character
Attributes".  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.2 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.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 is unicode-enabled, and Type 1 PostScript fonts are
used by default.  Although the Type 1 symbol fonts do have a significant
number of mathemetical symbols available some key special symbols (squares,
triangles) are missing so that 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.

Tranforms to the text (i.e., rotations, shears)
have been dramatically improved, and the PostScript driver now produces
"publication quality" output with the default PostScript fonts for text
and Hershey fonts for special symbols.


3.2.2 GD (png, jpeg, gif)

The GD driver 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 Canvas Widget"

The GCW "Gnome Canvas Widget" is a new driver that provides PLplot output in
a tabbed Gnome window.  It can alternatively be used to drive a special
widget called the PlplotCanvas that can be embedded in Gnome applications.
The driver, associated widget, and specialized API are fully documented in
the PLplot Programmer's Reference Manual in the sections titled "The GCW
Driver" and "Embedding Plots in Gnome/GTK Applications", respectively.

The GCW driver is unicode-enabled, and uses TrueType fonts by default.

Special examples that demonstrate the use of the PlplotCanvas are provided
for both the C and Python programming languages.

To install the GCW driver, use the "--enable-gcw" option during the
configure step of the install process.

For more information on GTK, see http://www.gtk.org/ .


3.2.4 AquaTerm (Mac OS X)

AquaTerm is a new driver 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, however it currently only supports the
default OS X fonts which are not TrueType.

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.




PLplot Development Release 5.5.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

Feedback on this development release can be communicated 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, and the
disclaimer of all warrantees, given in the COPYING.LIB file.


INDEX

1. Build Instructions
  1.1 Tcl
2. Changes
  2.1 API
  2.2 Drivers


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 (which is required for
documentation on any new feature since PLplot 5.3.1), you must 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).


1.1 Tcl

Due to unresolved problems in the build process, tcl has been temporarily
disabled for this release.

If you must have tcl, here are the instrutions.  DO NOT ATTEMPT THIS
UNLESS YOU ARE SURE YOU KNOW WHAT YOU ARE DOING.

  1) Move all plplot files in /usr/lib and /usr/local/lib into a
     temporary directory.

  2) Use the --enable-tcl and --enable-itcl options during configure.


2. Changes


2.1 API


2.2 Drivers




PLplot Development Release 5.5.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the ongoing efforts of the community to improve the PLplot plotting package.  The next full release will be 5.6.0.


INDEX

1. Build Instructions
2. Changes
  2.1 API
    2.1.1 Unicode
  2.2 Drivers
    2.2.1 Postscript
    2.2.2 GD (png, jpeg, gif)
    2.2.3 GCW "Gnome Canvas Widget"


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 build and install the PLplot Programmer's Reference Manual (which is required for documentation on any new feature since PLplot 5.3.1), you must use:

     ./configure --enable-builddoc

Detailed instructions on building the documentation, including the packages that you will need for a successful build, are provided in this tarball under doc/docbook/README.developers.


2. Changes


2.1 API


2.1.1 Unicode

PLplot now allows unicode text, and this is detailed in the PLplot Programmers Reference Manual in the section on "Setting Character Attributes".  The escape sequence for unicode characters is

     #[nnn]

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

The new unicode capabilities are demonstrated in example x23.


2.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.


2.2.1 PostScript

The PostScript driver is unicode-enabled, and Type 1 PostScript fonts are used by default.  Because many symbols are missing from the Type 1 PostScript fonts, Hershey fonts are used for calls to "plpoin".  Tranforms to the text (i.e., rotations, shears) have been dramatically improved, and the PostScript driver now produces "publication quality" output.


2.2.2 GD (png, jpeg, gif)

The GD driver 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.


2.2.3 GCW "Gnome Canvas Widget"

The GCW "Gnome Canvas Widget" is a new driver that provides PLplot output in a tabbed Gnome window.  It can alternatively be used to drive a special widget called the PlplotCanvas that can be embedded in Gnome applications.  The driver, associated widget, and specialized API are fully documented in the PLplot Programmer's Reference Manual in the sections titled "The GCW Driver" and "Embedding Plots in Gnome/GTK Applications", respectively.

The GCW driver is unicode-enabled, and uses truetype fonts by default.

Special examples that demonstrate the use of the PlplotCanvas are provided for both the C and Python programming languages.

To install the GCW driver, use the "--enable-gcw" option during the configure step of the install process.