git.iko.soy/urbit.org
on master help sign in
Various improvements
b783f26Philip C Monk
docs/about/runtime.md+1
compare with master
unifiedsplit
@@ -1,5 +1,6 @@
1---
1---
2sort: 2
2sort: 2
3+title: C runtime system
3---
4---
4
5
5# C runtime system
6# C runtime system
docs/using/admin.md+6−6
@@ -32,7 +32,7 @@ or
32
32
33Your 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.
33Your 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.
34
34
35−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.
35+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.
36
36
37`^X` - Switches the prompt between running console apps
37`^X` - Switches the prompt between running console apps
38
38
@@ -58,7 +58,7 @@ The following emacs-style key bindings are available:
58 ^U kill to beginning of line
58 ^U kill to beginning of line
59 ^Y yank from kill buffer
59 ^Y yank from kill buffer
60
60
61−Full coverage of the Urbit shell, the `:dojo` is covered in the [Shell walkthrough](/docs/walkthroughs/dojo).
61+Full coverage of the Urbit shell, the `:dojo` is covered in the [Shell walkthrough](/docs/using/shell).
62
62
63## Web
63## Web
64
64
@@ -67,19 +67,19 @@ On startup Urbit tries to bind to `localhost:8080`. If you're already running s
67
67
68Your Urbit serves a simple homepage from `http://localhost:8080` or `https://your-urbit.urbit.org` that should be self-explanatory. Since our HTTPS isn't audited / battle tested we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.
68Your Urbit serves a simple homepage from `http://localhost:8080` or `https://your-urbit.urbit.org` that should be self-explanatory. Since our HTTPS isn't audited / battle tested we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.
69
69
70−A complete walkthrough of the Urbit web interface is [here](/docs/walkthroughs/web).
70+A complete walkthrough of the Urbit web interface is [here](/docs/using/web).
71
71
72## Moons
72## Moons
73
73
74−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.
74+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.
75
75
76To generate a random moon from your planet run:
76To generate a random moon from your planet run:
77
77
78 ~your-urbit:dojo> +moon
78 ~your-urbit:dojo> +moon
79
79
80−You can use the resulting output in the same installation flow from [install](/install).
80+You can use the resulting output in the same installation flow from [install](/docs/using/install).
81
81
82−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/walkthroughs/filesystem) and [console](/docs/walkthroughs/console) walkthroughs.
82+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.
83
83
84## Moving your pier
84## Moving your pier
85
85
docs/using/filesystem.md+7−2
@@ -156,12 +156,16 @@ Example:
156
156
157### Merge strategies
157### Merge strategies
158
158
159−`%init` - Used iff it's the first commit to a desk.
159+`%init` - Used if it's the first commit to a desk. Also can be
160+used to "reinitialize" a desk -- revision numbers keep going up,
161+but the new revision isn't necessarily a descendent of the
162+previously-numbered version.
160
163
161`%this` - Keep what's in Bob's desk, but join the ancestry.
164`%this` - Keep what's in Bob's desk, but join the ancestry.
162
165
163`%that` - take what's in Alice's desk, but join the ancestry. This is
166`%that` - take what's in Alice's desk, but join the ancestry. This is
164−the reverse of `%this`.
167+the reverse of `%this`. This is different from `%init` because
168+the new commit has both sides in its ancestry.
165
169
166`%fine` - "fast-forward" merge. This succeeds iff one head is in the
170`%fine` - "fast-forward" merge. This succeeds iff one head is in the
167ancestry of the other.
171ancestry of the other.
@@ -195,6 +199,7 @@ doesn't we use an `%init` merge. Otherwise, we progressively try
195`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
199`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
196merge Bob's desk into a scratch desk. Then, we merge Alice's desk
200merge Bob's desk into a scratch desk. Then, we merge Alice's desk
197into the scratch desk with the `%meld` option to force the merge.
201into the scratch desk with the `%meld` option to force the merge.
202+Finally, we annotate any conflicts, if we know how.
198
203
199### Manipulation
204### Manipulation
200
205
docs/using/messaging.md+9−10
@@ -67,15 +67,15 @@ Last, let's create a channel we can invite some friends to:
67
67
68 ~your-urbit:talk> ;create channel %my-channel 'some description'
68 ~your-urbit:talk> ;create channel %my-channel 'some description'
69
69
70−Now you can your friends to `;join ~your-urbit/my-channel`.
70+Now you can tell your friends to `;join ~your-urbit/my-channel`.
71
71
72## Manual
72## Manual
73
73
74−`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet.
74+`:talk`'s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol), the underlying protocol for Usenet.
75
75
76Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.
76Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.
77
77
78−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 `%board` for general use.
78+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.
79
79
80### Posts
80### Posts
81
81
@@ -83,8 +83,7 @@ For the time being a post is either a line, a URL or a command.
83
83
84#### Lines
84#### Lines
85
85
86−A line is 64 bytes of ASCII lowercase and spaces. If the line
86+A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the line starts with '@', it's an action (IRC `/me`).
87−starts with '@', it's an action (IRC `/me`).
88
87
89The `:talk` interface will let you keep typing past 64 bytes, but
88The `:talk` interface will let you keep typing past 64 bytes, but
90insert a Unicode bullet-point character in an appropriate space
89insert a Unicode bullet-point character in an appropriate space
@@ -97,13 +96,13 @@ A URL is any valid URL.
97
96
98### Commands
97### Commands
99
98
100−A command is any line starting with `;`.
99+A command is a hoon expression, prefaced by '#'.
101
100
102### Creating and managing stations
101### Creating and managing stations
103
102
104`;create journal %serious-journal 'description'` - Creates a `%journal`, a privately writable publicly readable station.
103`;create journal %serious-journal 'description'` - Creates a `%journal`, a privately writable publicly readable station.
105
104
106−`;create channel %serious-journal 'description'` - Creates a `%channel`, a publicly readable publicly writeable station.
105+`;create channel %serious-channel 'description'` - Creates a `%channel`, a publicly readable publicly writeable station.
107
106
108### Presence
107### Presence
109
108
@@ -134,7 +133,7 @@ Received posts are prefixed with a glyph to let you know what the audience is.
134
133
135`;` - Posts to you and others (a multiparty conversation)
134`;` - Posts to you and others (a multiparty conversation)
136
135
137−`*` - Posts to a complex audience that doesn't directly include you are.
136+`*` - Posts to a complex audience that doesn't directly include you.
138
137
139### Audience
138### Audience
140
139
@@ -162,11 +161,11 @@ Here we're talking directly to `~dannum-mitryl`:
162
161
163`;~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.
162`;~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.
164
163
165−Your audience is configured 'implicitly' with regard to the following rules:
164+Your audience is configured 'implicitly' with regard to the following rules (in order):
166
165
166+- if you manually locked the audience, that audience.
167- if typing a post, the audience when you started typing.
167- if typing a post, the audience when you started typing.
168- if you activated a post, the post you activated.
168- if you activated a post, the post you activated.
169−- if you manually locked the audience, that audience.
170- audience of the last post received.
169- audience of the last post received.
171- audience of the last post sent.
170- audience of the last post sent.
172
171
docs/using/shell.md+67−60
@@ -9,7 +9,10 @@ title: Shell (:dojo)
9<div class="row">
9<div class="row">
10<div class="col-md-8">
10<div class="col-md-8">
11
11
12−The `:dojo` is the place to quickly experiment with Urbit. At first glance the `:dojo` is just a Hoon REPL. Looking a bit deeper the `:dojo` is set up to make operating on and transforming data in Urbit easy.
12+The `:dojo` is the place to quickly experiment with Urbit. On
13+the surface the `:dojo` is just a Hoon REPL. On the inside, the
14+`:dojo` is a system for operating on and transforming data in
15+Urbit.
13
16
14</div>
17</div>
15</div>
18</div>
@@ -21,7 +24,7 @@ Evaluate a hoon expression:
21 ~your-urbit:dojo> (add 2 2)
24 ~your-urbit:dojo> (add 2 2)
22 ~your-urbit:dojo> %+ add 2 2
25 ~your-urbit:dojo> %+ add 2 2
23
26
24−Tall form Hoon will be prompted for:
27+Tall form Hoon may require multiple lines:
25
28
26 ~your-urbit:dojo> %+ add
29 ~your-urbit:dojo> %+ add
27 ~your-urbit:dojo< 2
30 ~your-urbit:dojo< 2
@@ -47,6 +50,65 @@ Run system commands from `:hood`, like `reload`, using `|`:
47
50
48 ~your-urbit:dojo> |reload %eyre
51 ~your-urbit:dojo> |reload %eyre
49
52
53+
54+### Generators
55+
56+**`+cat`** - Similar to Unix `cat`. Accepts a path.
57+
58+ ~your-urbit:dojo> +cat %/web/md
59+ ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md
60+
61+**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
62+
63+ ~your-urbit:dojo> +curl "http://nyt.com"
64+
65+**`+hello`** - Just prints the argument. Accepts a `@ta`.
66+
67+ ~your-urbit:dojo> +hello 'mars'
68+
69+**`+ls`** - Similar to Unix `ls`. Accepts a path.
70+
71+ ~your-urbit:dojo> +ls %/web
72+ ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
73+
74+**`+moon`** - Generate a random moon from a planet. No arguments.
75+
76+**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.
77+
78+ ~your-urbit:dojo> .urbit/pill +solid
79+
80+**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
81+
82+ ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
83+
84+**`+tree`** - Generate a recursive directory listing. Takes a path.
85+
86+ ~your-urbit:dojo> +tree %/web
87+
88+### Hood
89+
90+The hood is the system daemon. See `gen/hood` and `app/hood`.
91+
92+**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts an urbit name (`@p`) and a string (`cord`).
93+
94+ ~your-urbit:dojo> |hi ~doznec 'you there?'
95+
96+**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.
97+
98+ ~your-urbit:dojo> |link ~talsur-todres %octo
99+
100+**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.
101+
102+**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.
103+
104+ ~your-urbit:dojo> |reload %clay %eyre
105+
106+**`|reset`** - Reloads `hoon.hoon`. No arguments.
107+
108+**`|start`** - Starts an app. Accepts an app name.
109+
110+ ~your-urbit:dojo> |start %curl
111+
50## Manual
112## Manual
51
113
52<h3 class="first child">Sources and sinks</h3>
114<h3 class="first child">Sources and sinks</h3>
@@ -131,6 +193,9 @@ Use `_` to run a gate (or function):
131
193
132`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body.
194`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body.
133
195
196+Note that the first of these is a source while the last two are
197+sinks.
198+
134#### `+` - Generators
199#### `+` - Generators
135
200
136Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`.
201Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`.
@@ -209,61 +274,3 @@ The current urbit plot. Read-only.
209 ~your-urbit:dojo> eny
274 ~your-urbit:dojo> eny
210 :: produces
275 :: produces
211 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
276 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
212−
213−### Generators
214−
215−**`+cat`** - Similar to Unix `cat`. Accepts a path.
216−
217− ~your-urbit:dojo> +cat %/web/md
218− ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md
219−
220−**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
221−
222− ~your-urbit:dojo> +curl "http://nyt.com"
223−
224−**`+hello`** - Just prints the argument. Accepts a `@ta`.
225−
226− ~your-urbit:dojo> +hello 'mars'
227−
228−**`+ls`** - Similar to Unix `ls`. Accepts a path.
229−
230− ~your-urbit:dojo> +ls %/web
231− ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
232−
233−**`+moon`** - Generate a random moon from a planet. No arguments.
234−
235−**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.
236−
237− ~your-urbit:dojo> .urbit/pill +solid
238−
239−**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
240−
241− ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
242−
243−**`+tree`** - Generate a recursive directory listing. Takes a path.
244−
245− ~your-urbit:dojo> +tree %/web
246−
247−### Hood
248−
249−The hood is the system daemon. See `gen/hood` and `app/hood`.
250−
251−**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts an urbit name (`@p`) and a string (`cord`).
252−
253− ~your-urbit:dojo> |hi ~doznec 'you there?'
254−
255−**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.
256−
257− ~your-urbit:dojo> |link ~talsur-todres %octo
258−
259−**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.
260−
261−**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.
262−
263− ~your-urbit:dojo> |reload %clay %eyre
264−
265−**`|reset`** - Reloads `hoon.hoon`. No arguments.
266−
267−**`|start`** - Starts an app. Accepts an app name.
268−
269− ~your-urbit:dojo> |start %curl
docs/using/web.md+4−3
@@ -24,7 +24,8 @@ We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its
24
24
25Your Urbit runs a web server and can be found at either `http://localhost:8080/` (or `8081` if you're running other processes that might be occupying `8080`, you can determine which port your urbit is on by looking at your boot sequence — it's specified there), or `http://your-urbit.urbit.org/`.
25Your Urbit runs a web server and can be found at either `http://localhost:8080/` (or `8081` if you're running other processes that might be occupying `8080`, you can determine which port your urbit is on by looking at your boot sequence — it's specified there), or `http://your-urbit.urbit.org/`.
26
26
27−(Make sure you have a desk mounted to unix, as covered in the [filesystem walkthrough](/filesystem))
27+(Make sure you have a desk mounted to unix, as covered in the
28+[filesystem walkthrough](/docs/using/filesystem))
28
29
29To switch the desk you're serving from:
30To switch the desk you're serving from:
30
31
@@ -203,7 +204,7 @@ As a file browser Tree does a simple job: it fetches data and keeps a cache of w
203
204
204Since we want to use React to manage our DOM lifecycle we actually transfer the DOM structure of each page as JSON over the wire, and 'reactify' it on the client side.
205Since we want to use React to manage our DOM lifecycle we actually transfer the DOM structure of each page as JSON over the wire, and 'reactify' it on the client side.
205
206
206−On the Urbit side we actually have a type for html: `++manx`. Our wire format for sending HTML as JSON is really similar to a `++manx`. If you're not interested here's what the json looks like:
207+On the Urbit side we have a type for html: `++manx`. Our wire format for sending HTML as JSON is really similar to a `++manx`. If you're not interested here's what the json looks like:
207
208
208```
209```
209"string" || {gn:"string", ga:{key:"string", [...]}, c:[...]}
210"string" || {gn:"string", ga:{key:"string", [...]}, c:[...]}
@@ -227,7 +228,7 @@ To see the mechanics of how this is handled on the frontend, checkout `component
227
228
228### Async component
229### Async component
229
230
230−Each of our components (even those we fetched from the server) can depend on data that may not exist in our stores we wrap our components in a general-purpose Async component. You can find the component in `components/Async.coffee` in the `urbit/tree` repo.
231+Each of our components (even those we fetched from the server) can depend on data that may not exist in our stores, so we wrap our components in a general-purpose Async component. You can find the component in `components/Async.coffee` in the `urbit/tree` repo.
231
232
232When we say that we just fetch HTML as JSON it's actually slightly more complicated. When we fetch a node in the filesystem we might not want to fetch its entire contents. Sometimes we just get the title as a part of a list of children, sometimes we might get a snippet (in a list with previews), and sometimes we get the whole thing. On the Urbit side these results are provided by `ren/tree/json`.
233When we say that we just fetch HTML as JSON it's actually slightly more complicated. When we fetch a node in the filesystem we might not want to fetch its entire contents. Sometimes we just get the title as a part of a list of children, sometimes we might get a snippet (in a list with previews), and sometimes we get the whole thing. On the Urbit side these results are provided by `ren/tree/json`.
233
234
docs/using/web/static.md−1
@@ -1,7 +1,6 @@
1---
1---
2sort: 3
2sort: 3
3title: A static site
3title: A static site
4−next: true
5---
4---
6
5
7# A static site
6# A static site