[racket-dev] Adding the new plot library [was: Re: Plot?]

On 09/29/2011 12:28 PM, Eli Barzilay wrote:
> Just now, Robby Findler wrote:
>> On Thu, Sep 29, 2011 at 1:25 PM, Eli Barzilay<eli at barzilay.org>  wrote:
>>> The issue is not pixel placements, it's keeping the C code that was
>>> ripped out of gnuplot.
>>
>> So I guess I don't understand. Why would we want to keep that? (I
>> can see why we would want to get rid of it.)
>
> Because you wanted to have a completely compatible interface?
> (Excluding pixels.)
>
> My point was that if you don't keep it (which I very strongly prefer),
> then you don't have a compatible interface to plot anyway, and
> changing the name from `plot' to `plot/compat' makes more sense.

The pixels that make up the plots generated by the compatibility library 
are quite different. But I can't imagine that nicer plots will be 
anything but a pleasant surprise.

So I don't want to read about pixels anymore. Seriously. Logical 
reductio ad absurdum about pixels in pictures - which are valuable 
because of their *semantic* content - borders on fallacious. It won't 
get us anywhere.

What will is discussing the most important user interactions.

--

The first is what happens when users run old code that uses the 'plot' 
library.

  - (Robby/Sam) The compatibility library is 'collects/plot' and the new 
library is 'collects/rackplot' (or 'collects/omg-raph' or whatever): 
their code just runs.

  - (Eli) The compatibility library is 'collects/plot/compat' and the 
new library is 'collects/plot': some code will run with more changes 
than just pixels ("semantic errors" in the plots), some will give 
runtime errors, and most will give compile-time errors.

Examples:

(plot (points (list (vector a b) ...)))
  => Runs, but puts tighter bounds on the plot (semantic error)

(plot (error-bars (list (vector a b c) ...)))
  => Runs, but puts tighter bounds on the plot (semantic error)

(plot (points (list (vector a b) ...) #:sym 'fullsquare))
  => points: does not expect an argument with keyword #:sym

(plot (vector-field (λ (v) v)))
  => vector-field: contract violation, expected a procedure that accepts 
2 mandatory arguments without any keywords, given: #<procedure>
   contract from: (function vector-field), blaming:
     <collects>/plot/plot2d/point.rkt

(plot (line sqr))
  => expand: unbound identifier in module in: line

Also, 'contour', 'shade' and 'surface' do the same as 'line'.


Observations: There's nothing that tells the user that changing (require 
plot) to (require plot/compat) will fix the errors. It just looks like 
random fail. But if it's random fail only once for a very small 
percentage of users, it might be okay-ish.

--

The second interaction is what happens when new users look for "plot" in 
the manual.

  - (Robby/Sam): They get the old 'plot'. Clicking on it reveals a big 
red deprecation warning, and a link to the new stuff. Of course, that 
doesn't guarantee that they will *read* the warning.

  - (Eli): They get the new 'plot', with a note about the compatibility 
library that they can ignore.


Observations: With Robby/Sam's idea, the apparent bait-and-switch, and 
needing two clicks to get to the right library, is also fail. And it 
lasts for years until we finally decide to rip out the compatibility 
library, and thus break more code.

--

To me, the ideal would be to name the compatibility library 
'collects/plot', and then somehow keep it from showing up in searches.

Oh, and also push 'mrlib/plot' downward in the search results. What is 
that, anyway? It seems that nothing in the collects uses it.

Neil T