update reference

README.md

@@ -6,7 +6,7 @@ A toy language.
 
 A kind of LOGO-like DSL built in the p5.js library.
 
-This is a rudimentary proof of concept right now with globals and without implementing classes or ability to loop.
+This is a rudimentary proof of concept right now with globals and without implementing classes.  To write loops or *subroutines* one must use regular javascript.
 
 ## How to Use
 
@@ -14,32 +14,110 @@ Put your code inside the turtle function in turtle.js
 
 ## Reference Commands
 
+
+### Movement
+
 ```
-//movement
+forward(n)
+```
+move n pixels ahead
 
-forward(n); //moves n pixels ahead
+```
+back(n)
+```
+move n pixels back
 
-back(n); //moves n pixels back
+```
+left(Δ)  
+```
+turns Δ degrees to the left
 
-left(Δ);  //turns Δ degrees to the left
+```
+right(Δ)
+```
+turns Δ degrees to the right
 
-right(Δ); //turns Δ degrees to the right
+### Drawing
 
-//drawing
+```
+penup()
+```
+Going forward, Turtle will stop drawing a line with movement commands
 
-penup(); //will draw a line with movement commands
+```
+pendown()
+``` 
+Turtle will start drawing lines tracing route.  **By default, pendown is on / true**
 
-pendown(); //will move to x,y coordinates without drawing line
-           //By default, pendown is on / true
-penColor('colorName'); //any color word: purple, grey, blue, etc.
-		       //color name must be in single or double quotes!
-                       //or a HTML color like #ff4d4d (in quotes!)
-penSize(n);	       //width of pen in pixels
+```
+penColor('colorName')
+```
+penColor takes any color word: purple, grey, blue, etc. **The color name must be in quotes.**
+
+Alternatively, a HTML color name, like #ff4d4d, may be specified in quotes. Example: ```penColor('$ff4d4d')```
+
+Alternatively, a RGB color or RGBA color with transparency can be specified, with *color*. Example: ```penColor(color(255,0,255))```. See transparency example in examples section below.
+
+```
+penSize(n)
+```
+Width of pen in pixels
 		       
-//randomness
+### Randomness
 
-randint(n); //returns a random int between 0 and n (exclusive)
-	    //if no input, default is between 0 and 100
-            //example: forward(randint(30)); 
+```
+randint(n)
 ```
 
+or
+
+```
+randint()
+```
+Returns a random int between 0 and n. Specifying a value is optional. If no input *n*, the default is between 0 and 100. Example: ```forward(randint(30))```
+
+
+## Examples
+
+### Backwards box
+
+```
+penColor('orange');
+penSize(3);
+
+left(90);
+back(100);
+left(90);
+back(100);
+left(90);
+back(100);
+left(90);
+back(100);
+```
+
+### Random Walk (with javascript for-loop)
+
+```
+for (let i = 0; i < 100; i++){
+  right(randint());
+  forward(randint());
+}
+ 
+```
+
+### Forward, with color transparency
+
+In this example, the last parameter inside penColor's color is the alpha transparency amount. Like the individual red, green, blue colors specified before it, this can be a number from 0 to 255. The lower the number, the more transparent.
+
+```
+penSize(20);
+
+penColor(color(100,0,100,50));
+forward(100);
+
+penColor(color(100,0,100,150));
+forward(100);
+
+penColor(color(100,0,100,250));
+forward(100);
+```