There are a large variety of hand-crafted files in our source tree which
specify the public API for some component of PLplot, and it is very easy for
these files to get out of synch.  Therefore, I have just committed a script
called scripts/ that checks whether at least the
list of names of PLplot functions is identical between the various API
definition files for docbook, swig, octave, f77, and f95, and our
fundamental definition of our public API in include/plplot.h.

I have made no attempt to make this script cross-platform so it is likely
only to work on Linux.  However, it is extremely useful there.

** Swig
scripts/ swig

shows that our swig interface is consistent

** Docbook
scripts/ docbook \
|grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++'

yields the following results:


which shows which functions have missing API documentation in
doc/docbook/src/api.xml.  (The missing documentation for plimage was
discovered by Hez, yesterday, which was the original motivation
for writing this check script.)

I looked a bit further into the plarrows case, and we use something entirely
different for our "arrows" example 22 and there is a comment in
bindings/swig-support/plplotcapi.i that it is deprecated.  However, it
is not yet official deprecated by moving its source to pldeprecated.c and
moving its documention to doc/docbook/src/api-obsolete.xml.

Andrew (Ross), do you think it is time to officially deprecate plarrows, and
if so, will you please do the honors?

plot3dcl and plsurf3dl are on my ToDo list to document.

** Octave
scripts/ octave \
|grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++'

yields the following results:


The plhls, plrgb, and plrgb1 results show that those officially deprecated
functions are implemented in our octave interface.  Andrew (Ross), would you
be willing to remove those or do you want to wait until the C removal
of those currently deprecated functions?  The "-" results shows there are
quite a few PLplot functions in our public API that are missing from the
octave interface.

** f77 (and f95)
scripts/ f77 \
|grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++'

yields the following results:


and similarly for f95.  The reason why plmap is missing and plmapc is found
even though not present in plplot.h and similarly for plmeridians and
plmeridiansc is a "c" suffix was used for these functions rather than the
more usual "7".

Arjen, is there any reason for that "c" suffix on plmap and plmeridians or
may I change it to "7" (or f77) to be consistent with every other fortran
function defined by our api?

Arjen, I don't know what to make of +plsetmapformc.  Could you comment?

The remaining "-" results are because quite a few functions are missing from
our f77 and f95 API's.

** Java
While writing this I was reminded there is a hand-crafted java file
(bindings/java/ that is supposed to give complete public API
coverage so I implemented an additional check of that.  Here are the
results (as of revision 8265).

scripts/ java \
|grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++'

We have discussed plarrows above, and plshade1 and plsmem are mentioned
but deliberately not implemented in bindings/swig-support/plplotcapi.i, but
the rest are genuinely missing functions in the java API.

If anybody here knows of any other hand-crafted file in our source tree that
mentions the entire public API, please let me know (or, better yet, add the
appropriate stanza to scripts/ to check the file
against the standard results derived from include/plplot.h).

Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (

Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (; PLplot scientific plotting software
package (; the libLASi project (; the Loads of
Linux Links project (; and the Linux Brochure Project

Linux-powered Science

This email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
Plplot-devel mailing list

Reply via email to