On 2009-01-04 13:47-0700 Jerry wrote: > Yesterday I posted an announcement (the first such announcement) to > comp.lang.ada about the official availability of the Ada bindings to > PLplot. Not too surprisingly (to me), the first response was a > request to have the "thick" Ada examples displayed on the PLplot home > page rather than the "traditional" examples. The comp.lang.ada poster > states, in part, > > "I noticed that all examples mirror the fortranesque C library > functions more or less directly. (6char names with a "pl" > prefix making them 8char, tons of numeric parameters...." > > I realize that this might be a sensitive subject, so I tread softly. > I concur with the comp.lang.ada poster but have deferred requesting > that the thick bindings be displayed out of respect for the PLplot > tradition. However, I developed the "thick" binding originally and > added the "traditional" binding at the request of our group of > developers. In so doing, I have maintained both bindings as co- > equals. Only a few days ago, Alan added the thick binding examples to > the test suite and they passed at the same level as the traditional > binding. > > As a still-new Ada programmer (at least compared to some of the gurus > on ada.comp.lang), I have detected that writing code with clarity is > a mantra in the Ada community which is the reason that the poster has > made his request. As far as documentation is concerned, the thick > binding has comments which are rigorously keyed to the traditional > PLplot names, making the look-up of names in the documentation very > easy. I would love to be able to respond to the poster with good news > while this topic is still current on comp.lang.ada. To my mind, > presenting potential Ada users of PLplot with a good first experience > is more important and more likely to create a new PLplot user than > presenting a consistent style on the PLplot home page--Ada users will > likely not even look at the other code examples, and if they do, will > immediately recognize the difference for what it is. >
One clarification. No source code appears on the PLplot home page. So I assume you were referring above to individual example pages such as http://plplot.sourceforge.net/examples.php?demo=01 which do show source code. Frankly, I think both sets of bindings are useful for promoting Ada use of PLplot. Traditional Ada programmers might prefer the thick bindings, but someone with experience in other languages that is just trying out Ada for the first time might prefer the thin bindings. Therefore, I think we should treat both bindings equally. That implies showing the source code for both sets of bindings on each individual example page. That should be straightforward to implement. Let me know if you want me to do that. Although it is really a separate topic, I would also like to take this opportunity to comment about the documentation of the thick binding names. Currently, it is stated in our documentation that However, this thick binding retains the original C subprogram names as comments immediately above the function or procedure name in the code listing so it is relatively easy to locate the relevant item in the PLplot documentation. That situation is far from ideal since the user will have to know which file(s) to dig into to find that correspondence (e.g., between Set_Color and plcol0) and then go back to his web browser to find the corresponding documentation for the PLplot C version of the name. To deal with this issue I suggest we document these name correspondences in the docbook section which describes the thick bindings. Would you be willing to give me a list of thick names and their corresponding C PLplot names? I think you have that already in some form for the script you use to generate the thin examples from thick or vice versa. The list should include not only the thick version of the procedure names but also all the constants which you name specially for the thick bindings. Once I have such a name correspondence list I should be able to turn it into a docbook table that allows any Ada thick bindings user to be one click away from the actual documentation for the corresponding C versions of the Ada thick bindings. 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 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 __________________________ ------------------------------------------------------------------------------ _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
