Re: [Plplot-general] PLplot-5.2.0 has just been released!

[Alan W. I. <ir...@be...>]

I will try to comment on what Joao and Rafael have said.

On Tue, 21 Jan 2003, [iso-8859-1] Jo=E3o Cardoso wrote:

> On Tuesday 21 January 2003 20:06, Rafael Laboissiere wrote:
>
> Hi Rafael!
>
> | * Alan W. Irwin <ir...@be...> [2003-01-21 10:23]:
> | > On Mon, 20 Jan 2003, Robert Schwebel wrote:
> | > > What's the state of the Perl/PDL interface?
> | >
> | > I don't know about PDL since that is an independent effort (see
> | > Doug Hunt's messages to this list right after PLplot-5.1.0 was
> | > released last year).
> |
> | Well, my original Perl bindings code had some limited support to PDL.
> | However, I think that Doug's approach should be superior than mine.
> |
> | > We do have a rudimentary perl interface as part of generic PLplot,
> | > but that is unsupported at this time because its developer ran out
> | > of time to work on it.
> |
> | (That is me.  I am still unable to participate to the PLplot effort.
> | Too many things on the way.)
> |
> | > Personally, I think we should abandon that approach (which depended
> | > on parsing the API from our DocBook API chapter) and go with swig
> | > instead.
> |
> | Well, my approach combined both parsing the XML source of the API
> | _and_ usign swig (see bindings/perl5/README).

OOPS.  Sorry I missed that, Rafael.  That immediately gives me much more
interest in the current perl interface.

> | I do not think that
> | parsing the XML source is a bad idea, provided that the plplot.h is
> | also automatically generated.  It is unacceptable to have two sources
> | of the same information being maintained in parallel.

Rafael, I agree that one source for our API would be better, but it will
take some effort, and we have lived with *many* parallel versions of our AP=
I
descriptions for a long time.  So it is the old tradeoff between a constant=
,
maintenance problem that makes a steady drain on our time/effort, or doing
something much better which requires a lot more immediate time/effort but
pays off later in reducing the maintenance required.  "Short term pain for
long-term gain".

Here is a summary of the current parallel API descriptions. We have the
docbook chapter describing the API, plplot.h, two separate files describing
the API for both java and python, and files describing the API for fortran
and tcl as well.  For the java and python case, the two files are almost
identical, but they *must* differ slightly because the current java
interface has cruder support of the call-back functions.  Once that is
sorted out, the two files could be merged together, but not yet.  Also,
these two files differ quite a bit from plplot.h to signal the swig typedef=
s
when something special has to be done with arguments (such as dropping
redundant dimensions from argument lists).

>
> In that case, let the documentation be generated from the code and not
> the other way around! And it's easier to maintain plplot.h than
> api.xml.

Joao, that's because api.xml has extra information such as detailed
documentation of each argument far beyond the argument types and minimal
documentation that plplot.h has at the moment.

Therefore, since doc/docbook/src/api.xml has the most documentation
information (by far) in an easily parsable form , I agree with Rafael that
this file should be the ultimate source of all other descriptions of our
API.  To implement that, scripts need to be developed to generate
include/plplot.h, bindings/python/plplotcapi, bindings/java/plplotcapi,
bindings/tcl/plapi.tpl, and the equivalent API description file(s) for
fortran.  I have put such scripts in the rough order from highest to lowest
priority.  From Rafael's comments above , it also looks like a script has
already been written to generate the required swig interface file for perl,
but I imagine there is some more work to do on that as well.

Rafael, generating include/plplot.h from doc/docbook/src/api.xml might be
the type of small project that might interest you. How about it?

Alan
__________________________
Alan W. Irwin
email: ir...@be...
phone: 250-727-2902

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the Canadian Centre for Climate Modelling and
Analysis (www.cccma.bc.ec.gc.ca) and the PLplot scientific plotting softwar=
e
package (plplot.org).

__________________________

Linux-powered Science
__________________________