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.
________________________________________________________________