git.iko.soy/urbit.org
on master help sign in
migrate :talk to dozbud
d9673e6Tobias Merkle
docs/about/glossary.md+1−1
compare with master
unifiedsplit
@@ -22,7 +22,7 @@ their address:
22 Size Name Parent Object Example
22 Size Name Parent Object Example
23 ----- ------ ------ ------ -------
23 ----- ------ ------ ------ -------
24 2^8 galaxy ~ supernode ~zod
24 2^8 galaxy ~ supernode ~zod
25− 2^16 star galaxy supernode ~doznec
25+ 2^16 star galaxy supernode ~dozbud
26 2^32 planet star user ~tasfyn-partyv
26 2^32 planet star user ~tasfyn-partyv
27 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
27 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
28 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
28 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
docs/hoon/examples.md+1−1
@@ -17,7 +17,7 @@ side of simple manual construction over high-octane FP.)
17## `sieve`: code in basic style
17## `sieve`: code in basic style
18
18
19A function that produces the list of primes less than or equal to
19A function that produces the list of primes less than or equal to
20−than its argument, an atom:
20+its argument, an atom:
21```
21```
22:gate thru/atom :: 1
22:gate thru/atom :: 1
23:cast (list atom) :: 2
23:cast (list atom) :: 2
docs/using/filesystem.md+81−69
@@ -1,24 +1,28 @@
1---
1---
2−navhome: /docs
2+navhome: '/docs'
3−next: true
3+next: True
4sort: 6
4sort: 6
5title: Filesystem
5title: Filesystem
6---
6---
7
7
8# Filesystem (`%clay`)
8# Filesystem (`%clay`)
9
9
10−<div class="row"> <div class="col-md-8">
10+<div class="row">
11
11
12−Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
12+<div class="col-md-8">
13−a typed, global, referentially transparent namespace. An easy way to
14−think about it is like typed `git` with continuous sync.
15
13
16−The most common way to use `%clay` is to mount a `%clay` node in a
14+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a
17−Unix directory. The Urbit process will watch this directory and
15+typed, global, referentially transparent namespace. An easy way to think
18−automatically record edits as changes, Dropbox style. The mounted
16+about it is like typed `git` with continuous sync.
19−directory is always at the root of your pier directory.
20
17
18+The most common way to use `%clay` is to mount a `%clay` node in a Unix
19+directory. The Urbit process will watch this directory and automatically
20+record edits as changes, Dropbox style. The mounted directory is always
21+at the root of your pier directory.
22+
21−</div> </div>
23+</div>
24+
25+</div>
22
26
23## Quickstart
27## Quickstart
24
28
@@ -28,14 +32,13 @@ Create a `%sandbox` desk based on the `%home` desk:
28
32
29 |merge %sandbox ~your-urbit %home
33 |merge %sandbox ~your-urbit %home
30
34
31−Most of the time we want to use `%clay` from Unix.
35+Most of the time we want to use `%clay` from Unix.
32
36
33Mount the entire contents of your `sandbox` desk to Unix:
37Mount the entire contents of your `sandbox` desk to Unix:
34
38
35 ~your-urbit:dojo> |mount /=sandbox=
39 ~your-urbit:dojo> |mount /=sandbox=
36
40
37−To explore the filesystem from inside Urbit `+ls` and `+cat` are
41+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
38−useful:
39
42
40 ~your-urbit:dojo> +ls /=sandbox=/web
43 ~your-urbit:dojo> +ls /=sandbox=/web
41
44
@@ -50,37 +53,41 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your
50
53
51## Manual
54## Manual
52
55
53−<h3 class="first child">Paths</h3>
56+<h3 class="first child">
57+Paths
58+</h3>
54
59
55−A path in `%clay` is a list of URL-safe text, restricted to `[a
60+A path in `%clay` is a list of URL-safe text, restricted to
56−z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
61+`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
57where each segment is a `@ta`.
62where each segment is a `@ta`.
58
63
59Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
64Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
60The first three segments of an urbit path are `/plot/desk/case`, for
65The first three segments of an urbit path are `/plot/desk/case`, for
61−example `/~doznec/home/1`.
66+example `/~dozbud/home/1`.
62
67
63#### Relative paths
68#### Relative paths
64
69
65Relative paths are expressed using `%` which is roughly equivalent to
70Relative paths are expressed using `%` which is roughly equivalent to
66−Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
71+Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
67−be. There are no local relative paths. `foo/bar` must be written
72+There are no local relative paths. `foo/bar` must be written
68`%/foo/bar`.
73`%/foo/bar`.
69
74
70#### Substitution
75#### Substitution
71
76
72If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
77If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
73−`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
78+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
74−or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
79+`/=/=/=/voo`, write `/==zoo` or `/===voo`.
75
80
76−Most commonly this is used to avoid having to know the current
81+Most commonly this is used to avoid having to know the current revision
77−revision number in the `dojo`. Instead of writing
82+number in the `dojo`. Instead of writing
78`/~your-urbit/home/4/path/to/file` you can just write
83`/~your-urbit/home/4/path/to/file` you can just write
79`/=home=/path/to/file`.
84`/=home=/path/to/file`.
80
85
81### Revision-control
86### Revision-control
82
87
88+<h3 class="first child">
83−<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
89+<code>|mount clay-path [unix-name]</code>
90+</h3>
84
91
85Mount the `clay-path` at the unix mount point `unix-name`.
92Mount the `clay-path` at the unix mount point `unix-name`.
86
93
@@ -112,7 +119,8 @@ Unmounts the Unix path `/generators`.
112
119
113Merges a `beak` into a `desk` using an optional merge `strategy`.
120Merges a `beak` into a `desk` using an optional merge `strategy`.
114
121
115−A `beak` is a ship-desk-case triple, encoded as a path(`/~doznec/home/2`)
122+A `beak` is a ship-desk-case triple, encoded as a
123+path(`/~dozbud/home/2`)
116
124
117**Examples:**
125**Examples:**
118
126
@@ -127,24 +135,24 @@ Merge the `%examples` desk from `~waxbex-ribmex`
127### `|sync desk plot [plot-desk]`
135### `|sync desk plot [plot-desk]`
128
136
129Subscribe to continuous updates from remote `plot` on local `desk`.
137Subscribe to continuous updates from remote `plot` on local `desk`.
130−`plot-desk` can specify the remote `desk` name. When omitted it is
138+`plot-desk` can specify the remote `desk` name. When omitted it is
131−defaulted to being the same as `desk`. Non-comet urbits have `|sync
139+defaulted to being the same as `desk`. Non-comet urbits have
132−%home ~parent %kids` automatically set up (where `~parent` is the
140+`|sync %home ~parent %kids` automatically set up (where `~parent` is the
133−planet that issued a moon, the star that issued a planet, or the
141+planet that issued a moon, the star that issued a planet, or the galaxy
134−galaxy that issued a star).
142+that issued a star).
135
143
136**Examples:**
144**Examples:**
137
145
138− |sync %home-local ~doznec %home |sync %home ~doznec
146+ |sync %home-local ~dozbud %home |sync %home ~doznec
139
147
140### `|unsync desk plot [plot-desk]`
148### `|unsync desk plot [plot-desk]`
141
149
142Unsubscribe from updates from remote `plot` on local `desk` with
150Unsubscribe from updates from remote `plot` on local `desk` with
143−optional `plot-desk`. Arguments must match original `|sync` command.
151+optional `plot-desk`. Arguments must match original `|sync` command.
144
152
145Example:
153Example:
146
154
147− |unsync %home-local ~doznec %home
155+ |unsync %home-local ~dozbud %home
148
156
149### `|label desk name`
157### `|label desk name`
150
158
@@ -156,57 +164,59 @@ Example:
156
164
157### Merge strategies
165### Merge strategies
158
166
159−`%init` - Used if it's the first commit to a desk. Also can be
167+`%init` - Used if it's the first commit to a desk. Also can be used to
160−used to "reinitialize" a desk -- revision numbers keep going up,
168+"reinitialize" a desk -- revision numbers keep going up, but the new
161−but the new revision isn't necessarily a descendent of the
169+revision isn't necessarily a descendent of the previously-numbered
162−previously-numbered version, allowing merges to be rerun.
170+version, allowing merges to be rerun.
163
171
164`%this` - Keep what's in Bob's desk, but join the ancestry.
172`%this` - Keep what's in Bob's desk, but join the ancestry.
165
173
166`%that` - take what's in Alice's desk, but join the ancestry. This is
174`%that` - take what's in Alice's desk, but join the ancestry. This is
167−the reverse of `%this`. This is different from `%init` because
175+the reverse of `%this`. This is different from `%init` because the new
168−the new commit has both sides in its ancestry.
176+commit has both sides in its ancestry.
169
177
170`%fine` - "fast-forward" merge. This succeeds iff one head is in the
178`%fine` - "fast-forward" merge. This succeeds iff one head is in the
171ancestry of the other.
179ancestry of the other.
172
180
173−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
181+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
174−to use as our merge base.
182+use as our merge base.
175
183
176A `%meet` merge only succeeds if the changes from the merge base to
184A `%meet` merge only succeeds if the changes from the merge base to
177−Alice's head (hereafter, "Alice's changes") are in different files
185+Alice's head (hereafter, "Alice's changes") are in different files than
178−than Bob's changes. In this case, the parents are both Alice's and
186+Bob's changes. In this case, the parents are both Alice's and Bob's
179−Bob's heads, and the data is the merge base plus Alice's changed files
187+heads, and the data is the merge base plus Alice's changed files plus
180−plus Bob's changed files.
188+Bob's changed files.
181
189
182A `%mate` merge attempts to merge changes to the same file when both
190A `%mate` merge attempts to merge changes to the same file when both
183−Alice and Bob change it. If the merge is clean, we use it; otherwise,
191+Alice and Bob change it. If the merge is clean, we use it; otherwise, we
184−we fail. A merge between different types of changes -- for example,
192+fail. A merge between different types of changes -- for example,
185deleting a file vs changing it -- is always a conflict. If we succeed,
193deleting a file vs changing it -- is always a conflict. If we succeed,
186−the parents are both Alice's and Bob's heads, and the data is the
194+the parents are both Alice's and Bob's heads, and the data is the merge
187−merge base plus Alice's changed files plus Bob's changed files plus
195+base plus Alice's changed files plus Bob's changed files plus the merged
188−the merged files.
196+files.
189
197
190A `%meld` merge will succeed even if there are conflicts. If there are
198A `%meld` merge will succeed even if there are conflicts. If there are
191−conflicts in a file, then we use the merge base's version of that
199+conflicts in a file, then we use the merge base's version of that file,
192−file, and we produce a set of files with conflicts. The parents are
200+and we produce a set of files with conflicts. The parents are both
193−both Alice's and Bob's heads, and the data is the merge base plus
201+Alice's and Bob's heads, and the data is the merge base plus Alice's
194−Alice's changed files plus Bob's changed files plus the successfully
202+changed files plus Bob's changed files plus the successfully merged
195−merged files plus the merge base's version of the conflicting files.
203+files plus the merge base's version of the conflicting files.
196−
204+
197−`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
205+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
198−doesn't we use an `%init` merge. Otherwise, we progressively try
206+doesn't we use an `%init` merge. Otherwise, we progressively try
199−`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
207+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
200−merge Bob's desk into a scratch desk. Then, we merge Alice's desk
208+merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
201−into the scratch desk with the `%meld` option to force the merge.
209+the scratch desk with the `%meld` option to force the merge. Finally, we
202−Finally, we annotate any conflicts, if we know how.
210+annotate any conflicts, if we know how.
203
211
204### Manipulation
212### Manipulation
205
213
206−<h3 class="first child"><code>|rm path</code></h3>
214+<h3 class="first child">
215+<code>|rm path</code>
216+</h3>
207
217
208−Remove the data at `path`. `path` must be a path to actual node, not
218+Remove the data at `path`. `path` must be a path to actual node, not a
209−a 'directory'
219+'directory'
210
220
211### `|cp to from`
221### `|cp to from`
212
222
@@ -216,14 +226,16 @@ Copy the file at `from` into the path `to`.
216
226
217Move the file at `from` into the path `to`.
227Move the file at `from` into the path `to`.
218
228
219−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
229+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
220doesn't happen unless the `|cp` succeeds.
230doesn't happen unless the `|cp` succeeds.
221
231
222### Generators
232### Generators
223
233
234+<h3 class="first child">
224−<h3 class="first child"><code>+cat path [path ...]</code></h3>
235+<code>+cat path [path ...]</code>
236+</h3>
225
237
226−Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
238+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
227their contents.
239their contents.
228
240
229### `+ls path`
241### `+ls path`
docs/using/messaging.md+83−47
@@ -1,35 +1,49 @@
1---
1---
2−navhome: /docs
2+navhome: '/docs'
3−next: true
3+next: True
4sort: 4
4sort: 4
5−title: Messaging (:talk)
5+title: 'Messaging (:talk)'
6---
6---
7
7
8# Messaging (`:talk`)
8# Messaging (`:talk`)
9
9
10<div class="row">
10<div class="row">
11+
11<div class="col-md-8">
12<div class="col-md-8">
12
13
13−`:talk` is the Urbit messaging and notifications protocol. Today we use `:talk` just to chat and coordinate, but it's really a general purpose piece of infrastructure.
14+`:talk` is the Urbit messaging and notifications protocol. Today we use
15+`:talk` just to chat and coordinate, but it's really a general purpose
16+piece of infrastructure.
14
17
15−For the time being come join us in `/urbit-meta` by using the <a href="#-quickstart">quickstart</a> below.
18+For the time being come join us in `/urbit-meta` by using the
19+<a href="#-quickstart">quickstart</a> below.
16
20
17−Today `:talk` is sort of like a distributed, encrypted Slack that can be used from the CLI and the browser. There’s no central `:talk` server. Any Urbit can host one.
21+Today `:talk` is sort of like a distributed, encrypted Slack that can be
22+used from the CLI and the browser. There’s no central `:talk` server.
23+Any Urbit can host one.
18
24
19−`:talk` is a general purpose tool for both aggregating and publishing streams of messages. Applications can use `:talk` as their transport protcol, API connectors can push disparate data sources into `:talk`, and so on. There are lots of things a distributed message protocol can be used for that we haven't even thought of.
25+`:talk` is a general purpose tool for both aggregating and publishing
26+streams of messages. Applications can use `:talk` as their transport
27+protcol, API connectors can push disparate data sources into `:talk`,
28+and so on. There are lots of things a distributed message protocol can
29+be used for that we haven't even thought of.
20
30
21</div>
31</div>
32+
22</div>
33</div>
23
34
24## Quickstart
35## Quickstart
25
36
26−For the most part we use `:talk` as a single-instance of Slack: one main channel (`/urbit-meta`) and dms. Everyone is more than welcome in `/urbit-meta`. It's the place to get help, ask questions and chat about Urbit in general.
37+For the most part we use `:talk` as a single-instance of Slack: one main
38+channel (`/urbit-meta`) and dms. Everyone is more than welcome in
39+`/urbit-meta`. It's the place to get help, ask questions and chat about
40+Urbit in general.
27
41
28Let's join `/urbit-meta`:
42Let's join `/urbit-meta`:
29
43
30Use `ctrl-x` to switch from `:dojo` to `:talk`, then:
44Use `ctrl-x` to switch from `:dojo` to `:talk`, then:
31
45
32− ~your-urbit:talk> ;join ~doznec/urbit-meta
46+ ~your-urbit:talk> ;join ~dozbud/urbit-meta
33
47
34You'll see:
48You'll see:
35
49
@@ -37,14 +51,14 @@ You'll see:
37 ---------:talk| rules of /urbit-meta:
51 ---------:talk| rules of /urbit-meta:
38 ---------:talk| don't be rude
52 ---------:talk| don't be rude
39 ---------:talk| urbit-meta is politically correct and safe for work
53 ---------:talk| urbit-meta is politically correct and safe for work
40− ~doznec= ~your-urbit admitted to %urbit-meta
54+ ~dozbud= ~your-urbit admitted to %urbit-meta
41 ~your-urbit:talk>
55 ~your-urbit:talk>
42
56
43Post a line to `/urbit-meta`:
57Post a line to `/urbit-meta`:
44
58
45 ~your-urbit:talk> hello, world
59 ~your-urbit:talk> hello, world
46
60
47−You'll see, echoed back at you through `~doznec`:
61+You'll see, echoed back at you through `~dozbud`:
48
62
49 ~your-urbit> hello, world
63 ~your-urbit> hello, world
50
64
@@ -60,15 +74,18 @@ Now you and `~talsur-todres` can exchange messages directly.
60
74
61To set your audience back to `/urbit-meta`:
75To set your audience back to `/urbit-meta`:
62
76
63− ~your-urbit:talk> ;~doznec/urbit-meta
77+ ~your-urbit:talk> ;~dozbud/urbit-meta
64
78
65Use `;leave` to unsubscribe from a channel:
79Use `;leave` to unsubscribe from a channel:
66
80
67− ~your-urbit:talk> ;leave ~doznec/urbit-meta
81+ ~your-urbit:talk> ;leave ~dozbud/urbit-meta
68
82
69−There are two ways of using `:talk`: from the CLI or through a web ui available at `http://your-urbit.urbit.org/talk` (or `http://localhost:8080/talk`).
83+There are two ways of using `:talk`: from the CLI or through a web ui
84+available at `http://your-urbit.urbit.org/talk` (or
85+`http://localhost:8080/talk`).
70
86
71−The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
87+The web ui ships as compiled JavaScript on your Urbit, but has its own
88+source repo [here](https://github.com/urbit/talk).
72
89
73Last, let's create a channel we can invite some friends to:
90Last, let's create a channel we can invite some friends to:
74
91
@@ -78,11 +95,18 @@ Now you can tell your friends to `;join ~your-urbit/my-channel`.
78
95
79## Manual
96## Manual
80
97
98+`:talk`'s design is similar in spirit to
81−`:talk`'s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol), the underlying protocol for Usenet.
99+[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
100+the underlying protocol for Usenet.
82
101
83−Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.
102+Our design is pretty simple: `:talk` messages are called ‘posts’. Posts
103+go to ‘stations’. Any urbit can host or subscribe to any number of
104+stations.
84
105
106+There are four kinds of station: a write-only `%mailbox` for direct
85−There are four kinds of station: a write-only `%mailbox` for direct messages, an invite-only `%party` for private conversation, a read-only `%journal` for curated content, and a public-access `%channel` for general use.
107+messages, an invite-only `%party` for private conversation, a read-only
108+`%journal` for curated content, and a public-access `%channel` for
109+general use.
86
110
87### Posts
111### Posts
88
112
@@ -90,12 +114,13 @@ For the time being a post is either a line, a URL or a command.
90
114
91#### Lines
115#### Lines
92
116
93−A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the line starts with '@', it's an action (IRC `/me`).
117+A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the
118+line starts with '@', it's an action (IRC `/me`).
94
119
95−The `:talk` interface will let you keep typing past 64 bytes, but
120+The `:talk` interface will let you keep typing past 64 bytes, but insert
96−insert a Unicode bullet-point character in an appropriate space
121+a Unicode bullet-point character in an appropriate space in your post,
97−in your post, to show you the prospective linebreak. Your essay
122+to show you the prospective linebreak. Your essay will be posted in
98−will be posted in multiple lines.
123+multiple lines.
99
124
100 ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
125 ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
101
126
@@ -112,13 +137,14 @@ A URL is any valid URL.
112
137
113### Commands
138### Commands
114
139
115−A command is a hoon expression, prefaced by '#'.
140+A command is a hoon expression, prefaced by '\#'.
116
141
117 ~your-urbit:talk> #(add 2 2)
142 ~your-urbit:talk> #(add 2 2)
118
143
119### Activating Lines
144### Activating Lines
120
145
121−A line number identifying the *subsequent* line is displayed every 5 lines.
146+A line number identifying the *subsequent* line is displayed every 5
147+lines.
122
148
123 ---------[0]
149 ---------[0]
124 ~your-urbit; this is my message
150 ~your-urbit; this is my message
@@ -144,21 +170,23 @@ and contents:
144Activating a URL will print the full URL (it could have been truncated),
170Activating a URL will print the full URL (it could have been truncated),
145and activating a command will evaluate it.
171and activating a command will evaluate it.
146
172
147−You can activate the most recent line with `;`, the second-most recent with
173+You can activate the most recent line with `;`, the second-most recent
148−`;;`, and so on.
174+with `;;`, and so on.
149
175
150### Creating and managing stations
176### Creating and managing stations
151
177
152−`;create journal %serious-journal 'description'` - Creates a `%journal`, a privately writable publicly readable station.
178+`;create journal %serious-journal 'description'` - Creates a `%journal`,
179+a privately writable publicly readable station.
153
180
154−`;create channel %serious-channel 'description'` - Creates a `%channel`, a publicly readable publicly writeable station.
181+`;create channel %serious-channel 'description'` - Creates a `%channel`,
182+a publicly readable publicly writeable station.
155
183
156### Presence
184### Presence
157
185
158−You'll see presence notifications when people enter or leave
186+You'll see presence notifications when people enter or leave stations
159−stations you're subscribed to.
187+you're subscribed to.
160
188
161−`;who` - list everyone in all your stations
189+`;who` - list everyone in all your stations
162
190
163`;who station` - list everyone in that station
191`;who station` - list everyone in that station
164
192
@@ -168,13 +196,16 @@ Glyphs are assigned by station hash out of the following list
168
196
169 > = + - } ) , . " ' ^ $ % & @
197 > = + - } ) , . " ' ^ $ % & @
170
198
171−Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists, and `\/!?({<`) can be manually assigned.
199+Alphanumeric characters and `|#;:*~_` are reserved; all others (the
200+above lists, and `\/!?({<`) can be manually assigned.
172
201
173`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
202`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
174
203
175### Prefixes
204### Prefixes
176
205
177−Received posts are prefixed with a glyph to let you know what the audience is. You can activate an individual post to see the full audience.
206+Received posts are prefixed with a glyph to let you know what the
207+audience is. You can activate an individual post to see the full
208+audience.
178
209
179`|` - Informational messages
210`|` - Informational messages
180
211
@@ -188,7 +219,8 @@ Received posts are prefixed with a glyph to let you know what the audience is.
188
219
189#### Prompt
220#### Prompt
190
221
191−The audience you're sending to is always shown in your prompt. If there's a glyph for it, it's shown as the glyph.
222+The audience you're sending to is always shown in your prompt. If
223+there's a glyph for it, it's shown as the glyph.
192
224
193Here we're talking to the station bound to `=`:
225Here we're talking to the station bound to `=`:
194
226
@@ -208,20 +240,21 @@ Here we're talking directly to `~dannum-mitryl`:
208
240
209`;%station` - Set audience to a station on your own ship
241`;%station` - Set audience to a station on your own ship
210
242
211−`;~dannum-mitryl this is a private message` - Set the audience and send a post in the same line. This works for all of the above.
243+`;~dannum-mitryl this is a private message` - Set the audience and send
244+a post in the same line. This works for all of the above.
212
245
213−Your audience is configured 'implicitly' with regard to the following rules (in order):
246+Your audience is configured 'implicitly' with regard to the following
247+rules (in order):
214
248
215−- if you manually locked the audience, that audience.
249+- if you manually locked the audience, that audience.
216−- if typing a post, the audience when you started typing.
250+- if typing a post, the audience when you started typing.
217−- if you activated a post, the post you activated.
251+- if you activated a post, the post you activated.
218−- audience of the last post received.
252+- audience of the last post received.
219−- audience of the last post sent.
253+- audience of the last post sent.
220
254
221−Clear any 'implicit' audience setting by moving your cursor to
255+Clear any 'implicit' audience setting by moving your cursor to the start
222−the start of the line and pressing backspace (whether the line is
256+of the line and pressing backspace (whether the line is empty or not).
223−empty or not). Posting a line clears the typing and activation
257+Posting a line clears the typing and activation configurations.
224−configurations.
225
258
226### Nicknames
259### Nicknames
227
260
@@ -239,4 +272,7 @@ configurations.
239
272
240`;unset noob` show urbit names instead of nicknames
273`;unset noob` show urbit names instead of nicknames
241
274
242−All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on entries in a phonebook. Sometimes in a post you want to mention someone you know by a nickname. Just type `~plato`, and `:talk` will replace it with `~your-urbit`.
275+All nicknames must be 14 characters or less, lowercase. Nicknames are
276+strictly local - like the names on entries in a phonebook. Sometimes in
277+a post you want to mention someone you know by a nickname. Just type
278+`~plato`, and `:talk` will replace it with `~your-urbit`.
docs/using/setup.md+41−33
@@ -1,50 +1,55 @@
1---
1---
2−navhome: /docs
2+navhome: '/docs'
3−next: true
3+next: True
4sort: 2
4sort: 2
5title: Setup
5title: Setup
6---
6---
7
7
8# Getting started
8# Getting started
9
9
10+On disk your urbit is an append-only log and a checkpoint. Or, in
10−On disk your urbit is an append-only log and a checkpoint. Or, in simpler terms, a directory where we keep your urbit’s state. We call this a ‘pier’.
11+simpler terms, a directory where we keep your urbit’s state. We call
12+this a ‘pier’.
11
13
12## Initialize
14## Initialize
13
15
14−To create an urbit, we need an identity. This identity
16+To create an urbit, we need an identity. This identity is both a network
15−is both a network address and a memorable name.
17+address and a memorable name.
16
18
17−You are probably creating one of two kinds of urbit: a 32-bit
19+You are probably creating one of two kinds of urbit: a 32-bit "planet"
18−"planet" or a 128-bit "comet." For a quick terminology guide
20+or a 128-bit "comet." For a quick terminology guide and high-level
19−and high-level refresher, refer to this [handy reference
21+refresher, refer to this [handy reference sheet](/docs/about/glossary).
20−sheet](/docs/about/glossary).
21
22
22If you have an Urbit invitation, you'll have a planet like
23If you have an Urbit invitation, you'll have a planet like
23−`~fintud-macrep` and `~fortyv-tombyt-tabsen-sonres`. To create
24+`~fintud-macrep` and `~fortyv-tombyt-tabsen-sonres`. To create your
24−your pier:
25+pier:
25
26
26 $ bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
27 $ bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
27
28
28−This will create a directory `fintud-macrep/` and begin building
29+This will create a directory `fintud-macrep/` and begin building your
29−your urbit. This may take a few minutes.
30+urbit. This may take a few minutes.
30
31
31−If you do not have a ticket, you can still make a 'comet', a wild
32+If you do not have a ticket, you can still make a 'comet', a wild urbit
32−urbit drifting through cyberspace. Pick your own directory name,
33+drifting through cyberspace. Pick your own directory name, it doesn't
33−it doesn't matter:
34+matter:
34
35
35 $ bin/urbit -c mycomet
36 $ bin/urbit -c mycomet
36
37
37−This will create the directory `mycomet/` and generate a 128-bit identity for your urbit.
38+This will create the directory `mycomet/` and generate a 128-bit
39+identity for your urbit.
38
40
39## Orientation
41## Orientation
40
42
41−When your urbit is finished booting you should see a `dojo>` prompt. Welcome!
43+When your urbit is finished booting you should see a `dojo>` prompt.
44+Welcome!
42
45
43−By default your urbit is quite bare-bones. Let's stroll through what's already running:
46+By default your urbit is quite bare-bones. Let's stroll through what's
47+already running:
44
48
45### Shell — `:dojo`
49### Shell — `:dojo`
46
50
47−The command prompt in front of you is a simple shell and Hoon REPL. Let's make sure it works:
51+The command prompt in front of you is a simple shell and Hoon REPL.
52+Let's make sure it works:
48
53
49 ~fitund-macrep:dojo> (add 2 2)
54 ~fitund-macrep:dojo> (add 2 2)
50
55
@@ -57,29 +62,30 @@ Good.
57
62
58### Messaging — `:talk`
63### Messaging — `:talk`
59
64
60−Use `^X` (ctrl-x) to change your prompt. Let's join the main Urbit chat channel:
65+Use `^X` (ctrl-x) to change your prompt. Let's join the main Urbit chat
66+channel:
61
67
62− ~fitund-macrep:talk() ;join ~doznec/urbit-meta
68+ ~fitund-macrep:talk() ;join ~dozbud/urbit-meta
63
69
64`:talk` is stateful, so your urbit will download a backlog.
70`:talk` is stateful, so your urbit will download a backlog.
65−`/urbit-meta` is the place to ask questions, get help and talk
71+`/urbit-meta` is the place to ask questions, get help and talk about
66−about anything Urbit-related.
72+anything Urbit-related.
67
73
68### Web — `:tree`
74### Web — `:tree`
69
75
70−Urbit is also accessible through the web. Try opening:
76+Urbit is also accessible through the web. Try opening:
71
77
72 http://localhost:8080/
78 http://localhost:8080/
73
79
74−in your favorite browser. You'll be prompted to use `+code`.
80+in your favorite browser. You'll be prompted to use `+code`. This page
75−This page was generated by `:tree`, the basic Urbit web
81+was generated by `:tree`, the basic Urbit web interface. You can also
76−interface. You can also access your urbit through
77−`http://fintud-macrep.urbit.org` (where `fintud-macrep` is your
82+access your urbit through `http://fintud-macrep.urbit.org` (where
78−planet name).
83+`fintud-macrep` is your planet name).
79
84
80### Filesystem — `%clay`
85### Filesystem — `%clay`
81
86
82−`%clay`, the Urbit filesystem, isn't mounted to unix by default. Switch to the `:dojo` prompt and run:
87+`%clay`, the Urbit filesystem, isn't mounted to unix by default. Switch
88+to the `:dojo` prompt and run:
83
89
84 ~fitund-macrep:dojo> |mount %
90 ~fitund-macrep:dojo> |mount %
85
91
@@ -90,10 +96,12 @@ This should produce:
90
96
91which indicates the command was processed.
97which indicates the command was processed.
92
98
99+`|mount %` will cause a `home/` directory to appear inside your pier
93−`|mount %` will cause a `home/` directory to appear inside your pier folder. Changes to these files are automatically synced into your urbit.
100+folder. Changes to these files are automatically synced into your urbit.
94
101
95## Learn more
102## Learn more
96
103
97−If you're eager to get started programming you're ready to head over to <a href="../../hoon/demo">the Hoon demo</a>.
104+If you're eager to get started programming you're ready to head over to
105+<a href="../../hoon/demo">the Hoon demo</a>.
98
106
99To learn more about using the system, let's keep going:
107To learn more about using the system, let's keep going:
docs/using/shell.md+62−44
@@ -1,21 +1,22 @@
1---
1---
2−navhome: /docs
2+navhome: '/docs'
3−next: true
3+next: True
4sort: 5
4sort: 5
5−title: Shell (:dojo)
5+title: 'Shell (:dojo)'
6---
6---
7
7
8# Shell (`:dojo`)
8# Shell (`:dojo`)
9
9
10<div class="row">
10<div class="row">
11+
11<div class="col-md-8">
12<div class="col-md-8">
12
13
13−The `:dojo` is the place to quickly experiment with Urbit. On
14+The `:dojo` is the place to quickly experiment with Urbit. On the
14−the surface the `:dojo` is just a Hoon REPL. On the inside, the
15+surface the `:dojo` is just a Hoon REPL. On the inside, the `:dojo` is a
15−`:dojo` is a system for operating on and transforming data in
16+system for operating on and transforming data in Urbit.
16−Urbit.
17
17
18</div>
18</div>
19+
19</div>
20</div>
20
21
21## Quickstart
22## Quickstart
@@ -51,78 +52,89 @@ Run system commands from `:hood`, like `reload`, using `|`:
51
52
52 ~your-urbit:dojo> |reload %eyre
53 ~your-urbit:dojo> |reload %eyre
53
54
54−
55### Generators
55### Generators
56
56
57−**`+cat`** - Similar to Unix `cat`. Accepts a path.
57+**`+cat`** - Similar to Unix `cat`. Accepts a path.
58
58
59 ~your-urbit:dojo> +cat %/web/md
59 ~your-urbit:dojo> +cat %/web/md
60 ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md
60 ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md
61
61
62−**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
62+**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
63
63
64 ~your-urbit:dojo> +curl "http://nyt.com"
64 ~your-urbit:dojo> +curl "http://nyt.com"
65
65
66−**`+hello`** - Just prints the argument. Accepts a `@ta`.
66+**`+hello`** - Just prints the argument. Accepts a `@ta`.
67
67
68 ~your-urbit:dojo> +hello 'mars'
68 ~your-urbit:dojo> +hello 'mars'
69
69
70−**`+ls`** - Similar to Unix `ls`. Accepts a path.
70+**`+ls`** - Similar to Unix `ls`. Accepts a path.
71
71
72 ~your-urbit:dojo> +ls %/web
72 ~your-urbit:dojo> +ls %/web
73 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
73 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
74
74
75−**`+moon`** - Generate a random moon from a planet. No arguments.
75+**`+moon`** - Generate a random moon from a planet. No arguments.
76
76
77 ~your-urbit:dojo> +moon
77 ~your-urbit:dojo> +moon
78
78
79−**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.
79+**`+solid`** - Compile the current state of the kernel and output a
80−
80+noun. Usually downloaded to a file in unix. No arguments.
81+
81 ~your-urbit:dojo> .urbit/pill +solid
82 ~your-urbit:dojo> .urbit/pill +solid
82
83
83−**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
84+**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name
85+(`@p`).
84
86
85 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
87 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
86
88
87−**`+tree`** - Generate a recursive directory listing. Takes a path.
89+**`+tree`** - Generate a recursive directory listing. Takes a path.
88
90
89 ~your-urbit:dojo> +tree %/web
91 ~your-urbit:dojo> +tree %/web
90
92
91### Hood
93### Hood
92
94
93−The hood is the system daemon. See `gen/hood` and `app/hood`.
95+The hood is the system daemon. See `gen/hood` and `app/hood`.
94
96
95−**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts an urbit name (`@p`) and a string (`cord`).
97+**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts
98+an urbit name (`@p`) and a string (`cord`).
96
99
97− ~your-urbit:dojo> |hi ~doznec "you there?"
100+ ~your-urbit:dojo> |hi ~dozbud "you there?"
98
101
99−**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.
102+**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an
103+Urbit name and an app name.
100
104
101 ~your-urbit:dojo> |link ~talsur-todres %octo
105 ~your-urbit:dojo> |link ~talsur-todres %octo
102
106
103−**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.
107+**`|mass`** - Prints the current memory usage of all the kernel modules.
108+No arguments.
104
109
105 ~your-urbit:dojo> |mass
110 ~your-urbit:dojo> |mass
106
111
107−**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.
112+**`|reload`** - Reloads a kernel module (vane) from source. Accepts any
113+number of vane names.
108
114
109 ~your-urbit:dojo> |reload %clay %eyre
115 ~your-urbit:dojo> |reload %clay %eyre
110
116
111−**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
117+**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
112
118
113 ~your-urbit:dojo> |reset
119 ~your-urbit:dojo> |reset
114
120
115−**`|start`** - Starts an app. Accepts an app name.
121+**`|start`** - Starts an app. Accepts an app name.
116
122
117 ~your-urbit:dojo> |start %curl
123 ~your-urbit:dojo> |start %curl
118
124
119## Manual
125## Manual
120
126
121−<h3 class="first child">Sources and sinks</h3>
127+<h3 class="first child">
128+Sources and sinks
129+</h3>
122
130
131+A dojo command is either a source or a sink. A source is just something
123−A dojo command is either a source or a sink. A source is just something that can be printed to your console or the result of some computation. A sink is an *effect*: a change to the filesystem, a network message, a change to your environment, or typed message to an app.
132+that can be printed to your console or the result of some computation. A
133+sink is an *effect*: a change to the filesystem, a network message, a
134+change to your environment, or typed message to an app.
124
135
125−Sources can be chained together, but we can only produce one effect per command.
136+Sources can be chained together, but we can only produce one effect per
137+command.
126
138
127### Sinks
139### Sinks
128
140
@@ -135,7 +147,7 @@ Set any envronment variable:
135
147
136 44
148 44
137
149
138−(There are a few special variables that the dojo maintains. See below.)
150+(There are a few special variables that the dojo maintains. See below.)
139
151
140#### `:` - Send to app
152#### `:` - Send to app
141
153
@@ -145,7 +157,7 @@ Send a `helm-hi` message to `hood`:
145
157
146 ~your-urbit:dojo> :hood &helm-hi 'hi'
158 ~your-urbit:dojo> :hood &helm-hi 'hi'
147
159
148−App usually expect marked data, so `&` is often used here.
160+App usually expect marked data, so `&` is often used here.
149
161
150#### `*` - Save in `%clay`
162#### `*` - Save in `%clay`
151
163
@@ -153,7 +165,8 @@ Save a new `md` file in `web`:
153
165
154 ~your-urbit:dojo> *%/web/foo/md '# hello'
166 ~your-urbit:dojo> *%/web/foo/md '# hello'
155
167
156−The last component of the path is expected to be the mark (or mime type).
168+The last component of the path is expected to be the mark (or mime
169+type).
157
170
158#### `.` - Export to Unix
171#### `.` - Export to Unix
159
172
@@ -196,16 +209,18 @@ Use `_` to run a gate (or function):
196
209
197`+http[s]://example.com` - sends a GET request
210`+http[s]://example.com` - sends a GET request
198
211
199−`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the JSON `"hi"` in the body.
212+`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
213+JSON `"hi"` in the body.
200
214
201−`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body.
215+`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
216+JSON `"hi"` in the body.
202
217
203−Note that the first of these is a source while the last two are
218+Note that the first of these is a source while the last two are sinks.
204−sinks.
205
219
206#### `+` - Generators
220#### `+` - Generators
207
221
208−Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`.
222+Generators are simple hoon scripts loaded from the filesystem. They live
223+in `gen/`.
209
224
210Create a random moon (from any planet):
225Create a random moon (from any planet):
211
226
@@ -213,9 +228,10 @@ Create a random moon (from any planet):
213 :: produces
228 :: produces
214 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
229 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
215
230
216−### Variables
231+### Variables
217
232
218−You can use `=` to set an environment variable in `:dojo`, but there are a few reserved names that have special uses.
233+You can use `=` to set an environment variable in `:dojo`, but there are
234+a few reserved names that have special uses.
219
235
220#### `dir`
236#### `dir`
221
237
@@ -228,9 +244,10 @@ Current working `%clay` desk and revision. Read / write.
228
244
229 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
245 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
230
246
231−#### `lib`
247+#### `lib`
232
248
233−Current set of libraries (`/lib`) in your environment. Can also be set with `/+`. Read / write.
249+Current set of libraries (`/lib`) in your environment. Can also be set
250+with `/+`. Read / write.
234
251
235**Examples:**
252**Examples:**
236
253
@@ -242,7 +259,8 @@ Current set of libraries (`/lib`) in your environment. Can also be set with `/+
242
259
243#### `sur`
260#### `sur`
244
261
245−Current set of structures (`/sur`) in your environment. Can also be set with `/-`. Read / write.
262+Current set of structures (`/sur`) in your environment. Can also be set
263+with `/-`. Read / write.
246
264
247**Examples:**
265**Examples:**
248
266
@@ -254,7 +272,7 @@ Current set of structures (`/sur`) in your environment. Can also be set with `/
254
272
255#### `now`
273#### `now`
256
274
257−The current (128-bit `@da`) time. Read-only.
275+The current (128-bit `@da`) time. Read-only.
258
276
259**Example:**
277**Example:**
260
278
@@ -264,7 +282,7 @@ The current (128-bit `@da`) time. Read-only.
264
282
265#### `our`
283#### `our`
266
284
267−The current urbit plot. Read-only.
285+The current urbit plot. Read-only.
268
286
269**Example:**
287**Example:**
270
288
@@ -274,7 +292,7 @@ The current urbit plot. Read-only.
274
292
275#### `eny`
293#### `eny`
276
294
277−256 bits of entropy. Read-only.
295+256 bits of entropy. Read-only.
278
296
279**Example:**
297**Example:**
280
298