fee2eb2 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

clay: stylistic fixes

update docs per review comments to: - capitalise vanes - backtick all type refs - fix task & gift formatting - minor other fixes

commitfee2eb2d0f8149c4daddcb84109c8685c405f1b9 authortinnus-napbus <admin@tinnus-napbus.xyz> dateThu 20 May 2021, 17:13 (5 years ago) parent5a67184

7 files changed+115−113

compare with master

unifiedsplit

arvo/clay/foreign-requests.md+10−10 arvo/clay/merge.md+11−11 arvo/clay/mounts.md+14−14 arvo/clay/permissions.md+16−16 arvo/clay/read.md+30−30 arvo/clay/scry.md+26−24 arvo/clay/write.md+8−8

arvo/clay/foreign-requests.md+10−10

@@ -4,9 +4,9 @@ weight = 11

44template = "doc.html"

55+++

7−Here we'll looking at making `clay` requests to a foreign ship.

7+Here we'll looking at making Clay requests to a foreign ship.

9−As it currently stands, it's not possible to write to a foreign desk. Additionally, remote scries are not implemented. That leaves requests to read files (`%warp`) and merge desks (`%merg`).

9+As it currently stands, it's not possible to write to a foreign `desk`. Additionally, remote scries are not implemented. That leaves requests to read files (`%warp`) and merge desks (`%merg`).

1010

1111## Contents

1212

@@ -15,9 +15,9 @@ As it currently stands, it's not possible to write to a foreign desk. Additional

1515

1616## %warp

1717

18−To read files on a foreign desk, you just send clay a `%warp` `task:clay` (as you would for a local read) and specify the target ship in the `wer` field. For details on making such requests, see the [Read and Subscribe](@/docs/arvo/clay/read.md) document.

18+To read files on a foreign `desk`, you just send Clay a `%warp` `task` (as you would for a local read) and specify the target ship in the `wer` field. For details on making such requests, see the [Read and Subscribe](@/docs/arvo/clay/read.md) document.

1919

20−Clay only allows a subset of cares to be used remotely. They are:

20+Clay only allows a subset of `care`s to be used remotely. They are:

2121

2222- `%u` - Check for existence of file.

2323- `%v` - Get entire `dome:clay` state of a desk.

@@ -30,13 +30,13 @@ Any other `care` will crash with a `%clay-bad-foreign-request-care` error.

3030

3131The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details.

3232

33−Note that if you're reading a whole desk or directory, all subfolders and files must also permit reading. If even a single file does not permit you reading it, the foreign ship will not respond to the request.

33+Note that if you're reading a whole `desk` or directory, all subfolders and files must also permit reading. If even a single file does not permit you reading it, the foreign ship will not respond to the request.

3434

3535Example:

3636

3737We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.

3838

39−First we'll set permissions on the foreign ship. Here's a simple thread that just sends a task to clay:

39+First we'll set permissions on the foreign ship. Here's a simple thread that just sends a `task` to Clay:

4040

4141`send-clay-task.hoon`

4242

@@ -63,7 +63,7 @@ Create a file called `foo.txt` in the `%home` of ~nes. Save the above thread to

6363> -send-clay-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]

6464```

6565

66−If we scry the file for its permissions with a `%p` care, we'll see ~zod is now whitelisted:

66+If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:

6767

6868```hoon

6969> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)

@@ -139,8 +139,8 @@ call: failed

139139

140140## %merg

141141

142−To merge a foreign desk into a local one, you just send clay a `%merg` `task:clay` (as you would for a local merge) and specify the foreign ship in the `her` field. For details on making such requests, see the [Merge Desks](@/docs/arvo/clay/merge.md) document.

142+To merge a foreign `desk` into a local one, you just send Clay a `%merg` `task` (as you would for a local merge) and specify the foreign ship in the `her` field. For details on making such requests, see the [Merge Desks](@/docs/arvo/clay/merge.md) document.

143143

144−The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` desk.

144+The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` `desk`.

145145

146−Note that all subfolders and individual files within the desk must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.

146+Note that all subfolders and individual files within the `desk` must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.

arvo/clay/merge.md+11−11

@@ -4,9 +4,9 @@ weight = 9

44template = "doc.html"

55+++

7−Here we'll look at merging desks programmatically.

7+Here we'll look at merging `desk`s programmatically.

9−A `%merg` tagged `task:clay` will merge the specified source desk into the target local desk. It looks like:

9+A `%merg` `task` will merge the specified source `desk` into the target local `desk`. It looks like:

1010

1111```hoon

1212$: %merg :: merge desks

@@ -36,9 +36,9 @@ The `germ` specifies the merge strategy and looks like:

3636

3737You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.

3838

39−If you're merging into a new desk you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.

39+If you're merging into a new `desk` you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.

4040

41−Clay will respond to the request with a `%mere` tagged `gift:clay` which looks like:

41+Clay will respond to the request with a `%mere` `gift` which looks like:

4242

4343```hoon

4444[%mere p=(each (set path) (pair term tang))] :: merge result

@@ -59,7 +59,7 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher

5959

6060Example:

6161

62−Here's a thread that sends the given `task:clay` to clay and prints the `gift:clay` response:

62+Here's a thread that sends the given `task` to Clay and prints the `gift` response:

6363

6464`send-task.hoon`

6565

@@ -82,21 +82,21 @@ Here's a thread that sends the given `task:clay` to clay and prints the `gift:cl

8282

8383Save it to `ted/send-task.hoon` and `|commit %home`.

