The notes in this file concern the floating-point precision
that users should adopt when using the plplot module.

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
is supplied by the plplot module, but use of plflt is not 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. In general, the Fortran examples in this subdirectory are the
best source of documentation for users, but a strong exception to this
rule is our wide-spread use of pl_test_flt in these examples.  That
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 by 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.

Therefore, users should adapt these examples for their own use by
replacing pl_test_flt wherever it occurs with, e.g., my_float where
that parameter is defined by their code either as

integer, parameter :: my_float  = kind(1.0)

or

integer, parameter :: my_float  = kind(1.0d0)

depending on which of these two floating-point precisions is most
convenient for their own needs.

PLplot floating-point precision caveats

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.
See the examples in this directory for how these
cases are handled when pl_test_flt (to be replaced by my_float,
see above) is not the same as kind(1.0d0).