Fixed discrete-histogram gap and bounds calculation, expanded docs

collects/plot/plot2d/rectangle.rkt

@@ -130,14 +130,13 @@
     [else
      (define n (length cats))
      (let* ([x-min  (if x-min x-min 0)]
-            [x-max  (if x-max x-max (+ x-min (* n skip)))]
+            [x-max  (if x-max x-max (max x-min (+ x-min (* (- n 1) skip) 1)))]
             [y-min  (if y-min y-min (apply min* rys))]
             [y-max  (if y-max y-max (apply max* rys))])
-       (define xs (linear-seq x-min x-max (add1 n)))
+       (define xs (build-list n (λ (i) (+ x-min (* i skip)))))
-       (define x-ivls (for/list ([x1  (in-list xs)] [x2  (in-list (rest xs))])
+       (define x-ivls (for/list ([x  (in-list xs)])
-                        (define 1/2-gap-size (+ (* 1/2 (- skip 1)) (* 1/2 gap (- x2 x1))))
+                        (ivl (+ x (* 1/2 gap)) (- (+ x 1) (* 1/2 gap)))))
-                        (ivl (+ x1 1/2-gap-size) (- x2 1/2-gap-size))))
+       (define tick-xs (for/list ([x  (in-list xs)]) (+ x 1/2)))
-       (define tick-xs (linear-seq x-min x-max n #:start? #f #:end? #f))
        (define y-ivls (map (λ (y) (if (ivl? y) y (ivl 0 y))) ys))
        (define maybe-invert (if invert? (λ (x y) (vector y x)) vector))
        (renderer2d

collects/plot/scribblings/renderer2d.scrbl

@@ -272,41 +272,45 @@ The @(racket #:samples) argument determines the accuracy of the calculated areas
 @doc-apply[discrete-histogram]{
 Returns a renderer that draws a discrete histogram.
 
-Each bar takes up exactly one plot unit; e.g. the first bar in a histogram uses the space between @(racket 0) and @(racket 1).
+@examples[#:eval plot-eval
-To plot histograms side-by-side, pass the appropriate @(racket #:x-min) value to the second renderer. For example,
+                 (plot (discrete-histogram (list #(A 1) #(B 2) #(B 3)
+                                                 (vector 'C (ivl 0.5 1.5)))))]
+
+Use @racket[#:invert? #t] to draw horizontal bars. See @racket[stacked-histogram] for an example.
+
+Each bar takes up exactly one plot unit, and is drawn with @racket[(* 1/2 gap)] empty space on each side.
+Bar number @racket[i] is drawn at @racket[(+ x-min (* i skip))].
+Thus, the first bar (@racket[i] = @racket[0]) is drawn in the interval between @racket[x-min] (default @racket[0]) and @racket[(+ x-min 1)].
+
+To plot two histograms side-by-side, pass the appropriate @racket[x-min] value to the second renderer. For example,
 @interaction[#:eval plot-eval
                     (plot (list (discrete-histogram (list #(a 1) #(b 2) #(c 3) #(d 2)
                                                           #(e 4) #(f 2.5) #(g 1))
                                                     #:label "Numbers per letter")
                                 (discrete-histogram (list #(1 1) #(4 2) #(3 1.5))
                                                     #:x-min 8
-                                                    #:color 2 #:line-color 2
+                                                    #:label "Numbers per number"
-                                                    #:label "Numbers per number")))]
+                                                    #:color 2 #:line-color 2)))]
-
+Here, the first histogram has @racket[7] bars, so the second is drawn starting at @racket[x-min] = @racket[8].
-Using the @racket[#:skip] argument, a discrete histogram can be used to show
-benchmark results where each configuration has a specific color, but
-the runs on a specific benchmark are grouped together. For example,
-
-@interaction[#:eval
-             plot-eval
-             (parameterize ([discrete-histogram-gap 1/32])
-               (plot (list (discrete-histogram '(#(aa 1.5) #(ab 2.5) #(ac 3.5))
-                                               #:x-min 0 #:color 0 #:line-color 0
-                                               #:skip 5)
-                           (discrete-histogram '(#(ba 1.4) #(bb 2.4) #(bc 3.4))
-                                               #:x-min 1 #:color 1 #:line-color 1
-                                               #:skip 5)
-                           (discrete-histogram '(#(ca 1.3) #(cb 2.3) #(cc 3.3))
-                                               #:x-min 2 #:color 2 #:line-color 2
-                                               #:skip 5)
-                           (discrete-histogram '(#(da 1.2) #(db 2.2) #(dc 3.2))
-                                               #:x-min 3 #:color 3 #:line-color 3
-                                               #:skip 5))))]
 
+To interleave histograms, such as when plotting benchmark results, use a @racket[skip] value larger than or equal to the number of histograms, and give each histogram a different @racket[x-min].
+For example,
+@interaction[#:eval plot-eval
+                    (plot (list (discrete-histogram
+                                 '(#(Eggs 1.5) #(Bacon 2.5) #(Pancakes 3.5))
+                                 #:skip 2.5 #:x-min 0
+                                 #:label "AMD")
+                                (discrete-histogram
+                                 '(#(Eggs 1.4) #(Bacon 2.3) #(Pancakes 3.1))
+                                 #:skip 2.5 #:x-min 1
+                                 #:label "Intel" #:color 2 #:line-color 2))
+                          #:x-label "Breakfast Food" #:y-label "Cooking Time (minutes)"
+                          #:title "Cooking Times For Breakfast Food, Per Processor")]
+When interleaving many histograms, consider setting the @racket[discrete-histogram-skip] parameter to change @racket[skip]'s default value.
 }
 
 @doc-apply[stacked-histogram]{
-Returns a renderer that draws a stacked histogram.
+Returns a list of renderers that draw parts of a stacked histogram.
 The heights of each bar section are given as a list.
 @examples[#:eval plot-eval
                  (plot (stacked-histogram (list #(a (1 1 1)) #(b (1.5 3))