suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added "Porting" section to the PLoT docs

Browse Source
This commit is contained in:
Neil Toronto 2011-10-05 22:30:27 -06:00
parent cd98c4ac89
commit 8ae5b8c1f3
5 changed files with 136 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
collects/plot/scribblings/compat.scrbl
View File

@ -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}

11
collects/plot/scribblings/plot.scrbl
View File

@ -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"]

22
collects/plot/scribblings/plot2d.scrbl
View File

@ -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").
}

9
collects/plot/scribblings/plot3d.scrbl
View File

@ -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").
}

130
collects/plot/scribblings/porting.scrbl Normal file
View File

@ -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).
}