On Jan 4, 2009, at 7:16 PM, Alan W. Irwin wrote: > 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.
That is correct. > > 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. That sounds like a great idea to me. If there is any difference in the amount of visibility of how they are displayed, I would prefer to have the thick version (or link thereto) to be more visible. > > 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. That is correct, on both counts. It is not ideal and that is exactly how I find the proper documentation. It's a bit of a nuisance and a similar situation exists when actually writing code compared to simply looking up functions in code that is already written, e.g., the examples. > To deal with this issue > I suggest we document these name correspondences in the docbook > section > which describes the thick bindings. Good. Also, I think I suggested something like this in the Ada documentation--the possibility of having an HTML page, perhaps resident on the user's machine, that has links from names to the relevant documentation. This slightly improves the situation, but only slightly since there (1) is still the extra step of switching to the HTML file, doing a search, and then clicking on the link, and (2) the reverse process is still awkward, that is, the user reads the PLplot docs about a function and then has to go to the (different?) HTML page to look up the thick name. Maybe the worst part is that the user's learning process is slowed. > > 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. I'll send those lists off-list. They are in the form of sed script files, one that maps from traditional to thick (which I use in converting the examples) and one to go in the other direction. They are not perfect. From time to time there is a weird mistake or two which I just fix manually. These mistakes don't appear to be errors in the sed file entries but are probably due to an inappropriate use of sed--I've never tracked down the actual cause. Nonetheless, the name correspondences should be correct and you can use them however you see fit. > 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. In the Ada docs, I tried to list all of the constants and integers to which I gave names-- see Unique Features of the Ada bindings > Integer-options Given Ada Names. (I recently changed the ada.xml file to correct formatting problems in this section.) I included these "renamings" in both the thick and traditional bindings but they can be used or ignored (i.e., the numeric equivalents used) in both bindings. There is a problem with completely automating the conversion from thick code to traditional code with respect to the renamed integers and that is because the mapping from Ada names to the integers is many-to-one and thus has no unique inverse mapping, at least not without applying some sort of context-sensitive analysis to the surrounding code that uses the integers. (For example, "1" means both "first color in map 0), "Justified (plot placement)," "Linear_Zero_Axes (axis style)," "Normal_Font," "Extended_Character_Set," "Parse_Full," "Lines_Parallel_To_X," "Grid_Bivariate_Cubic_Spline_Approximation," "DRAW_LINEY," "GRID_CSA," "Histogram_Noscaling," and "Bin_Centered"-- and "True." (A couple of these are already covered in the C version.) When I convert a traditional example to thick I have to manually analyze the code and try to find all of those instances and fix them manually. In other cases, I have replaced C entities (integers or strings) with Ada enumerated types. This is actually the preferred way to handle this situation but I have not applied the technique universally. I think that doing so will not break the Ada API, however. Examples are in the use of Color_Model_Type which has values (HLS, RGB) corresponding in C to PLBOOL being true or false (which is actually an integer 0 or 1, unchecked for range) and Map_Type which replaces a series of C strings with the values (Continents, USA_and_States, Continents_and_Countries, USA_States_and_Continents). > > 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. I think I also mentioned in the Ada docs the possibility of having a complete version PLplot documentation that has the Ada thick names already substituted throughout. I don't think my sed scripts are robust enough to handle that completely--at most, just replacing the subprogram names. Jerry > > Alan > __________________________ > Alan W. Irwin > ------------------------------------------------------------------------------ _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
