From: <hba...@ma...> - 2007-02-08 02:36:39
|
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? thanks, -Hazen |
From: Alan W. I. <ir...@be...> - 2007-02-08 07:57:37
|
On 2007-02-07 21:34-0500 hba...@ma... 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. 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 __________________________ |
From: Andrew R. <and...@us...> - 2007-02-08 18:57:52
|
On Wed, Feb 07, 2007 at 10:47:14PM -0800, Alan Irwin wrote: > On 2007-02-07 21:34-0500 hba...@ma... 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 |
From: <hba...@ma...> - 2007-02-10 02:26:38
|
On Feb 8, 2007, at 1:47 AM, Alan W. Irwin wrote: > On 2007-02-07 21:34-0500 hba...@ma... 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. > > 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. Ok. I will do that, probably a few weeks before the next release. -Hazen |
From: Alan W. I. <ir...@be...> - 2007-02-08 22:10:35
|
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 __________________________ |
From: <hba...@ma...> - 2007-02-10 02:23:56
|
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'll volunteer to make this happen. -Hazen |
From: Alan W. I. <ir...@be...> - 2007-02-10 03:22:46
|
On 2007-02-09 21:22-0500 hba...@ma... 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 __________________________ |
From: Jerry <lan...@qw...> - 2007-02-12 01:14:44
|
Is there any interest in including the Ada binding in the new documentation, assuming that I get busy and finish converting the examples as I promised? The binding is here: http://homepage.mac.com/oscarruitt/plplotinada/ plplot_ada.html Jerry On Feb 9, 2007, at 8:22 PM, Alan W. Irwin wrote: > On 2007-02-09 21:22-0500 hba...@ma... 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 |
From: Alan W. I. <ir...@be...> - 2007-02-12 02:07:39
|
On 2007-02-11 18:14-0700 Jerry wrote: > Is there any interest in including the Ada binding in the new > documentation, assuming that I get busy and finish converting the > examples as I promised? Jerry, the next step (assuming you want to donate your Ada binding and one or more example to us) is an e-mail from you stating that you want to donate under the LGPL with an attached tarball of the code you want to donate. Assuming there is something we can test (such as at least one example), and it works, our track record is we graciously accept such donations. :-) Once your Ada binding and your current example are in our CVS, then you might be able to get some additional Ada help through the publicity we would give your Ada binding in our release announcements. However, you should expect that much of the further work will still be your responsibility. For example, we would hope to continue to get donations from you until you have a full-fledged Ada binding with good documentation and all standard examples implemented. But working up to a full-fledged binding can be a gradual process so let us know whether you want to donate what you currently have under the LGPL, and we can take it from there. 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 __________________________ |
From: <hba...@ma...> - 2007-02-19 22:29:34
|
On Feb 11, 2007, at 9:07 PM, Alan W. Irwin wrote: > On 2007-02-11 18:14-0700 Jerry wrote: > >> Is there any interest in including the Ada binding in the new >> documentation, assuming that I get busy and finish converting the >> examples as I promised? > > Jerry, the next step (assuming you want to donate your Ada binding > and one > or more example to us) is an e-mail from you stating that you want > to donate > under the LGPL with an attached tarball of the code you want to > donate. > Assuming there is something we can test (such as at least one > example), and > it works, our track record is we graciously accept such donations. :-) As an aside, you might also consider going the route of providing your bindings independently of the PLplot project. This is what I choose to do for the Lisp bindings (cl-plplot) that I wrote, and this was also done for the Perl bindings. This particularly makes sense if there is a central code repository for Ada, such as CPAN for Perl, and if Ada bindings load a pre-existing PLplot library (as do Perl and Lisp) rather than having to be compiled with the PLplot (Fortran, C++). -Hazen |