[Plplot-devel] Proposed documentation and optional C example updates for the "arbitrary storage of 2D user data" commit

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

Hi David:

I have been doing a large review and update of our DocBook
documentation on a private topic branch with the goal of pushing it in
the next few days so that it will be part of the 5.12.0 release.  I
reviewed documentation of the plfsurf3d function this morning and
moved it from api.xml (documentation for our common API for all
languages) to api-c.xml (documentation of our C-only API) because this
is obviously a C-only function that should not be propagated to other
languages.  You created this function as part of your "support
arbitrary storage of 2D user data" patch which I committed (b035137)
back in 2010.

While making that documentation location change, I noticed that the
remaining functions you created in that patch (e.g., plfgriddata,
plfmesh, plfmeshc, plfplot3d, plfplot3dc, plfplot3dcl, plfshades,
plfshade, plfimagefr, plfimage, plfsurf3dl, and plfvect) are
completely ignored by our DocBook documentation and are not used in
our C examples. (None of these functions should be propagated to
languages other than C, but they might prove to be useful for our C
users. Also note in the above list of functions I deliberately ignored
plfshade1 because I plan to deprecate its non-"f" counterpart
plshade1.) Following what has been done for plfsurf3d do you think it is
worth publicizing this list of functions (after the current release is
out the door) by documenting them in api-c.xml and providing options
in our C examples to test these functions as replacements for their
non-"f" counterparts which we test now?

Alan
__________________________
Alan W. Irwin

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); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________