8484

85−First, let's try creating a new desk:

85+First, let's try creating a new `desk`:

8686

8787```hoon

8888> -send-task-take-gift [%merg %foo our %home da+now %init]

8989[%mere p=[%.y p={}]]

9090```

9191

92−Now if we scry for our desks we'll see `%foo` is there:

92+Now if we scry for our `desk`s we'll see `%foo` is there:

9393

9494```hoon

9595> .^((set desk) %cd /===)

9696{%home %foo %kids}

9797```

9898

99−Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both desks but with different text in each and `|commit` them.

99+Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both `desk`s but with different text in each and `|commit` them.

100100

101101Now we'll try merging `%home` into `%foo` with a `%mate` strategy:

102102

@@ -132,15 +132,15 @@ Now the merge has succeeded and the `%mere` notes the file with a merge conflict

132132: /~zod/foo/6/foo/txt

133133```

134134

135−...you can see it's overwritten the `foo/txt` in the `%foo` desk and the `%mere` now has an empty set, indicating no merge conflicts.

135+...you can see it's overwritten the `foo/txt` in the `%foo` `desk` and the `%mere` now has an empty `set`, indicating no merge conflicts.

136136

137−Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` task, we can set in in the future:

137+Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` `task`, we can set it in the future:

138138

139139```hoon

140140> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]

141141```

142142

143−Now change the text in the `foo.txt` in the `%home` desk, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:

143+Now change the text in the `foo.txt` in the `%home` `desk`, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:

144144

145145```hoon

146146[/foo [%clay [%mere p=[%.y p={}]]]]

arvo/clay/mounts.md+14−14

@@ -4,11 +4,11 @@ weight = 8

44template = "doc.html"

55+++

7−Here we'll look at managing clay unix mounts programmatically.

7+Here we'll look at managing Clay unix mounts programmatically.

99## Contents

1010

11−There are four `task:clay` tags relevant to mounts:

11+There are four Clay `task`s relevant to mounts:

1212

