015625e732
Many little doc fixes Closes PR 12433 Closes PR 12435 Please please please merge into release
136 lines
7.1 KiB
Racket
136 lines
7.1 KiB
Racket
#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.}
|
||
@item{The @racket[fit] function and @racket[fit-result] struct type have been removed.}
|
||
|
||
]
|
||
|
||
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)))]
|
||
|
||
Change @(racket #:az) in calls to @(racket plot3d) to @(racket #:angle), and @(racket #:alt) to @(racket #:altitude).
|
||
Alternatively, parameterize multiple plots by setting the @(racket plot3d-angle) and @(racket plot3d-altitude) parameters.
|
||
|
||
|
||
@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).
|
||
}
|