Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

legend: update documentation #77

Merged
merged 3 commits into from
Sep 22, 2020
Merged

legend: update documentation #77

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a0bda7
legend: update documentation
bdeket Sep 11, 2020
64f726d
legend: update doc for latest changes
bdeket Sep 21, 2020
e1dabdf
legend: doc review
bdeket Sep 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion plot-doc/plot/scribblings/contracts.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Identifies values that meet the contract @racket[elem-contract], lists of such v
'left 'center 'right
'bottom-left 'bottom 'bottom-right
'auto)]{
The contract for @(racket anchor) arguments and parameters, such as @(racket plot-legend-anchor).
The contract for @(racket anchor) arguments and parameters.

The @racket['auto] anchor will place labels so they are visible on the plot
area. This anchor type is useful for @(racket point-label) and similar
Expand All @@ -50,6 +50,32 @@ The @racket['auto] anchor is only valid for placement of text labels, for all
other use cases, the @racket['auto] anchor is always the same as
@racket['bottom-left].}

@defthing[legend-anchor/c contract? #:value (or/c anchor/c
(one-of/c 'no-legend
'outside-top-left 'outside-top 'outside-top-right
'outside-left-top 'outside-left 'outside-left-bottom
'outside-right-top 'outside-right 'outside-right-bottom
'outside-bottom-left 'outside-bottom 'outside-bottom-right
'outside-global-top))]{
The contract for the @(racket plot-legend-anchor) parameter.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you use the following text for the documentation (it documents the values in the logical order: inside, outside, no-legend and explains the purpose of auto)

The contract for the @racket[plot-legend-anchor] parameter and the
@racket[#:legend-anchor] parameters for the various plot procedures.

When @racket[legend-anchor] is one of the symbols from @racket[anchor/c], the
legend will be placed inside the plot area.

@racket[legend-anchor/c] values which start with "outside" will place the
legend outside the plot area, for 2D plots the legend will be aligned with the
plot area, while for 3D plots the legend will be relative to the overall
@racket[plot-width] and @racket[plot-height].

The @racket['outside-global-top] value will place the legend the plot-area,
centered on the complete @racket[plot-width]. For 3D plots there is no
difference between this value and @racket['outside-top].

The value @racket['no-legend], will omit the legend from the plot, the legend
will also be omitted if none of the renderers have a @racket[#:label]
specified, regardless of the value used for @racket[#:legend-anchor].

The value @racket['auto], will place the legend in the top-left corner of the
plot area, this is not usefull for plot legends, this ancor values is used for
renderers such as @racket[point-label].


When the @racket[legend-anchor] is an @racket[anchor/c] this will place the legend inside the plot area. For @racket['auto] the legend will be drawn as if it was @racket['top-left].

If the @racket[legend-anchor] is @racket['no-legend], the legend will be omitted from the plot.

For @racket['outside-top-left] to @racket['outside-bottom-right] the legend will be drawn outside the
plot-area. For 2D plots the alignment will be with the plot-area. For 3D plots the alignment is with
the overall width and height. The difference between @racket['outside-top-left] and
@racket['outside-left-top] is that the first will place the legend above the plot-area, with their
left sides aligned. Whereas the second is plotted on the left side of the plot-area with the top
border of the legend and the plot-area aligned.

When the @racket[legend-anchor] is @racket['outside-global-top] the legend will be printed above the
plot-area, but centered on the complete width. Note that for 3D plots there is no difference between
this and @racket['outside-top]

@history[#:added "7.9"]}

@defthing[color/c contract? #:value (or/c (list/c real? real? real?)
string? symbol?
(is-a?/c color%))]{
Expand Down
2 changes: 1 addition & 1 deletion plot-doc/plot/scribblings/params.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ The font size (in drawing units), face, and family of the title, axis labels, ti
The font size (in drawing units), face, and family to prefer for the legend text. If set to @racket[#f], then the corresponding @racket[plot-font-X] parameter is used.
}

@deftogether[((defparam plot-legend-anchor anchor anchor/c #:value 'top-left)
@deftogether[((defparam plot-legend-anchor legend-anchor legend-anchor/c #:value 'top-left)
(defparam plot-legend-box-alpha alpha (real-in 0 1) #:value 2/3))]{
The placement of the legend and the opacity of its background.
}
Expand Down
8 changes: 4 additions & 4 deletions plot-doc/plot/scribblings/plotting.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Each 3D plotting procedure behaves the same way as its corresponding 2D procedur
[#:title title (or/c string? pict? #f) (plot-title)]
[#:x-label x-label (or/c string? pict? #f) (plot-x-label)]
[#:y-label y-label (or/c string? pict? #f) (plot-y-label)]
[#:legend-anchor legend-anchor anchor/c (plot-legend-anchor)]
[#:legend-anchor legend-anchor legend-anchor/c (plot-legend-anchor)]
[#:out-file out-file (or/c path-string? output-port? #f) #f]
[#:out-kind out-kind plot-file-format/c 'auto]
) (or/c (is-a?/c snip%) void?)]{
Expand Down Expand Up @@ -61,7 +61,7 @@ Here, the renderer draws in [-1,1] × [-1,1], but the plot area is [-1.5,1.5] ×
Please set the @(racket plot-foreground) and @(racket plot-background) parameters instead of using these keyword arguments.
The @(racket #:lncolor) keyword argument is also accepted for backward compatibility but deprecated. It does nothing.

@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label"]
@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor"]
}

@defproc[(plot3d [renderer-tree (treeof (or/c renderer3d? nonrenderer?))]
Expand All @@ -76,7 +76,7 @@ The @(racket #:lncolor) keyword argument is also accepted for backward compatibi
[#:x-label x-label (or/c string? pict? #f) (plot-x-label)]
[#:y-label y-label (or/c string? pict? #f) (plot-y-label)]
[#:z-label z-label (or/c string? pict? #f) (plot-z-label)]
[#:legend-anchor legend-anchor anchor/c (plot-legend-anchor)]
[#:legend-anchor legend-anchor legend-anchor/c (plot-legend-anchor)]
[#:out-file out-file (or/c path-string? output-port? #f) #f]
[#:out-kind out-kind plot-file-format/c 'auto]
) (or/c (is-a?/c snip%) void?)]{
Expand All @@ -94,7 +94,7 @@ The @(racket #:lncolor) keyword argument is also accepted for backward compatibi

The @(racket #:az) and @(racket #:alt) keyword arguments are backward-compatible, deprecated aliases for @(racket #:angle) and @(racket #:altitude), respectively.

@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label, #:y-label and #:z-label"]
@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor"]
}

@defproc[(plot-snip [<plot-argument> <plot-argument-contract>] ...)
Expand Down