1313- [%boat](#boat) - List mounts.

1414- [%mont](#mont) - Mount something.

@@ -17,13 +17,13 @@ There are four `task:clay` tags relevant to mounts:

1717

1818## %boat

1919

20−This type of `task:clay` will request the list of existing mounts. It looks like:

20+This type of `task` will request the list of existing mounts. It looks like:

2121

2222```hoon

2323[%boat ~]

2424```

2525

26−Pretty simple. The type it returns is a `%hill` tagged `gift:clay`, which looks like:

26+Pretty simple. The type it returns is a `%hill` `gift`, which looks like:

2727

2828```hoon

2929[%hill p=(list @tas)]

@@ -33,7 +33,7 @@ Pretty simple. The type it returns is a `%hill` tagged `gift:clay`, which looks

3333

3434Example:

3535

36−Here's a thread that sends a `task:clay` and takes a `gift:clay` in response:

36+Here's a thread that sends a `task` and takes a `gift` in response:

3737

3838`send-task-take-gift.hoon`

3939

@@ -65,7 +65,7 @@ Save it to `ted/send-task-take-gift.hoon`, `|commit %home`, and run it like:

6565

6666## %mont

6767

68−This type of `task:clay` mounts the specified `beam:clay` to the specified `term` mount point. It looks like:

68+This type of `task` mounts the specified `beam:clay` to the specified `term` mount point. It looks like:

6969

7070```hoon

7171[%mont pot=term bem=beam]

@@ -81,7 +81,7 @@ You can mount the whole desk with a `path` of `/`, and you can also mount subdir

8181

8282Example:

8383

84−Here's a thread which will send the given `task:clay` to clay.

84+Here's a thread which will send the given `task` to Clay.

8585

8686`send-task.hoon`

8787

@@ -108,7 +108,7 @@ Save it to `ted/send-task.hoon`, `|commit %home` and run it like:

108108> -send-task [%mont %kids [our %kids da+now] /]

109109```

110110

111−If you look in your pier, you should now see a `kids` folder which contains the contents of that desk.

111+If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.

112112

113113If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:

114114

@@ -117,13 +117,13 @@ If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll no

117117[%hill p=~[%kids %home]]

118118```

119119

120−Note the mount point doesn't need to match a desk, file or directory. We can also do:

120+Note the mount point doesn't need to match a `desk`, file or directory. We can also do:

121121

122122```hoon

123123> -send-task [%mont %wibbly-wobbly [our %home da+now] /]

124124```

125125

126−And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` desk. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

126+And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

127127

128128Let's try mounting a subdirectory and a single folder:

129129

@@ -136,13 +136,13 @@ If you look in your pier you'll now see a `gen` folder with the contents of `/ge

136136

137137## %ogre

138138

139−This type of `task:clay` unmounts the specified mount. It's defined in `lull.hoon` as:

139+This type of `task` unmounts the specified mount. It's defined in `lull.hoon` as:

140140

141141```hoon

142142[%ogre pot=$@(desk beam)]

143143```

144144

145−But in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the desk but otherwise it won't work. Passing it a `beam:clay` will simply not work.

145+But in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.

146146

147147Using the thread from the [%mont](#mont) section, we can unmount `%kids` like:

148148

@@ -183,7 +183,7 @@ This type of `task:clay` commits changes in the target mount. It's defined in `l

183183

184184Example:

185185

186−With your `%home` desk mounted, try adding a file and, using the thread from the [%mont](#mont) section, send a `%dirk` to commit the change:

186+With your `%home` `desk` mounted, try adding a file and, using the thread from the [%mont](#mont) section, send a `%dirk` to commit the change:

187187

188188```hoon

189189> -send-task [%dirk %home]

@@ -192,4 +192,4 @@ With your `%home` desk mounted, try adding a file and, using the thread from the

192192

193193Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.

194194

195−If you have the same desk mounted to multiple points, a committed change in one mount will also update the others.

195+If you have the same `desk` mounted to multiple points, a committed change in one mount will also update the others.

arvo/clay/permissions.md+16−16

@@ -17,7 +17,7 @@ Here we'll look at file permissions.

1717

1818For each file or directory, there is both a read permission and a write permission. Each may be set separately and is either a whitelist or a blacklist (but not both). The whitelist/blacklist contains a `set` of ships and/or groups which are allowed or banned respectively. If it's an empty whitelist it means all foreign ships are denied. If it's an empty blacklist it means all foreign ships are allowed.

1919

20−If permissions are not set for a particular file, they will be inherited from the directory in which it resides. If *that* directory has no permissions set, they will be inherited from another level up, and so on to the desk's root directory. If the root directory has no permissions set, it will have the default permissions of an empty whitelist, meaning "deny all".

20+If permissions are not set for a particular file, they will be inherited from the directory in which it resides. If *that* directory has no permissions set, they will be inherited from another level up, and so on to the `desk`'s root directory. If the root directory has no permissions set, it will have the default permissions of an empty whitelist, meaning "deny all".

2121

2222A group is called a `crew` and is just a `set` of ships with a `@ta` name.

2323

@@ -38,20 +38,20 @@ The `src` path is where the permissions were inherited from and the `real` is th

3838 == ::

3939```

4040

41−So if we scry for permissions with a `%p` care, it'll look like:

41+So if we scry for permissions with a `%p` `care`, it'll look like:

4242

4343```hoon

4444> .^([r=dict:clay w=dict:clay] %cp /===/lib/strandio/hoon)

4545[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]

4646```

4747

48−There are four permission-related tasks which you can pass to clay.

48+There are four permission-related `task`s which you can pass to Clay.

4949

50−A `%perm` task is for setting permissions, and the other three are for managing groups:

50+A `%perm` `task` is for setting permissions, and the other three are for managing groups:

5151

52−- `%cred` - add permission group

53−- `%crew` - get permission groups

54−- `%crow` - get group usage

52+- `%cred` - Add permission group.

53+- `%crew` - Get permission groups.

54+- `%crow` - Get group usage.

5555

5656We'll look at each of these in turn.

5757

@@ -61,7 +61,7 @@ This sets permissions for the target file or directory.

6161

6262Note this will replace existing permissions rather than add to them, so if you want to add a ship to an existing whitelist or whatever you'll have to first read the existing permissions, add the ship, then send the whole lot back.

6363

64−A `%perm` tagged `task:clay` looks like:

64+A `%perm` `task` looks like:

6565

6666```hoon

6767[%perm des=desk pax=path rit=rite] :: change permissions

@@ -92,7 +92,7 @@ As the comment suggests, the `@ta` is the name of a `crew` (group).

9292

9393Example:

9494

95−Here's a generic thread that just sends the given `task:clay` to clay so we can try a few different things:

95+Here's a generic thread that just sends the given `task` to Clay so we can try a few different things:

9696

9797`send-clay-task.hoon`

9898

@@ -121,7 +121,7 @@ Save it to `ted/send-clay-task.hoon` and `|commit %home`. Now, let's allow `~nes

121121

122122...and we'll do a `%p` scry to see that the permission was set:

123123

124−```hood

124+```hoon

125125> .^([r=dict:clay w=dict:clay] %cp /===/gen/hood/hi/hoon)

126126[r=[src=/gen/hood/hi/hoon rul=[mod=%white who=[p={~nes} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]

127127```

@@ -178,7 +178,7 @@ For example, to remove a read permission (or write if you specify `%w`):

178178> -send-clay-task [%perm %home /gen/help/hoon %rw ~ ~]

179179```

180180

181−```hood

181+```hoon

182182> .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)

183183[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]

184184```

@@ -211,7 +211,7 @@ We'll use the same thread from the [%perm](#perm) example. Try:

211211-send-clay-task [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]

212212```

213213

214−We'll check it with the next kind of task: [%crew](#crew).

214+We'll check it with the next kind of `task`: [%crew](#crew).

215215

216216## %crew

217217

@@ -221,7 +221,7 @@ This retrieves all permission groups. It looks like:

221221[%crew ~] :: permission groups

222222```

223223

224−Clay wil return a sign containing a `gift:clay` with a `%cruz` tag. It looks like:

224+Clay wil return a sign containing a `%cruz` `gift`. It looks like:

225225

226226```hoon

227227[%cruz cez=(map @ta crew)] :: permission groups

@@ -231,7 +231,7 @@ The `cez` is just a map from group name to `crew` which is just a `(set ship)`.

231231

232232Example:

233233

234−Here's a generic thread that sends the given `task:clay` and receives a gift which it just prints to the dojo.

234+Here's a generic thread that sends the given `task` and receives a `gift` which it just prints to the dojo.

235235

236236`send-task-take-gift.hoon`

237237

@@ -263,13 +263,13 @@ Save the above to `ted/send-task-take-gift.hoon` and `|commit %home`. Now we'll

263263

264264## %crow

265265

266−This is the last group task. It retrieves all files and directories in all desks which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set. It looks like:

266+This is the last group `task`. It retrieves all files and directories in all `desk`s which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set. It looks like:

267267

268268```hoon

269269[%crow nom=@ta] :: group usage

270270```

271271

272−The `gift:clay` you get back is a `%croz` which looks like:

272+The `gift` you get back is a `%croz` which looks like:

273273

274274```hoon

275275[%croz rus=(map desk [r=regs w=regs])] :: rules for group

arvo/clay/read.md+30−30

@@ -4,7 +4,7 @@ weight = 6

44template = "doc.html"

55+++

7−Here we'll look at reading files and subscribing to changes. We'll do this by sending clay a `card:agent:gall` containing a `%warp` tagged `task:clay`.

7+Here we'll look at reading files and subscribing to changes. We'll do this by sending Clay a `card` containing a `%warp` `task`.

99## Contents

1010

@@ -12,12 +12,12 @@ Here we'll look at reading files and subscribing to changes. We'll do this by se

1212- [%sing](#sing) - Read a single file or directory.

1313- [%next](#next) - Subscribe for the next change to a file or directory.

1414- [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.

15−- [%many](#many) - Track changes to a desk for the specified range of revisions.

15+- [%many](#many) - Track changes to a `desk` for the specified range of revisions.

1616- [Cancel Subsciption](#cancel-subscription)

1717

1818## Introduction

1919

20−A `%warp` task looks like:

20+A `%warp` `task` looks like:

2121

2222```hoon

2323[%warp wer=ship rif=riff] :: internal file req

@@ -29,7 +29,7 @@ The `riff` part is the following structure:

2929+$ riff [p=desk q=(unit rave)] :: request+desist

3030```

3131

32−The `desk` is the desk in question. The `(unit rave)` is null to cancel a subscription, otherwise the `rave` is:

32+ The `(unit rave)` is null to cancel a subscription, otherwise the `rave` is:

3333

3434```hoon

3535+$ rave :: general request

@@ -47,15 +47,15 @@ The `desk` is the desk in question. The `(unit rave)` is null to cancel a subscr

4747

4848We'll look at each of these in more detail later.

4949

50−Clay responds to a `%mult` request with a sign containing a `%wris` tagged `gift:clay`, and the rest with a `%writ`.

50+Clay responds to a `%mult` request with a `sign` containing a `%wris` `gift`, and the rest with a `%writ` `gift`.

5151

52−A `%wris` gift looks like:

52+A `%wris` `gift` looks like:

5353

5454```hoon

5555[%wris p=[%da p=@da] q=(set (pair care path))] :: many changes

5656```

5757

58−A `%writ` gift looks like:

58+A `%writ` `gift` looks like:

5959

6060```hoon

6161[%writ p=riot] :: response

@@ -93,9 +93,9 @@ This is for reading a single file or directory immediately. The `mood` structure

9393+$ mood [=care =case =path] :: request in desk

9494```

9595

96−The `care` is `%x`, `%y` or whatever else. This will determine what you can read and what type of data will be returned. See the type documentation and scry documentation for details on the various cares.

96+The `care` is `%x`, `%y` or whatever else. This will determine what you can read and what type of data will be returned. See the type documentation and scry documentation for details on the various `care`s.

9797

98−The `case` specifies the desk revision and looks like:

98+The `case` specifies the `desk` revision and looks like:

9999

100100```hoon

101101+$ case :: ship desk case spur

@@ -155,7 +155,7 @@ You should see something like this as the output:

155155]

156156```

157157

158−The `cage` in the `riot` contains the file's data due to our use of an `%x` care. It needn't be an `%x` though. If we change it to `%u`, for example, we'll get a `?` cage instead:

158+The `cage` in the `riot` contains the file's data due to our use of an `%x` `care`. It needn't be an `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:

159159

160160```hoon

161161> -read-file /gen/hood/hi/hoon

@@ -167,7 +167,7 @@ The `cage` in the `riot` contains the file's data due to our use of an `%x` care

167167]

168168```

169169

170−Here's a breakdown of the task we sent:

170+Here's a breakdown of the `task` we sent:

171171

172172![read file diagram](https://pub.m.tinnus-napbus.xyz/read-file.png "read file diagram")

173173

@@ -179,7 +179,7 @@ Here's a breakdown of the task we sent:

179179

180180This subscribes to the next version of the specified file. The `mood` structure is the same as described in the `%sing` example.

181181

182−If you subscribe to the current case of the desk, clay will not respond until the file changes. If you subscribe to a previous case of the desk and the file has changed in between then and now, it will immediately return the first change it comes across in that range. For example, if you're currently at case `100`, subscribe to case `50` and the file in question has been modified at both `60` and `80`, clay will immediately return the version of the file at case `60`.

182+If you subscribe to the current `case` of the `desk`, Clay will not respond until the file changes. If you subscribe to a previous `case` of the `desk` and the file has changed in between then and now, it will immediately return the first change it comes across in that range. For example, if you're currently at `case` `100`, subscribe to case `50` and the file in question has been modified at both `60` and `80`, clay will immediately return the version of the file at `case` `60`.

183183

184184`sub-next.hoon`

185185

@@ -208,7 +208,7 @@ If you subscribe to the current case of the desk, clay will not respond until th

208208(pure:m !>(~))

209209```

210210

211−This thread will subscribe to the next version of the file given as an argument. It will print the `riot` it gets back from clay and will also print a message saying whether the file's been deleted or changed.

211+This thread will subscribe to the next version of the file given as an argument. It will print the `riot` it gets back from Clay and will also print a message saying whether the file's been deleted or changed.

212212

213213Save this in `ted/sub-next.hoon`, `|commit %home` and run like:

214214

@@ -255,9 +255,9 @@ Here's a breakdown of the task we sent:

255255[%mult =mool] :: next version of any

256256```

257257

258−This subscribes to the next version of a set of files or directories. Clay will only send a single response, and it will send it when *any* of the specified files change. For example, if you subscribe to both `/foo/txt` and `/bar/txt`, and only `/foo/txt` changes, clay will send a response indicating a change to `/foo/txt`. If `/bar/txt` changes subsequently, it will not tell you. If more than one file changes at once, it will tell you about each of the changes in the one response.

258+This subscribes to the next version of a `set` of files or directories. Clay will only send a single response, and it will send it when *any* of the specified files change. For example, if you subscribe to both `/foo/txt` and `/bar/txt`, and only `/foo/txt` changes, Clay will send a response indicating a change to `/foo/txt`. If `/bar/txt` changes subsequently, it will not tell you. If more than one file changes at once, it will tell you about each of the changes in the one response.

259259

260−The behaviour with respect to requesting old cases is the same as explained in the [`%next`](#next) section above.

260+The behaviour with respect to requesting old `case`s is the same as explained in the [`%next`](#next) section above.

261261

262262The `mool` specified in the request is this structure:

263263

@@ -265,11 +265,11 @@ The `mool` specified in the request is this structure:

265265+$ mool [=case paths=(set (pair care path))] :: requests in desk

266266```

267267

268−You can use a different `care` for each of the files specified by the `path` if you like. Significantly, the `care` will determine whether clay sends a response for a given change. For example, if you subscribe to an existing `/foo/txt` with a `%u` care and `/foo/txt` is modified but isn't deleted, clay will *not* tell you. However, if you subscribe with an `%x` care, it *will* tell you.

268+You can use a different `care` for each of the files specified by the `path` if you like. Significantly, the `care` will determine whether Clay sends a response for a given change. For example, if you subscribe to an existing `/foo/txt` with a `%u` `care` and `/foo/txt` is modified but isn't deleted, Clay will *not* tell you. However, if you subscribe with an `%x` `care`, it *will* tell you.

269269

270270Example:

271271

272−This thread will subscribe to `/foo/txt` with an `%x` care and `/bar/txt` with a `%u` care. It will print out the `%wris` it gets back from clay.

272+This thread will subscribe to `/foo/txt` with an `%x` `care` and `/bar/txt` with a `%u` `care`. It will print out the `%wris` it gets back from Clay.

273273

274274`sub-mult.hoon`

275275

@@ -305,7 +305,7 @@ Save the above to `ted/sub-mult.hoon`, `|commit %home` and run with `-sub-mult`.

305305+ /~zod/home/151/bar/txt

306306```

307307

308−You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells gives you the cares and paths of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.

308+You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells you the `care`s and `path`s of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.

309309

310310Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %home`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.

311311

@@ -320,7 +320,7 @@ Lastly, delete `foo.txt` and `|commit %home`. You should see something like:

320320

321321As you can see, a relevant change to any of the subscribed files will trigger a response, not just when all of them change.

322322

323−Here's a breakdown of the task we sent:

323+Here's a breakdown of the `task` we sent:

324324

325325![subscribe mult diagram](https://pub.m.tinnus-napbus.xyz/sub-mult.png "subscribe mult diagram")

326326

@@ -330,7 +330,7 @@ Here's a breakdown of the task we sent:

330330[%many track=? =moat] :: track range

331331```

332332

333−This subscribes to all changes to a desk for the specified range of cases. Note that you're unlikely to use this directly, it's mostly used implicitly if you make a `%sing` or `%next` request with a `%v` care to a foreign desk. It's basically what the system uses to keep in sync with a foreign desk. Regardless, we'll have a look at it for completeness.

333+This subscribes to all changes to a `desk` for the specified range of `case`s. Note that you're unlikely to use this directly, it's mostly used implicitly if you make a `%sing` or `%next` request with a `%v` `care` to a foreign `desk`. Regardless, we'll have a look at it for completeness.

334334

335335If the `track` is `%.y` it will just return a `%writ` like:

336336

@@ -357,7 +357,7 @@ If the `track` is `%.n`, the `cage` of the `%writ` will contain a `nako`, which

357357 == ::

358358```

359359

360−As the comment explains, it contains all relevant data for a changes to a desk between what you have and the case requested. It is very large and fairly complicated. The `nako` structure is defined in the `clay.hoon` source file itself rather than in `lull.hoon` or elsewhere since you're unlikely to work with it yourself.

360+As the comment explains, it contains all relevant data for a changes to a desk between what you have and the `case` requested. It is very large and fairly complicated. The `nako` structure is defined in the `clay.hoon` source file itself rather than in `lull.hoon` or elsewhere since you're unlikely to work with it yourself.

361361

362362The `moat` in the `%many` is the following structure:

363363

@@ -365,11 +365,11 @@ The `moat` in the `%many` is the following structure:

365365 +$ moat [from=case to=case =path] :: change range

366366```

367367

368−The `from` and `to` fields specify the range of cases for which to subscribe. The range is *inclusive*. It can be specified by date or by revision number, whichever you prefer.

368+The `from` and `to` fields specify the range of `case`s for which to subscribe. The range is *inclusive*. It can be specified by date or by revision number, whichever you prefer.

369369

370−The `path` is a path to a file or directory. If it's `~` it refers to the root of the desk in question. This lets you say "only inform me of changes to the desk if the specified file or directory exists". If it doesn't exist, clay will send you nothing.

370+The `path` is a path to a file or directory. If it's `~` it refers to the root of the `desk` in question. This lets you say "only inform me of changes to the `desk` if the specified file or directory exists". If it doesn't exist, Clay will not send you anything.

371371

372−When you reach the end of the subscribed range of cases, clay will send you a `%writ` with a null `riot` to inform you the subscription has ended like:

372+When you reach the end of the subscribed range of `case`s, Clay will send you a `%writ` with a null `riot` to inform you the subscription has ended like:

373373

374374```hoon

375375[%writ p=~]

@@ -377,7 +377,7 @@ When you reach the end of the subscribed range of cases, clay will send you a `%

377377

378378Example:

379379

380−This thread will subscribe to changes to your `%home` desk for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of signs and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.

380+This thread will subscribe to changes to your `%home` `desk` for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of `sign`s and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.

381381

382382`sub-many.hoon`

383383

@@ -415,7 +415,7 @@ This thread will subscribe to changes to your `%home` desk for the next three mi

415415(pure:m !>(~))

416416```

417417

418−Make sure `foo.txt` doesn't exist in the root of your `%home` desk. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your desk and `|commit %home`. You should see something like:

418+Make sure `foo.txt` doesn't exist in the root of your `%home` `desk`. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your `desk` and `|commit %home`. You should see something like:

419419

420420```hoon

421421> |commit %home

@@ -423,7 +423,7 @@ Make sure `foo.txt` doesn't exist in the root of your `%home` desk. Save this to

423423+ /~zod/home/260/bar/txt

424424```

425425

426−Notice you've received no `%writ` from clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:

426+Notice you've received no `%writ` from Clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:

427427

428428```hoon

429429> |commit %home

@@ -459,7 +459,7 @@ Now wait until the three minutes is up and try making a change, for example dele

459459- /~zod/home/263/baz/txt

460460```

461461

462−You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of cases to which you subscribed.

462+You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of `case`s to which you subscribed.

463463

464464Run `:spider|kill` to stop the thread.

465465

@@ -497,7 +497,7 @@ This thread will subscribe to the `%next` version of `/foo/txt`, then immediatel

497497(pure:m !>(~))

498498```

499499

500−Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` desk and `|commit %home`. You should see:

500+Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` `desk` and `|commit %home`. You should see:

501501

502502```hoon

503503> |commit %home

@@ -509,6 +509,6 @@ As you can see we've received no `%writ`. We can thus conclude the subscription

509509

510510Run `:spider|kill` to stop the thread.

511511

512−Here's a breakdown of the task we sent:

512+Here's a breakdown of the `task` we sent:

513513

514514![cancel subscription diagram](https://pub.m.tinnus-napbus.xyz/stop-sub.png "cancel subscription diagram")

arvo/clay/scry.md+26−24

@@ -4,7 +4,7 @@ weight = 5

44template = "doc.html"

55+++

7−The various clay scries are specified by a `care`, which is a single character that corresponds with a clay submodule. Apart from `%s` they just take a path to a desk, file or directory. All examples are dojo commands, the ='s in the path are automatically populated by the dojo like:

7+The various Clay scries are specified by a `care`, which is a single character corresponding with a Clay submodule. Apart from `%s` they just take a `path` to a `desk`, file or directory. All examples are dojo commands, the ='s in the path are automatically populated by the dojo like:

99```hoon

1010> /===

@@ -39,7 +39,7 @@ The various clay scries are specified by a `care`, which is a single character t

3939

4040## a

4141

42−A scry with a care of `%a` will build a hoon file and return it as a `vase`.

42+A scry with a `care` of `%a` will build a `hoon` file and return it as a `vase`.

4343

4444Example:

4545

@@ -49,7 +49,7 @@ Example:

4949

5050## b

5151

52−A scry with a care of `%b` will produce a `dais:clay` processed mark core for the specified mark. The `path` in the scry is a `mark`.

52+A scry with a `care` of `%b` will produce a `dais:clay` processed `mark` core for the specified `mark`. The `path` in the scry is a `mark`.

5353

5454Example:

5555

@@ -59,7 +59,7 @@ Example:

5959

6060## c

6161

62−A scry with a care of `%c` will produce a `tube:clay` dynamically typed mark conversion gate. The `path` specifies two marks - *from* and *to*, like `/txt/noun`.

62+A scry with a `care` of `%c` will produce a `tube:clay` dynamically typed `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/noun`.

6363

6464Example:

6565

@@ -71,7 +71,7 @@ Example:

7171

7272## d

7373

74−A scry with a care of `%d` will return a `(set desk)` of the desks that exist on your ship.

74+A scry with a `care` of `%d` will return a `(set desk)` of the `desk`s that exist on your ship.

7575

7676Example:

7777

@@ -82,7 +82,7 @@ Example:

8282

8383## e

8484

85−A scry with a care of `%e` will return a statically typed `nave:clay` mark core in a `vase`. The `path` in the scry specifies the `mark`.

85+A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark` core in a `vase`. The `path` in the scry specifies the `mark`.

8686

8787Example:

8888

@@ -92,7 +92,7 @@ Example:

9292

9393## f

9494

95−A scry with a care of `%f` will return a static mark conversion gate. The `path` specifies two marks - *from* and *to*, like `/txt/mime`.

95+A scry with a `care` of `%f` will return a static `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/mime`.

9696

9797```hoon

9898> =a .^($-(text mime) %cf /===/txt/mime)

@@ -102,7 +102,7 @@ A scry with a care of `%f` will return a static mark conversion gate. The `path`

102102

103103## p

104104

105−A scry with a care of `%p` will return the permissions of the file or directory in question. The type returned is a `[dict:clay dict:clay]` where the head is read permissions and the tail is write permissions.

105+A scry with a `care` of `%p` will return the permissions of the file or directory in question. The type returned is a `[dict:clay dict:clay]` where the head is read permissions and the tail is write permissions.

106106

107107A `dict` is:

108108

@@ -124,7 +124,7 @@ A `dict` is:

124124- `mod` specifies either a **black**list or a **white**list.

125125- `who` specifies:

126126 - the set of allowed/disallowed ships.

127− - allowed/disallowed named crews (a crew is just a set of ships) - basically groups.

127+ - allowed/disallowed named `crew`s (a `crew` is just a `set` of ships) - basically groups.

128128

129129If the specified file or directory has no permissions set, it will default to the permissions of its parent. If nothing above it has permissions set, it will default to empty whitelists. If the specified file or directory doesn't exist, it will also return the default empty whitelist.

130130

@@ -137,7 +137,7 @@ Example:

137137

138138## r

139139

140−A scry with a care of `%r` will return the data of the given file wrapped in a vase or crash if it's a directory. It's basically just a vase-wrapped `x`.

140+A scry with a `care` of `%r` will return the data of the given file wrapped in a `vase` or crash if it's a directory. It's basically just a vase-wrapped `%x` scry.

141141

142142Examples:

143143

@@ -161,7 +161,9 @@ Crash!

161161

162162## s

163163

164−A scry with a care of `%s` is more complex than the rest. Rather than just a path to a file, the path has a head of one of `%yaki %blob %hash %cage %open %late %base`. The rest of the path will depend on which of these tags you use. We'll look at each in turn. Note that `%s` is miscellaneous internal and debug functions and is liable to change in the future.

164+A scry with a `care` of `%s` is for miscellaneous internal and debug functions and is liable to change in the future.

165+

166+Rather than just a `path` to a file, the head of the `path` is tagged with one of `%yaki %blob %hash %cage %open %late %base` and the tail depends on which tag you use. We'll look at each in turn.

165167

166168### yaki

167169

@@ -250,11 +252,11 @@ Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use i

250252

251253### open

252254

253−This is like an `%a` scry but it only compiles the prelude to the file, eg. the ford rune imports. Proper documentation for this will be done as part of ford documentaton at a later date.

255+This is like a `%a` scry but it only compiles the prelude to the file, e.g. the Ford rune imports. Proper documentation for this will be done as part of Ford documentaton at a later date.

254256

255257### late

256258

257−This will return the most recent revision number of a desk that has been fully downloaded. The type it returns is a `cass:clay`. The case in the `beak` must be a revision number rather than a date. You can just provide a case of `1` since it returns the latest regardless. If we have nothing for the specified desk, this will just return the bunt of a `cass:clay` like `cass=[ud=0 da=~2000.1.1]`

259+This will return the most recent revision number of a `desk` that has been fully downloaded. The type it returns is a `cass:clay`. The `case` in the `beak` must be a revision number rather than a date. You can just provide a case of `1` since it returns the latest regardless. If we have nothing for the specified `desk`, this will just return the bunt of a `cass:clay` like `cass=[ud=0 da=~2000.1.1]`.

258260

259261Example:

260262

@@ -270,7 +272,7 @@ cass=[ud=0 da=~2000.1.1]

270272

271273### base

272274

273−This will return the mergebase (i.e. most recent common ancestor) between two desks. The type it returns is a `(list tako:clay)`. The first desk will just be the one in the `beak` path prefix and the second will be specified like `/ship/desk` at the end of the scry path. If there is no common ancestor between the two desks, this will just produce an empty list.

275+This will return the mergebase (i.e. most recent common ancestor) between two `desk`s. The type it returns is a `(list tako:clay)`. The first `desk` will just be the one in the `beak` `path` prefix and the second will be specified like `/ship/desk` at the end of the scry `path`. If there is no common ancestor between the two `desk`s, this will just produce an empty `list`.

274276

275277Examples:

276278

@@ -286,7 +288,7 @@ Examples:

286288

287289## t

288290

289−A scry with a care of `%t` will return a `(list path)` of all files in the given directory, or just a `(list path)` of the single file if it's a file. This is done recursively so will provide files in sub-directories as well. The paths will be fully qualified except for the ship, desk and case. If the directory or file specified does not exist, it will return null.

291+A scry with a `care` of `%t` will return a `(list path)` of all files in the given directory, or just a `(list path)` of the single file if it's a file. This is done recursively so will provide files in subdirectories as well. The paths will be fully qualified except for the `ship`, `desk` and `case`. If the directory or file specified does not exist, it will return an empty `list`.

290292

291293Examples:

292294

@@ -314,7 +316,7 @@ Examples:

314316

315317## u

316318

317−A scry with a care of `%u` will return a `?` depending on whether the file exists. It will produce `%.n` if it's a directory or doesn't exist and will produce `%.y` if it's a file and exists.

319+A scry with a `care` of `%u` will return a `?` depending on whether the file exists. It will produce `%.n` if it's a directory or doesn't exist and will produce `%.y` if it's a file and exists.

318320

319321Examples:

320322

@@ -335,7 +337,7 @@ Examples:

335337

336338## v

337339

338−A scry with a care of `%v` will return the entire state of a desk as a `dome:clay`.

340+A scry with a care of `%v` will return the entire state of a `desk` as a `dome:clay`.

339341

340342Example:

341343

@@ -345,11 +347,11 @@ Example:

3453471

346348```

347349

348−If you try printing this it will take forever and probably OOM your ship.

350+Note: If you try printing this it will take forever and probably OOM your ship.

349351

350352## w

351353

352−A scry with a care of `%w` will return the revision number and date of a given case. The type returned is a `cass:clay` like `[ud=@ud da=@da]` where `ud` is the revision number and `da` is the date.

354+A scry with a `care` of `%w` will return the revision number and date of a given `case`. The type returned is a `cass:clay` like `[ud=@ud da=@da]` where `ud` is the revision number and `da` is the date.

353355

354356Example:

355357

@@ -360,7 +362,7 @@ Example:

360362

361363## x

362364

363−A scry with a care of `%x` will return the raw data of a file as an `@` or crash if it's a directory.

365+A scry with a `care` of `%x` will return the raw data of a file as an `@` or crash if it's a directory.

364366

365367

366368Examples:

@@ -382,11 +384,11 @@ Crash!

382384

383385## y

384386

385−A scry with a care of `%y` will return the `arch` of a file or directory.

387+A scry with a `care` of `%y` will return the `arch` of a file or directory.

386388

387−An `arch` is a `[fil=(unit lobe:clay) dir=(map @ta ~)]`. The `fil` will contain the `lobe:clay` hash if it's a file, otherwise will be null. The `dir` will contain a map of the files and directories it contains, otherwise will be null.

389+An `arch` is a `[fil=(unit lobe:clay) dir=(map @ta ~)]`. The `fil` will contain the `lobe:clay` hash if it's a file, otherwise it will be null. The `dir` will contain a map of the files and directories it contains, otherwise it will be null.

388390

389−It will return the bunt of an arch—`[fil=~ dir={}]`—if the file or directory is not found.

391+It will return the bunt of an `arch` if the file or directory is not found.

390392

391393Examples:

392394

@@ -423,7 +425,7 @@ Examples:

423425

424426## z

425427

426−A scry with a care of `%z` will return the hash of a file or the recursive hash of a directory. If the file or directory doesn't exist it will return a null value.

428+A scry with a `care` of `%z` will return the hash of a file or the recursive hash of a directory. If the file or directory doesn't exist it will return a null value.

427429

428430The type returned is a `@uxI`.

429431

arvo/clay/write.md+8−8

@@ -4,7 +4,7 @@ weight = 7

44template = "doc.html"

55+++

7−Here we'll look at creating, changing and deleting files by passing clay an `%info` tagged `task:clay`.

7+Here we'll look at creating, changing and deleting files by passing Clay an `%info` `task`.

99## Contents

1010

@@ -16,7 +16,7 @@ Here we'll look at creating, changing and deleting files by passing clay an `%in

1616

1717## Introduction

1818

19−An `%info` task looks like:

19+An `%info` `task` looks like:

2020

2121```hoon

2222[%info des=desk dit=nori] :: internal edit

@@ -48,10 +48,10 @@ This is just a list of changes so you can make more than one change in one reque

4848

4949- `%del` - Delete a file.

5050- `%ins` - Insert file. This will also replace an existing file.

51−- `%dif` - this has not yet been implemented so will crash with a `%dif-not-implemented` error.

51+- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.

5252- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.

5353

54−Clay does not give any response to an `%info` task so don't expect a sign back.

54+Clay does not give any response to an `%info` `task` so don't expect a `sign` back.

5555

5656Now we'll look at some example threads:

5757

@@ -87,9 +87,9 @@ Save it in `/ted/add-file.hoon`, `|commit %home` and run it like:

8787

8888If you have a look in the home of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.

8989

90−We've created the cage of the content like `[%txt !>(wain)]`, if you want to write something besides a text file you'd just give it the appropriate mark and vase.

90+We've created the `cage` of the content like `[%txt !>(wain)]`, if you want to write something besides a text file you'd just give it the appropriate `mark` and `vase`.

9191

92−Here's a breakdown of the `task:clay` we sent:

92+Here's a breakdown of the `task` we sent:

9393

9494![write file diagram](https://pub.m.tinnus-napbus.xyz/write-file-diagram.png)

9595

@@ -124,7 +124,7 @@ Save the above code in `ted/delete-file.hoon`, `|commit %home` and run it like:

124124

125125If you have a look in the home of your pier you'll see the `foo.txt` file you created is now gone.

126126

127−Here's a breakdown of the `task:clay` we sent:

127+Here's a breakdown of the `task` we sent:

128128

129129![delete file diagram](https://pub.m.tinnus-napbus.xyz/delete-file-diagram.png)

130130

@@ -134,7 +134,7 @@ Identical to the [Add File](#add-file) example, just replace `%ins` with `%mut`.

134134

135135## Multiple Changes

136136

137−Since `soba:clay` is just a `list` of `miso:clay`, you can add a bunch of `miso:clay` and they'll all be applied. This thread adds three files and then deletes them. Here there's only one type of `miso` in each request but you could mix different types together too.

137+Since `soba` is just a `list` of `miso`, you can add a bunch of `miso` and they'll all be applied. This thread adds three files and then deletes them. Here there's only one type of `miso` in each request but you could mix different types together too.

138138

139139`multi-change.hoon`

140140