Merge branch 'master' of github.com:inkle/ink

Documentation/WritingWithInk.md

@@ -541,7 +541,15 @@ You can use several logical tests on an option; if you do, *all* the tests must
 	+ 	{ visit_paris } { not bored_of_paris } 
 		[Return to Paris] -> visit_paris 
 
+#### Logical operators: AND and OR 
 
+The above "multiple conditions" are really just conditions with an the usual programming AND operator. Ink supports `and` (also written as `&&`) and `or` (also written as `||`) in the usual way, as well as brackets. 
+
+	*	{ not (visit_paris or visit_rome) && (visit_london || visit_new_york) } [ Wait. Go where? I'm confused. ] -> visit_someplace
+
+For non-programmers `X and Y` means both X and Y must be true. `X or Y` means either or both. We don't have a `xor`. 
+
+You can also use the standard `!` for `not`, though it'll sometimes confuse the compiler which thinks `{!text}` is a once-only list. We recommend using `not` because negated boolean tests are never that exciting. 
 
 #### Advanced: knot/stitch labels are actually read counts
 
@@ -555,6 +563,7 @@ If it's non-zero, it'll return true in a test like the one above, but you can al
 
 	* {seen_clue > 3} [Flat-out arrest Mr Jefferson]
 
+
 #### Advanced: more logic
 
 **ink** supports a lot more logic and conditionality than covered here - see the section on 'variables and logic'.
@@ -721,13 +730,13 @@ or:
 
 	"I missed him. Was he particularly evil?"
 
-## 7) Game Queries
+## 7) Game Queries and Functions
 
 **ink** provides a few useful 'game level' queries about game state, for use in conditional logic. They're not quite parts of the language, but they're always available, and they can't be edited by the author. In a sense, they're the "standard library functions" of the language.
 
 The convention is to name these in capital letters.
 
-### CHOICE_COUNT
+### CHOICE_COUNT()
 
 `CHOICE_COUNT` returns the number of options created so far in the current chunk. So for instance.
 
@@ -737,7 +746,11 @@ The convention is to name these in capital letters.
 
 produces two options, B and C. This can be useful for controlling how many options a player gets on a turn. 
 
-### TURNS_SINCE
+### TURNS()
+
+This returns the number of game turns since the game began. 
+
+### TURNS_SINCE(-> knot)
 
 `TURNS_SINCE` returns the number of moves (formally, player inputs) since a particular knot/stitch was last visited.
 
@@ -750,6 +763,14 @@ Note that the parameter passed to `TURNS_SINCE` is a "divert target", not simply
 
 TODO: (requirement of passing `-c` to the compiler)
 
+### SEED_RANDOM()
+
+For testing purposes, it's often useful to fix the random number generator so ink will produce the same outcomes every time you play. You can do this by "seeding" the random number system. 
+
+	~ SEED_RANDOM(235) 
+
+The number you pass to the seed function is arbitrary, but providing different seeds will result in different sequences of outcomes. 
+
 #### Advanced: more queries
 
 You can make your own external functions, though the syntax is a bit different: see the section on functions below.
@@ -1263,6 +1284,18 @@ and the following will test conditions:
 
 If more complex operations are required, one can write functions (using recursion if necessary), or call out to external, game-code functions (for anything more advanced). 
 
+#### RANDOM(min, max) 
+
+Ink can generate random integers if required using the RANDOM function. RANDOM is authored to be like a dice (yes, pendants, we said *a dice*), so the min and max values are both inclusive. 
+
+	~ temp dice_roll = RANDOM(1, 6) 
+
+	~ temp lazy_grading_for_test_paper = RANDOM(30, 75)  
+
+	~ temp number_of_heads_the_serpent_has = RANDOM(3, 8)
+
+The random number generator can be seeded for testing purposes, see the section of Game Queries and Functions section above. 
+
 #### Advanced: numerical types are implicit
 
 Results of operations - in particular, for division - are typed based on the type of the input. So integer division returns integer, but floating point division returns floating point results. 
@@ -2339,6 +2372,7 @@ We have a few basic ways of getting information about what's in a list:
 	{LIST_COUNT(DoctorsInSurgery)} 	//  "2"
 	{LIST_MIN(DoctorsInSurgery)} 		//  "Adams"
 	{LIST_MAX(DoctorsInSurgery)} 		//  "Cartwright"
+	{LIST_RANDOM(DoctorsInSurgery)} 	//  "Adams" or "Cartwright"
 
 #### Testing for emptiness