@@ -18,9 +18,9 @@ very simple union in the `vase` for incoming pokes:
1818=/ action !<(?(%inc %dec) vase)
1919```
2020
21−A real Gall agent, however, is likely to have a more complicated API. The most
22−common approach is to define a head-tagged union of all possible poke types the
23−agent will accept, and another for all possible updates it might send out to
21+A real Gall agent is likely to have a more complicated API. The most common
22+approach is to define a head-tagged union of all possible poke types the agent
23+will accept, and another for all possible updates it might send out to
2424subscribers. Rather than defining these types in the agent itself, you would
2525typically define them in a separate core saved in the `/sur` directory of the
2626desk. The `/sur` directory is short for "**s**truct**ur**es", and is the
@@ -28,8 +28,8 @@ canonical location for userspace type definitions.
2828
2929With this approach, your agent can simply import the structure file and make use
3030of its types. Additionally, if someone else wants to write an agent that
31−interfaces with yours, they can simply include your structure file in their own
32−desk and easily interface with your agent's API.
31+interfaces with yours, they can include your structure file in their own desk
32+and easily interact with your agent's API.
3333
3434#### Example
3535
@@ -126,9 +126,9 @@ Let's break this down a bit. Firstly, our `on-poke` arm includes a
126126core with a `$` arm that's computed immediately. We extract the `vase` to the
127127`action:todo` type and immediately pass it to the `handle-poke` arm of the core
128128created with the barket. This `handle-poke` arm tests what kind of `action` it's
129−received by checking its head, updates the state, and also sends an update to
130−subscribers, as appropriate. Don't worry too much about the `%give` `card` for
131−now - we'll cover subscriptions in the next lesson.
129+received by checking its head. It then updates the state, and also sends an
130+update to subscribers, as appropriate. Don't worry too much about the `%give`
131+`card` for now - we'll cover subscriptions in the next lesson.
132132
133133Notice that the `handle-poke` arm produces a `(quip card _state)` rather than
134134`(quip card _this)`. The call to `handle-poke` is also part of the following
@@ -168,7 +168,9 @@ what such `mark`s represent, or considered writing custom ones.
168168
169169Formally, marks are file types in the Clay filesystem. They correspond to mark
170170files in the `/mar` directory of a desk. The `%noun` mark, for example,
171−corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data type for the file (e.g. a `*` noun for the `%noun` mark), but they also specify some extra things:
171+corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data
172+type for the file (e.g. a `*` noun for the `%noun` mark), but they also specify
173+some extra things:
172174
173175- Methods for converting between the mark in question and other marks.
174176- Revision control functions like patching, diffing, merging, etc.
@@ -176,14 +178,14 @@ corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data
176178Aside from their use by Clay for storing files in the filesystem, they're also
177179used extensively for exchanging data with the outside world, and for exchanging
178180data between Gall agents. When data comes in from a remote ship, destined for a
179−particular Gall agent, it will be validated by the local mark file in `/mar`
180−which corresponds to its `mark` before being delivered to the agent. If the
181−remote data has no corresponding mark in `/mar` or it fails validation, it will
182−crash before it touches the agent.
181+particular Gall agent, it will be validated by the mark file in `/mar` that
182+corresponds to its `mark` before being delivered to the agent. If the remote
183+data has no corresponding mark in `/mar` or it fails validation, it will crash
184+before it touches the agent.
183185
184−A mark file is a `door` with three arms. The door's sample is the data type that
185−particular mark will handle. For example, the sample of the `%noun` mark is just
186−`non=*`, since it handles any noun. The three arms are as follows:
186+A mark file is a `door` with three arms. The door's sample is the data type the
187+mark will handle. For example, the sample of the `%noun` mark is just `non=*`,
188+since it handles any noun. The three arms are as follows:
187189
188190- `grab`: Methods for converting _to_ our mark _from_ other marks.
189191- `grow`: Methods for converting _from_ our mark _to_ other marks.
@@ -192,16 +194,16 @@ particular mark will handle. For example, the sample of the `%noun` mark is just
192194In the context of Gall agents, you'll likely just use marks for sending and
193195receiving data, and not for actually storing files in Clay. Therefore, it's
194196unlikely you'll need to write custom revision control functions in the `grad`
195−arm for marks you use in your agent. Instead, you can simply delegate `grad`
196−functions to another mark - typically `%noun`. If you want to learn more about
197−writing such `grad` functions, you can refer to the [Marks
198−Guide](/docs/arvo/clay/marks/marks) in the Clay vane documentation, which is
199−much more comprehensive, but it's not necessary for our purposes here.
197+arm. Instead, you can simply delegate `grad` functions to another mark -
198+typically `%noun`. If you want to learn more about writing such `grad`
199+functions, you can refer to the [Marks Guide](/docs/arvo/clay/marks/marks) in
200+the Clay vane documentation, which is much more comprehensive, but it's not
201+necessary for our purposes here.
200202
201203#### Example
202204
203205Here's a very simple mark file for the `action` structure we created in the
204−[previous section](sur):
206+[previous section](#sur):
205207
206208```hoon
207209/- todo
@@ -231,10 +233,10 @@ it will handle. Now let's consider the arms:
231233- `grow`: This handles conversion methods _from_ our mark. Like `grab`, it
232234 contains a core with arm names corresponding to other marks. Here we've also
233235 only added an arm for a `%noun` mark. In this case, `action` data will come in
234− as the sample of our `door`, and the `noun` arm simply returns its, since it's
236+ as the sample of our `door`, and the `noun` arm simply returns it, since it's
235237 already a noun (as everything is in Hoon).
236238- `grad`: This is the revision control arm, and as you can see we've simply
237− delegated such functions to the `%noun` mark.
239+ delegated it to the `%noun` mark.
238240
239241This mark file could be saved as `/mar/todo/action.hoon`, and then the `on-poke`
240242arm in the previous example could test for it instead of `%noun` like so:
@@ -249,7 +251,7 @@ arm in the previous example could test for it instead of `%noun` like so:
249251```
250252
251253Note how `%todo-action` will be resolved to `/mar/todo/action.hoon` - the hyphen
252−will be interpreted as `/` if there's not already `/mar/todo-action.hoon`.
254+will be interpreted as `/` if there's not already a `/mar/todo-action.hoon`.
253255
254256This simple mark file isn't all that useful. Typically, you'd add `json` arms to
255257`grow` and `grab`, which allow your data to be converted to and from JSON, and
@@ -270,10 +272,9 @@ pokes are actually coming from - our example agents would accept data from
270272anywhere, including random foreign ships. We'll now have a look at how to handle
271273such permission checks.
272274
273−The `bowl` provided as the sample of an agent core includes a couple of useful
274−fields: `our` and `src`. The `our` field just contains the `@p` of the local
275−ship. The `src` field contains the `@p` of the ship from which the event
276−originated.
275+The `bowl` includes a couple of useful fields: `our` and `src`. The `our` field
276+just contains the `@p` of the local ship. The `src` field contains the `@p` of
277+the ship from which the event originated.
277278
278279When messages come in over Ames from other ships on the network, they're
279280encrypted with our ship's public keys and signed by the ship which sent them.
@@ -338,7 +339,8 @@ Mark files:
338339- A `mark` like `%foo` corresponds to a file in `/mar` like `/mar/foo.hoon`
339340- Marks are file types in Clay, but are also used for passing data between
340341 agents as well as for external data generally.
341−- A mark file is a `door` with a sample of the data type it handles and three arms: `grab`, `grow` and `grad`.
342+- A mark file is a `door` with a sample of the data type it handles and three
343+ arms: `grab`, `grow` and `grad`.
342344- `grab` and `grow` each contain a core with arm names corresponding to other marks.
343345- `grab` and `grow` define functions for converting to and from our mark,
344346 respectively.