scriblib/figure: add `#:continue?' option

original commit: a5f8584bab556be365233adb73fd9b8d42130bef

collects/scriblib/figure.rkt

@@ -42,6 +42,7 @@
 (define figureinside-style (make-style "FigureInside" figure-style-extras))
 
 (define legend-style (make-style "Legend" figure-style-extras))
+(define legend-continued-style (make-style "LegendContinued" figure-style-extras))
 
 (define centertext-style (make-style "Centertext" figure-style-extras))
 
@@ -54,18 +55,30 @@
                                        figure-style-extras))
     c))
 
-(define (figure tag caption #:style [style center-figure-style] . content)
+(define (figure tag caption 
-  (figure-helper figure-style style tag caption content))
+                #:style [style center-figure-style]
+                #:continue? [continue? #f]
+                . content)
+  (figure-helper figure-style style tag caption content continue?))
 
-(define (figure-here tag caption #:style [style center-figure-style] . content)
+(define (figure-here tag caption 
-  (figure-helper herefigure-style style tag caption content))
+                     #:style [style center-figure-style] 
+                     #:continue? [continue? #f]
+                     . content)
+  (figure-helper herefigure-style style tag caption content continue?))
 
-(define (figure* tag caption #:style [style center-figure-style] . content)
+(define (figure* tag caption 
-  (figure-helper figuremulti-style style tag caption content))
+                 #:style [style center-figure-style]
-(define (figure** tag caption #:style [style center-figure-style] . content)
+                 #:continue? [continue? #f]
-  (figure-helper figuremultiwide-style style tag caption content))
+                 . content)
+  (figure-helper figuremulti-style style tag caption content continue?))
+(define (figure** tag caption 
+                  #:style [style center-figure-style] 
+                  #:continue? [continue? #f]
+                  . content)
+  (figure-helper figuremultiwide-style style tag caption content continue?))
 
-(define (figure-helper figure-style content-style tag caption content)
+(define (figure-helper figure-style content-style tag caption content continue?)
   (make-nested-flow 
    figure-style 
    (list
@@ -74,13 +87,19 @@
      (list (make-nested-flow figureinside-style (decode-flow content))))
     (make-paragraph
      centertext-style
-     (list (make-element legend-style (list (Figure-target tag) caption)))))))
+     (list (make-element (if continue?
+                             legend-continued-style
+                             legend-style)
+                         (list (Figure-target tag #:continue? continue?) caption)))))))
 
 (define figures (new-counter "figure" 
                              #:target-wrap make-figure-target
                              #:ref-wrap make-figure-ref))
-(define (Figure-target tag)
+(define (Figure-target tag #:continue? [continue? #f])
-  (counter-target figures tag "Figure" ": "))
+  (counter-target figures tag 
+                  "Figure" 
+                  (if continue? " (continued): " ": ")
+                  #:continue? continue?))
 
 (define (ref-proc initial)
   (case-lambda 

collects/scriblib/figure.tex

@@ -12,6 +12,8 @@
                         \vspace{4pt}
                         \legend{#1}}
 
+\newcommand{\LegendContinued}[1]{\Legend{#1}}
+
 \newcommand{\FigureTarget}[2]{#1}
 \newcommand{\FigureRef}[2]{#1}
 

collects/scriblib/private/counter.rkt

@@ -14,7 +14,9 @@
                      #:ref-wrap [ref-wrap (lambda (c s) c)])
   (make-counter 0 name target-wrap ref-wrap))
 
-(define (counter-target counter tag label . content)
+(define (counter-target counter tag label 
+                        #:continue? [continue? #f]
+                        . content)
   (let ([content (decode-content content)])
     (define c
       (make-target-element
@@ -37,7 +39,9 @@
                           (list* label 'nbsp "N" content)
                           (cons "N" content)))))
          (lambda (ci)
-           (let ([n (add1 (counter-n counter))])
+           (let ([n (if continue?
+                        (counter-n counter)
+                        (add1 (counter-n counter)))])
              (set-counter-n! counter n)
              (collect-put! ci `(counter (,(counter-name counter) ,tag "value")) n)))))
        `(counter (,(counter-name counter) ,tag))))

collects/scriblib/scribblings/figure.scrbl

@@ -12,11 +12,26 @@
 @defmodule[scriblib/figure]
 
 @deftogether[(
-@defproc[(figure [tag string?] [caption content?] [#:style style style?] [p pre-flow?] ...) block?]
+@defproc[(figure [tag string?] [caption content?] 
-@defproc[(figure* [tag string?] [caption content?] [#:style style style?] [p pre-flow?] ...) block?]
+                 [p pre-flow?] ...
-@defproc[(figure** [tag string?] [caption content?] [#:style style style?] [p pre-flow?] ...)
+                 [#:style style style? center-figure-style]
-block?]
+                 [#:continue? continue? any/c #f]) 
-@defproc[(figure-here [tag string?] [caption content?] [#:style style style?] [pre-flow pre-flow?] ...) block?]
+         block?]
+@defproc[(figure* [tag string?] [caption content?]
+                  [p pre-flow?] ...
+                  [#:style style style? center-figure-style]
+                 [#:continue? continue? any/c #f])
+         block?]
+@defproc[(figure** [tag string?] [caption content?]
+                   [p pre-flow?] ...
+                   [#:style style style? center-figure-style]
+                   [#:continue? continue? any/c #f])
+         block?]
+@defproc[(figure-here [tag string?] [caption content?]
+                      [pre-flow pre-flow?] ...
+                      [#:style style style? center-figure-style]
+                      [#:continue? continue? any/c #f])
+         block?]
 )]{
 
 Creates a figure. The given @racket[tag] is for use with
@@ -35,7 +50,10 @@ place the figure where the use appears in the source text.
 
 By default, @racket[style] is set so that the content of the figure is
 centered.  Use @racket[left-figure-style], @racket[center-figure-style],
-or @racket[right-figure-style] to specify the alignment.}
+or @racket[right-figure-style] to specify the alignment.
+
+If @racket[continue?] is a true value, then the figure counter is not
+incremented.}
 
 @deftogether[(
 @defthing[left-figure-style style?]
@@ -59,7 +77,9 @@ Generates a reference to one or more figures, using a lowercase word ``figure''.
 Generates a reference to one or more figures, capitalizing the word ``Figure''.}
 
 
-@defproc[(Figure-target [tag string?]) element?]{
+@defproc[(Figure-target [tag string?]
+                        [#:continue? continue? any/c #f]) 
+         element?]{
 
 Generates a new figure label. This function is normally not used
 directly, since it is used by @racket[figure].}
@@ -87,6 +107,9 @@ overriding @filepath{.css} or @filepath{.tex} specification:
 
  @item{@sn{Legend} --- Wraps the caption for a figure.}
 
+ @item{@sn{LegendContinued} --- Wraps the caption for a figure that
+       does not increment the figure counter.}
+
  @item{@sn{FigureTarget} --- Wraps the label anchor and text within a
        figure's caption.  For Latex output, the corresponding command
        is given a second argument, which is just the generated label

collects/tests/scribble/docs/figure.scrbl

@@ -0,0 +1,20 @@
+#lang scribble/base
+@(require scriblib/figure)
+
+@title{Waterfowl}
+
+@figure[
+"one"
+"The Figure"
+@para{Duck}]
+
+@figure[
+#:continue? #t
+"two"
+"More of The Figure"
+@para{Duck}]
+
+@figure[
+"three"
+"A Different Figure"
+@para{Goose!}]

collects/tests/scribble/docs/figure.txt

@@ -0,0 +1,10 @@
+Waterfowl
+
+Duck
+Figure 1: The Figure
+
+Duck
+Figure 1 (continued): More of The Figure
+
+Goose!
+Figure 2: A Different Figure