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

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

On Wed, 22 Jan 2003, Joao Cardoso wrote:

> That means that when I need to add/change something in plplot.h, because I'm
> *developing*, then I need to change api.xml.....

Joao, you do have *one* legitimate point there which I will now discuss.
Putting in all the xml boilerplate in api.xml does take quite an effort if
done by hand.

So here is the compromise that I propose instead.  It means continued
parallel development of api.xml and plplot.h, but good scripts can
substantially reduce the maintenance cost of this parallel development.

First, the script to convert from api.xml to plplot.h should include all the
function and argument documentation in the generated plplot.h in a standard
form.  This would help guide developers in any future changes to plplot.h if
they wanted to fully document their new API.  Also, when any documenter runs
that script they can carefully check that the resulting plplot.h is
consistent with the original (except possibly for improvements in the
documentation and whitespace changes).

Second, a script should be developed (Rafael had something like this in
rudimentary form years ago) to translate a single API description from
plplot.h in standard form (i.e, including full documentation) to api.xml. If
the developer has chosen not to put in documentation in plplot.h in the
standard form, then some provision should be made to put in the phrase
"NEEDS DOCUMENTATION" in the resulting api.xml fragment.  With such a script,
then any developer change to plplot.h can quickly be put into api.xml with
a simple cut and paste operation.

Here is how I think it would work in practice. After a developer has
iterated on a change to plplot.h and finalized it, then he (or somebody else
if the developer does not want to document his API) has the option to run
the second script on the changed fragment and do the cut and paste to
api.xml. Then follow with the first script to confirm plplot.h is
consistent with api.xml.

Of course all this discussion is moot without the two scripts.

Rafael if you could make those two scripts, then they would be a big help to
me in my forthcoming efforts to bring api.xml into consistency with
plplot.h.  Part of the reason why I have fallen behind in keeping api.xml up
to date is I don't have such scripts.  Also, if such easy-to-use scripts
were available, I believe developers would be much more willing to document
their API changes which would take additional documentation load off me.

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 software
package (plplot.org).

__________________________

Linux-powered Science
__________________________