more discrete scale documentation

docs/src/gallery/scales.md

@@ -162,6 +162,26 @@ p2 = plot(dataset("datasets", "CO2"), x=:Conc, y=:Uptake,
 hstack(p1,p2)
 ```
 
+## [`Scale.shape_discrete`](@ref)
+
+```@example
+using Gadfly, RDatasets, Statistics
+set_default_plot_size(14cm, 8cm)
+
+tips = dataset("reshape2", "tips")
+tipsm = by(tips, [:Day, :Sex], :TotalBill=>mean, :Tip=>mean)
+
+ plot(tipsm, Geom.point,
+    x=:TotalBill_mean, y=:Tip_mean, color=:Sex, shape=:Day,
+    layer(x=:TotalBill_mean, y=:Tip_mean, group=:Day, Geom.line,
+        style(default_color=colorant"gray")),
+    Scale.shape_discrete(levels=["Thur","Fri","Sat","Sun"]),
+    Guide.shapekey(pos=[14.5, 3.8]), Guide.colorkey(pos=[16, 3.87]),
+    Theme(discrete_highlight_color=identity, alphas=[0.1],
+        point_size=8pt, key_swatch_color="slate gray")
+)
+```
+
 
 ## [`Scale.x_continuous`](@ref), [`Scale.y_continuous`](@ref)
 

docs/src/tutorial.md

@@ -206,18 +206,20 @@ hstack(p3, p4)
 
 ## Discrete Scales
 
-| Aesthetic | Scale. | Guide. |
-|-----------|------------------|-------|
-| `x` | `x_discrete` | `xticks` |
-| `y` | `y_discrete` | `yticks` |
-| `color` | `color_discrete` | `colorkey` |
-| `shape` | `shape_discrete` | `shapekey` |
-| `size` | `size_discrete` | sizekey (tbd) |
-| `linestyle` | `linestyle_discrete` | linekey (tbd) |
-| `alpha`  | `alpha_discrete` | alphakey (tbd) |
-| `group`  | `group_discrete` |  |
-| `xgroup` | `xgroup` |  |
-| `ygroup` | `ygroup` |  |
+For some discrete scales, there is a corresponding palette in `Theme()`.
+
+| Aesthetic | Scale. | Guide. | Theme palette |
+|-----------|------------------|-------|-----------------|
+| `x` | `x_discrete` | `xticks` |  |
+| `y` | `y_discrete` | `yticks` |  |
+| `color` | `color_discrete` | `colorkey` |  |
+| `shape` | `shape_discrete` | `shapekey` | `point_shapes` |
+| `size` | `size_discrete` | sizekey (tbd) | (tbd) |
+| `linestyle` | `linestyle_discrete` | linekey (tbd) | `line_style`  |
+| `alpha`  | `alpha_discrete` | alphakey (tbd) | `alphas`  |
+| `group`  | `group_discrete` |  |  |
+| `xgroup` | `xgroup` |  |  |
+| `ygroup` | `ygroup` |  |  |
 
 e.g. `Scale.shape_discrete(labels= , levels= , order= )`
 
@@ -232,6 +234,22 @@ p6 = plot(mtcars, x=:Cyl, color=:Cyl, Geom.histogram,
 hstack(p5, p6)
 ```
 
+For discrete scales with a Theme palette, the order of `levels` and the order of the Theme palette match.
+
+```@example 1
+set_default_plot_size(14cm, 8cm) # hide
+x, y = 0.55*rand(4), 0.55*rand(4)
+plot( Coord.cartesian(xmin=0, ymin=0, xmax=1.0, ymax=1.0),
+    layer(x=x, y=y, shape=["A"], alpha=["day","day","day","night"]),
+    layer(x=1.0.-y[1:3], y=1.0.-x[1:3], shape=["B", "C","C"], alpha=["night"]),
+    Scale.shape_discrete(levels=["A","B","C"]),
+    Scale.alpha_discrete(levels=["day","night"]),
+    Theme(discrete_highlight_color=identity, point_size=12pt,
+   point_shapes=[Shape.circle, Shape.star1, Shape.star2], alphas=[0, 1.0],
+         default_color="midnightblue" )
+)
+```
+
 
 ## Gadfly defaults