fix doc bugs

docs/src/index.md

@@ -45,7 +45,7 @@ using Luxor
     scaleby!(S, 150)
 
     setopacity(0.8)
-    pin(S) # the "draw in 2D" function
+    pin(S) # the "project into 2D" function
 end 800 500
 ```
 

docs/src/objects.md

@@ -119,7 +119,7 @@ vertices = Point3D[]
 N = 7
 
 # make the base
-polygon = ngon(O, 150, N, verices=true)
+polygon = ngon(O, 150, N, vertices=true)
 for i in eachindex(polygon)
     push!(vertices, convert(Point3D, polygon[i]))
 end
@@ -130,7 +130,7 @@ push!(vertices, Point3D(0, 0, 200))
 # make the faces
 faces = Vector{Int64}[]
 for i in eachindex(polygon)
-    push!(faces, [i, mod1(i + t1, N), N + 1])
+    push!(faces, [i, mod1(i + 1, N), N + 1])
 end
 
 obj = make([vertices, faces], "")
@@ -266,7 +266,9 @@ The surface normal is an imaginary line that meets the face at right angles, and
 
 ## Using custom code
 
-Thebes.jl is a toy rather than a full 3D renderer, and a general-purpose rendering function that draws everything with lots of optional parameters is not provided. There are plenty of ways to experiment though:
+Thebes.jl is a toy rather than a full 3D renderer, and a general-purpose rendering function that draws everything with lots of optional parameters is not provided. There are plenty of ways to experiment though.
+
+Suppose you want to remove the front-facing faces of an object, in order to see inside. That's possible, but a bit of code is needed.
 
 ```@example
 using Thebes
@@ -332,6 +334,8 @@ end
 end 800 600
 ```
 
+The object on the left has had its frontfacing faces removed. The one on the right is intact.
+
 !!! note
 
    There are probably better ways to do this...!

docs/src/polys.md

@@ -45,47 +45,45 @@ function makemobius()
     return result # as an array of 3D polygons
 end
 
-# ... in a drawing
+# ... on a drawing
 @drawsvg begin
-    origin() # hide
     background("grey20")
     eyepoint(300, 300, 300)
     perspective(1200)
     setopacity(0.7)
     sethue("white")
+    setline(0.4)
     mb = makemobius()
     for pgon in mb
         pin(100pgon)
     end
 end 800 600
 ```
 
-This isn’t always going to be correct - if the 3D points don’t define a “face” lying in a 2D plane, for example.
-
-The default action when `pin()` is called on a set of `Point3D`s is `poly(pts, fill)`, once the `Point3D`s have been projected into 2D space.
+This isn’t always going to be correct - although three 3D points always define a flat face in a 2D plane, more than three points don’t always do so.
 
-You can also pass a `gfunction`. It should accept two arguments: a list of `Point3D`s and a list of `Point`s.
+The default action when `pin()` is called on a list of `Point3D`s is `poly(pts, fill)`, once the `Point3D`s have been projected into 2D space as `pts`.
 
-For example, this calls Luxor's `poly()` function on the list of 2D points in `p2`:
+You can also pass a `gfunction`. It should accept two arguments: a list of `Point3D`s and a list of `Point`s. For example, this calls Luxor's `poly()` function on the list of 2D points in `p2` that are the projections of the `Point3D`s in `pgon`.
 
 ```
-pin(plist,
-    gfunction = (p3, p2) -> begin
-        poly(p2, close=true, :fill)
+pin(pgon,
+    gfunction = (p3list, p2list) -> begin
+        poly(p2list, close=true, :fill)
     end)
 ```
 
-Each square is constructed in a `plist` and then `pin()` applies its custom gfunction to it.
+In this example, the gfunction draws colored circles inside each square:
 
 ```@example
-using Thebes, Luxor # hide
+using Thebes, Luxor, Colors # hide
 
 function makemobius()
     x(u, v) = (1 + (v / 2 * cos(u / 2))) * cos(u)
     y(u, v) = (1 + (v / 2 * cos(u / 2))) * sin(u)
     z(u, v) = v / 2 * sin(u / 2)
     w = 1
-    st = 2π / 150
+    st = 2π / 160
     Δ = 0.1
     result = Array{Point3D,1}[]
     for u in 0:st:2π-st
@@ -114,17 +112,16 @@ end
 
 # ... in a drawing
 @drawsvg begin
-    origin() # hide
     background("grey20")
     eyepoint(300, 300, 300)
     perspective(1200)
-    setopacity(0.7)
-    sethue("white")
     mb = makemobius()
     for (n, pgon) in enumerate(mb)
-        isodd(n) ? sethue("black") : sethue("white")
         pin(100pgon, 
-            gfunction = (p3, p2) -> poly(p2, close=true, :fill))
+        gfunction = (p3list, p2list) -> begin
+                sethue(HSB(rand(200:300), 0.7, 0.8))
+                ellipseinquad(p2list, action=:fill)
+            end)
     end
 end 800 600
 ```

docs/src/tools.md

@@ -8,69 +8,6 @@ DocTestSetup = quote
 
 There are some useful tools that might help you explore the limited 3D world provided by Thebes.jl.
 
-## Getting your hands dirty
-
-Suppose you want to remove the front-facing faces of an object, in order to see inside. That's possible, but a bit of code is needed.
-
-```@example
-using Thebes, Luxor, Colors # hide
-
-@drawsvg begin
-background("grey20") # hide
-helloworld() # hide
-eyepoint(200, 200, 200)
-axes3D(300)
-setlinejoin("bevel")
-
-include(dirname(pathof(Thebes)) * "/../data/moreobjects.jl")
-
-objectfull = make(cuboctahedron, "the full object")
-objectcut  = make(cuboctahedron, "the cut-open object")
-
-map(o -> scaleby!(o, 60, 60, 60), (objectfull, objectcut))
-
-function cullfrontfaces!(m::Object, angle;
-        eyepoint::Point3D=eyepoint())
-    avgs = Float64[]
-    for f in m.faces
-        vs = m.vertices[f]
-        s = 0.0
-        for v in vs
-            s += distance(v, eyepoint)
-        end
-        avg = s/length(unique(vs))
-
-        θ = surfacenormal(vs)
-        if anglebetweenvectors(θ, eyepoint) > angle
-            push!(avgs, avg)
-        end
-    end
-    neworder = reverse(sortperm(avgs))
-    m.faces = m.faces[neworder]
-    m.labels = m.labels[neworder]
-    return m
-end
-
-sortfaces!.((objectcut, objectfull))
-cullfrontfaces!(objectcut, π/3)
-
-translate(-200, 0)
-pin(objectcut)
-
-translate(400, 0)
-pin(objectfull)
-
-@show length(objectcut.faces)
-@show length(objectfull.faces)
-end 800 600
-```
-
-The object on the left has had its four frontfacing faces removed. The one on the right is intact.
-
-# Geometry
-
-There are some basic geometry utility functions - some of them are analogous to their Luxor 2D counterparts.
-
 ## General
 
 ```@docs
@@ -83,13 +20,16 @@ drawcube
 using Thebes, Luxor # hide
 @drawsvg begin
 background("grey20")
+helloworld()
 sethue("grey40")
 carpet(400)
 drawcube(150)
 axes3D()
 end 800 400
 ```
 
+There are some basic geometry utility functions - some of them are analogous to their Luxor 2D counterparts.
+
 ## Distances
 
 ```@docs