On 2007-02-09 21:22-0500 [EMAIL PROTECTED] wrote: > > On Feb 8, 2007, at 5:09 PM, Alan W. Irwin wrote: > >> 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 sounds good. I think we might need one line per language though, as some > interfaces like Perl/PDL also change the order of the arguments. > > So, something like: > c: plline(n, x, y) > ... current documentation ... > > f77: plline(n,x,y) > f95: plline(n,x,y) > c++: plline(n,x,y) > java: plline(x,y) > perl: plline(x,y) > python: plline(x,y) > tcl/tk: plline(x,y) > > This function is used in examples x,y,z > > > That looks pretty redundant though, so maybe c:, redacted: and variants by > language if necessary?
I think your last idea is a good one. I have now realized each language tends to have a different form. For example, I found the following variations of 'line' in our examples. c, f77: plline(n,x,y) c++: pls->line(n,x,y) tcl: $w cmd plline $n x y f95, python: plline(x,y) java: pls.line(x,y) perl: plline($x, $y) You would want to write a general paragraph at the start of the API chapter describing the variations in how plline(n, x, y) transformed for each of the 8 languages into a full argument API (c, c++, f77, tcl) or redacted argument API (f95, python, java, perl) as an example of the general form of variations that will occur for every language. Then in the body of the api chapter you only have to document the full and redacted forms, e.g., full: plline(n,x,y) redacted: plline(x,y) As you said there will also be additional variations some times (such as occur for python when values are returned from the function) so you might want to check through the examples (like I did with 'line' but much more extensively) to make sure you don't get surprised half way through your project by some odd variation. > > I'll volunteer to make this happen. > Thanks, Hazen. That will be most useful. 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 Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
