To Andrew and Phil: @Andrew: there is an important API question for you below.
On 2014-05-22 08:59-0700 phil rosenberg wrote: > Hi Alan > Your suggestion for a single function which does everything was also my > initial thought, and this function already exists behind the scenes. The > prototype is > void > drawmap( void ( *mapform )( PLINT, PLFLT *, PLFLT * ), const char *type, > PLFLT dx, PLFLT dy, int shapetype, PLFLT just, const char *text, > PLFLT minlong, PLFLT maxlong, PLFLT minlat, PLFLT maxlat, int* > plotentries, int nplotentries ) > > The four frontend functions simply call this backend function with appropriate variables and the shapetype variable defines whether we want line, text/point or fill. The reasons why I added the front ends were: > 1) Convenience for the user and a simpler front end. > 2) It allows us to keep the current plmap function without having to dream up a non-obvious new name for the new function. plmap in the current implementation is equivalent to plmapline with plotentries set to NULL to cause all elements to be plotted . > 3) It gives flexibility in the future. Your gradient version is a useful example. Currently I cannot imagine much need for it, but perhaps in the future someone might decide they want this feature. To do this we could change the drawmap function and add a plmapgradient function without breaking the existing public API. > However if you still think a single function is better I can easily rename drawmap to something more relevant to our front end. Also if you want to try to catch more use scenarios then I can easily add a gradient option. Are there any other versions that may be useful? I lean toward the "one function which does everything" approach. I see your point on (1) but there are also advantages to just one map API function for a map user to have to learn. With regard to (2) I think if the final decision is to use just one function than drawmap should be renamed to plmap and the old plmap API dropped, i.e., we introduce a backwards-incompatible API change. I may be wrong, but I have a gut feeling such an API change would be perfectly acceptable to almost all our users because the old plmap function (before you adapted it to shapelib) used a fairly obscure map format, i.e., it was mostly just a historical curiosity used to run example 19, and I doubt your released shapelib changes to the current plmap have attracted that many users yet. I agree with you on (3); the proposed new single-function plmap has sufficient flexibility with the shapetype argument that any new type of map object attribute such as gradient could be added without changing the public API in a backwards-incompatible way. @Andrew: Will you decide this? I lean toward the one-function approach with a backwards-incompatible change to the plmap API, but I am willing to go along with Phil's presently proposed multiple function approach as well, and it appears from what Phil said above he leans the other way but is similarly easy with either way of doing things. > Regarding documentation - I will be happy to make the needed changes to the docbook documentation. I now have Cygwin installed so I should be able to build the documentation, although when I tried yesterday I wasn't quite successful. I think because I was trying to build it from a Windows build. @ Phil: In case you didn't know this already, the directions for how to build the documentation are given in doc/docbook/README.developers. I frankly don't know whether those instructions will work on Cygwin, but at least there is good up-to-date advice there on what software packages will need to be installed. Let me know how that goes in detail if you continue to get errors since I do have a lot of experience with recent builds of our documentation on Linux. If it turns out you ultimately cannot make the documentation build work on Cygwin, then a reasonable backup plan is for you to commit your proposed changes to our DocBook source files, I modify those changes (if necessary) to work here on Linux, and I then return to you our updated documentation in PDF form so you will be able to see the result of your changes. 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); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); 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 __________________________ ------------------------------------------------------------------------------ "Accelerate Dev Cycles with Automated Cross-Browser Testing - For FREE Instantly run your Selenium tests across 300+ browser/OS combos. Get unparalleled scalability from the best Selenium testing platform available Simple to use. Nothing to install. Get started now for free." http://p.sf.net/sfu/SauceLabs _______________________________________________ Plplot-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/plplot-devel
