figure.scrbl (6249B)
1 #lang scribble/manual 2 @(require (for-label scribble/core 3 scribble/decode 4 scriblib/figure 5 scheme/base 6 scheme/contract)) 7 8 @(define-syntax-rule (sn s) @racket[s]) 9 10 @title[#:tag "figure"]{Figures} 11 12 @defmodule[scriblib/figure] 13 14 @deftogether[( 15 @defproc[(figure [tag string?] [caption content?] 16 [p pre-flow?] ... 17 [#:style style style? center-figure-style] 18 [#:label-sep label-sep pre-content? ": "] 19 [#:label-style label-style element-style? #f] 20 [#:continue? continue? any/c #f]) 21 block?] 22 @defproc[(figure* [tag string?] [caption content?] 23 [p pre-flow?] ... 24 [#:style style style? center-figure-style] 25 [#:label-sep label-sep pre-content? ": "] 26 [#:label-style label-style element-style? #f] 27 [#:continue? continue? any/c #f]) 28 block?] 29 @defproc[(figure** [tag string?] [caption content?] 30 [p pre-flow?] ... 31 [#:style style style? center-figure-style] 32 [#:label-sep label-sep pre-content? ": "] 33 [#:label-style label-style element-style? #f] 34 [#:continue? continue? any/c #f]) 35 block?] 36 @defproc[(figure-here [tag string?] [caption content?] 37 [pre-flow pre-flow?] ... 38 [#:style style style? center-figure-style] 39 [#:label-sep label-sep pre-content? ": "] 40 [#:label-style label-style element-style? #f] 41 [#:continue? continue? any/c #f]) 42 block?] 43 )]{ 44 45 Creates a figure. The given @racket[tag] is for use with 46 @racket[figure-ref] or @racket[Figure-ref]. The @racket[caption] is an 47 element. The @racket[pre-flow] is decoded as a flow. 48 49 For HTML output, the @racket[figure] and @racket[figure*] functions 50 are the same, while @racket[figure**] allows the content to be wider 51 than the document body. For two-column Latex output, @racket[figure*] 52 and @racket[figure**] generate a figure that spans columns. 53 54 For Latex output, @racket[figure-here] generates a figure to be included at 55 the position in the output text where the @racket[figure-here] occurs 56 in the source text. For HTML output, all @racket[figure] variants 57 place the figure where the use appears in the source text. 58 59 By default, @racket[style] is set so that the content of the figure is 60 centered. Use @racket[left-figure-style], @racket[center-figure-style], 61 or @racket[right-figure-style] to specify the alignment. 62 63 The @racket[label-sep] and @racket[label-style] arguments adjust the 64 way that the caption's label is shown. By default, the label is the 65 word ``Figure'' followed by a space, the figure number, ``:'', and a 66 space, but @racket[label-sep] can specify an alternative to the ``:'' 67 and ending space. The composed label is given the style specified by 68 @racket[label-style]. 69 70 If @racket[continue?] is a true value, then the figure counter is not 71 incremented. 72 73 @history[#:changed "1.24" @elem{Added the @racket[#:label-sep] and 74 @racket[#:label-style] arguments.}]} 75 76 @deftogether[( 77 @defthing[left-figure-style style?] 78 @defthing[center-figure-style style?] 79 @defthing[right-figure-style style?] 80 @defthing[left style?] 81 )]{ 82 Implements figure alignments. 83 84 The @racket[left] binding is a synonym for @racket[left-figure-style], 85 provided for backward compatibility.} 86 87 88 @defproc[(figure-ref [tag string?] ...+ 89 [#:link-render-style link-style (or/c link-render-style? #f)]) 90 element?]{ 91 92 Generates a reference to one or more figures, using a lowercase word ``figure''. 93 94 If @racket[link-style] or @racket[(current-link-render-style)] at the 95 time of rendering indicates the @racket['number] style mode, then the 96 word ``figure'' itself is not hyperlinked. Otherwise, the word 97 @racket[figure] is hyperlinked together with the referenced figure's 98 number. 99 100 @history[#:changed "1.26" @elem{Added the @racket[#:link-render-style] argument.}]} 101 102 103 @defproc[(Figure-ref [tag string?] ...+ 104 [#:link-render-style link-style (or/c link-render-style? #f)]) 105 element?]{ 106 107 Like @racket[figure-ref], but capitalizes the word ``Figure''. 108 109 @history[#:changed "1.26" @elem{Added the @racket[#:link-render-style] argument.}]} 110 111 112 @defproc[(Figure-target [tag string?] 113 [#:continue? continue? any/c #f]) 114 element?]{ 115 116 Generates a new figure label. This function is normally not used 117 directly, since it is used by @racket[figure].} 118 119 120 @defproc[(suppress-floats) element?]{ 121 122 Produces an empty element that renders in Latex as 123 @tt{\suppressfloats}, which discourages the placement of figures in 124 the column or page of the surrounding text.} 125 126 127 @section{Configuring Output} 128 129 Output uses the following style names, which can be adjusted in an 130 overriding @filepath{.css} or @filepath{.tex} specification: 131 132 @itemize[ 133 134 @item{@sn{Figure}, @sn{FigureMulti}, @sn{FigureMultiWide}, or 135 @sn{HereFigure} --- used for the outer of three 136 @racket[nested-flow]s for a figure, depending on whether 137 @racket[figure], @racket[figure*], @racket[figure**], or 138 @racket[figure-here] is used to generate the figure.} 139 140 @item{@sn{Leftfigure}, @sn{Centerfigure}, or @sn{Rightfigure} --- 141 used for the middle of three @racket[nested-flow]s for a 142 figure, depending on the specified style.} 143 144 @item{@sn{FigureInside} --- used for the inner of three 145 @racket[nested-flow]s for a figure.} 146 147 @item{@sn{Legend} --- Wraps the caption for a figure.} 148 149 @item{@sn{LegendContinued} --- Wraps the caption for a figure that 150 does not increment the figure counter.} 151 152 @item{@sn{FigureTarget} --- Wraps the label anchor and text within a 153 figure's caption. For Latex output, the corresponding command 154 is given a second argument, which is just the generated label 155 (used with @tt{\label} in the command's first argument).} 156 157 @item{@sn{FigureRef} --- Wraps a reference to a figure. For Latex 158 output, the corresponding command is given a second argument, 159 which is just the target label.} 160 161 ]