On Saturday, October 1, 2011, Neil Toronto <neil.toro...@gmail.com> wrote: > On 10/01/2011 10:44 AM, Neil Van Dyke wrote: >> >> Neil Toronto wrote at 10/01/2011 12:15 PM: >>>> >>>> 2. Whether to call the new library "plot" (rather than, say, "plot2" or >>>> "newimprovedsuperplot2000"). >>> >>> Yep. That's part of the main question. >> >> [...] >>> >>> If the answer to #2 is "the new library is called 'plot'", then the >>> answer to #4 is "you have to change (require plot) to (require >>> plot/compat)". And then everything should work. >> >> Thanks, Neil T. >> >> If that's a big point of contention, then would everyone be happy either >> with one of the following? >> >> 1. Call the new library "plot2", and make "plot" be a compatibility >> layer for "plot2". Add pointers in strategic locations of "plot" parts >> of documentation, saying telling reader probably want to use "plot2" for >> new development. > > That's what Robby wants. I've tried it that way as well. It works fine. > > My main problem with it is when *future* users search for "plot" in the documentation. They'd get the pointers in strategic locations, yes, but users don't always read text. And the pointers would have to be in a lot of places.
Just to be clear I don't insist that it be that way forever. Only for a while so people have tine to port according to their schedules as opposed to ours. That said, we definitely should still do a good job on the docs (explaining how to port and what is deprecated). I don't think that this is really all that bad; easier than what Neil T is contemplating below, I expect. :) >> 2. Make the APIs for the old library and new library not conflict, by >> making any necessary changes to the new API, and put both APIs together >> in single library named "plot" that users get with "(require plot)". >> Document the old API parts as deprecated. > > I had thought of this, but not seriously checked it out until you suggested it just now. > > The main incompatibility is how "plot data" is represented. In the old library, it's a function from a plot-view% (a descendant of image-snip%) to void. There's no way for something like that to communicate its bounds to 'plot'. So in the new one, plot data is represented by a struct. > > That difference is okay as long as nobody peeks at the plot data, just passing it off to 'plot', and combining them using 'mix'. I assume most users have done that. > > There's wonkiness in the old API. The 'line' function, for example, plots functions, parametric functions, polar functions, and parametric functions with a polar mapping. Sometimes some keywords matter, based on the values of other keywords. It's overloaded and messy. > > The 'plot3d' function has a keyword named '#:az', for "azimuth". No user needs to know that technical term. It's just the horizontal angle at which you view the plot. I called it '#:angle'. > > The 'vector-field' function has a '#:style' keyword that determines how the arrows are scaled. I use '#:style' for pen and brush styles (dashes, cross-hatching, etc.). > > There are quite a few little differences like that. > > But there are enough similarities that I think I could do this option. I'd still want to have a compatibility module, just in case. The documentation would be tricky. I'd probably document only new, self-consistent functions and keywords, but have notes about extra keywords for compatibility, and a separate section on backward-compatible functions. > > Hmm... > > Neil T > _________________________________________________ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/users >
_________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/users
