On 2007-02-08 18:57-0000 Andrew Ross wrote: > I'm happy to fill in some of the details of the C++ / Java interfaces > and the ethos behind them, since I wrote them. What I don't (currently) > have time for is filling in all the API specific details. What we need > is some way of doing this automatically. All the information is already > there so I _really_ don't want to have to maintain lots of versions by > hand. As Alan says, in most cases the only change in the C++ / Java / > perl / python interfaces are a reduction in the number of arguments. The > differences are things like passing functions to things like the contour > plotters. > > I suggest we maintain one copy of the API information. At the bottom of > each entry we can list which bindings this ifunction is implemented in > and any language specific features.
I don't think it is necessary to mention languages for each entry, because most interfaces are complete so you would end up with the same list of languages for virtually every entry. I suggest instead an introductory paragraph to the current api chapter giving examples of how the "full" API could be used in the fortran 77, C, C++, and Tcl cases, and a following introductory paragraph showing how the "redacted" API could be used in the fortran 95, C++, python, java, and perl cases. (I have put C++ on both lists because I think it implements both.) I am only referring here to a few examples for each language since a full list of our examples in each language is given elsewhere, see below. Furthermore, the examples should include at least one function call with output since that must be handled in a special way (see comments below). I suggest we document both the full API and the redacted API for each of the PLplot functions where there is a difference. This amounts to simply an extra listing of the function call, for example, full API: plline(n, x, y) redacted API: plline(x, y) This style would keep the common plline information (i.e., the paragraph describing what plline does, and a description of the parameters) together without duplicating it. This style should keep everything easier to maintain as well. One confusing factor we have to deal with here is a few of the PLplot calls output information. Those functions are treated specially by Python; the function value is set to a list of the returned arguments. I think Java does something special as well. So for those special cases with output arguments we may want to put an asterisk or some other indicator by the redacted API to show that this needs special treatment for Python (and Java?). > Also great would be to reference which > examples to look at to see how it works. It seems to me we already have that in http://plplot.sourceforge.net/examples/index.html. If you click on any of those examples, you get full code in each language for them in a nicely presented way. However, I strongly agree we should provide good links to that part of our website from within the documentation. 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); 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 __________________________ ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier. Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Plplot-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/plplot-devel
