@@ -106,9 +106,9 @@ need to do is produce `card`s with `%fact`s in them:
106106==
107107```
108108
109−The `(list path)` in the `%fact` specifies which subscription `path`s to which
110−the `%fact` should be sent. All subscribers of all `path`s specified will
111−receive the `%fact`. Any agent arm which produces a `(quip card _this)` can send
109+The `(list path)` in the `%fact` specifies which subscription `path`s the
110+`%fact` should be sent on. All subscribers of all `path`s specified will receive
111+the `%fact`. Any agent arm which produces a `(quip card _this)` can send
112112`%fact`s to subscribers. Most often they will be produced in the `on-poke` arm,
113113since new data will often be added in `poke`s.
114114
@@ -129,13 +129,13 @@ from, and the `(unit ship)` specifies which ship to kick. The `(unit ship)` can
129129
130130In this case, all subscribers to the specified `path`s will be kicked.
131131
132−Note that `%kick`s are not exclusively sent by the agent itself - Gall can also
133−automatically kick subscribers under certain network conditions. Because of
134−this, `%kick`s are not typically interpreted as intentional, and the usual
135−behavior for a kicked agent is to try and resubscribe. Therefore, if you want to
136−disallow a particular subscriber, your agent's `on-watch` arm should reject
137−further subscription requests from them - your agent should not just `%kick`
138−them and call it a day.
132+Note that `%kick`s are not exclusively sent by the agent itself - Gall itself
133+can also kick subscribers under certain network conditions. Because of this,
134+`%kick`s are not assumed to be intentional, and the usual behavior is for a
135+kicked agent to try and resubscribe. Therefore, if you want to disallow a
136+particular subscriber, your agent's `on-watch` arm should reject further
137+subscription requests from them - your agent should not just `%kick` them and
138+call it a day.
139139
140140## Outgoing subscriptions
141141
@@ -148,17 +148,20 @@ it: Subscribing to other agents. This is done by `%pass`ing the target agent a
148148```
149149
150150If yor agent's subscription request is successful, updates will come in to your
151−agent's `on-agent` arm on the `wire` (`/some/wire` in this example) specified.
151+agent's `on-agent` arm on the `wire` specified (`/some/wire` in this example).
152152The `wire` can be anything you like - its purpose is for your agent to figure
153153out which subscription the updates are for. The `[ship term]` pair specifies the
154154ship and agent you're trying to subscribe to, and the final `path` (`/some/path`
155−in this example) is the subscription path to which you want to to subscribe - a
156−`path` the target agent has defined in its `on-watch` arm.
155+in this example) is the path you want to subscribe to - a `path` the target
156+agent has defined in its `on-watch` arm.
157157
158158Gall will deliver the `card` to the target agent and call that agent's
159159`on-watch` arm, which will process the request [as described
160160above](#incoming-subscription-requests), accept or reject it, and send back
161−either a positive or negative `%watch-ack`. The `%watch-ack` will come back in to your agent's `on-agent` arm in a `sign`, along with the `wire` you specified (`/some/wire` in this example):
161+either a positive or negative `%watch-ack`. The `%watch-ack` will come back in
162+to your agent's `on-agent` arm in a `sign`, along with the `wire` you specified
163+(`/some/wire` in this example). Recall in the lesson on pokes, the `on-agent`
164+arm starts with:
162165
163166```hoon
164167++ on-agent
@@ -173,15 +176,11 @@ The `sign` will be of the following format:
173176[%watch-ack p=(unit tang)]
174177```
175178
176−How you want to handle the `%watch-ack` really depends on the particular agent. In the simplest case, you can just pass it to the `on-agent` arm of `%default-agent`:
177−
178−```hoon
179−++ on-agent on-agent:def
180−```
181−
182−`%default-agent` will just accept it and do nothing apart from printing the
183−error in the `%watch-ack` `tang` if it's a nack. You shouldn't have your agent
184−crash on a `%watch-ack` - even if it's a nack your agent should process it
179+How you want to handle the `%watch-ack` really depends on the particular agent.
180+In the simplest case, you can just pass it to the `on-agent` arm of
181+`default-agent`, which will just accept it and do nothing apart from printing
182+the error in the `%watch-ack` `tang` if it's a nack. You shouldn't have your
183+agent crash on a `%watch-ack` - even if it's a nack your agent should process it
185184successfully. If you wanted to apply some additional logic on receipt of the
186185`%watch-ack`, you'd typically first test the `wire`, then test whether it's a
187186`%watch-ack`, then test whether it's an ack or a nack and do whatever's
@@ -213,10 +212,9 @@ an error message fed into the `on-fail` arm of your agent.
213212## Receiving updates
214213
215214Assuming the `%watch` succeeded, your agent will now begin receiving any
216−`%fact`s the agent to which you've subscribed publishes on the path to which
217−you've subscribed. These `%fact`s will also come in to your agent's `on-agent`
218−arm in a `sign`, just like the initial `%watch-ack`. The `%fact` `sign` will
219−have the following format:
215+`%fact`s the other agent publishes on the path to which you've subscribed. These
216+`%fact`s will also come in to your agent's `on-agent` arm in a `sign`, just like
217+the initial `%watch-ack`. The `%fact` `sign` will have the following format:
220218
221219```hoon
222220[%fact =cage]
@@ -606,7 +604,8 @@ currently exists, getting the new subscriber up to date.
606604```
607605
608606This is the subscriber agent. Since it's just for demonstrative purposes, it has
609−no state and just prints updates it receives. In practice it would probably keep the `tasks` map it receives in its own state, and then update it as it receives new
607+no state and just prints updates it receives. In practice it would keep the
608+`tasks` map it receives in its own state, and then update it as it receives new
610609`%fact`s.
611610
612611The `on-poke` arm is fairly simple - it accepts two pokes, to either `[%sub ~some-ship]` or `[%unsub ~some-ship]`.
@@ -618,7 +617,10 @@ failed, as well as printing a message when it gets kicked. When it receives a
618617
619618### Trying it out
620619
621−We're going to try this between two different ships. The first ship will be the usual fakezod. We'll add both `mark` files, the `/sur` file, and the `todo.hoon` agent to the `%base` desk of our fakezod, putting them in the following directories:
620+We're going to try this between two different ships. The first ship will be the
621+usual fakezod. We'll add both `mark` files, the `/sur` file, and the `todo.hoon`
622+agent to the `%base` desk of our fakezod, putting them in the following
623+directories:
622624
623625```
624626base
@@ -644,7 +646,8 @@ Now we need to spin up another fake ship. We'll use `~nut` in this example:
644646urbit -F nut
645647```
646648
647−Once it's booted, we can `|mount %base` and then add just the `update.hoon` mark file, the `/sur` file, and the `todo-watcher.hoon` agent like so:
649+Once it's booted, we can `|mount %base` and then add just the `update.hoon` mark
650+file, the `/sur` file, and the `todo-watcher.hoon` agent like so:
648651
649652```
650653base
@@ -827,8 +830,9 @@ was rejected because `~nut` is no longer in `friends`:
827830
828831## Exercises
829832
830−- Have a look at the [Strings Guide](/docs/hoon/guides/strings) if you're
833+- Have a look at the [Strings Guide](/docs/hoon/guides/strings) if you're not
831834 already familiar with decoding/encoding atoms in strings.
832−- Try running through the [Example](#example) yourself, if you've not done so already.
835+- Try running through the [example](#example) yourself, if you've not done so
836+ already.
833837- Try modifying `%todo-watcher` to recording the data it receives in its state,
834838 rather than simply printing it to the terminal.