adds doc on color and wait

README.md

@@ -197,6 +197,146 @@ The turtle has a pen that it drags along where it goes, creating a drawing.  We
 
 ![](https://github.com/google/clojure-turtle/blob/master/doc/img/frame14.png)
 
+### color
+
+Color can be set for the turtle.  A color is specified by a vector of
+size 1, 3, or 4.
+
+A three-element color vector has 3 integers for the red,
+green, and blue components of the color (in that order) in the range
+0 - 255. (See
+[this page](https://en.wikipedia.org/wiki/Web_colors#X11_color_names)
+for examples of specifying color in terms of RGB values.)
+
+```clojure
+(def octagon (all (repeat 8 (all (forward 30) (right))))) 
+(color [0 0 255])
+(repeat 12 (all (octagon) (right 30)))
+```
+
+The turtle sprite (the triangle representing the turtle) will be drawn
+in the same color as the turtle's pen.
+
+![](https://github.com/google/clojure-turtle/blob/master/doc/img/frame15.png)
+
+We can also use our color value to fill the interior of shapes that we
+draw.  To draw shapes will a fill color, we first have to indicate
+when we start and when we end drawing the shape.  For that, we use the
+`start-fill` and `end-fill` commands.  Every line segment that the turtle
+draws in between `start-fill` and `end-fill` is assumed to form the
+perimeter of the shape.
+
+Let us define `filled-octagon` as the combination of commands to draw a filled
+octagon.  In between the `start-fill` and `end-fill` that demarcate our
+fill shape, we will use our `octagon` function to draw the perimeter of the
+octagon that we want filled.
+
+```clojure
+(def filled-octagon (all (start-fill) (octagon) (end-fill))) 
+```
+
+If a four-element color vector is given for a color, then the 4th value is known
+as the "alpha" value.  In clojure-turtle, the alpha value is also an
+integer that ranges from 0 to 255.  The value 0 represents full
+transparency, and 255 represents full opacity.
+
+```clojure
+(color [255 255 0 100]) 
+```
+
+We will want to draw 4 octagons that
+overlap, so we will create a `points` vector of 4 x,y-coordinates from
+which we will start drawing
+each octagon.
+
+```clojure
+(def points [[-11 -11] [-62 -11] [-36 14] [-36 -36]])
+```
+
+For now, let's retrieve only the first of the four points,
+set our position to that first point, and then draw our first octagon
+from there.
+
+```clojure
+(let [point-1 (first points)
+      x (first point-1)
+      y (second point-1)]
+  (setxy x y)
+  (filled-octagon))
+  ```
+
+![](https://github.com/google/clojure-turtle/blob/master/doc/img/frame16.png)
+
+Next, we will draw our the remaining 3 octagons.  Since we will
+perform similar actions in repetition, let's create a function to
+store the behavior we want to repeat.
+
+```clojure
+(defn filled-octagon-from-point
+  [point]
+  (let [x (first point)
+        y (second point)]
+    (setxy x y)
+    (filled-octagon)))
+```
+
+Given a point in the form `[x y]`, the function
+`filled-octagon-from-point` will draw a filled octagon starting at
+(x,y).
+
+```clojure
+;; octagon starting from 2nd point:
+(filled-octagon-from-point (second points))
+;; ... from 3rd point:
+(filled-octagon-from-point (nth points 2))
+;; ... from 4th point:
+(filled-octagon-from-point (nth points 3))
+```
+
+![](https://github.com/google/clojure-turtle/blob/master/doc/img/frame17.png)
+
+A color vector of size 1 creates a grayscale color ranging from black
+to white.  The grayscale
+color is equivalent to using a 3-element RGB color vector where the
+values for red, green, and blue are the same.
+
+![](https://github.com/google/clojure-turtle/blob/master/doc/img/frame18.png)
+
+### wait and animation
+
+We can use `wait` to make the turtle pause.  The number passed to wait
+indicates how many milliseconds the turtle should wait (1 millisecond
+= 0.001 seconds = 1 / 1000 seconds).
+
+```clojure
+(clean)
+(home)
+(forward 30)
+(wait 2000)
+(right 90)
+(forward 30)
+```
+
+Computers today are fast.  If we use `wait` to slow them down, we can
+watch the turtle move and perceive motion.
+
+```clojure
+(clean)
+
+(defn slower-octagon
+  []
+  (repeat 8 (fn []
+              (forward 30)
+              (right 45)
+              (wait 100))))
+(repeat 12 (all (slower-octagon) (right 30)))
+```
+
+What happens when you combine `wait` with `clean`?  If we repeatedly
+draw, wait, and clean images in a loop, we can create the effect of
+motion!  See the [Animation page](https://github.com/google/clojure-turtle/wiki/Animation) for more
+information and examples.
+
 ### What next?
 
 clojure-turtle uses Quil, which uses [Processing](https://processing.org/). clojure-turtle also has the full power and fun of Clojure available to it, too.