git.iko.soy/urbit.org
on master help sign in
Update Using docs
commitcc551c1445989221d90d2d3600cd3e0c2ceee67c authorKeaton Dunsford <keaton@tlon.io> dateThu 7 Dec 2017, 20:45 (9 years ago) parent4251b1f
10 files changed+217−548
compare with master
unifiedsplit
docs/using.md+1 docs/using/admin.md+8−19 docs/using/filesystem.md+11−10 docs/using/install.md+15−1 docs/using/layout.md+20−19 docs/using/messaging.md+125−104 docs/using/setup.md+20−23 docs/using/shell.md+9−8 docs/using/urb.md−356 docs/using/web.md+8−8
docs/using.md+1
@@ -1,6 +1,7 @@
11---
22navhome: /docs/
33sort: 1
4+title: Using
45---
56
67# Get Started
docs/using/admin.md+8−19
@@ -1,11 +1,12 @@
11---
22navhome: /docs/
3+navuptwo: true
34next: true
4−sort: 3
5−title: Administration and Operation
5+sort: 4
6+title: Administration and operation
67---
78
8−# Administration
9+# Administration and operation
910
1011<div class="row">
1112<div class="col-md-8">
@@ -17,7 +18,7 @@ Your Urbit is a persistent Unix process that you mainly control from the console
1718
1819## Shutdown
1920
20−You can turn your Urbit off with `ctrl-d` from the `:talk` or `:dojo` prompts.
21+You can turn your Urbit off with `ctrl-d` from the Talk or Dojo prompts.
2122
2223## Restart
2324
@@ -50,13 +51,13 @@ To move a pier, simply move the contents of the directory it lives in. To keep
5051
5152Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.
5253
53−In the CLI Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the `:dojo` prompt. Since there is no dojo command or hoon expression that starts with ')', the dojo rejects it.
54+In the CLI Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no dojo command or hoon expression that starts with ')', the dojo rejects it.
5455
5556`ctrl-x` - Switches the prompt between running console apps
5657
5758`ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack trace.
5859
59−`ctrl-d` - From `:talk` or `:dojo` stops your Urbit process.
60+`ctrl-d` - From Talk or Dojo stops your Urbit process.
6061
6162`↑` / `↓` - History navigation
6263
@@ -76,7 +77,7 @@ The following emacs-style key bindings are available:
7677 ctrl-u kill to beginning of line
7778 ctrl-y yank from kill buffer
7879
79−Full coverage of the Urbit shell, the `:dojo` is covered in the [Shell walkthrough](/docs/using/shell).
80+Full coverage of the Urbit shell, the Dojo is covered in the [Shell walkthrough](/docs/using/shell).
8081
8182## Web
8283
@@ -87,18 +88,6 @@ Your Urbit serves a simple homepage from `http://localhost:8080` or `https://you
8788
8889A complete walkthrough of the Urbit web interface is [here](/docs/using/web).
8990
90−## Moons
91−
92−Urbit namespace is distributed by having parent nodes sign the keys for child nodes. If you have a planet, your parent star issued your ticket. As a planet you, in turn, can sign the keys for moons. The basic idea is: your planet runs permanently in a data center somewhere and moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
93−
94−To generate a random moon from your planet run:
95−
96− ~your-urbit:dojo> +moon
97−
98−You can use the resulting output in the same installation flow from [install](/docs/using/install).
99−
100−Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`. You can read more about those things in the [filesystem](/docs/using/filesystem) and [console](/docs/using/shell) walkthroughs.
101−
10291## Continuity breaches
10392
10493While the Urbit network is in this alpha state we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.
docs/using/filesystem.md+11−10
@@ -1,21 +1,22 @@
11---
2−navhome: '/docs'
3−next: True
4−sort: 6
5−title: Filesystem
2+navhome: /docs/
3+navuptwo: true
4+next: true
5+sort: 7
6+title: Filesystem (Clay)
67---
78
8−# Filesystem (`%clay`)
9+# Filesystem (Clay)
910
1011<div class="row">
1112
1213<div class="col-md-8">
1314
14−Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a
15+Urbit has its own revision-controlled filesystem, Clay. Clay is a
1516typed, global, referentially transparent namespace. An easy way to think
1617about it is like typed `git` with continuous sync.
1718
18−The most common way to use `%clay` is to mount a `%clay` node in a Unix
19+The most common way to use Clay is to mount a Clay node in a Unix
1920directory. The Urbit process will watch this directory and automatically
2021record edits as changes, Dropbox style. The mounted directory is always
2122at the root of your pier directory.
@@ -32,7 +33,7 @@ Create a `%sandbox` desk based on the `%home` desk:
3233
3334 |merge %sandbox ~your-urbit %home
3435
35−Most of the time we want to use `%clay` from Unix.
36+Most of the time we want to use Clay from Unix.
3637
3738Mount the entire contents of your `sandbox` desk to Unix:
3839
@@ -57,7 +58,7 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your
5758Paths
5859</h3>
5960
60−A path in `%clay` is a list of URL-safe text, restricted to
61+A path in Clay is a list of URL-safe text, restricted to
6162`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
6263where each segment is a `@ta`.
6364
@@ -228,7 +229,7 @@ Copy the file at `from` into the path `to`.
228229
229230Move the file at `from` into the path `to`.
230231
231−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
232+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
232233doesn't happen unless the `|cp` succeeds.
233234
234235### Generators
docs/using/install.md+15−1
@@ -77,12 +77,26 @@ Which can usually be installed with the following one-liners:
7777
7878### Clone and make
7979
80−Once your dependencies are installed the rest is easy:
80+Once your dependencies are installed the rest is easy.
81+
82+If you're cloning the `urbit/urbit` Git repository for the first time, run:
8183
8284 $ git clone https://github.com/urbit/urbit
8385 $ cd urbit
8486 $ make # gmake on FreeBSD
8587
88+_**Updated for the `2017.12.7` continuity breach**_
89+
90+If you already have a clone of the `urbit/urbit` Git repository, assuming
91+your `origin` upstream is the `urbit/urbit` repository on Github, run the
92+following commands to make sure you're on the correct, clean Git branch:
93+
94+ $ cd urbit
95+ $ git fetch --all
96+ $ git checkout master
97+ $ git reset --hard origin/master
98+ $ make # gmake on FreeBSD
99+
86100After running `make`, your Urbit executable is in `bin/urbit`. Install it wherever you'd like.
87101
88102 # sudo install -m 0755 bin/urbit /usr/local/bin
docs/using/layout.md+20−19
@@ -1,6 +1,8 @@
11---
22navhome: /docs/
3−sort: 9
3+navuptwo: true
4+next: true
5+sort: 3
46title: Source layout
57---
68
@@ -29,63 +31,63 @@ Looking at the top level of [the Arvo repo](http://github.com/urbit/arvo), or an
2931
3032Let's step through directory by directory.
3133
32−## `app/`
34+## `app/`
3335
34−This is where `%gall` apps live. `%gall` apps are stateful servers, sort of like unix daemons. One familiar one is `app/talk.hoon` which is the source code for `:talk` the urbit messaging transport layer. And there's also `app/dojo.hoon` — that's your shell.
36+This is where Gall apps live. Gall apps are stateful servers, sort of like unix daemons. One familiar one is `app/talk.hoon` which is the source code for Talk the urbit messaging transport layer. And there's also `app/dojo.hoon` — that's your shell.
3537
3638## `arvo/`
3739
38−This is where the `%arvo` vanes live. Vanes are sort of like kernel modules. These are worth listing one by one:
40+This is where the Arvo vanes live. Vanes are sort of like kernel modules. These are worth listing one by one:
3941
4042### `arvo/ames.hoon`
4143
42−`%ames` is our network protocol.
44+Ames is our network protocol.
4345
4446### `arvo/behn.hoon`
4547
46−`%behn` is a simple timer.
48+Behn is a simple timer.
4749
4850### `arvo/clay.hoon`
4951
50−`%clay` is our filesystem.
52+Clay is our filesystem.
5153
5254### `arvo/dill.hoon`
5355
54−`%dill` is our terminal driver.
56+Dill is our terminal driver.
5557
5658### `arvo/eyre.hoon`
5759
58−`%eyre` is our webserver.
60+Eyre is our webserver.
5961
6062### `arvo/ford.hoon`
6163
62−`%ford` is our build system.
64+Ford is our build system.
6365
6466### `arvo/gall.hoon`
6567
66−`%gall` is our application model.
68+Gall is our application model.
6769
6870### `arvo/hoon.hoon`
6971
70−`%hoon` is our programming langauge. Since Hoon compiles itself the language is actually specified in this source file.
72+Hoon is our programming langauge. Since Hoon compiles itself the language is actually specified in this source file.
7173
7274### `arvo/zuse.hoon`
7375
74−`%zuse` is the Hoon library.
76+Zuse is the Hoon library.
7577
76−That's it. That's the whole system.
78+That's it. That's the whole system.
7779
7880## `gen/`
7981
80−`gen/` holds generators. Generators are short `:dojo` scripts.
82+`gen/` holds generators. Generators are short Dojo scripts.
8183
8284## `lib/`
8385
84−`lib/` holds shared libraries for programs. `lib/sole` is a good example — that's the console library that's shared by both `:dojo` in the command line, and the `dojo` web client.
86+`lib/` holds shared libraries for programs. `lib/sole` is a good example — that's the console library that's shared by both Dojo in the command line, and the Dojo web client.
8587
8688## `mar/`
8789
88−This is where marks live. Marks are data type definitions used by `%ford`. A mark is like a mime-type, but specified in executable code.
90+This is where marks live. Marks are data type definitions used by Ford. A mark is like a mime-type, but specified in executable code.
8991
9092## `ren/`
9193
@@ -99,9 +101,8 @@ Default web requests in urbit are handled as a `.urb`, which is caught by the `u
99101
100102## `web/`
101103
102−There are the files publicly accessible to the web, as made possible by `%eyre`.
104+There are the files publicly accessible to the web, as made possible by Eyre.
103105
104106## `web.md`
105107
106108This is the homepage for your urbit. You'll see it at `http://localhost:8080/` or `http://fintud-macrep.urbit.org/`.
107−
docs/using/messaging.md+125−104
@@ -1,36 +1,37 @@
11---
2−navhome: '/docs'
3−next: True
4−sort: 4
5−title: Messaging (:talk)
2+navhome: /docs/
3+navuptwo: true
4+next: true
5+sort: 5
6+title: Messaging (Talk and Hall)
67---
78
8−# Messaging (`:talk`)
9+# Messaging (Talk and Hall)
910
1011<div class="row">
1112
1213<div class="col-md-8">
1314
14−`:talk` is the built-in frontend for the Urbit messaging and notifications
15−protocol, `:hall`. Today we use `:hall` just to chat and coordinate, but
16−it's really a general purpose piece of infrastructure.
15+Talk is the built-in frontend for the Urbit messaging and notifications
16+protocol, Hall. Today we use Hall to chat and coordinate, but it's really
17+a general purpose piece of infrastructure.
1718
1819For the time being come join us in `/urbit-meta` by using the
1920<a href="#-quickstart">quickstart</a> below.
2021
21−Today `:hall` is sort of like a distributed, encrypted Slack that can be
22−used from the CLI and the browser. There’s no central `:hall` server.
22+Today, Hall is sort of like a distributed, encrypted Slack that can be
23+used from the CLI and the browser. There’s no central Hall server.
2324Any Urbit can host one.
2425
25−`:hall` is a general purpose tool for both aggregating and publishing
26−streams of messages. Applications can use `:hall` as their transport
27−protocol, API connectors can push disparate data sources into `:hall`,
26+Hall is a general purpose tool for both aggregating and publishing
27+streams of messages. Applications can use Hall as their transport
28+protcol, API connectors can push disparate data sources into Hall,
2829and so on. There are lots of things a distributed message protocol can
2930be used for that we haven't even thought of.
3031
31−Here we'll be discussing how to operate the default CLI frontend, `:talk`,
32−to send and receive messages. For a more in-depth look at `:hall`'s
33−internals, take a look at its [documentation](#TODO).
32+Here we'll be discussing how to operate the default CLI frontend, Talk,
33+to send and receive messages. For a more in-depth look at Hall's internals,
34+take a look at its [documentation](../../hall/architecture).
3435
3536</div>
3637
@@ -38,36 +39,39 @@ internals, take a look at its [documentation](#TODO).
3839
3940## Quickstart
4041
41−For the most part we use `:talk` as a single-instance of Slack: one main
42−channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
42+For the most part we use Talk as a single-instance of Slack: one main
43+channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
4344in `/urbit-meta`. It's the place to get help, ask questions and chat about
4445Urbit in general.
4546
4647Let's join `/urbit-meta`:
4748
48−Use `ctrl-x` to switch from `:dojo` to `:talk`.
49+Use `ctrl-x` to switch from Dojo to Talk.
4950
5051To join `/urbit-meta`:
5152
52− ~your-urbit:talk[] ;join /urbit-meta
53+ ~your-urbit:talk> ;join /urbit-meta
5354
54−You'll see:
55+You'll see something like:
5556
5657 --------------| ;join /urbit-meta
57− --------------| new glyph '>'
58− ~your-urbit:talk>
58+ --------------| :: onn /urbit-meta
59+ --------------| bound '=' {[hos=~marzod nom=%urbit-meta]}
60+ --------------| new = /urbit-meta
61+ --------------| /urbit-meta: hey ~marzod hear
62+ ~your-urbit:talk-
5963
6064Post a line to `/urbit-meta`:
6165
62− ~your-urbit:talk> hello, world
66+ ~your-urbit:talk- Hello, world!
6367
6468You'll see, echoed back at you:
6569
66− ~your-urbit> hello, world
70+ ~your-urbit- Hello, world!
6771
6872To send a direct message to someone, first set your audience:
6973
70− ~your-urbit:talk> ;~talsur-todres
74+ ~your-urbit:talk- ;~talsur-todres
7175
7276You'll see your prompt change:
7377
@@ -75,35 +79,48 @@ You'll see your prompt change:
7579
7680Now you and `~talsur-todres` can exchange messages directly.
7781
82+ ~your-urbit:talk[~talsur-todres] Hey buddy!
83+
7884To set your audience back to `/urbit-meta`:
7985
80− ~your-urbit:talk> ;/urbit-meta
86+ ~your-urbit:talk[~talsur-todres] ;/urbit-meta
87+
88+You'll see your prompt change back:
89+
90+ ~your-urbit:talk-
91+
92+You can also use the ASCII "glyph" assigned to your `/urbit-meta` circle as a shortcut:
93+
94+ ~your-urbit:talk[~talsur-todres] ;-
95+ ~your-urbit:talk-
96+
97+(Your ship may have a different glyph than `-` for your circle)
8198
8299Use `;leave` to unsubscribe from a channel:
83100
84− ~your-urbit:talk> ;leave /urbit-meta
101+ ~your-urbit:talk- ;leave /urbit-meta
85102
86−There are two ways of using `:talk`: from the CLI or through a web ui
87−available at `http://your-urbit.urbit.org/talk` (or
88−`http://localhost:8080/talk`).
103+There are two ways of using Talk: from the CLI or through a web UI
104+available at `http://your-urbit.urbit.org/~~/talk` (or
105+`http://localhost:8080/~~/talk`).
89106
90−The web ui ships as compiled JavaScript on your Urbit, but has its own
107+The web UI ships as compiled JavaScript on your Urbit, but has its own
91108source repo [here](https://github.com/urbit/talk).
92109
93110Last, let's create a channel we can invite some friends to:
94111
95− ~your-urbit:talk> ;create channel %my-channel 'some description'
112+ ~your-urbit:talk> ;create channel %my-channel 'Some description.'
96113
97114Now you can tell your friends to `;join ~your-urbit/my-channel`.
98115
99116## Manual
100117
101−`:hall`'s design is similar in spirit to
102−[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
118+Hall's design is similar in spirit to
119+[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
103120the underlying protocol for Usenet.
104121
105−Our design is pretty simple: `:hall` messages go to ‘circles’. Any urbit
106−can host or subscribe to any number of circles.
122+Our design is pretty simple: Hall messages are called _posts_. Posts
123+go to _circles_. Any urbit can host or subscribe to any number of circles.
107124
108125There are four kinds of circles: a write-only `%mailbox` for direct
109126messages, an invite-only `%village` for private conversation, a read-only
@@ -113,7 +130,7 @@ general use.
113130### Posts
114131
115132A post can be a variety of different data structures. Let's look at the
116−ones you can use from within `:talk`: lines, URLs, expressions and
133+ones you can use from within Talk: lines, URLs, Hoon and
117134replies.
118135
119136#### Lines
@@ -121,31 +138,32 @@ replies.
121138A line is simply a string of text. Depending on the filtering rules set
122139by the circle's host, these may or may not include uppercase and Unicode
123140characters.
141+
124142If the line starts with `@`, it's an action (IRC `/me`).
125143
126− ~your-urbit:talk> @sends a message
144+ ~your-urbit:talk> @sends a message.
127145
128146will print as
129147
130− ~your-urbit sends a message
148+ ~your-urbit sends a message.
131149
132150#### URLs
133151
134152A URL is any valid URL.
135153
136− ~your-urbit:talk> http://example.com/
154+ ~your-urbit:talk> https://example.com/
137155
138−### Expressions
156+### Hoon
139157
140−Expressions can be used to show and evaluate Hoon code. Send an expression
141−by prefacing your message with `#`.
158+You can use Talk to evaluate Hoon code and share the result with everyone in a
159+Hall circle. To do so, preface your Hoon with `#`.
142160
143− ~your-urbit:talk> #(add 1 2)
161+ ~your-urbit:talk- #(add 2 2)
144162
145163will print as
146164
147− ~your-urbit# (add 1 2)
148− 3
165+ ~your-urbit# (add 2 2)
166+ 4
149167
150168### Replies
151169
@@ -153,12 +171,12 @@ To indicate what you're saying is in direct response to a specific
153171message, select the message (see Activating Lines below) and type your
154172response.
155173
156− ~some-urbit> hello! how are you?
157− ~your-urbit:talk> ; good, thanks!
174+ ~some-urbit- Hello! How are you?
175+ ~your-urbit:talk> ; Good, thanks!
158176
159177will print as
160178
161− ~your-urbit>^ good, thanks!
179+ ~your-urbit>^ Good, thanks!
162180
163181### Activating Lines
164182
@@ -166,18 +184,18 @@ A line number identifying the *subsequent* line is displayed every 5
166184lines.
167185
168186 ---------[0]
169− ~your-urbit> this is my message
170− ~your-urbit> this is another message
171− ~your-urbit sends a message
187+ ~your-urbit- This is my message.
188+ ~your-urbit- This is another message.
189+ ~your-urbit sends a message.
172190 ~your-urbit/ http://example.com/
173− ~your-urbit# (add 1 2)
174− 3
191+ ~your-urbit# (add 2 2)
192+ 4
175193 ---------[5]
176− ~your-urbit>^ that's my message!
194+ ~your-urbit>^ That's my message!
177195
178196You can use a line number to *activate* a line:
179197
180− ~your-urbit:talk> ;5
198+ ~your-urbit:talk- ;5
181199
182200which prints the number, line identifier, timestamp, sender, audience,
183201and contents:
@@ -186,8 +204,8 @@ and contents:
186204 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
187205 ~your-urbit to ~another-urbit
188206 in reply to: ~your-urbit:
189− > this is my message
190− that's my message!
207+ > This is my message.
208+ That's my message!
191209
192210If information got truncated — like happens for long URLs or expressions —
193211or if there's additional information available — as is the case with
@@ -199,40 +217,40 @@ with `;;`, and so on.
199217
200218### Creating and managing circles
201219
202−`;create [type] %name 'description'`
220+###### `;create [type] %name 'description'`
203221Creates and joins a circle, where `[type]` is any of the following:
204222- `channel`: public circle. Has a blacklist for write control.
205223- `village`: invite-only circle.
206224- `journal`: publicly readable, invite-only for writing.
207225- `mailbox`: publicly writeable, can only be read by its host.
208226
209−`;delete %name 'optional reason'`
227+###### `;delete %name 'optional reason'`
210228Deletes a circle. If a reason is specified, that gets sent to all
211229subscribers before the circle gets deleted.
212230
213−`;depict %name 'description'`
231+###### `;depict %name 'description'`
214232Changes the description of circle `%name`.
215233
216−`;filter %name [capitals] [unicode]`
234+###### `;filter %name [capitals] [unicode]`
217235Configures the message filter for circle `%name`: whether to allow
218236capital and/or unicode characters. `y`/`&`/`true` for allowed,
219237`n`/`|`/`false` for disallowed.
220238
221−`;invite %name ~someone`
239+###### `;invite %name ~someone`
222240Invite someone into your circle `%name`. If they were previously banished,
223241removes them from the blacklist.
224242Can also invite multiple ships at once, `~comma, ~separated`.
225243
226−`;banish %name ~someone`
244+###### `;banish %name ~someone`
227245Banish someone from your circle `%name`. If they were previously invited,
228246removes them from the whitelist.
229247Can also banish multiple ships at once, `~comma, ~separated`.
230248
231−`;source %name ~other/circle`
249+###### `;source %name ~other/circle`
232250Adds `~other/circle` as a source for circle `%name`. This causes all
233251messages sent to `~other/circle` to also appear in `%name`.
234252
235−`;unsource %name ~other/circle`
253+###### `;unsource %name ~other/circle`
236254Removes `~other/circle` as a source for circle `%name`.
237255
238256### Membership
@@ -240,37 +258,40 @@ Removes `~other/circle` as a source for circle `%name`.
240258If you have joined a circle, you can make this information publicly
241259available to help others find that circle as well.
242260
243−`;show ~some/circle`
261+###### `;show ~some/circle`
244262Adds a circle to your public membership list.
245263
246−`;hide ~some/circle`
264+###### `;hide ~some/circle`
247265Removes a circle from your public membership list.
248266
249267### Status
250268
251269You'll see status notifications when people enter or leave stations
252−you're subscribed to.
253270
254−`;set quiet`
271+###### `;set quiet`
255272Turn off status (and config) notifications.
256273
257−`;unset quiet`
274+###### `;unset quiet`
258275Turn on status (and config) notifications.
259276
260−`;who`
277+###### `;who`
261278List everyone in all your subscribed circles. Optionally specify a
262279specific circle to list members of just those.
263280
264−`;attend ~some/circle [presence]`
281+You'll see presence notifications when people enter or leave stations
282+you're subscribed to.
283+
284+###### `;attend ~some/circle [presence]`
265285Manually set your presence to show up as one of the following. (In the
266286future, a sufficiently advanced client can automatically set these for
267287you.)
288+
268289- `talk` - typing
269290- `hear` - listening
270291- `idle` - inactive
271292- `gone` - not present
272293
273−`;name ~some/circle 'my handle'`
294+###### `;name ~some/circle 'my handle'`
274295Set a handle ("name") for yourself in a specific circle. It will display
275296to users who have done `;set nicks`, but gets truncated if it's longer
276297than 14 characters.
@@ -280,7 +301,6 @@ than 14 characters.
280301An audience consists of one or more messaging targets. These can be
281302circles or ships. (In the latter case, it's secretly the `~ship/inbox`
282303circle.)
283−
284304### Circle glyphs
285305
286306Glyphs are assigned by circle hash out of the following list
@@ -290,10 +310,10 @@ Glyphs are assigned by circle hash out of the following list
290310Alphanumeric characters and `|#;:*~_` are reserved; all others (the
291311above list, and `\/!?({<`) can be manually assigned.
292312
293−`;bind + /urbit-test`
313+###### `;bind + /urbit-test`
294314Assigns the `+` glyph to `/urbit-test`.
295315
296−`;unbind + /urbit-test`
316+###### `;unbind + /urbit-test`
297317Unassigns the `+` glyph from `/urbit-test`.
298318
299319To see what circle is bound to a glyph:
@@ -305,8 +325,9 @@ To see what circle is bound to a glyph:
305325
306326Received posts are prefixed with a glyph to let you know what the
307327audience is. You can activate an individual post to see the full
308−audience.
309−There are a few special-purpose glyphs.
328+audience.
329+
330+There are a few special-purpose glyphs:
310331
311332- `|` - Informational messages
312333- `:` - Posts directly to you
@@ -328,20 +349,20 @@ Here we're talking directly to `~dannum-mitryl`:
328349
329350#### Configuration
330351
331−`;~urbit/station`
332−Set audience to `~urbit/station`.
352+###### `;~urbit/circle`
353+Set audience to `~urbit/circle`.
333354
334−`;=`
335−Set audience to the station bound to the `=` glyph.
355+###### `;=`
356+Set audience to the station bound to the `=` glyph
336357
337−`;~dannum-mitryl`
358+###### `;~dannum-mitryl`
338359Set audience to `~dannum-mitryl` (a direct post).
339360
340−`;%station`
341−Set audience to a station on your own ship.
361+###### `;%circle`
362+Set audience to a circle on your own ship
342363
343−`;~dannum-mitryl this is a private message`
344−Set the audience and send a post to it. This works for all of the above.
364+###### `;~dannum-mitryl this is a private message`
365+Set the audience and send a post in the same line. This works for all of the above.
345366
346367Your audience is configured with regard to the following rules (in order):
347368
@@ -351,26 +372,26 @@ Your audience is configured with regard to the following rules (in order):
351372
352373### Local nicknames
353374
354−`;nick`
375+###### `;nick`
355376List all local nicknames.
356377
357−`;nick ~some-urbit`
378+###### `;nick ~some-urbit`
358379Look up a nickname.
359380
360−`;nick plato`
381+###### `;nick plato`
361382Search in reverse.
362383
363−`;nick ~some-urbit plato`
384+###### `;nick ~some-urbit plato`
364385Create a nickname.
365−
366−`;nick ~some-urbit ~`
386+
387+###### `;nick ~some-urbit ~`
367388Clear an assigned nickname.
368389
369−`;set nicks`
390+###### `;set nicks`
370391Show nicknames instead of urbit names. If no local nickname is set, uses
371392that user's handle. If the user has no handle, just the urbit name.
372393
373−`;unset nicks`
394+###### `;unset nicks`
374395Show urbit names instead of nicknames.
375396
376397Nicknames and handles longer than 14 character will be truncated in
@@ -379,22 +400,22 @@ phonebook.
379400
380401### Miscellaneous configuration
381402
382−`;set showtime`
403+###### `;set showtime`
383404Show the timestamp for each message.
384405
385−`;unset showtime`
386−Stop showing the timestamp for each message.
406+###### `;unset showtime`
407+Stop showing the timestamp for each message.
387408
388−`;set timezone [+/-][hours]`
409+###### `;set timezone [+/-][hours]`
389410Adjust the display of the timestamps to a specific timezone. Relative to UTC.
390411
391−`;set notify`
412+###### `;set notify`
392413Emit a terminal bell sound if your six-syllable ship name is mentioned in
393414a message.
394415
395−`;unset notify`
416+###### `;unset notify`
396417Do not notify when your ship name is mentioned.
397418
398−`;set width [number]`
419+###### `;set width [number]`
399420Set the rendering width of `:talk` to a specific number of characters.
400421(Minimum of 30.)
docs/using/setup.md+20−23
@@ -1,6 +1,7 @@
11---
2−navhome: '/docs'
3−next: True
2+navhome: /docs/
3+navuptwo: true
4+next: true
45sort: 2
56title: Setup
67---
@@ -46,12 +47,12 @@ Welcome!
4647By default your urbit is quite bare-bones. Let's stroll through what's
4748already running:
4849
49−### Shell — `:dojo`
50+### Shell — Dojo
5051
5152The command prompt in front of you is a simple shell and Hoon REPL.
5253Let's make sure it works:
5354
54− ~fitund-macrep:dojo> (add 2 2)
55+ ~your-urbit:dojo> (add 2 2)
5556
5657Should produce:
5758
@@ -60,40 +61,36 @@ Should produce:
6061
6162Good.
6263
63−### Messaging — `:talk`
64+### Messaging — Talk
6465
6566Use `ctrl-x` to change your prompt. Let's join the main Urbit chat
66−channel.
67+channel, `/urbit-meta`:
6768
68−For planets:
69+ ~your-urbit:talk[] ;join /urbit-meta
6970
70− ~fitund-macrep:talk() ;join /urbit-meta
71−
72−For comets:
73−
74− ~ticlen-nidrup-larwyl-rivtyc--folsel-tocwyl-hosrex-nimder:talk() ;join ~binzod/urbit-meta
75−
76−`:talk` is stateful, so your urbit will download a backlog.
71+Talk is stateful, so your urbit will download a backlog.
7772`/urbit-meta` is the place to ask questions, get help and talk about
7873anything Urbit-related.
7974
80−### Web — `:tree`
75+### Web — Tree
8176
8277Urbit is also accessible through the web. Try opening:
8378
8479 http://localhost:8080/
8580
86−in your favorite browser. You'll be prompted to use `+code`. This page
87−was generated by `:tree`, the basic Urbit web interface. You can also
88−access your urbit through `http://fintud-macrep.urbit.org` (where
89−`fintud-macrep` is your planet name).
81+in your favorite browser. You'll be prompted to use `+code` in your Dojo
82+to retrive your password and log in. This page was generated by Tree,
83+the basic Urbit web interface. You can also access your urbit through
84+`http://your-urbit.urbit.org`. Note that this latter approach is slower
85+for the time being because we proxy over the Urbit network, Ames, but a
86+better, faster solution for this is in the works.
9087
91−### Filesystem — `%clay`
88+### Filesystem — Clay
9289
93−`%clay`, the Urbit filesystem, isn't mounted to unix by default. Switch
94−to the `:dojo` prompt and run:
90+Clay, the Urbit filesystem, isn't mounted to Unix by default. Switch
91+to the Dojo prompt and run:
9592
96− ~fitund-macrep:dojo> |mount %
93+ ~your-urbit:dojo> |mount %
9794
9895This should produce:
9996
docs/using/shell.md+9−8
@@ -1,18 +1,19 @@
11---
2−navhome: '/docs'
3−next: True
4−sort: 5
5−title: Shell (:dojo)
2+navhome: /docs/
3+navuptwo: true
4+next: true
5+sort: 6
6+title: Shell (Dojo)
67---
78
8−# Shell (`:dojo`)
9+# Shell (Dojo)
910
1011<div class="row">
1112
1213<div class="col-md-8">
1314
14−The `:dojo` is the place to quickly experiment with Urbit. On the
15−surface the `:dojo` is just a Hoon REPL. On the inside, the `:dojo` is a
15+The Dojo is the place to quickly experiment with Urbit. On the
16+surface the Dojo is just a Hoon REPL. On the inside, the Dojo is a
1617system for operating on and transforming data in Urbit.
1718
1819</div>
@@ -232,7 +233,7 @@ Create a random moon (from any planet):
232233
233234### Variables
234235
235−You can use `=` to set an environment variable in `:dojo`, but there are
236+You can use `=` to set an environment variable in Dojo, but there are
236237a few reserved names that have special uses.
237238
238239#### `dir`
docs/using/urb.mddeleted−356
@@ -1,356 +0,0 @@
1−---
2−navhome: /docs/
3−sort: 8
4−title: From Unix
5−---
6−
7−<div class="row">
8−<div class="col-md-8">
9−
10−# Using Urbit from Unix
11−
12−With `urb` at your Unix command line, you can execute hoon, run
13−dojo commands, and more. Additionally, with `fuse`, you can
14−inspect the urbit namespace.
15−
16−</div>
17−</div>
18−
19−## Installation
20−
21−These commands are in the a [separate
22−repo](https://github.com/urbit/urb). Clone this repo to get the
23−commands.
24−
25−You'll also need the `requests` and `fuse` libraries for python.
26−If you have `pip`, you can just run:
27−
28−```
29−pip install requests fuse-python
30−```
31−
32−Otherwise, on Ubuntu, run:
33−
34−```
35−apt-get install python-requests python-fuse
36−```
37−
38−Then you can either run the python commands from the git repo, or
39−put them somewhere in your path.
40−
41−## `urb`
42−
43−`urb` transfers data from a source to a sink. Examples of data
44−sources include literal data, a file, a URL, or some
45−tranformation of another source. Examples of data sinks are
46−stdout, output file, POST request, or dojo command.
47−
48−Here are some examples. This takes the literal data "hello
49−world" and sends it to stdout (the default sink).
50−
51− urb --data 'hello world'
52−
53−Let's run some hoon code at the dojo.
54−
55− urb --dojo '(add 2 2)'
56−
57−Let's convert a markdown file to html.
58−
59− urb --data @@file.md -m md -m html
60−
61−Mount the `%home` desk. This syncs the `home` desk into the pier
62−directory.
63−
64− urb --dojo '+hood/mount /=home=' --app hood
65−
66−### Sources
67−
68−Sources can be any of the following:
69−
70−- `-d, --dojo command` runs a dojo command. This is commonly
71− naked hoon code, but it can also be a generator, or any of the
72− other ways the dojo gets data.
73−
74−- `-D, --data text` is literal text data, as a cord.
75−
76−- `-c, --clay path` pulls data from Urbit's filesystem.
77−
78−- `-u, --url url` pulls data from a URL.
79−
80−- `-m, --mark mark source` converts the output from another source to
81− a new 'mark' (datatype).
82−
83−- `-H, --hoon code source` transforms the output of another
84− source by running it through some hoon code.
85−
86−- `[source-0 source-1 ...]`. Sources can be combined into tuples
87− of different sources.
88−
89−Any of the arguments to a source (except in the "compound
90−sources" `--mark` and `--hoon`) can be replaced by `-` to
91−represent stdin or `@@filename` to pull data in from a Unix file.
92−Thus, `urb [-D @@file1 -D - -D @@file2]` is equivalent to Unix's
93−`cat file1 - file2`.
94−
95−Additionally, if no source is specified, `--data -` (stdin as
96−literal text data) is assumed.
97−
98−### Sinks
99−
100−- `-s, --stdout` outputs to stdout. This is the default.
101−
102−- `-f, --output-file path` writes to a unix file.
103−
104−- `-C, --output-clay path` writes to Urbit's filesystem.
105−
106−- `-U, --output-url url` sends a POST request with the data to
107− the URL.
108−
109−- `-p, --app app` sends the data to an urbit app.
110−
111−- `-x, --command` outputs to a literal dojo command.
112−
113−## `fuse`
114−
115−Urbit's namespace is accessible through the `fuse` command.
116−`fuse` takes all the normal FUSE arguments, which you can see
117−with `fuse -h`. Generally, you just run `fuse MOUNT-POINT`.
118−
119−When accessing the namespace through `fuse`, everything is
120−read-only. If you want to write to Clay, mount a desk, as
121−described above.
122−
123−Let's look first in the Clay portion of the Urbit namespace.
124−Assume we've mounted to `./pt`.
125−
126− $ ls ./pt/c/=/=/=
127− app arvo gen lib mar ren sec sur web
128− $ ls ./pt/c/=/=/=/arvo
129− ames behn clay dill eyre ford gall hoon zuse
130−
131−Those `=`s aren't decorative. The first `=` means "current
132−ship", the second "current desk", and the third "current
133−revision". Let's try something a little more exciting.
134−
135−This runs the Unix `diff` command on the first and current
136−versions of the `app/gh/hoon` file, showing all the changes we've
137−made to the file.
138−
139−```
140−$ diff pt/c/=/=/{1,=}/app/gh/hoon
141−73c73,75
142−< (malt (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~])))
143−---
144−> %- malt ^- (list {@ta $~})
145−> :- [%gh-list-issues ~]
146−> (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~]))
147−92c94,101
148−< read-y=(read-get /issues)
149−---
150−> read-y=(read-static %gh-list-issues ~)
151−> sigh-x=sigh-list-issues-x
152−> sigh-y=sigh-list-issues-y
153−> ==
154−> ^- place :: /issues/mine/<mark>
155−> :* guard={$issues $mine @t $~}
156−> read-x=read-null
157−> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
158−126c135
159−< ^- place :: /issues/by-repo/<user>/<repo>
160−---
161−> ^- place :: /issues/by-repo/<user>/<repo>/<number>
162−131c140,146
163−< read-y=(read-static ~)
164−---
165−> ^= read-y
166−> |= pax/path
167−> %. pax
168−> ?: ((sane %tas) -.+>+>.pax)
169−> (read-static ~)
170−> (read-static %gh-issue ~)
171−> ::
172−137a153,159
173−> sigh-y=sigh-strange
174−> ==
175−> ^- place :: /issues/by-repo/<u>/<r>/<n>/<mark>
176−> :* guard={$issues $by-repo @t @t @t @t $~}
177−> read-x=read-null
178−> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
179−> sigh-x=sigh-strange
180−```
181−
182−Urbit's namespace is not just revisioned, but global. Here's a
183−diff of our version of `arvo/gall/hoon` compared to the one on
184−the `~bud` urbit.
185−
186−```
187−$ diff pt/c/{~bud,=}/=/=/arvo/gall/hoon
188−2d1
189−<
190−640a640,644
191−> =+ ?. ?=($x ren)
192−> [mar=%$ tyl=tyl]
193−> =+ `path`(flop tyl)
194−> ?> ?=(^ -)
195−> [mar=i tyl=(flop t)]
196−643c647
197−< ((slog leaf+"peek find fail" >tyl< ~) [~ ~])
198−---
199−> ((slog leaf+"peek find fail" >tyl< >mar< ~) [~ ~])
200−654a659,660
201−> ?. =(mar p.q.caz)
202−> [~ ~]
203−1308a1315,1316
204−> ?. ?=(^ tyl)
205−> ~
206−```
207−
208−Besides Clay, the namespace contains Gall apps. One common usage
209−of the app namespace is to expose APIs. For example, if you
210−start the `%gh` app (`|start %gh`), you can do things like `cat`
211−an issue from a repository.
212−
213−```
214−$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/txt
215−title: big news! (#7)
216−state: open
217−creator: philipcmonktest
218−created-at: 2016-03-24T22:27:33Z
219−assignee: philipcmonktest
220−labels: invalid, wontfix, help wanted
221−comments: 0
222−url: https://api.github.com/repos/philipcmonktest/testing/issues/7
223−
224−Yup, that's it. i mean, maybe it's a bit longer than that.
225−
226−But you get the point, right?
227−
228−Code `is` cool!
229−```
230−
231−Or all open issues for a repository.
232−
233−```
234−$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/txt
235−title: i found a bug! (#11)
236−state: open
237−creator: philipcmonktest
238−created-at: 2016-04-14T23:14:49Z
239−assignee: none
240−labels:
241−comments: 1
242−url: https://api.github.com/repos/philipcmonktest/testing/issues/11
243−
244−
245−----------------------------------------
246−title: more newz (#8)
247−state: open
248−creator: philipcmonktest
249−created-at: 2016-03-24T22:29:16Z
250−assignee: none
251−labels:
252−comments: 4
253−url: https://api.github.com/repos/philipcmonktest/testing/issues/8
254−
255−Yup, that's it. i mean, maybe it's a bit longer than that.
256−
257−But you get the point, right?
258−
259−Code `is` cool!
260−----------------------------------------
261−title: big news! (#7)
262−state: open
263−creator: philipcmonktest
264−created-at: 2016-03-24T22:27:33Z
265−assignee: philipcmonktest
266−labels: invalid, wontfix, help wanted
267−comments: 0
268−url: https://api.github.com/repos/philipcmonktest/testing/issues/7
269−
270−Yup, that's it. i mean, maybe it's a bit longer than that.
271−
272−But you get the point, right?
273−
274−Code `is` cool!
275−----------------------------------------
276−title: something different (#4)
277−state: open
278−creator: philipcmonktest
279−created-at: 2016-01-26T21:45:08Z
280−assignee: philipcmonktest
281−labels: duplicate, help wanted, question, bug
282−comments: 1
283−url: https://api.github.com/repos/philipcmonktest/testing/issues/4
284−```
285−
286−Don't like the textual format? How about we get the raw JSON
287−(and prettyprint it).
288−
289−```
290−$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/json | python -m json.tool
291−{
292− "assignee": {
293− "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
294− "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
295− "followers_url": "https://api.github.com/users/philipcmonktest/followers",
296− "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
297− "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
298− "gravatar_id": "",
299− "html_url": "https://github.com/philipcmonktest",
300− "id": 16787461,
301− "login": "philipcmonktest",
302− "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
303− "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
304− "repos_url": "https://api.github.com/users/philipcmonktest/repos",
305− "site_admin": false,
306− "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
307− "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
308− "type": "User",
309− "url": "https://api.github.com/users/philipcmonktest"
310− },
311− "body": "Yup, that's it. i mean, maybe it's a bit longer than that.\r\n\r\nBut you get the point, right?\r\n\r\nCode `is` cool!",
312− "closed_at": null,
313− "closed_by": null,
314− "comments": 0,
315− "comments_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/comments",
316− "created_at": "2016-03-24T22:27:33Z",
317− "events_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/events",
318− "html_url": "https://github.com/philipcmonktest/testing/issues/7",
319− "id": 143377108,
320− "labels": [
321− {
322− "color": "ffffff",
323− "name": "wontfix",
324− "url": "https://api.github.com/repos/philipcmonktest/testing/labels/wontfix"
325− }
326− ],
327− "labels_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/labels{/name}",
328− "locked": false,
329− "milestone": null,
330− "number": 7,
331− "repository_url": "https://api.github.com/repos/philipcmonktest/testing",
332− "state": "open",
333− "title": "big news!",
334− "updated_at": "2016-03-24T22:27:33Z",
335− "url": "https://api.github.com/repos/philipcmonktest/testing/issues/7",
336− "user": {
337− "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
338− "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
339− "followers_url": "https://api.github.com/users/philipcmonktest/followers",
340− "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
341− "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
342− "gravatar_id": "",
343− "html_url": "https://github.com/philipcmonktest",
344− "id": 16787461,
345− "login": "philipcmonktest",
346− "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
347− "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
348− "repos_url": "https://api.github.com/users/philipcmonktest/repos",
349− "site_admin": false,
350− "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
351− "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
352− "type": "User",
353− "url": "https://api.github.com/users/philipcmonktest"
354− }
355−}
356−```
docs/using/web.md+8−8
@@ -1,18 +1,18 @@
11---
22navhome: /docs/
3−next: true
4−sort: 7
5−title: Web
3+navuptwo: true
4+sort: 8
5+title: Web (Eyre)
66---
77
8−# Web
8+# Web (Eyre)
99
1010<div class="row">
1111<div class="col-md-8">
1212
13−Your Urbit runs its own webserver, `%eyre`, that handles all things HTTP. Here we'll cover the features of `%eyre` that most resemble a traditional web server.
13+Your Urbit runs its own webserver, Eyre, that handles all things HTTP. Here we'll cover the features of Eyre that most resemble a traditional web server.
1414
15−By default `%eyre` uses Tree, which is sort of like a combination of [Jekyll](https://jekyllrb.com/) or [Kirby](https://getkirby.com/) and Finder on OSX. Tree is a simple ui for browsing the contents of the filesystem, statically publishing a blog or any kind of content and for running single-page apps.
15+By default Eyre uses Tree, which is sort of like a combination of [Jekyll](https://jekyllrb.com/) or [Kirby](https://getkirby.com/) and Finder on OSX. Tree is a simple ui for browsing the contents of the filesystem, statically publishing a blog or any kind of content and for running single-page apps.
1616
1717Tree was built primarily to display both our documentation and the contents of `urbit.org`. We provide a few simple examples [here](#-examples) of how to publish using Tree. If you're interested in doing anything complex it's worth checking out the [docs source](https://github.com/urbit/docs) and the [urbit.org](https://github.com/urbit/urbit.org) source.
1818
@@ -52,7 +52,7 @@ Now modify `/sandbox/web/test.md` to list the children using the `<list/>` JSX:
5252 This is a simple markdown file.
5353
5454 <div><list /></div>
55−
55+
5656To view your file rendered using tree:
5757
5858 http://localhost:8080/test/
@@ -289,7 +289,7 @@ Each JSON message sent to your Urbit needs an app endpoint. Can be set as a glo
289289
290290### `window.urb.oryx`
291291
292−CSRF token. Written to the page by `%eyre`, our webserver, when logged in. Required part of any authenticated request and included by default.
292+CSRF token. Written to the page by Eyre, our webserver, when logged in. Required part of any authenticated request and included by default.
293293
294294### `window.urb.req(method,url,params,json,cb)`
295295