Re: [Plplot-devel] Re: [Plplot-cvs] plplot/doc/docbook/src advanced.xml, 1.26, 1.27

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

On 2005-04-04 09:19-0700 Alan W. Irwin wrote:

> On 2005-04-04 13:11-0000 Thomas J. Duck wrote:
>>       beginning of execution.  The function
>> -      <function>plParseInternalOpts</function> is responsible for parsing
>> +      plParseInternalOpts (*** UNDOCUMENTED ***) is responsible for 
>> parsing
>
> Tom, your finding plParseInternalOpts in advanced.xml has opened up a can
> of worms.  :-)
>
> That is an obsolete name that is #defined as plParseOpts (see plplot.h) which 
> itself remains undocumented.
>
> Actually this function should be put into the common API with full
> documentation since all interfaces use it now. Following what was recently
> done when both plHLS_RGB and plRGB_HLS were brought into the common API, I
> assume that plParseOpts should be deprecated (and #defined in terms of
> c_plparseopts), we should #define plparseopts as c_plparseopts, and use
> plparseopts in the examples and c_plparseopts in the source code. It is a
> straightforward but big editing job since plParseOpts, occurs in a number of
> places in the examples and source code.  Also, both plParseInternalOpts and
> plParseOpts appear elsewhere in advanced.xml and should be replaced by
> <function>plparseopts</function>. (Note the function tags should be kept
> since that signals the docbook backends to give special formatting of the
> enclosed function name).
>
> I am willing to clean up this mess tomorrow if I don't hear any objections
> to the proposed changes.

Well, I have made a substantial start on the ParseOpts ==> parseopts change.

Here is the current status: The change has been made for the C library; the
C++, java, and python interfaces; and the corresponding examples. The
current CVS HEAD builds for me and so do the examples from all our
interfaces, but let me know if you find any problems.

The java and python interfaces no longer support the ParseOpts form so this
is a backwards incompatible API change for these particular cases 
consistent with the tradition for those wrappers that we don't support
deprecated functions for them.

The C library and C++ wrapper still has the deprecated form (as well as the
new form).  We are probably stuck with that deprecated version for the C
library (until plplot-6 when all deprecated forms should disappear), but I
leave it to Andrew Ross's best judgement whether he wants to remove the
ParseOpts form from the C++ wrapper or not.

I am pooped by all this editing so I will probably put off continuing this
change for the fortran and tcl interfaces and the documentation until
substantially later today or tomorrow.  That's all I plan to do.  Thus,
Rafael, I am leaving to you whether or not you want to make this change for
the octave and pdl interfaces and examples to be consistent with everything
else.

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 FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the Yorick front-end to PLplot (yplot.sf.net); the
Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project
(lbproject.sf.net).
__________________________

Linux-powered Science
__________________________