From 8ae5b8c1f38dcba0d30fc736e84c73c3161f0b83 Mon Sep 17 00:00:00 2001 From: Neil Toronto Date: Wed, 5 Oct 2011 22:30:27 -0600 Subject: [PATCH] Added "Porting" section to the PLoT docs --- collects/plot/scribblings/compat.scrbl | 16 --- collects/plot/scribblings/plot.scrbl | 11 +- collects/plot/scribblings/plot2d.scrbl | 22 ---- collects/plot/scribblings/plot3d.scrbl | 9 -- collects/plot/scribblings/porting.scrbl | 130 ++++++++++++++++++++++++ 5 files changed, 136 insertions(+), 52 deletions(-) create mode 100644 collects/plot/scribblings/porting.scrbl diff --git a/collects/plot/scribblings/compat.scrbl b/collects/plot/scribblings/compat.scrbl index 68a35fc108..bc573f3de4 100644 --- a/collects/plot/scribblings/compat.scrbl +++ b/collects/plot/scribblings/compat.scrbl @@ -14,22 +14,6 @@ This module provides an interface compatible with PLoT 5.1.3 and earlier. -The update from PLoT version 5.1.3 to 5.2 introduces a few incompatibilities: -@itemlist[ - @item{PLoT now allows plot elements to request plot area bounds, and finds bounds large enough to fit all plot elements. - The old default plot area bounds of [-5,5] × [-5,5] cannot be made consistent with the improved behavior; the default bounds are now "no bounds". - This causes code such as @(racket (plot (line sin))), which does not state bounds, to fail.} - @item{The @(racket #:width) and @(racket #:style) keyword arguments to @(racket vector-field) have been replaced by @(racket #:line-width) and @(racket #:scale) to be consistent with other functions.} - @item{The @(racket plot) function no longer takes a @(racket ((is-a?/c 2d-view%) . -> . void?)) as an argument, but a @(racket (treeof renderer2d?)). - The argument change in @(racket plot3d) is similar. - This should not affect most code because PLoT encourages regarding these data types as black boxes.} - @item{The @(racket plot-extend) module no longer exists.} - ] - -Many programs written using PLoT 5.1.3 and earlier will still compile, run and generate plots. -For those that do not, replacing @(racket (require plot)) with @(racket (require plot/compat)) should fix most errors. -(This will unfortunately not fix programs that use @(racket plot-extend).) - @; ---------------------------------------- @section[#:tag "plot"]{Plotting} diff --git a/collects/plot/scribblings/plot.scrbl b/collects/plot/scribblings/plot.scrbl index cf6faa6a15..4c6dc0a0cf 100644 --- a/collects/plot/scribblings/plot.scrbl +++ b/collects/plot/scribblings/plot.scrbl @@ -14,11 +14,10 @@ It includes many common kinds already, such as scatter plots, line plots, contou Thanks to Racket's excellent multiple-backend drawing library, @(plot-name) can render plots as manipulatable images in DrRacket, as bitmaps in slideshows, as PNG, PDF, PS and SVG files, or on any device context. @bold{A note on backward compatibility.} @(plot-name) has undergone a major rewrite between versions 5.1.3 and 5.2. -Many programs written using @(plot-name) 5.1.3 and earlier will still compile, run and generate plots. -For code that does not, see the @(racketmodname plot/compat) module. - -Some functions, like @(racket mix), @(racket line) and @(racket surface), still exist for backward compatibility, but are deprecated and may be removed in the future. -Set @(racket (plot-deprecation-warnings? #t)) to be alerted to uses of deprecated features. +Many programs written using PLoT 5.1.3 and earlier will still compile, run and generate plots. +Some programs will not. +Most programs use deprecated functions such as @(racket mix), @(racket line) and @(racket surface). These functions still exist for backward compatibility, but are deprecated and may be removed in the future. +If you have code written for PLoT 5.1.3 or earlier, please see @secref["porting"] (and possibly @secref["compat"]). @table-of-contents[] @@ -40,6 +39,8 @@ Set @(racket (plot-deprecation-warnings? #t)) to be alerted to uses of deprecate @include-section["custom.scrbl"] +@include-section["porting.scrbl"] + @include-section["compat.scrbl"] @include-section["todo.scrbl"] diff --git a/collects/plot/scribblings/plot2d.scrbl b/collects/plot/scribblings/plot2d.scrbl index 240f578b50..61285f3bc9 100644 --- a/collects/plot/scribblings/plot2d.scrbl +++ b/collects/plot/scribblings/plot2d.scrbl @@ -95,25 +95,3 @@ Every @secref{plot2d} procedure is defined in terms of @(racket plot/dc). Use this if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot)-like functions with different backends. } - -@section{Deprecated 2D Functions} - -The following functions exist for backward compatibility, but may be removed in the future. -Set @(racket (plot-deprecation-warnings? #t)) to be alerted the first time one is used. - -@defproc[(mix [plot-data (any/c . -> . void?)] ...) - (any/c . -> . void?)]{ -See @(secref "compat"). -} - -@doc-apply[line]{ -See @(secref "compat"). -} - -@doc-apply[contour]{ -See @(secref "compat"). -} - -@doc-apply[shade]{ -See @(secref "compat"). -} diff --git a/collects/plot/scribblings/plot3d.scrbl b/collects/plot/scribblings/plot3d.scrbl index bf4ee839b8..4eaa012ac1 100644 --- a/collects/plot/scribblings/plot3d.scrbl +++ b/collects/plot/scribblings/plot3d.scrbl @@ -61,12 +61,3 @@ Use this if you need to continually update a plot on a @(racket canvas%), or to This procedure corresponds with @(racket plot/dc). } - -@section{Deprecated 3D Functions} - -The following functions exist for backward compatibility, but may be removed in the future. -Set @(racket (plot-deprecation-warnings? #t)) to be alerted the first time one is used. - -@doc-apply[surface]{ -See @(secref "compat"). -} diff --git a/collects/plot/scribblings/porting.scrbl b/collects/plot/scribblings/porting.scrbl new file mode 100644 index 0000000000..d6340b4fa0 --- /dev/null +++ b/collects/plot/scribblings/porting.scrbl @@ -0,0 +1,130 @@ +#lang scribble/manual + +@(require "common.rkt") + +@declare-exporting[plot] + +@title[#:tag "porting"]{Porting From PLoT <= 5.1.3} + +If it seems porting will take too long, you can get your old code running more quickly using the @secref["compat"]. + +The update from PLoT version 5.1.3 to 5.2 introduces a few incompatibilities: +@itemlist[ + @item{PLoT now allows plot elements to request plot area bounds, and finds bounds large enough to fit all plot elements. + The old default plot area bounds of [-5,5] × [-5,5] cannot be made consistent with the improved behavior; the default bounds are now "no bounds". + This causes code such as @(racket (plot (line sin))), which does not state bounds, to fail.} + @item{The @(racket #:width) and @(racket #:style) keyword arguments to @(racket vector-field) have been replaced by @(racket #:line-width) and @(racket #:scale) to be consistent with other functions.} + @item{The @(racket plot) function no longer takes a @(racket ((is-a?/c 2d-view%) . -> . void?)) as an argument, but a @(racket (treeof renderer2d?)). + The argument change in @(racket plot3d) is similar. + This should not affect most code because PLoT encourages regarding these data types as black boxes.} + @item{The @(racket plot-extend) module no longer exists.} + ] + +This section of the PLoT manual will help you port code written for PLoT 5.1.3 and earlier to the most recent PLoT. +There are four main tasks: +@itemlist[ + @item{Replace deprecated functions.} + @item{Ensure that plots have bounds.} + @item{Change @(racket vector-field), @(racket plot) and @(racket plot3d) keyword arguments.} + @item{Fix broken calls to @(racket points).} + ] + +You should also set @(racket (plot-deprecation-warnings? #t)) to be alerted to uses of deprecated features. + + +@section{Replacing Deprecated Functions} + +Replace @(racket mix) with @(racket list), and replace @(racket surface) with @(racket surface3d). These functions are drop-in replacements, but @(racket surface3d) has many more features (and a name more consistent with similar functions). + +Replace @(racket line) with @(racket function), @(racket parametric) or @(racket polar), depending on the keyword arguments to @(racket line). These are not at all drop-in replacements, but finding the right arguments should be straightforward. + +Replace @(racket contour) with @(racket contours), and replace @(racket shade) with @(racket contour-intervals). +These are @italic{mostly} drop-in replacements: they should always work, but may not place contours at the same values (unless the levels are given as a list of values). +For example, the default @(racket #:levels) argument is now @(racket 'auto), which chooses contour values in the same way that @italic{z} axis tick locations are usually chosen in 3D plots. +The number of contour levels is therefore some number between @(racket 4) and @(racket 10), depending on the plot. + + +@section{Ensuring That Plots Have Bounds} + +The safest way to ensure that @(racket plot) can determine bounds for the plot area is to add @(racket #:x-min -5 #:x-max 5 #:y-min -5 #:y-max 5) to every call to @(racket plot). Similarly, add @(racket #:x-min -5 #:x-max 5 #:y-min -5 #:y-max 5 #:z-min -5 #:z-max 5) to every call to @(racket plot3d). + +Because PLoT is now smarter about choosing bounds, there are better ways. For example, suppose you have + +@interaction[#:eval plot-eval (plot (line sin))] + +You could either change it to + +@interaction[#:eval plot-eval (plot (function sin) #:x-min -5 #:x-max 5 #:y-min -5 #:y-max 5)] + +or change it to + +@interaction[#:eval plot-eval (plot (function sin -5 5))] + +When @(racket function) is given @italic{x} bounds, it determines tight @italic{y} bounds. + + +@section{Changing Keyword Arguments} + +Replace every @(racket #:width) in a call to @(racket vector-field) with @(racket #:line-width). + +Replace every @(racket #:style 'scaled) with @(racket #:scale 'auto) (or because it is the default in both the old and new, take it out). + +Replace every @(racket #:style 'real) with @(racket #:scale 1.0). + +Replace every @(racket #:style 'normalized) with @(racket #:scale 'normalized). + +The @(racket plot) and @(racket plot3d) functions still accept @(racket #:bgcolor), @(racket #:fgcolor) and @(racket #:lncolor), but these are deprecated. +Parameterize on @(racket plot-background) and @(racket plot-foreground) instead. + +For example, if you have @(racket (plot (function sin -5 5) #:fgcolor '(0 0 128) #:bgcolor '(224 224 224))), change it to +@interaction[#:eval plot-eval (parameterize ([plot-foreground '(0 0 128)] + [plot-background '(224 224 224)]) + (plot (function sin -5 5)))] + +The @(racket #:lncolor) keyword argument now does nothing; change the renderer instead. +For example, if you have @(racket (plot (function sin -5 5) #:lncolor '(0 0 128))), change it to +@interaction[#:eval plot-eval (plot (function sin -5 5 #:color '(0 0 128)))] + + +@section{Fixing Broken Calls to @(racket points)} + +The @(racket points) function used to be documented as accepting a @(racket (listof (vector/c real? real?))), but actually accepted a @(racket (listof (vectorof real?))) and silently ignored any extra vector elements. + +If you have code that takes advantage of this, strip down the vectors first. +For example, if @(racket vs) is the list of vectors, send @(racket (map (λ (v) (vector-take v 2)) vs)) to @(racket points). + + +@section{Replacing Uses of @(racket plot-extend)} + +Chances are, if you used @(racket plot-extend), you no longer need it. +The canonical @(racket plot-extend) example used to be a version of @(racket line) that drew dashed lines. +Every line-drawing function in PLoT now has a @(racket #:style) or @(racket #:line-style) keyword argument. + +The rewritten PLoT will eventually have a similar extension mechanism. + + +@section{Deprecated Functions} + +The following functions exist for backward compatibility, but may be removed in the future. +Set @(racket (plot-deprecation-warnings? #t)) to be alerted the first time each is used. + +@defproc[(mix [plot-data (any/c . -> . void?)] ...) + (any/c . -> . void?)]{ +See @(secref "compat") for the original documentation. Replace this with @(racket list). +} + +@doc-apply[line]{ +See @(secref "compat") for the original documentation. Replace this with @(racket function), @(racket parametric) or @(racket polar), depending on keyword arguments. +} + +@doc-apply[contour]{ +See @(secref "compat") for the original documentation. Replace this with @(racket contours). +} + +@doc-apply[shade]{ +See @(secref "compat") for the original documentation. Replace this with @(racket contour-intervals). +} + +@doc-apply[surface]{ +See @(secref "compat") for the original documentation. Replace this with @(racket surface3d). +}