@@ -21,7 +21,11 @@ pier directory.
2121
2222## Quickstart
2323
24−When developing it's a good idea to use a separate desk. Create a `%sandbox`
24+This quick-start guide will walk you through some common commands. Follow along
25+using your Dojo. When you get a `>=` message after entering a command, the means
26+that the command was successful.
27+
28+When developing it's a good idea to use a separate desk. Create a `%sandbox`
2529desk based on the `%home` desk:
2630
2731```
@@ -29,8 +33,8 @@ desk based on the `%home` desk:
2933```
3034
3135Running `our` produces your ship-name, meaning that you can run the following
32−command instead of typing out your entire. Useful for comets, due to their very
33−long names!
36+command instead of typing out the entire thing. Useful for comets, due to their
37+very long names.
3438
3539```
3640|merge %sandbox our %home
@@ -69,17 +73,17 @@ Let's see the contents of `/=sandbox=/web/md`:
6973~your-urbit:dojo> +cat /=sandbox=/web/md
7074```
7175
72−Now let's navigate to that folder using `=dir`, which is a like `cd` in unix.
76+Now let's navigate to that folder using `=dir`, which is a like `cd` in Unix.
7377
7478```
7579~your-urbit:dojo> =dir /=sandbox=/web/md
7680```
7781
7882Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To
79−change back to our home directory:
83+change back to our home directory, we use `=dir` without any path.
8084
8185```
82−~your-urbit:dojo> =dir
86+~your-urbit:dojo/sandbox/web/md> =dir
8387```
8488
8589Sync from your friend `~some-ship`'s `%experiment` desk to your
@@ -89,35 +93,138 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your
8993|sync %sandbox ~some-ship %experiment
9094```
9195
96+If and when your sync is successful, you will receive a message:
97+
98+```
99+activated sync from %experiment on ~some-ship to %sandbox
100+```
101+
102+The ship that you sync from will get their own message indicating that you're
103+both connected as peers:
104+
105+```
106+; ~your-urbit is your neighbor.
107+```
108+
109+---
110+
92111## Manual
93112
94113### Paths
95114
96115A path in Clay is a list of URL-safe text, restricted to the characters
97−`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`
98−where each segment is a `@ta`.
99−
100−Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
101−The first three segments of an urbit path are `/plot/desk/case`, for
102−example `/~dozbud/home/1`.
116+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
117+meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
118+In other words, paths are expressed as `/foo/bar/baz`. File extensions are
119+separated from file names with `/`, not `.`. Extensions are syntactically
120+identical to subdirectories, except that they must terminate the path.
121+
122+Paths begin with a piece of data called a `beak`. A beak is formally a
123+`(p=ship q=desk r=case)`; it has three components, and might look like
124+`/~dozbud-namsep/home/11`.
125+
126+The first `beak` component is `ship`, which is, as you might guess, the name of
127+an Urbit ship. The second component is `desk`, which is a workspace meant to
128+contain other directories; the default desk is `%home`. The third component is
129+`case`, which represents version information in various ways: date and time;
130+a version sequence, which is a value incremented by one whenever a file on the
131+given `desk` is modified; or an arbitrary plaintext label.
132+
133+You can find what your `beak` is at any given moment by
134+typing `%` in the Dojo and looking at the first three results.
135+
136+We use `beak`s because, unlike the current internet, the Urbit network uses a
137+global namespace. That means that a file named `example.hoon` in the `/gen`
138+directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
139+universal address to anyone else on the network:
140+`~lodleb-ritrul/home/186/gen/example.hoon`. That, of
141+course, doesn't mean that everyone on the network has privileges to access that
142+path.
143+
144+The structure that combines a `beak` with further path information is called a
145+`beam`.
103146
104147##### Relative paths
105148
106−Relative paths are expressed using `%`, which is roughly equivalent to
107−Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
108−There are no local relative paths. `foo/bar` must be written
149+The `%` command, which we gestured at in the above section, represents the
150+*relative path*, which is the path where you are currently working. If your
151+working directory is just your home desk, indicated by the
152+prompt `~your-planet:dojo>`, then running the command below will print your
153+working directory's `beam` information: your `beak`, and a `~` that represents
154+the empty list since no path is present.
155+
156+```
157+~your-urbit:dojo> %
158+```
159+
160+`%`s can be stacked to indicate one level further up in the hierarchy for each
161+additional `%`. Try the following command:
162+
163+```
164+~your-planet:dojo> %%%
165+```
166+
167+You'll probably notice that it only has your ship name and the empty list. The
168+two additional `%`s abandoned the `case` and the `desk` information by moving
169+up twice the hierarchy.
170+
171+There are no local relative paths. `/foo/bar` must be written as
109172`%/foo/bar`.
110173
111174##### Substitution
112175
113−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
114−`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
115−`/=/=/=/voo`, write `/==zoo` or `/===voo`.
176+You don't need to write out the explicit path every time you want to reference
177+somewhere outside of your working directory. You can substitute `=` for the
178+segments of a path.
179+
180+Recall that a full address in the the Urbit namespace is a `beam`: the
181+`/ship/desk/case/path`. If you've switched to another desk before, you're
182+already familiar with substitution syntax:
183+
184+```
185+~your-urbit:dojo> =dir /=sandbox=
186+```
187+
188+The above command substitutes uses substitution to use your current `ship` and
189+`case`; only the `desk` argument, which is located between the other two, is
190+given something new. Without substitution, you would need to write:
191+
192+```
193+~your-urbit:dojo> =dir /~your-urbit/home/85
194+```
195+
196+Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
197+paths. For example, if you are in the `/gen` directory, you can reference a file
198+in the `/app` directory like below. (`+cat` displays the contents of a file).
199+
200+```
201+~your-urbit:dojo/home/gen> +cat /===/app/curl/hoon
202+```
203+
204+Note what was substituted out, and note that we don't need to separate `=` with
205+`/`.
206+
207+If we changed our working directory to something called `/gen/gmail`, we could
208+access a file called
209+
210+```
211+~fasdul-balsev-lodleb-ritrul:dojo/home/gen/gmail> +cat /===/app/=/split/hoon
212+```
213+
214+Because both paths share a directory named `/gmail` at the same position in the
215+address hierarchy -- which, if you recall, is just a `list` -- the above command
216+works!
217+
218+We can do the same thing between desks. If `%sandbox` has been merged with
219+`%home`, the following command will produce the same results as the above
220+command.
221+
222+```
223+~your-urbit:dojo/home/gen/gmail> +cat /=sandbox=/app/=/split/hoon
224+```
116225
117226Most commonly this is used to avoid having to know the current revision
118−number in the `dojo`. Instead of writing
119−`/~your-urbit/home/4/path/to/file` you can just write
120−`/=home=/path/to/file`.
227+number in the `dojo`: `~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example.hoon`
121228
122229##### Changing directories
123230
@@ -135,19 +242,29 @@ This command will turn your prompt into something like this:
135242~your-urbit:dojo/gen/ask>
136243```
137244
138−Using `=dir` without anything else uses the null path, which
139−returns you to your home desk.
245+Using `=dir` without anything else uses the null path, which returns you to
246+your home desk.
140247
141248```
142249~your-urbit:dojo> =dir
143250```
144251
252+To go up levels in the path hierarchy, recall the relative path expression
253+`%`. Stacking them represents another level higher in the hierarchy than
254+the current working directory for each `%` beyond the initial. The command below
255+brings you one level up:
256+
257+```
258+~your-urbit:dojo/gen> =dir %%
259+```
145260
146261### Revision-control
147262
148−Syntax: `|mount /clay/path [unix-name]`
263+##### Mount
264+
265+Syntax: `|mount /clay/path [Unix-name]`
149266
150−Mount the `clay-path` at the unix mount point `unix-name`.
267+Mount the `clay-path` at the Unix mount point `Unix-name`.
151268
152269*Examples:*
153270
@@ -163,8 +280,10 @@ Mounts `%/web` to `/web` inside your pier directory.
163280
164281Mounts `%/gen` to `/generators` inside your pier directory.
165282
283+##### Unmount
284+
166285```
167−|unmount [clay-path || unix-name]
286+|unmount [clay-path || Unix-name]
168287```
169288
170289Unmount the path or name from Unix.
@@ -263,7 +382,7 @@ version, allowing merges to be rerun.
263382the reverse of `%this`. This is different from `%init` because the new
264383commit has both sides in its ancestry.
265384
266−`%fine` - "fast-forward" merge. This succeeds iff one head is in the
385+`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
267386ancestry of the other.
268387
269388`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
@@ -299,31 +418,44 @@ annotate any conflicts, if we know how.
299418
300419### Manipulation
301420
302−#### `|rm path`
421+##### +cat
303422
304−Remove the data at `path`. `path` must be a path to actual node, not a
305−'directory'
423+Syntax: `+cat path [path ...]`
306424
307−#### `|cp to from`
425+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
426+contents. If that `path` is a file, the contents of the file is printed. If the
427+`path` terminates in a directory, the list of names at that path is produced.
308428
309−Copy the file at `from` into the path `to`.
429+##### +ls
310430
311−#### `|mv to from`
431+Syntax: `+ls path`
312432
313−Move the file at `from` into the path `to`.
433+Similar to Unix `ls`. `+ls` takes a single `path`.
314434
315−In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
316−doesn't happen unless the `|cp` succeeds.
435+Produces a list of names at the `path`.
317436
318−### Generators
437+```
438+~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
439+```
319440
320−#### `+cat path [path ...]`
441+##### |rm
321442
322−Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
323−their contents.
443+Syntax: `|rm path`
324444
325−### `+ls path`
445+Remove the data at `path`. `path` must be a path to actual node, not a
446+'directory'
326447
327−Similar to Unix `ls`. `+ls` takes a single `path`.
448+##### |cp
328449
329−Produces a list of names at the `path`.
450+Syntax: `|cp to from`
451+
452+Copy the file at `from` into the path `to`.
453+
454+##### |mv
455+
456+Syntax: `|mv to from`
457+
458+Move the file at `from` into the path `to`.
459+
460+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
461+doesn't happen unless the `|cp` succeeds.