On Wed, Feb 07, 2007 at 10:47:14PM -0800, Alan Irwin wrote: > On 2007-02-07 21:34-0500 [EMAIL PROTECTED] wrote: > > > > > Some questions / issues with our current docbook manual: > > > > (1a) Chapter 23 (i.e. how to install). Should we keep this and update > > it? Refer users to the INSTALL file instead? To the wiki? > > (1b) Chapter 4, how to deploy. See questions for 1a. > > > > (2) We seem to be missing a chapter on Java. Any Java experts have > > any interest in providing at least a quick overview? > > > > (3) The Python chapter is, well, terse & probably dated. Any Python > > experts willing to bring this up to date, including (a) a brief > > overview of the bindings and (b) a simple example? > > > > (4) The C language chapter claims to be old & in need of updating. > > Any ideas about what specifically might be wrong? Do we no longer > > recommend FLOAT, INT and PROTO? Do we no longer support non-standard > > C compilers? Notes are needed about PLBOOL & PLUNICODE? > > > > (5) Chapter 10, The plstream C++ interface. This is stable now and > > hasn't changed for a long time? Is there an example to reference that > > demonstrates how to use it? > > (6) and the chapter on fortran 95 is essentially copied (with many errors in > detail as a result) from the fortran 77 chapter simply as a placeholder for > now. > > With regard to your 1a and 1b questions, I think our docbook documentation > should stand completely on its own as the definitive source of our > documentation. So once our wiki settles down (and I think we have reached > that point or are pretty close) I think we should copy a lot of that > material to our docbook documentation. > > With regard to your further questions, note that for python, perl(?), java, > fortran 95, and C++ we actually deploy an alternative interface where the > redundant dimensions are dropped (for backwards compatibility the C++ > interface also has an interface similar to the old C-like interface as > well). Perhaps the best procedure here is to add a chapter closely > following our existing API chapter, but with the details changed for all the > dropped redundant dimensions. Then you could add short documentation for > each of the above languages that simply refers to the alternative api > chapter for the details. > > Unfortunately, I will not be able to work further on that alternative API > documentation idea until my responsibility for the svn testing and > conversion is done, but hopefully somebody else will have the time to move > forward with that idea in the meanwhile.
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. Also great would be to reference which examples to look at to see how it works. This would minimise the work involved maintaining the documentation, while maximising the usefulness to the user. Andrew ------------------------------------------------------------------------- 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
