Merge pull request #207 from urbit/say-fix

Expand on %say generators.

content/guides/core/hoon-school/J-stdlib-text.md

@@ -512,14 +512,14 @@ The expression above creates a cell with `%say` as the head. The tail is the `|=
 
 `|= *` constructs a [gate](/reference/glossary/gate/) that takes a noun. This [gate](/reference/glossary/gate/) will itself produce a `cask`, which is cell formed by the prepending `:-`. The head of that `cask` is `%noun` and the tail is the rest of the program, `(add 40 2)`. The tail of the `cask` will be our actual data produced by the body of the program: in this case, just adding 40 and 2 together.
 
-A `%say` generator has access to values besides those passed into it and the Hoon standard subject.  Namely, a `%say` generator knows about `our`, `eny`, and `now`:
+A `%say` generator has access to values besides those passed into it and the Hoon standard subject.  Namely, a `%say` generator knows about `our`, `eny`, and `now`, as well as the current desk:
 
 - `our` is our current ship identity.
 - `eny` is entropy, a source of randomness.
 - `now` is the current system timestamp.
 - `bec` is the current path (beak).
 
-Dojo will automatically supply these values to the gate unless they are stubbed out with `*`.
+These values can be stubbed out with `*` or `^` if they are not needed in a particular generator.
 
 ### `%say` generators with arguments
 
@@ -577,6 +577,11 @@ Since this is a `%say` generator, we can run it without arguments:
 "Ask again later."
 ```
 
+If we need to include optional arguments to a generator, we separate them using a `,` com:
+
+```hoon
++cat /===/gen/cat/hoon, =vane %c
+```
 
 ##  Exercise:  Using the Playing Card Library
 

content/guides/core/hoon-school/O-subject.md

@@ -255,6 +255,8 @@ To act in a stateful manner, a core must mutate itself and then pin the mutated
 
 We will use `%say` generators as a bridge concept.  We will produce some short applications that maintain state while carrying out a calculation; they still result in a single return value, but gesture at the big-picture approach to maintaining state in persistent agents.
 
+[As you may recall](./J-stdlib-text.md), a `%say` generator is like a naked generator except rather than being simply a gate, it is a cell of `%say` (as a tag) and a gate.  This gate can receive more information as gate arguments as part of its `sample`, such as a timestamp `now`, some entropy `eny`, and a file system beak `bec`.  These allow us to think about how a core can modify and maintain state.  Although a `%say` generator, like all generators, ultimately simply terminates, a Gall agent will be a persistent core with state that can continue to be used.
+
 Here are a couple of new runes for modifying the subject and chaining computations together, aside from `%=` centis which you've already seen:
 
 - [`=.` tisdot](/reference/hoon/rune/tis#-tisdot) is used to change a leg in the subject.

content/guides/core/hoon-school/P-stdlib-io.md

@@ -203,7 +203,7 @@ For instance, how does `+cat` work?  Let's look at the structure of `/gen/cat/ho
 ==
 ```
 
-- What is the top-level structure of the generator?  (A cell of `%say` and the gate, previewing `%say` generators.)
+- What is the top-level structure of the generator?  (A cell of `%say` and the gate, what Dojo recognizes as a `%say` generator.)
 
 - Some points of interest include:
   - `/?` faswut pins the expected Arvo kelvin version; right now it doesn't do anything.