5b9c970 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

fixes dead links, updates using

commit5b9c970742dce825c196df7780302332a2774138 authorRobert <robert@tlon.io> dateFri 28 Sep 2018, 17:49 (8 years ago) parent752a7ac

34 files changed+1102−443

compare with master

unifiedsplit

docs/about/contributing.umd+3−1 docs/about/overview.umd+108−32 docs/reference/advanced.umd+7−7 docs/reference/basic.umd+38−12 docs/reference/cheat-sheet.umd+3−2 docs/reference/glossary.umd+28−29 docs/reference/irregular.umd+6−6 docs/reference/library/1b.umd−2 docs/reference/library/2a.umd+2−2 docs/reference/library/4b.umd+1−1 docs/reference/library/4h.umd+2−2 docs/reference/library/5f.umd+1−1 docs/reference/rune/bar.umd+3−1 docs/reference/rune/bar/hep.umd+2−2 docs/reference/rune/bus.umd+6−1 docs/reference/rune/constants/cold.umd+1−1 docs/reference/rune/limb.umd+7−2 docs/reference/rune/tis.umd+12−5 docs/reference/rune/wut.umd+5−1 docs/tutorials/gall.umd+4−1 docs/tutorials/hall.umd+2−1 docs/tutorials/urbitmarkdown.umd+13−2 docs/using/web/blog.umd → docs/tutorials/urbitmarkdown/blog.umd+27−18 docs/using/web/comments.umd → docs/tutorials/urbitmarkdown/comments.umd+4−4 docs/using/web/static.umd → docs/tutorials/urbitmarkdown/static.umd+10−4 docs/using.umd+2−1 docs/using/admin.umd+55−22 docs/using/filesystem.umd+77−13 docs/using/install.umd+12−7 docs/using/layout.umd+61−24 docs/using/messaging.umd+274−98 docs/using/setup.umd+91−66 docs/using/shell.umd+71−25 docs/using/web.umd+164−47

docs/about/contributing.umd+3−1

@@ -15,4 +15,6 @@ for improving our [code](https://github.com/urbit/urbit/) and

1515

1616Our official guide to contributing can be found

1717[here](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md),

18−which is most useful for large and low-level changes. For a good example of preferred Hoon coding style, see [ford.hoon](https://github.com/urbit/arvo/blob/master/sys/vane/ford.hoon).

18+which is most useful for large and low-level changes. For a good example of

19+preferred Hoon coding style, see

20+[ford.hoon](https://github.com/urbit/arvo/blob/master/sys/vane/ford.hoon).

docs/about/overview.umd+108−32

@@ -8,44 +8,88 @@

99# Technical overview

1010

11−Urbit is a clean-slate software stack designed to implement an encrypted P2P network of general-purpose personal servers. Each server on this network is a deterministic computer called an 'urbit' that runs on a Unix-based virtual machine.

11+Urbit is a clean-slate software stack designed to implement an encrypted P2P

12+network of general-purpose personal servers. Each server on this network is a

13+deterministic computer called an 'urbit' that runs on a Unix-based virtual

14+machine.

1215

1316The current Urbit stack includes (among other things):

1417

1518- Arvo: the functional operating system of each urbit, written in Hoon.

16−- Hoon: a strictly typed functional programming language whose standard library includes a Hoon-to-Nock compiler.

17−- Nock: a low-level combinator language whose formal specification gzips to 340 bytes.

18−- Vere: a Nock interpreter and Unix-based virtual machine that mediates between each urbit and the Unix software layer.

19+- Hoon: a strictly typed functional programming language whose standard library

20+ includes a Hoon-to-Nock compiler.

21+- Nock: a low-level combinator language whose formal specification gzips to 340

22+ bytes.

23+- Vere: a Nock interpreter and Unix-based virtual machine that mediates between

24+ each urbit and the Unix software layer.

1925

2026## Anatomy of a personal server

2127

22−Your urbit is a deterministic computer in the sense that its state is a pure function of its event history. Every event in this history is a [transaction](https://en.wikipedia.org/wiki/Transaction_processing); your urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).

28+Your urbit is a deterministic computer in the sense that its state is a pure

29+function of its event history. Every event in this history is a

30+[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your

31+urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).

2332

24−Because each urbit is deterministic we can describe its role appropriately in purely functional terms: it maps an input event and the old urbit state to a list of output actions and the subsequent state. This is the Urbit transition function.

33+Because each urbit is deterministic we can describe its role appropriately in

34+purely functional terms: it maps an input event and the old urbit state to a

35+list of output actions and the subsequent state. This is the Urbit transition

36+function.

2537

2638```

2739<input event, old state> -> <output actions, new state>

2840```

2941

30−For example, one input event could be a keystroke from the terminal, say `[enter]` after having already typed `(add 2 2)`; and an output action could be to print in the terminal window the resulting value of a computation performed when the user hit `[enter]`, in this case `4`. The input event is stored in the urbit's event history.

31−

32−Events always start from outside of your urbit, whether they're local to the computer running the urbit (e.g., a keystroke in the terminal) or they originate elsewhere (e.g., a packet received from another urbit). When an event is processed, various parts of the urbit state can be modified before the resulting list of output actions is returned.

33−

34−Can output actions from your urbit cause side-effects in the outside world? The answer had better be "yes," because a personal server without side effects isn't useful for much. In another sense the answer had better be "no," or else there is a risk of losing functional purity; your urbit cannot _guarantee_ that the side effects in question actually occur. What's the solution?

35−

36−Each urbit is [sandboxed](https://en.wikipedia.org/wiki/Sandbox_(computer_security)) in a virtual machine, Vere, which runs on Unix. Code running in your urbit cannot make Unix system calls or otherwise directly affect the underlying platform. Strictly speaking, internal urbit code can only change internal urbit state; it has no way of sending events outside of its runtime environment. Functional purity is preserved.

37−

38−In practical terms, however, you don't want your urbit to be an impotent [brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why Vere also serves as the intermediary between your urbit and Unix. Vere observes the list of output events, and when external action is called for makes the appropriate system calls itself. When external events relevant to your urbit occur in the Unix layer, Vere encodes and delivers them as input events.

42+For example, one input event could be a keystroke from the terminal, say

43+`[enter]` after having already typed `(add 2 2)`; and an output action could be

44+to print in the terminal window the resulting value of a computation performed

45+when the user hit `[enter]`, in this case `4`. The input event is stored in the

46+urbit's event history.

47+

48+Events always start from outside of your urbit, whether they're local to the

49+computer running the urbit (e.g., a keystroke in the terminal) or they originate

50+elsewhere (e.g., a packet received from another urbit). When an event is

51+processed, various parts of the urbit state can be modified before the resulting

52+list of output actions is returned.

53+

54+Can output actions from your urbit cause side-effects in the outside world?

55+The answer had better be "yes," because a personal server without side effects

56+isn't useful for much. In another sense the answer had better be "no," or else

57+there is a risk of losing functional purity; your urbit cannot _guarantee_ that

58+the side effects in question actually occur. What's the solution?

59+

60+Each urbit is

61+[sandboxed](https://en.wikipedia.org/wiki/Sandbox_(computer_security)) in a

62+virtual machine, Vere, which runs on Unix. Code running in your urbit cannot

63+make Unix system calls or otherwise directly affect the underlying platform.

64+Strictly speaking, internal urbit code can only change internal urbit state; it

65+has no way of sending events outside of its runtime environment. Functional

66+purity is preserved.

67+

68+In practical terms, however, you don't want your urbit to be an impotent

69+[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why

70+Vere also serves as the intermediary between your urbit and Unix. Vere observes

71+the list of output events, and when external action is called for makes the

72+appropriate system calls itself. When external events relevant to your urbit

73+occur in the Unix layer, Vere encodes and delivers them as input events.

3974

4075### Arvo

4176

42−Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking) OS, written in Hoon, that serves as the event manager of your urbit. It can upgrade itself from over the network without downtime. The Arvo kernel proper is quite simple -- it's only about 600 lines of code, excluding its various modules.

77+Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking)

78+OS, written in Hoon, that serves as the event manager of your urbit.

79+It can upgrade itself from over the network without downtime. The Arvo kernel

80+proper is quite simple -- it's only about 600 lines of code, excluding its

81+various modules.

4382

44−The Urbit transition function is implemented in Arvo. Upon being 'poked' by Vere with the pair of `<input event, state>`, Arvo directs the event to the appropriate OS module. The result of each Vere 'poke' is a pair of `<output events, new state>`. Events are typed, and each has an explicit call-stack structure indicating the event's source module in Arvo.

83+The Urbit transition function is implemented in Arvo. Upon being 'poked' by

84+Vere with the pair of `<input event, state>`, Arvo directs the event to the

85+appropriate OS module. The result of each Vere 'poke' is a pair of

86+`<output events, new state>`. Events are typed, and each has an explicit

87+call-stack structure indicating the event's source module in Arvo.

4588

4689Arvo modules are also called 'vanes'. Arvo's vanes are:

4790

48−- Ames: defines and implements Urbit's encrypted P2P network protocol, as well as Urbit's identity protocol.

91+- Ames: defines and implements Urbit's encrypted P2P network protocol, as well

92+ as Urbit's identity protocol.

4993- Behn: manages timer events for other vanes.

5094- Clay: global, version-controlled, and referentially-transparent file system.

5195- Dill: terminal driver.

@@ -57,24 +101,56 @@ Arvo modules are also called 'vanes'. Arvo's vanes are:

57101

58102### Hoon

59103

60−Hoon is a strictly typed functional programming language that compiles itself to Nock and is designed to support higher-order functional programming without requiring knowledge of category theory or other advanced mathematics. Haskell is fun but it isn't for everybody.

104+Hoon is a strictly typed functional programming language that compiles itself

105+to Nock and is designed to support higher-order functional programming without

106+requiring knowledge of category theory or other advanced mathematics. Haskell

107+is fun but it isn't for everybody.

61108

62−Hoon aspires to a concrete, imperative feel. To discourage the creation of write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead of keywords. The type system infers only forward and does not use unification, but is not much weaker than Haskell's. The compiler and inference engine is about 3000 lines of Hoon.

109+Hoon aspires to a concrete, imperative feel. To discourage the creation of

110+write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead

111+of keywords. The type system infers only forward and does not use unification,

112+but is not much weaker than Haskell's. The compiler and inference engine is

113+about 3000 lines of Hoon.

63114

64115### Nock

65116

66−Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity) combinator language. It's so simple that its [specification](../../nock/definition) fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions are more narrow. Most Lisps are one-layer: a practical language is to be created by extending a theoretically simple interpreter. The abstraction is simple and the implementation is practical. Unfortunately it's far more difficult to enforce both simplicity and practicality in an actual Lisp codebase. Hoon and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it can upgrade Hoon over the network without downtime.

67−

68−The Nock data model is quite simple. Every piece of data is a 'noun'. A noun is an atom or a cell. An atom is any unsigned integer. A cell is an ordered pair of nouns. Nouns are acyclic and expose no pointer equality test.

117+Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)

118+combinator language. It's so simple that its [specification](../../nock/definition)

119+fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions

120+are more narrow. Most Lisps are one-layer: a practical language is to be

121+created by extending a theoretically simple interpreter. The abstraction is

122+simple and the implementation is practical. Unfortunately it's far more difficult

123+to enforce both simplicity and practicality in an actual Lisp codebase. Hoon

124+and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the

125+simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it

126+can upgrade Hoon over the network without downtime.

127+

128+The Nock data model is quite simple. Every piece of data is a 'noun'. A noun

129+is an atom or a cell. An atom is any unsigned integer. A cell is an ordered

130+pair of nouns. Nouns are acyclic and expose no pointer equality test.

69131

70132### Vere

71133

72−Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on Unix, and is the intermediate layer between your urbit and Unix. As noted earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode and deliver relevant external events to Arvo. Vere is also responsible for implementing jets and maintaining the persistent state of each urbit.

73−

74−In principle, Vere keeps a comprehensive log of every event from the time you initially booted your urbit. What happens if the physical machine loses power and your urbit's state is 'lost' from memory? When your urbit restarts it will replay its entire event history and totally recover its latest state from scratch.

75−

76−In practice, event logs become large and unwieldy over time. Periodically a snapshot of the permanent state is taken and the logs are pruned. You're still able to rebuild your state in case of power outage, down to the last keystroke.

77−

78−Vere is not essential to the Urbit stack; one can imagine using Urbit on a hypervisor, or even bare metal. One member of the community is even working on an independent implementation of Urbit using Graal/Truffle on the JVM.

79−

80−The Urbit stack (compiler, standard library, kernel, modules, and applications, but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT licensed.

134+Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on

135+Unix, and is the intermediate layer between your urbit and Unix. As noted

136+earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode

137+and deliver relevant external events to Arvo. Vere is also responsible for

138+implementing jets and maintaining the persistent state of each urbit.

139+

140+In principle, Vere keeps a comprehensive log of every event from the time you

141+initially booted your urbit. What happens if the physical machine loses power

142+and your urbit's state is 'lost' from memory? When your urbit restarts it will

143+replay its entire event history and totally recover its latest state from

144+scratch.

145+

146+In practice, event logs become large and unwieldy over time. Periodically a

147+snapshot of the permanent state is taken and the logs are pruned. You're still

148+able to rebuild your state in case of power outage, down to the last keystroke.

149+

150+Vere is not essential to the Urbit stack; one can imagine using Urbit on a

151+hypervisor, or even bare metal. One member of the community is even working on

152+an independent implementation of Urbit using Graal/Truffle on the JVM.

153+

154+The Urbit stack (compiler, standard library, kernel, modules, and applications,

155+but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT

156+licensed.

docs/reference/advanced.umd+7−7

@@ -186,15 +186,15 @@ of secret superpowers for hacking the namespace. Remember that

186186Hoon doesn't have anything like a symbol table; to resolve a

187187limb, we just search the type depth-first.

188188

189−If a name is in the `p.p` map, it's an alias. (An alias is defined using the `=*` rune.) The map contains a

190−`(unit hoon)`; if the unit is full, the name resolves to that

191−hoon (compiled against the `q` type). If the unit is empty,

192−the name is blocked / skipped (see [limb](../limb/) for what

189+If a name is in the `p.p` map, it's an alias. (An alias is defined using the

190+`=*` rune.) The map contains a `(unit hoon)`; if the unit is full, the name

191+resolves to that hoon (compiled against the `q` type). If the unit is empty,

192+the name is blocked / skipped (see [limb](../rune/limb/) for what

193193this means).

194194

195−If a name is in the `q.p` map, it's a bridge. (A bridge is defined using the `=,` rune.) When we search for

196−a name, we also compile the bridge, and check if the name

197−resolves against the bridge product. If so, we use it.

195+If a name is in the `q.p` map, it's a bridge. (A bridge is defined using the

196+`=,` rune.) When we search for a name, we also compile the bridge, and check

197+if the name resolves against the bridge product. If so, we use it.

198198

199199These hacks let us deal with interesting large-scale problems,

200200like complex library dependencies. You definitely don't need to

docs/reference/basic.umd+38−12

@@ -7,17 +7,32 @@

88# Basic types

10−A type is usually understood to be a set of values. Hoon values are all nouns, so a Hoon type is a set of nouns.

10+A type is usually understood to be a set of values. Hoon values are all nouns,

11+so a Hoon type is a set of nouns.

1112

12−Hoon's type system conducts various type-checks at compile time in order to ensure type safety. For example, one's program might have an integer squaring function, such that given some atom `n` the return value is `n^2`. The output value should be an unsigned integer (i.e., an atom). Hoon uses type inference on the expression that defines the squaring function in to determine what possible values it could produce. If the inferred type 'nests' under the desired type then the program compiles; otherwise the compile fails with a `nest-fail` crash.

13+Hoon's type system conducts various type-checks at compile time in order to

14+ensure type safety. For example, one's program might have an integer squaring

15+function, such that given some atom `n` the return value is `n^2`. The output

16+value should be an unsigned integer (i.e., an atom). Hoon uses type inference

17+on the expression that defines the squaring function in to determine what

18+possible values it could produce. If the inferred type 'nests' under the

19+desired type then the program compiles; otherwise the compile fails with a

20+`nest-fail` crash.

1321

14−(For an introduction on how to use Hoon's type system, see Chapter 2 of the Hoon tutorial.)

22+(For an introduction on how to use Hoon's type system, see Chapter 2 of the Hoon

23+tutorial.)

1524

16−In this document we discuss the recursive data structure Hoon uses for type inference. Because the Hoon compiler is written in Hoon this structure is likewise defined in Hoon.

25+In this document we discuss the recursive data structure Hoon uses for type

26+inference. Because the Hoon compiler is written in Hoon this structure is

27+likewise defined in Hoon.

1728

1829## `$type`

1930

20−Below is a simplified version the `+$ type` arm, which defines the data structure Hoon uses to keep track of types. But this data structure is used for more than simply type inference. It also handles the resolution of names, including both faces and arm names. (See Chapter 1 of the Hoon tutorial for an introduction to name resolution.)

31+Below is a simplified version the `+$ type` arm, which defines the data

32+structure Hoon uses to keep track of types. But this data structure is used for

33+more than simply type inference. It also handles the resolution of names,

34+including both faces and arm names. (See Chapter 1 of the Hoon tutorial for an

35+introduction to name resolution.)

2136

2237As noted, this is a simplified version of `type`. We undo and

2338explain the simplifications in the [advanced types](../advanced)

@@ -38,31 +53,42 @@ section.

3853 ==

3954```

4055

41−Effectively this structure defines a set of nouns that Hoon uses to keep track track of (1) type information, and (2) name resolution information. This set of nouns is recursively defined.

56+Effectively this structure defines a set of nouns that Hoon uses to keep track

57+track of (1) type information, and (2) name resolution information. This set of

58+nouns is recursively defined.

4259

4360### `?(%noun %void)`

4461

45−`%noun` is the label for a noun about which nothing else is known. Every piece of Hoon data is a noun, so everything nests under `%noun`.

62+`%noun` is the label for a noun about which nothing else is known. Every piece

63+of Hoon data is a noun, so everything nests under `%noun`.

4664

4765`%void` is the label for the empty set.

4866

4967### `[%cell p=type q=type]`

5068

51−`[%cell p=type q=type]` is for cells. The `type` of the head is labelled `p` and the tail `type` is `q`.

69+`[%cell p=type q=type]` is for cells. The `type` of the head is labelled `p`

70+and the tail `type` is `q`.

5271

5372### `[%fork p=(set type)]`

5473

55−`[%fork p=(set type)]` is for the union of all types in the set `p`. That is, when the type of an expression is known to be a `%fork`, the expression must evaluate as one of the types in `p`.

74+`[%fork p=(set type)]` is for the union of all types in the set `p`. That is,

75+when the type of an expression is known to be a `%fork`, the expression must

76+evaluate as one of the types in `p`.

5677

57−Hoon uses branching (usually with conditional runes of the `?` family) for type inference in order to rule out which of the types in `p` can apply.

78+Hoon uses branching (usually with conditional runes of the `?` family) for type

79+inference in order to rule out which of the types in `p` can apply.

5880

5981### `[%hold p=type q=hoon]`

6082

61−A `%hold` type, with type `p` and hoon `q`, is a lazy reference to the type of `(mint p q)`. In English, it means: "the type of the product when we compile Hoon expression `q` against a subject with type `p`."

83+A `%hold` type, with type `p` and hoon `q`, is a lazy reference to the type of

84+`(mint p q)`. In English, it means: "the type of the product when we compile

85+Hoon expression `q` against a subject with type `p`."

6286

6387### `[%face p=term q=type]`

6488

65−A `[%face p=term q=type]` wraps the label `p` around the type `q`. `p` is a `term` or `@tas`, an atomic ASCII string which obeys symbol rules: lowercase and digit only, infix hyphen, first character must be a lowercase letter.

89+A `[%face p=term q=type]` wraps the label `p` around the type `q`. `p` is a

90+`term` or `@tas`, an atomic ASCII string which obeys symbol rules: lowercase and

91+digit only, infix hyphen, first character must be a lowercase letter.

6692

6793### `[%atom p=term q=(unit atom))]`

6894

docs/reference/cheat-sheet.umd+3−2

@@ -21,9 +21,10 @@ hand. So above is a download link to a Hoon cheatsheet .pdf. It's missing a

2121few of the literal syntaxes, but it covers the most common ones.

2222

2323This doesn't list any of the Ford runes, although there is now at least

24−some documentation for those [here](/docs/arvo/internals/ford/runes).

24+some documentation for those [here](../../tutorials/internals/ford/runes).

2525

26−The following runes also exist, but are currently undocumented and not listed in the cheat sheet:

26+The following runes also exist, but are currently undocumented and not listed in

27+the cheat sheet:

2728

2829```

2930!: :: turn on debugging printfs

docs/reference/glossary.umd+28−29

@@ -47,7 +47,7 @@ dry.

4747 path, which works as if we expanded the callee with the caller's

4848 context.

4949

50−_See [advanced types](../../hoon/advanced/)_.

50+_See [advanced types](../advanced/)_.

5151

5252

5353;h3

@@ -73,7 +73,7 @@ their effects happen like so:

7373Arvo is located in `/home/sys/arvo.hoon` within your urbit.

7474

7575More in-depth information on Arvo can be found

76−[`here`](https://urbit.org/docs/arvo/internals/).

76+[`here`](../../tutorials/internals).

7777

7878Below are Arvo modules, which are called "vanes".

7979

@@ -86,7 +86,7 @@ Below are Arvo modules, which are called "vanes".

8686 Ames is located in `/home/sys/vane/ames.hoon` within your urbit.

8787

8888 More in-depth information on Ames can be found

89− [`here`](https://urbit.org/docs/arvo/internals/ames/commentary/).

89+ [`here`](../../tutorials/internals/ames/commentary).

9090

9191- ##### Behn

9292

@@ -112,7 +112,7 @@ Below are Arvo modules, which are called "vanes".

112112 Basic information on using Clay can be found

113113 [`here`](https://urbit.org/docs/using/filesystem/). An in-depth explanation

114114 of the architecture can be found

115− [`here`](https://urbit.org/docs/arvo/internals/clay/architecture/).

115+ [`here`](../../tutorials/internals/clay/commentary).

116116

117117- ##### Dill

118118

@@ -130,8 +130,8 @@ Below are Arvo modules, which are called "vanes".

130130

131131 Dill is located at `/home/sys/vane/clay.hoon` within your urbit.

132132

133− More in-depth information on Eyre can be found

134− [`here`](https://urbit.org/docs/arvo/internals/dill/).

133+ More in-depth information on Dill can be found

134+ [`here`](../../tutorials/internals/dill).

135135

136136- ##### Eyre

137137

@@ -160,7 +160,7 @@ Below are Arvo modules, which are called "vanes".

160160 Ford is located at `/home/sys/vane/ford.hoon` within your urbit.

161161

162162 More in-depth information on Ford can be found

163− [`here`](https://urbit.org/docs/arvo/internals/ford/).

163+ [`here`](../../tutorials/internals/ford).

164164

165165- ##### Gall

166166

@@ -176,7 +176,7 @@ Below are Arvo modules, which are called "vanes".

176176 Gall is located at `/home/sys/vane/gall.hoon` within your urbit.

177177

178178 More in-depth information on Ford can be found

179− [`here`](https://urbit.org/docs/arvo/internals/gall/).

179+ [`here`](../tutorials/internals/gall/).

180180

181181### atom

182182

@@ -195,13 +195,13 @@ An atom type is _warm_ or _cold_ based on whether the constant exists.

195195

196196 If the constant is `[~ atom]`, its only legal value is `atom`.

197197

198−_See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)_

198+_See [basic types](../basic)_

199199

200200;h3

201201 ;div(id "aura"): aura

202202==

203203

204−An aura a soft atom type. They appear as strings beginning with `@`. Auras

204+An aura is a soft atom type. They appear as strings beginning with `@`. Auras

205205represent the structure of an atom, print format, or other semantics. Its

206206constraints on the value of an atom aren't enforced in any way.

207207

@@ -253,7 +253,7 @@ Aura Meaning Example Literal Syntax

253253 @ux unsigned hexadecimal 0x5f5.e138

254254```

255255

256−You can find the list of all auras [here](../../hoon/atom/sand/).

256+You can find the list of all auras [here](../rune/constants/warm).

257257

258258### blocksize

259259

@@ -360,7 +360,7 @@ In the above example, `a` is the face and `2` is the value.

360360Hoon has no scope or symbol-table; there is only the subject. To "declare" a

361361"variable" is to construct a new subject: `[name=value old-subject]`.

362362

363−_See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)_.

363+_See [advanced types](../advanced)_.

364364

365365

366366### flag

@@ -377,7 +377,7 @@ keeps you on your toes. And it's also just intuitively right.

377377

378378A _gate_ is a [core](#core) with one [arm](#arm) -- Hoon's closest

379379analog to a function. To call a gate on an argument, replace the sample

380−(at [tree address](../../hoon/limb/limb/) `+6`

380+(at [tree address](../rune/limb/limb) `+6`

381381in the core) with the argument, and then compute the arm.

382382

383383The payload of a gate has a shape of `[sample context]`.

@@ -390,8 +390,8 @@ The payload of a gate has a shape of `[sample context]`.

390390

391391 The subject in which the gate was defined.

392392

393−_See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),

394−[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the

393+_See [basic types](../basic/),

394+[`%-` ("cenhep")](../rune/cen/hep/) (the

395395[rune](#rune) for calling a `gate`)._

396396

397397### generator

@@ -412,7 +412,7 @@ information pipeline.

412412

413413Generators are run from the `/gen` directory of your current desk. For example,

414414to run a generator named `whatever.hoon`, you would type `> +whatever` in the

415−[Dojo](../dojo).

415+[Dojo](../../using/shell).

416416

417417### glyph

418418

@@ -518,8 +518,7 @@ The result should be:

518518[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]

519519```

520520

521−See [expression reference](../../hoon/reference/) for the

522−full of hoons.

521+See [expression reference](../rune/) for the full list of hoons.

523522

524523### irregular form

525524

@@ -592,7 +591,7 @@ found, the result is the product of the arm.

592591 a search path into the subject, composed of

593592 limbs. Search occurs from right to left (`a.b` means `b` within `a`).

594593

595−_See [Limbs and wings](../../hoon/limb/)_

594+_See [Limbs and wings](../rune/limb/)_

596595

597596

598597;h3

@@ -665,7 +664,7 @@ Urbit's low-level programming language. Nock is functional and typeless.

665664 a noun - the result of evaluating a formula against a subject.

666665 ==

667666

668−_See the [Nock definition](../../nock/definition/)._

667+_See the [Nock definition](../../tutorials/nock/definition)._

669668

670669

671670;h3

@@ -694,7 +693,7 @@ properties of the type of a compatible core). The default is `gold`

694693- `zinc`: _covariant_

695694- `iron`: _contravariant_

696695

697−_See [advanced types](../../hoon/advanced)_.

696+_See [advanced types](../advanced)_.

698697

699698### ship

700699

@@ -780,7 +779,7 @@ Here's some common structure terminology:

780779

781780- ##### icon: The type of the mold's range.

782781

783−_See [mold hoons](../../hoon/rune/buc/)._

782+_See [mold hoons](../rune/buc/)._

784783

785784;h3

786785 ;div(id "rune"): rune

@@ -789,10 +788,10 @@ _See [mold hoons](../../hoon/rune/buc/)._

789788A Hoon _rune_ is a pair of ASCII symbols used to begin a

790789[Hoon expression](#a-hoon).

791790

792−For example, the rune [`?:`](../../hoon/rune/wut/col/) is

791+For example, the rune [`?:`](../rune/wut/col/) is

793792Hoon's most common conditional, a branch on a boolean test. The first

794793symbol in a rune represents a family of related runes. For example, the

795−[`?` family](../../hoon/rune/wut/) are all conditionals.

794+[`?` family](../rune/wut/) are all conditionals.

796795

797796The result of parsing a Hoon source expression—the rune, followed

798797by its respective children—into an AST node is simply called

@@ -827,7 +826,7 @@ Runes have two syntactic forms, _tall_ and _flat_:

827826Tall hoons can contain flat hoons, but not vice versa. All irregular

828827forms are flat.

829828

830−_See [hoon concept](../../hoon/concepts/#-hoon),

829+_See [hoon concept](#a-hoon),

831830[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)_.

832831

833832### Sail

@@ -839,7 +838,7 @@ _Sail_ is the Hoon markup language for XML.

839838To _scry_ means to request data from the Arvo namespace and bring it

840839to userspace.

841840

842−_See [.^ (dot-ket)](../../hoon/rune/dot/ket/)._

841+_See [.^ (dot-ket)](../rune/dot/ket/)._

843842

844843### slot

845844

@@ -860,7 +859,7 @@ The head of `+n` is `+2n`, the tail is `+(2n+1)`.

860859_Talk_ is Urbit's built-in chat app. It’s one example of an app that can be

861860built on top of Hall, the Urbit back-end messaging system.

862861

863−_See [Messaging](../using/messaging). for more information._

862+_See [Messaging](../../using/messaging). for more information._

864863

865864### type

866865

@@ -882,8 +881,8 @@ of the simpler built-in types.

882881 If `nest` produces no, the Hoon programmer will receive a `nest-fail`

883882 error. This is one of the most commons errors in Hoon programming.

884883

885− _See [advanced types](../../hoon/advanced/)_.

886− _See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)_.

884+ _See [advanced types](../advanced/)_.

885+ _See [troubleshooting](../troubleshooting/#nest-fail)_.

887886

888887

889888### Unit

docs/reference/irregular.umd+6−6

@@ -38,13 +38,13 @@ I: `+(p)`

3838R: `.=(p q)`

3939I: `=(p q)`

4040

41−## ; sem (make)

41+## ; mic (make)

4242

4343Miscellaneous useful macros.

4444

45−### ;: semcol

45+### ;: miccol

4646

47−[docs](../rune/sem/col/) \\:

47+[docs](../rune/mic/col/) \\:

4848`[%smcl p=hoon q=(list hoon)]`: call a binary function as an n-ary function.

4949

5050R: `;:(p q)`

@@ -217,7 +217,7 @@ I: `p=q`

217217- `|` loobean false.

218218- `%a` constant `a`, where `a` can be an ((ir)regularly defined) atom or a symbol.

219219

220−See [%sand](../atom/sand/) for other irregular definitions of atoms.

220+See [%sand](../rune/constant/warm) for other irregular definitions of atoms.

221221

222222### List addressing

223223

@@ -226,7 +226,7 @@ See [%sand](../atom/sand/) for other irregular definitions of atoms.

226226

227227### Limbs

228228

229−[docs](../limb/limb/) \\+\\.\\^

229+[docs](../rune/limb/limb/) \\+\\.\\^

230230`[%limb p=(each @ud [p=@ud q=@tas])]`: attribute of subject.

231231

232232- `+15` is slot 15

@@ -249,7 +249,7 @@ See [%sand](../atom/sand/) for other irregular definitions of atoms.

249249

250250### Wings

251251

252−[docs](../limb/wing/)

252+[docs](../rune/limb/wing/)

253253`[%wing p=(list limb)]`; a limb search path.

254254`a.b` finds limb `a` within limb `b` ("var" `a` within "var" `b`).

255255

docs/reference/library/1b.umd−2

@@ -5,8 +5,6 @@

66;>

8−[create an anchor](#anchors-in-markdown)

9−

108# 1b: tree addressing

119

1210Check out the Nock [explanation](docs/nock/explanation/) for more

docs/reference/library/2a.umd+2−2

@@ -421,11 +421,11 @@ Either the unwrapped value of `a` (`u.a`), or crash.

421421

422422Wrap value in a unit

423423

424−Takes any atom `a` and produces a [`++unit`]() with the value set to `a`.

424+Takes any atom `a` and produces a `++unit` with the value set to `a`.

425425

426426#### Accepts

427427

428−`a` is a [noun]().

428+`a` is a noun.

429429

430430#### Produces

431431

docs/reference/library/4b.umd+1−1

@@ -189,7 +189,7 @@ XX document

189189

190190To lowercase

191191

192−Produce the case insensitive (all lowercase) [`++cord`]() of a [`++tape`]().

192+Produce the case insensitive (all lowercase) `++cord` of a `++tape`.

193193

194194#### Accepts

195195

docs/reference/library/4h.umd+2−2

@@ -74,7 +74,7 @@ Parses ASCII character 124, the vertical bar.

7474Parse backslash

7575

7676Parses ASCII character 92, the backslash. Note the extra `\` in the calling of

77−`bas` with [`++just`](/docs/hoon/library/2ec#++just) is to escape the escape

77+`bas` with [`++just`](../4f) is to escape the escape

7878character, `\`.

7979

8080#### Source

@@ -800,7 +800,7 @@ Parses ASCII character 126, the tilde.

800800Parse single quote

801801

802802Parses ASCII character 39, soq. Note the extra '' is to escape the first

803−`soq` because soq delimits a [`++cord`]().

803+`soq` because soq delimits a `++cord`.

804804

805805#### Source

806806

docs/reference/library/5f.umd+1−1

@@ -60,7 +60,7 @@ See also: `++sail` doc

6060

6161List of XML nodes

6262

63−A list of [`++manx`]().

63+A list of `++manx`.

6464

6565#### Source

6666

docs/reference/rune/bar.umd+3−1

@@ -7,7 +7,9 @@

88# Cores `|` "bar"

10−Core expressions produce cores. A core is a cell of `[battery payload]`. The `battery` is code, a battery of Nock formulas. The `payload` is the data needed to run those formulas correctly.

10+Core expressions produce cores. A core is a cell of `[battery payload]`.

11+The `battery` is code, a battery of Nock formulas. The `payload` is the data

12+needed to run those formulas correctly.

1113

1214Four core runes (`|=`, `|.`, `|-`, and `|*`) produce a

1315core with a single arm, named `$`. We can recompute this arm

docs/reference/rune/bar/hep.umd+2−2

@@ -26,8 +26,8 @@ point". Since `|-` makes a `|.` (["bardot"](../dot), a core

2626with one arm named `$`, we can recurse back into it with `$()`.

2727

2828> `$()` expands to `%=($)` (["centis"](../../cen/tis)),

29−> accepting a *jogging* body containing a list of changes to

30−> the subject.

29+ accepting a *jogging* body containing a list of changes to

30+ the subject.

3131

3232## Examples

3333

docs/reference/rune/bus.umd+6−1

@@ -7,7 +7,12 @@

88# Structures $ ("bus")

10−The `$` family of runes is used for defining custom types. Strictly speaking, these runes are used to produce 'structures'. A structure is a compile-time value that at runtime can be converted to either an example value (sometimes called a 'bunt' value) for its corresponding type, or to a 'factory' (sometimes called a 'mold'). An example value is used as a placeholder for sample values, among other things. A factory/mold is used as a data validator.

10+The `$` family of runes is used for defining custom types. Strictly speaking,

11+these runes are used to produce 'structures'. A structure is a compile-time

12+value that at runtime can be converted to either an example value (sometimes

13+called a 'bunt' value) for its corresponding type, or to a 'factory' (sometimes

14+called a 'mold'). An example value is used as a placeholder for sample values,

15+among other things. A factory/mold is used as a data validator.

1116

1217## Overview

1318

docs/reference/rune/constants/cold.umd+1−1

@@ -17,7 +17,7 @@ A cold (fixed) atom `q` with aura `p`.

1717

1818### Syntax

1919

20−Irregular: any warm atom [(`%sand`)](../sand/) form, prefixed with `%`.

20+Irregular: any warm atom [(`%sand`)](../warm/) form, prefixed with `%`.

2121

2222Irregular: e.g., `%hi`. Character constraints: `a-z`

2323lowercase to start, `a-z` or `0-9` thereafter, with infix

docs/reference/rune/limb.umd+7−2

@@ -7,8 +7,13 @@

88# Limbs and wings

10−One feature Hoon lacks: a context that isn't a first-class value. Hoon has no concept of scope, environment, etc. An expression has exactly one data source, the *subject*, a noun like any other.

10+One feature Hoon lacks: a context that isn't a first-class value. Hoon has no

11+concept of scope, environment, etc. An expression has exactly one data source,

12+the *subject*, a noun like any other.

1113

12−In Hoon we use 'wings' to extract information from the subject. A wing is a list of limbs (including a trivial list of one limb). A limb is used to resolve to a piece of data in the subject. A wing is thus a resolution path into the subject.

14+In Hoon we use 'wings' to extract information from the subject. A wing is a

15+list of limbs (including a trivial list of one limb). A limb is used to resolve

16+to a piece of data in the subject. A wing is thus a resolution path into the

17+subject.

1318

1419;list(datapreview "true", classname "runes");

docs/reference/rune/tis.umd+12−5

@@ -12,11 +12,18 @@ evaluate at least one of their subexpressions with a modified subject.)

1212

1313## Overview

1414

15−Hoon doesn't have variables in the ordinary sense. If you want to bind a name to a value, e.g., `a` to `12`, you do so by pinning `12` to the subject and associating the name with it. This sort of operation is done with the `=` family of runes.

16−

17−Let's say you have some old subject `p`. To 'pin' a value to the head means to modify the subject by repacing it with a cell of `[new-value p]`. The head of the cell is the new value. So to pin `12` with the face `a` the new subject would be: `[a=12 p]`.

18−

19−Of course there are many variations on ways to modify the subject, useful for different situations. Hence the whole family of `=` runes.

15+Hoon doesn't have variables in the ordinary sense. If you want to bind a name

16+to a value, e.g., `a` to `12`, you do so by pinning `12` to the subject and

17+associating the name with it. This sort of operation is done with the `=`

18+family of runes.

19+

20+Let's say you have some old subject `p`. To 'pin' a value to the head means to

21+modify the subject by repacing it with a cell of `[new-value p]`. The head of

22+the cell is the new value. So to pin `12` with the face `a` the new subject

23+would be: `[a=12 p]`.

24+

25+Of course there are many variations on ways to modify the subject, useful for

26+different situations. Hence the whole family of `=` runes.

2027

2128## Runes

2229

docs/reference/rune/wut.umd+5−1

@@ -7,7 +7,11 @@

88# Conditionals ? ("wut")

10−Hoon has the usual program control branches. It also has the usual logical operators: AND `?&`, OR `?|`, and NOT `?!`. It also has a `?=` rune that tests whether a value matches a given type. In the course of type inference, Hoon learns from `?=` tests in the test condition of [`?:` ("wutcol")](./col/) expressions.

10+Hoon has the usual program control branches. It also has the usual logical

11+operators: AND `?&`, OR `?|`, and NOT `?!`. It also has a `?=` rune that tests

12+whether a value matches a given type. In the course of type inference, Hoon

13+learns from `?=` tests in the test condition of [`?:` ("wutcol")](./col/)

14+expressions.

1115

1216## Overview

1317

docs/tutorials/gall.umd+4−1

@@ -9,6 +9,9 @@

1010This is documentation about how to write Gall apps. Some knowledge of Hoon is assumed.

1111

12−> Note: the last major revision of these lessons was in 2016. They need to be rewritten; in some ways they are outdated, and in other ways they were not always accessible enough to beginners. We are planning to rewrite these in the near future. In the meantime there is still useful information to be found.

12+> Note: the last major revision of these lessons was in 2016. They need to be

13+ rewritten; in some ways they are outdated, and in other ways they were not

14+ always accessible enough to beginners. We are planning to rewrite these in the

15+ near future. There is still useful information to be found in the meantime.

1316

1417;list;

docs/tutorials/hall.umd+2−1

@@ -8,7 +8,8 @@

99# Hall

1010

11−> Last major revision of this tutorial: 2017. Some of the information here may be outdated.

11+> Last major revision of this tutorial: 2017. Some of the information here may

12+ be outdated.

1213

1314Hall is the Urbit messaging and notifications protocol. Read up on Hall's

1415architecture, its interfaces and the new Gall model it's built to target.

docs/tutorials/urbitmarkdown.umd+13−2

@@ -16,7 +16,6 @@ allowing it to be used as standalone prose in its own file or embedded inside a

1616Hoon source file, in which case it will be parsed into a tree of HTML nodes

1717using Hoon's XML-templating syntax, Sail.

1818

19−

2019This document is itself written in Urbit Markdown, and its source file is of the

2120Urbit Markdown `.umd` extension. As such, we use some `formatted text` to make

2221it clear what is and isn't code, and to display that code to you instead of

@@ -28,6 +27,9 @@ existing knowledge of the latter. Urbit Markdown generally supports only one

2827syntax for each type of HTML node it emits. Urbit Markdown is also stricter than

2928Markdown: some syntax errors will prevent the file from being parsed at all.

3029

30+We provide a few simple examples [here](#examples) of how to publish

31+Urbit Markdown files using our web interface.

32+

3133

3234### Getting Started

3335

@@ -39,7 +41,8 @@ web-server, called [Eyre](https://urbit.org/docs/using/web/), that can be found

3941at `http://localhost:8080/` if it’s your first ship that’s running on the

4042machine, `http://localhost:8081/` if it’s the second ship on that same machine,

4143and so on. If you can't find your ship on one of these for some reason, try the

42−next one.

44+next one. When a ship starts, it will print a message like

45+`http: live (insecure, public) on 8081` to let you know what port it's using.

4346

4447That server has access to source files located in `/<your-urbit>/home/web` and

4548any sub-folders thereof (except for `/home/web/pages`, which has special

@@ -613,3 +616,11 @@ Produces:

613616 ;small: [reactive publishing intensifies]

614617 ==

615618==

619+;h2

620+ ;div(id "examples"): Examples

621+==

622+

623+We've created a few simple examples of how to get set up publishing content from

624+your Urbit. Feel free to ask questions in the comments.

625+

626+;list;

docs/using/web/blog.umd → docs/tutorials/urbitmarkdown/blog.umdrenamed+27−18

@@ -7,8 +7,9 @@

88# A simple blog

10−Publishing markdown using Urbit is really easy. Here we'll create a

11−very simple blog and publish our first posts.

10+[Urbit Markdown](../../tutorials/urbitmarkdown) is our markup language that

11+is able to run Hoon code. Publishing using Urbit Markdown is really easy. Here

12+we'll create a very simple blog and publish our first posts.

1213

1314First, let's setup a desk to serve our posts from:

1415

@@ -46,9 +47,12 @@ This is a simple blog I built on Urbit.

4647;list(dataType "post");

4748```

4849

49−Try viewing this file at `http://your-urbit.urbit.org/blog`. The only

50−special thing about this page is the `anchor/'none'` frontmatter which simply

51−turns off the Tree navigation. Normally Tree gives navigation

50+Try viewing this file at `http://localhost:8080`. Note that `8080` might be

51+`8081`, `8082`, and so on, depending if those ports were being used when you

52+started your urbit.

53+

54+The only special thing about this page is the `anchor/'none'` front-matter

55+which simply turns off the Tree navigation. Normally Tree gives navigation

5256controls for walking around the filesystem, but taking them away makes

5357the page seem more like a landing page.

5458

@@ -72,28 +76,33 @@ Is this a decentralized Medium? Let's find out.

7276But first, how about a long quote from Paramenides:

7377

7478> True, he said; and therefore when ideas are what they are in

75−relation to one another, their essence is determined by a relation

76−among themselves, and has nothing to do with the resemblances, or

77−whatever they are to be termed, which are in our sphere, and from

78−which we receive this or that name when we partake of them. And

79−the things which are within our sphere and have the same names

80−with them, are likewise only relative to one another, and not to

81−the ideas which have the same names with them, but belong to

82−themselves and not to them.

79+ relation to one another, their essence is determined by a relation

80+ among themselves, and has nothing to do with the resemblances, or

81+ whatever they are to be termed, which are in our sphere, and from

82+ which we receive this or that name when we partake of them. And

83+ the things which are within our sphere and have the same names

84+ with them, are likewise only relative to one another, and not to

85+ the ideas which have the same names with them, but belong to

86+ themselves and not to them.

8387

8488Good to get that out of the way.

8589```

8690

8791You should be able to view this file at:

88−`http://your-urbit.urbit.org/blog/post-1.umd`. You'll also notice that

89−now the list of posts here: `http://your-urbit.urbit.org/blog` has

92+`http://localhost:8080/blog/post-1.umd`.

93+

94+You'll also notice that

95+now the list of posts here: `http://localhost:8080/blog` has

9096updated.

9197

92−Here we use two pieces of frontmatter worth noting: `type` and `navhome`.

98+Here we use two pieces of front-matter worth noting: `type` and `navhome`.

9399

94−- `type` implies that the page has some special handling by Tree. When `type` is `post` we automatically put in the `date`, `title` and `author` when they're specified and add some styles.

100+- `type` implies that the page has some special handling by Tree. When `type` is

101+ `post` we automatically put in the `date`, `title` and `author` when they're

102+ specified and add some styles.

95103

96−- `navhome` sets the path used by the home button (the circle in the top left). Since we want to send people back to the root of our blog, we set this to `/blog`

104+- `navhome` sets the path used by the home button (the circle in the top left).

105+ Since we want to send people back to the root of our blog, we set this to `/blog`

97106

98107Adding posts is as easy as dropping markdown files into the `blog/`

99108directory. Pretty easy!

docs/using/web/comments.umd → docs/tutorials/urbitmarkdown/comments.umdrenamed+4−4

@@ -7,17 +7,17 @@

88# Blog comments

10−If you followed [our previous example](./blog) you should have a

10+If you followed [our previous example](../blog) you should have a

1111simple blog accessible at `your-urbit.urbit.org/blog`. Here we'll

1212enable comments on a post.

1313

14−First, turn comments on by editing the frontmatter in `post-1.umd`. Your frontmatter

15−should look like this:

14+First, turn comments on by editing the frontmatter in `post-1.umd`. Your

15+frontmatter should look like this:

1616

1717```

1818:- :~ navhome/'/blog'

1919 type/'post'

20− date/'~2016.6.20'

20+ date/'~2018.6.20'

2121 title/'Blog comments'

2222 comments/'true'

2323 ==

docs/using/web/static.umd → docs/tutorials/urbitmarkdown/static.umdrenamed+10−4

@@ -10,10 +10,14 @@ Hosting a static tree of content is easy. Let's put together a really

1010simple site for an imaginary Urbit meetup group.

1111

1212We assume you have at least followed the beginning of [our first

13−example](./blog) and created a desk called `site` and mounted it to

13+examples](/../blog) and created a desk called `site` and mounted it to

1414unix.

1515

16−Note: below we use Urbit's implementation of markdown, UMD. This version of markdown allows you to use snippets of Hoon code but not HTML. In particular, we use Sail, a subset of Hoon. This Sail is rendered as HTML when the file is served to a client. To learn about UMD and Sail, head over to the Tutorial section of the docs.

16+Note: below we use Urbit's implementation of Markdown, Urbit Markdown (UMD).

17+This version of markdown allows you to use snippets of Hoon code but not HTML.

18+In particular, we use Sail, a subset of Hoon. This Sail is rendered as HTML

19+when the file is served to a client. To learn about UMD and Sail, head over to

20+the Tutorial section of the docs.

1721

1822In `site/web/meet.umd` put:

1923

@@ -60,7 +64,9 @@ Then put the following in `site/web/about.umd`:

6064

6165## Mission statement

6266

63−The existing framework cannot subdue the new human force that is increasing day by day alongside the irresistible development of technology and the dissatisfaction of its possible uses in our senseless social life.

67+The existing framework cannot subdue the new human force that is increasing day

68+by day alongside the irresistible development of technology and the

69+dissatisfaction of its possible uses in our senseless social life.

6470

6571## Members

6672

@@ -133,5 +139,5 @@ Discussion on getting urbit to power Kaneda's motorcycle.

133139Here we just use the `comments` frontmatter to enable comments on the page.

134140Adding other imaginary projects is left to the reader.

135141

136−Building a static site takes only a few minutes and a few markdown

142+Building a static site takes only a few minutes and a few Urbit Markdown

137143files. Have fun!

docs/using.umd+2−1

@@ -7,6 +7,7 @@

88# Using

10−These short guides will get you installed, setup, and will walk you through the basic features of Urbit.

10+These short guides will get you installed, setup, and will walk you through the

11+basic features of Urbit.

1112

1213;list;

docs/using/admin.umd+55−22

@@ -8,12 +8,14 @@

99# Admin and operation

1010

11−Your Urbit is a persistent Unix process that you mainly control from the

12−console. For some things, a browser will also work.

11+Your urbit (also called your _ship_) is a persistent Unix process that you

12+mainly control from the console. For some things, a browser will also work.

1313

1414## Shutdown

1515

16−You can turn your Urbit off with `Ctrl-d` from the Talk or Dojo prompts.

16+You can turn your urbit off with `Ctrl-d` from the Talk or Dojo prompts.

17+

18+You can force-quit your urbit with `Ctrl-z` from anywhere.

1719

1820## Restart

1921

@@ -39,14 +41,13 @@ $ script urbit.log urbit your-urbit

3941

4042## Moving your pier

4143

42−Piers are designed to be portable, but it _must_ be done while the Urbit

44+Piers are designed to be portable, but it _must_ be done while the urbit

4345is turned off. Urbit networking is stateful, so you can't run two copies

4446of the same Urbit in two places.

4547

4648To move a pier, simply move the contents of the directory it lives in.

4749To keep these files as small as possible we usually use the `--sparse`

48−option in `tar`. With a pier `your-urbit/` something like this (from

49−inside `urbit/`) should work:

50+option in `tar`. With a pier `your-urbit/`, something like this should work:

5051

5152```

5253tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/

@@ -80,9 +81,12 @@ with ')', the Dojo rejects it.

8081

8182`Ctrl-x` - Switches the prompt between running console apps

8283

83−`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack trace.

84+`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack

85+trace.

86+

87+`Ctrl-d` - From Talk or Dojo, stops your Urbit process.

8488

85−`Ctrl-d` - From Talk or Dojo stops your Urbit process.

89+`Ctrl-z` - Stops the Urbit process from _anywhere_.

8690

8791`↑` / `↓` - History navigation

8892

@@ -109,14 +113,15 @@ Full coverage of the Urbit shell, the Dojo is covered in the

109113

110114## Web

111115

112−On startup Urbit tries to bind to `localhost:8080`. If you're already

113−running something on `8080` you'll find your Urbit on `8081`, and so on.

114−For planets only, we also proxy web domains through Urbit's own servers.

115−Any planet `~your-urbit` is also at `your-urbit.urbit.org`.

116+On startup Urbit tries to bind to `localhost:8080`. If you're already

117+running something on `8080` -- such as another urbit -- you'll find the urbit

118+that you just started on `8081`, and so on. For planets only, we also proxy web

119+domains through Urbit's own servers. Any planet `~your-urbit` is also at

120+`your-urbit.urbit.org`.

116121

117122Your Urbit serves a simple homepage from `http://localhost:8080` or

118123`https://your-urbit.urbit.org` that should be self-explanatory. Since

119−our HTTPS isn't audited / battle tested we just call it "secure" HTTPS.

124+our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.

120125You can find that on `8443`. Or `8444` (and so on) if you're already

121126running something on `8443`.

122127

@@ -125,7 +130,11 @@ A complete walkthrough of the Urbit web interface is

125130

126131## Moons

127132

128−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.

133+Urbit namespace is distributed by having parent nodes sign the keys for child

134+nodes. If you have a planet, your parent star issued your ticket. As a planet

135+you, in turn, can sign the keys for moons. The basic idea is: your planet runs

136+permanently in a data center somewhere and moons run on all your devices. Each

137+planet can issue ~4 billion (`2^32`) moons.

129138

130139To generate a random moon from your planet run:

131140

@@ -133,14 +142,33 @@ To generate a random moon from your planet run:

133142~your-urbit:dojo> +moon

134143```

135144

136−You can use the resulting output in the same installation flow from [install](/docs/using/install) and [setup](/docs/using/setup).

145+You can use the resulting output in the same installation flow from

146+[install](/../install) and [setup](/../setup), following the same scheme as

147+for booting a planet. That scheme is:

148+

149+```

150+$ urbit -w <moonname> -t <ticket> -c <piername>

151+```

152+

153+The `-c <piername>` argument is not required, but it is recommended; otherwise,

154+the resulting directory is a rather unwieldy moon name.

155+

156+Here's how an example moon might be booted:

157+

158+```

159+$ urbit -w faswep-navred-sampel-palnet -t habref-mebsem-harrut-batlus -c mymoon

160+```

161+

137162

138−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.

163+Moons are automatically synced to their parent `%kids` desk, and can control

164+applications on their parent planet using `|link`. You can read more about

165+those things in the [filesystem](/../filesystem) and [console](/../shell)

166+walkthroughs.

139167

140168

141169## Continuity breaches

142170

143−While the Urbit network is in this alpha state we sometimes have to

171+While the Urbit network is in this alpha state, we sometimes have to

144172reboot the whole network. This happens either when major changes need

145173to be shipped or we hit a bug that can't be fixed over the air.

146174

@@ -154,14 +182,19 @@ Urbit and recreate it (as if you were starting for the first time).

154182

155183## Creating SSL certificates

156184

157−It is possible to create SSL certificates so that you serve files through your ship's webserver using https.

158−To do that you, would need a machine that has OpenSSL installed.

159−In order to create a new private key and a self-signed certificate for your localhost, valid for a year, you can issue the following commands:

185+It is possible to create SSL certificates so that you serve files through your

186+ship's webserver using https. To do that you, would need a machine that has

187+OpenSSL installed. In order to create a new private key and a self-signed

188+certificate for your localhost, valid for a year, you can issue the following

189+commands:

160190

161191```

162192$ openssl req -x509 -sha256 -newkey rsa:4096 -keyout private.pem -out certificate.pem -subj '/CN=localhost' -days 365

163193$ mkdir -p your-urbit/.urb/tls

164194$ mv private.pem certificate.pem your-urbit/.urb/tls

165195```

166−These certificates would have to be manually trusted by your browser, and it's advisable that they are used only for your localhost.

167−For public-facing webservers, it would be better to create certificates for your fully qualified domain name using a trusted certificate authority like Let's Encrypt.

196+These certificates would have to be manually trusted by your browser, and it's

197+advisable that they are used only for your localhost.

198+For public-facing webservers, it would be better to create certificates for your

199+fully qualified domain name using a trusted certificate authority like Let's

200+Encrypt.

docs/using/filesystem.umd+77−13

@@ -9,26 +9,55 @@

99# Filesystem (Clay)

1010

1111

12−Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global, referentially transparent namespace. An easy way to think about it is like typed `git` with continuous sync.

12+Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,

13+referentially transparent namespace. An easy way to think about it is like typed

14+`git` with continuous sync.

1315

14−The most common way to use Clay is to mount a Clay node in a Unix directory. The Urbit process will watch this directory and automatically record edits as changes, Dropbox style. The mounted directory is always at the root of your pier directory.

16+The most common way to use Clay is to mount a Clay node in a Unix directory. The

17+Urbit process will watch this directory and automatically record edits as

18+changes, Dropbox style. The mounted directory is always at the root of your

19+pier directory.

1520

1621

1722## Quickstart

1823

19−When developing it's a good idea to use a separate desk. Create a `%sandbox` desk based on the `%home` desk:

24+When developing it's a good idea to use a separate desk. Create a `%sandbox`

25+desk based on the `%home` desk:

2026

2127```

2228|merge %sandbox ~your-urbit %home

2329```

2430

25−Most of the time we want to use Clay from Unix. Mount the entire contents of your `sandbox` desk to Unix:

31+Running `our` produces your ship-name, meaning that you can run the following

32+command instead of typing out your entire. Useful for comets, due to their very

33+long names!

34+

35+```

36+|merge %sandbox our %home

37+```

38+

39+Most of the time we want to use Clay from Unix. Mount the entire contents of

40+your `sandbox` desk to Unix:

2641

2742```

2843~your-urbit:dojo> |mount /=sandbox=

2944```

3045

31−To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:

46+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`

47+displays files in the current directory, and `+cat` displays the contents of

48+a file.

49+

50+We can use `%` to mean "current directory." The result of the command below

51+is just like using `ls` in a Unix terminal.

52+

53+```

54+~your-urbit:dojo> +ls %

55+```

56+

57+Notice how `+cat %` does the same thing. That's because everything in Clay,

58+including directories, is a file.

59+

60+Let's explore the `/web` directory of the `%sandbox` desk.

3261

3362```

3463~your-urbit:dojo> +ls /=sandbox=/web

@@ -40,6 +69,19 @@ Let's see the contents of `/=sandbox=/web/md`:

4069~your-urbit:dojo> +cat /=sandbox=/web/md

4170```

4271

72+Now let's navigate to that folder using `=dir`, which is a like `cd` in unix.

73+

74+```

75+~your-urbit:dojo> =dir /=sandbox=/web/md

76+```

77+

78+Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To

79+change back to our home directory:

80+

81+```

82+~your-urbit:dojo> =dir

83+```

84+

4385Sync from your friend `~some-ship`'s `%experiment` desk to your

4486`%sandbox` desk:

4587

@@ -51,22 +93,22 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your

5193

5294### Paths

5395

54−A path in Clay is a list of URL-safe text, restricted to

55−`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`

96+A path in Clay is a list of URL-safe text, restricted to the characters

97+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`

5698where each segment is a `@ta`.

5799

58100Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.

59101The first three segments of an urbit path are `/plot/desk/case`, for

60102example `/~dozbud/home/1`.

61103

62−#### Relative paths

104+##### Relative paths

63105

64−Relative paths are expressed using `%` which is roughly equivalent to

106+Relative paths are expressed using `%`, which is roughly equivalent to

65107Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.

66108There are no local relative paths. `foo/bar` must be written

67109`%/foo/bar`.

68110

69−#### Substitution

111+##### Substitution

70112

71113If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and

72114`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or

@@ -77,12 +119,34 @@ number in the `dojo`. Instead of writing

77119`/~your-urbit/home/4/path/to/file` you can just write

78120`/=home=/path/to/file`.

79121

80−### Revision-control

122+##### Changing directories

123+

124+Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.

125+

126+For example, the syntax to navigate to `/home/gen/ask` is:

127+

128+```

129+~your-urbit:dojo> =dir /=gen=/ask

130+```

131+

132+This command will turn your prompt into something like this:

81133

82134```

83−|mount clay-path [unix-name]

135+~your-urbit:dojo/gen/ask>

84136```

85137

138+Using `=dir` without anything else uses the null path, which

139+returns you to your home desk.

140+

141+```

142+~your-urbit:dojo> =dir

143+```

144+

145+

146+### Revision-control

147+

148+Syntax: `|mount /clay/path [unix-name]`

149+

86150Mount the `clay-path` at the unix mount point `unix-name`.

87151

88152*Examples:*

@@ -190,7 +254,7 @@ Example:

190254

191255`%init` - Used if it's the first commit to a desk. Also can be used to

192256"reinitialize" a desk -- revision numbers keep going up, but the new

193−revision isn't necessarily a descendent of the previously-numbered

257+revision isn't necessarily a descendent of the previously numbered

194258version, allowing merges to be rerun.

195259

196260`%this` - Keep what's in Bob's desk, but join the ancestry.

docs/using/install.umd+12−7

@@ -20,9 +20,9 @@ forum: [fora.urbit.org](https://fora.urbit.org). You can also chat

2020with us at [urbit.org/stream](https://urbit.org/stream).

2121

2222> Urbit is alpha software. It’s not yet completely stable, its crypto

23−> hasn’t been audited, and there are plenty of rough edges. Urbit is

24−> lots of fun to play with, but not quite ready for your important or

25−> sensitive data.

23+ hasn’t been audited, and there are plenty of rough edges. Urbit is

24+ lots of fun to play with, but not quite ready for your important or

25+ sensitive data.

2626

2727## Build from source

2828

@@ -53,13 +53,18 @@ re2c

5353

5454### Instructions

5555

56−First, you'll install the required dependencies to build Urbit from source. Then, you'll clone the Urbit source code, hosted on Github. Next, you'll bootstrap the Git submodules needed for the build. Lastly, you'll run a [Meson](https://github.com/mesonbuild/meson) build on the Urbit source to create your Urbit binary for your host operating system. Then, finally, you'll be able to boot your urbit.

56+First, you'll install the required dependencies to build Urbit from source.

57+Then, you'll clone the Urbit source code, hosted on Github. Next, you'll

58+bootstrap the Git submodules needed for the build. Lastly, you'll run a

59+[Meson](https://github.com/mesonbuild/meson) build on the Urbit source to create

60+your Urbit binary for your host operating system. Then, finally, you'll be able

61+to boot your urbit.

5762

5863For your host OS platform and relevant package installer, run the respective Bash shell commands listed below in a fresh terminal window to get Urbit installed:

5964

6065> For those new to the command line, see:

61−> - Mac: [Introduction to the Mac OS X Command Line](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)

62−> - Linux: [An Introduction to the Linux Terminal](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal)

66+ - Mac: [Introduction to the Mac OS X Command Line](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)

67+ - Linux: [An Introduction to the Linux Terminal](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal)

6368

6469#### macOS

6570

@@ -318,7 +323,7 @@ After running your installed `urbit` command, check to see if the following outp

318323$ urbit

319324Urbit: a personal server operating function

320325https://urbit.org

321−Version 0.5.1

326+Version 0.6.0

322327

323328Usage: urbit [options...] ship_name

324329where ship_name is a @p phonetic representation of an urbit address

docs/using/layout.umd+61−24

@@ -8,14 +8,14 @@

99# Arvo source

1010

11−When you boot an Urbit we transfer the current version of the Arvo

11+When you boot an Urbit, we transfer the current version of the Arvo

1212operating environment to your Urbit over our network. That is, the

1313source for the system lives on your Urbit. Here we'll take a brief tour

1414through the structure of a base Arvo desk.

1515

1616Looking at the top level of

1717[the Arvo repo](http://github.com/urbit/arvo), or any Urbit desk that

18−has been mounted to Unix we see something like:

18+has been mounted to unix, we see something like:

1919

2020```

2121app/

@@ -27,93 +27,111 @@ ren/

2727sec/

2828sur/

2929sys/

30+tests/

3031web/

3132web.md

3233```

3334

34−Let's step through directory by directory.

35+Running the command `+ls %` from your urbit's Dojo produces something similar:

36+

37+```

38+~your-urbit:dojo> +ls %

39+LICENSE/txt app/ gen/ lib/ mar/ ren/ sec/com/ sur/ sys/ tests/ web/

40+```

41+

42+Let's step through, directory by directory.

3543

3644## `sys/`

3745

3846This is where the Arvo kernel lives. `sys/` contains:

3947

40−### `sys/hoon.hoon`

48+##### `sys/hoon.hoon`

4149

42−Hoon is our programming langauge. Since Hoon compiles itself the

43−language is actually specified in this source file.

50+[Hoon](../../tutorials/hoon-ch1) is our programming language. Since Hoon

51+compiles itself, the language is actually specified in this source file.

4452

45−### `sys/zuse.hoon`

53+##### `sys/zuse.hoon`

4654

4755Zuse is the Arvo standard library.

4856

49−### `sys/arvo/hoon`

57+##### `sys/arvo/hoon`

5058

5159This is the source file for the central Arvo event dispatcher.

5260

53−### `sys/vane`

61+##### `sys/vane`

5462

5563Vanes are sort of like kernel modules. These are worth listing one by one:

5664

57−### `sys/vane/ames.hoon`

65+##### `sys/vane/ames.hoon`

5866

5967Ames is our network protocol.

6068

61−### `sys/vane/behn.hoon`

69+##### `sys/vane/behn.hoon`

6270

6371Behn is a simple timer.

6472

65−### `sys/vane/clay.hoon`

73+##### `sys/vane/clay.hoon`

6674

6775Clay is our filesystem.

6876

69−### `sys/vane/dill.hoon`

77+##### `sys/vane/dill.hoon`

7078

7179Dill is our terminal driver.

7280

73−### `sys/vane/eyre.hoon`

81+##### `sys/vane/eyre.hoon`

7482

7583Eyre is our webserver.

7684

77−### `sys/vane/ford.hoon`

85+##### `sys/vane/ford.hoon`

7886

7987Ford is our build system.

8088

81−### `sys/vane/gall.hoon`

89+##### `sys/vane/gall.hoon`

8290

8391Gall is our application model.

8492

85−### `sys/vane/jael.hoon`

93+##### `sys/vane/jael.hoon`

8694

8795Jael is our secret vault.

8896

89−### `sys/vane/xmas.hoon`

97+##### `sys/vane/xmas.hoon`

9098

9199Xmas is the new Ames, which will go live in our next big release.

92100

93101That's it. That's the whole system.

94102

103+---

104+

95105## `app/`

96106

97−This is where Gall apps live. Gall apps are stateful servers, sort of

98−like unix daemons. One familiar one is `app/hall.hoon` which is the

99−source code for Hall, the Urbit messaging transport layer. And there's

100−also `app/dojo.hoon` — that's your shell.

107+This is where [Gall](../../tutorials/gall) apps live. Gall apps are stateful

108+servers, sort of like unix daemons. One familiar one is `app/hall.hoon` which is

109+the source code for [Hall](../../tutorials/hall), the Urbit messaging transport

110+layer. And there's also `app/dojo.hoon` — that's your shell.

111+

112+---

101113

102114## `gen/`

103115

104116`gen/` holds generators. Generators are short Dojo scripts.

105117

118+---

119+

106120## `lib/`

107121

108122`lib/` holds shared libraries for programs. `lib/sole` is a good

109123example — that's the console library that's shared by both Dojo in the

110124command line, and the Dojo web client.

111125

126+---

127+

112128## `mar/`

113129

114130This is where marks live. Marks are data type definitions used by Ford.

115131A mark is like a mime-type, but specified in executable code.

116132

133+---

134+

117135## `ren/`

118136

119137These are web renderers. A renderer handles web requests of a particular

@@ -123,15 +141,34 @@ Default web requests in urbit are handled as a `.urb`, which is caught

123141by the `urb.hoon` renderer. This wraps the request in our default `CSS`

124142and `JS` and adds some routing magic for certain paths.

125143

144+---

145+

146+## `sec/`

147+

148+Here are security drivers that Urbit uses to log into the APIs of various

149+non-Urbit services.

150+

151+---

152+

126153## `sur/`

127154

128155`sur/` contains shared data structures. Files in `sur` are like header

129156files in C.

130157

158+---

159+

160+## `tests/`

161+

162+`tests/` contains code that tests them.

163+

164+---

165+

131166## `web/`

132167

133−There are the files publicly accessible to the web, as made possible by

134−Eyre.

168+Here are files publicly accessible to the web, as made possible by

169+[Eyre](../web).

170+

171+---

135172

136173## `web.md`

137174

docs/using/messaging.umd+274−98

@@ -8,10 +8,9 @@

99# Messaging (Talk and Hall)

1010

11−

1211Talk is the built-in frontend for the Urbit messaging and notifications

1312protocol, Hall. Today we use Hall to chat and coordinate, but it's really

14−a general purpose piece of infrastructure. Test.

13+a general purpose piece of infrastructure.

1514

1615For the time being come join us in `/urbit-meta` by using the

1716'quickstart' section below.

@@ -22,26 +21,34 @@ Any Urbit can host one.

2221

2322Hall is a general purpose tool for both aggregating and publishing

2423streams of messages. Applications can use Hall as their transport

25−protcol, API connectors can push disparate data sources into Hall,

24+protocol, API connectors can push disparate data sources into Hall,

2625and so on. There are lots of things a distributed message protocol can

2726be used for that we haven't even thought of.

2827

2928Here we'll be discussing how to operate the default CLI frontend, Talk,

3029to send and receive messages. For a more in-depth look at Hall's internals,

31−take a look at its [documentation](../../hall/architecture).

30+take a look at its [documentation](../../tutorials/hall).

3231

3332## Quickstart

3433

35−For the most part we use Talk as a single-instance of Slack: one main

34+The most common use of talk right now is as a single-instance of Slack: one main

3635channel (`/urbit-meta`) and direct messages. Everyone is more than welcome

3736in `/urbit-meta`. It's the place to get help, ask questions and chat about

3837Urbit in general.

3938

40−Let's join `/urbit-meta`:

39+There are two ways of using Talk: from the terminal running the Urbit process,

40+or through a web UI available at `http://localhost:8080/~~/talk`. This

41+quick-start guide will cover the first method.

42+

43+##### Joining a Channel

4144

42−Use `ctrl-x` to switch from Dojo to Talk.

45+In Hall, a medium for a message is called a _circle_. There are four types of

46+circles, but we for now we'll be dealing with the _channel_: a publicly

47+accessible chatroom for general use. We'll discuss the other three

48+kinds in the [manual](#manual) section.

4349

44−To join `/urbit-meta`:

50+Let's join the `/urbit-meta` channel. Use `ctrl-x` to switch from Dojo to Talk.

51+Then, :

4552

4653```

4754~your-urbit:talk> ;join /urbit-meta

@@ -55,23 +62,28 @@ You'll see something like:

5562--------------| bound '=' {[hos=~binzod nom=%urbit-meta]}

5663--------------| new = /urbit-meta

5764--------------| /urbit-meta: cap: For Urbit-related discussion. Politically

58− | correct and safe for work. Don't be rude!

65+ | correct and safe for work. Don't be rude.

5966--------------| /urbit-meta: fit: caps:n unic:n

6067~your-urbit:talk=

6168```

6269

70+Scrolling down your terminal window, you'll probably also see the playback of

71+previous `/urbit-meta` messages that you missed.

72+

6373Post a line to `/urbit-meta`:

6474

6575```

6676~your-urbit:talk= Hello, world!

6777```

6878

69−You'll see, echoed back at you:

79+You'll see your message printed below messages from others that came before it:

7080

7181```

7282~your-urbit= Hello, world!

7383```

7484

85+##### Direct Messaging

86+

7587To send a direct message to someone, first set your audience:

7688

7789```

@@ -117,10 +129,6 @@ Use `;leave` to unsubscribe from a channel:

117129~your-urbit:talk= ;leave /urbit-meta

118130```

119131

120−There are two ways of using Talk: from the CLI or through a web UI

121−available at `http://your-urbit.urbit.org/~~/talk` (or

122−`http://localhost:8080/~~/talk`).

123−

124132The web UI ships as compiled JavaScript on your Urbit, but has its own

125133source repo [here](https://github.com/urbit/talk).

126134

@@ -132,7 +140,9 @@ Last, let's create a channel we can invite some friends to:

132140

133141Now you can tell your friends to `;join ~your-urbit/my-channel`.

134142

135−## Manual

143+;h2

144+ ;div(id "manual"): Manual

145+==

136146

137147Hall's design is similar in spirit to

138148[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),

@@ -149,16 +159,15 @@ general use.

149159### Posts

150160

151161A post can be a variety of different data structures. Let's look at the

152−ones you can use from within Talk: lines, URLs, Hoon and

153−replies.

162+ones you can use from within Talk: lines, URLs, Hoon and replies.

154163

155−#### Lines

164+##### Lines

156165

157166A line is simply a string of text. Depending on the filtering rules set

158167by the circle's host, these may or may not include uppercase and Unicode

159168characters.

160169

161−If the line starts with `@`, it's an action (IRC `/me`).

170+If the line starts with `@`, it's an action (like `/me` in IRC).

162171

163172```

164173~your-urbit:talk= @sends a message.

@@ -170,7 +179,7 @@ will print as

170179~your-urbit sends a message.

171180```

172181

173−#### URLs

182+##### URLs

174183

175184A URL is any valid URL.

176185

@@ -178,7 +187,7 @@ A URL is any valid URL.

178187~your-urbit:talk= https://example.com/

179188```

180189

181−### Hoon

190+##### Hoon

182191

183192You can use Talk to evaluate Hoon code and share the result with everyone in a

184193Hall circle. To do so, preface your Hoon with `#`.

@@ -194,7 +203,7 @@ will print as

1942034

195204```

196205

197−### Replies

206+##### Replies

198207

199208To indicate what you're saying is in direct response to a specific

200209message, select the message (see Activating Lines below) and type your

@@ -246,7 +255,7 @@ in reply to: ~your-urbit:

246255That's my message!

247256```

248257

249−If information got truncated — like happens for long URLs or expressions —

258+If information got truncated — like what happens for long URLs or expressions,

250259or if there's additional information available — as is the case with

251260replies and attachments — activating the message will show you all the

252261details.

@@ -256,7 +265,13 @@ with `;;`, and so on.

256265

257266### Creating and managing circles

258267

259−###### `;create [type] %name 'description'`

268+As mentioned before, any urbit can host any number of circles. Existing circles

269+can be deleted or modified with various commands. All commands in this section

270+shoild be sent from the `talk>` prompt.

271+

272+###### Create

273+

274+Syntax: `;create [type] %name 'description'`

260275

261276Creates and joins a circle, where `[type]` is any of the following:

262277- `channel`: public circle. Has a blacklist for write control.

@@ -264,76 +279,173 @@ Creates and joins a circle, where `[type]` is any of the following:

264279- `journal`: publicly readable, invite-only for writing.

265280- `mailbox`: publicly writeable, can only be read by its host.

266281

267−###### `;delete %name 'optional reason'`

282+Let's create an example mailbox:

283+

284+```

285+sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'

286+```

287+

288+Something like this should print:

289+

290+```

291+--------------| ;create mailbox %coolbox 'cool messages only'

292+--------------| :: onn %coolbox

293+--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}

294+--------------| %coolbox: see ~sampel-palnet hear

295+--------------| new > %coolbox

296+--------------| %coolbox: cap: cool messages only

297+--------------| %coolbox: fit: caps:Y unic:â

298+```

299+

300+###### Delete

301+

302+Syntax: `;delete %name 'optional reason'`

268303

269304Deletes a circle. If a reason is specified, that gets sent to all

270305subscribers before the circle gets deleted.

271306

272−###### `;depict %name 'description'`

307+To delete our example above:

308+

309+```

310+sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'

311+```

312+

313+###### Change Description

314+

315+Syntax: `;depict %name 'description'`

273316

274−Changes the description of circle `%name`.

317+Changes the description of an existing circle `%name`.

275318

276−###### `;filter %name [capitals] [unicode]`

319+For example:

320+

321+```

322+sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'

323+```

324+

325+###### Filter

326+

327+Syntax: `;filter %name [capitals] [unicode]`

277328

278329Configures the message filter for circle `%name`: whether to allow

279330capital and/or unicode characters. `y`/`&`/`true` for allowed,

280331`n`/`|`/`false` for disallowed.

281332

282−###### `;invite %name ~someone`

333+So, to allow capital letters and disallow unicode in the circle `%coolbox`:

283334

284−Invite someone into your circle `%name`. If they were previously banished,

335+```

336+sampel-palnet:talk> ;filter %coolbox & |

337+```

338+or

339+```

340+sampel-palnet:talk> ;filter %coolbox y n

341+```

342+

343+And we get the output:

344+

345+```

346+--------------| ;filter %coolbox & |

347+--------------| %coolbox: fit: caps:Y unic:n

348+```

349+

350+###### Invite

351+

352+Syntax: `;invite %name ~someone`

353+

354+Invites someone into your circle `%name`. If they were previously banished,

285355removes them from the blacklist.

286356Can also invite multiple ships at once, `~comma, ~separated`.

287357

288−###### `;banish %name ~someone`

358+For example:

359+

360+```

361+~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul

362+```

363+

364+###### Banish

365+

366+Syntax: `;banish %name ~someone`

289367

290−Banish someone from your circle `%name`. If they were previously invited,

368+Removes someone from your circle `%name`. If they were previously invited,

291369removes them from the whitelist.

292370Can also banish multiple ships at once, `~comma, ~separated`.

293371

294−###### `;source %name ~other/circle`

372+###### Source

373+

374+Syntax: `;source %name ~other/circle`

295375

296376Adds `~other/circle` as a source for circle `%name`. This causes all

297377messages sent to `~other/circle` to also appear in `%name`.

298378

299−###### `;unsource %name ~other/circle`

379+For example:

380+

381+```

382+~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-meta

383+```

384+

385+###### Unsource

386+

387+Syntax: `;unsource %name ~other/circle`

300388

301389Removes `~other/circle` as a source for circle `%name`.

302390

303−### Membership

391+For example:

392+

393+```

394+~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-meta

395+```

396+

397+### Circle Membership

304398

305399If you have joined a circle, you can make this information publicly

306400available to help others find that circle as well.

307401

308−###### `;show ~some/circle`

402+###### Show Membership

403+

404+Syntax: `;show ~some/circle`

309405

310−Adds a circle to your public membership list.

406+Adds a circle to your public membership list on your Hall profile. Hall profiles

407+are not used yet.

311408

312−###### `;hide ~some/circle`

409+###### Hide Membership

313410

314−Removes a circle from your public membership list.

411+Syntax: `;hide ~some/circle`

412+

413+Removes a circle from your public membership list on your Hall profile. Hall

414+profiles are not used yet.

315415

316416### Status

317417

318−You'll see status notifications when people enter or leave stations

418+You'll see status notifications when people enter or leave circles you're

419+subscribed to.

420+

421+###### Notifications Off

319422

320−###### `;set quiet`

423+Syntax: `;set quiet`

321424

322425Turn off status (and config) notifications.

323426

324−###### `;unset quiet`

427+###### Notifications On

428+

429+Syntax: `;unset quiet`

325430

326431Turn on status (and config) notifications.

327432

328−###### `;who`

433+###### Who

434+

435+Syntax: `;who`

329436

330437List everyone in all your subscribed circles. Optionally specify a

331−specific circle to list members of just those.

438+specific circle to list members of just those: `;who ~some/circle`

332439

333−You'll see presence notifications when people enter or leave stations

334−you're subscribed to.

440+For example:

441+

442+```

443+~sampel-palnet:talk> ;who ~marzod/urbit-meta

444+```

335445

336−###### `;attend ~some/circle [presence]`

446+###### Attend

447+

448+Syntax: `;attend ~some/circle [presence]`

337449

338450Manually set your presence to show up as one of the following. (In the

339451future, a sufficiently advanced client can automatically set these for

@@ -344,21 +456,32 @@ you.)

344456- `idle` - inactive

345457- `gone` - not present

346458

347−###### `;name ~some/circle 'my handle'`

459+For example:

460+

461+```

462+~sampel-palnet:talk> ;attend ~marzod/urbit-meta idle

463+```

464+

465+###### Set Display Name

466+

467+Syntax: `;name ~some/circle 'my handle'`

348468

349469Set a handle ("name") for yourself in a specific circle. It will display

350470to users who have done `;set nicks`, but gets truncated if it's longer

351471than 14 characters.

352472

353−### Audience

473+## Audience

354474

355475An audience consists of one or more messaging targets. These can be

356476circles or ships. (In the latter case, it's secretly the `~ship/inbox`

357477circle.)

358478

359−### Circle glyphs

479+#### Circle Glyphs

360480

361−Glyphs are assigned by circle hash out of the following list

481+Glyphs are found at the end of your prompt to as a quick indicator of where

482+your messages will be sent.

483+

484+Glyphs are assigned by circle hash out of the following list:

362485

363486```

364487> = + - } ) , . " ' ^ $ % & @

@@ -367,19 +490,51 @@ Glyphs are assigned by circle hash out of the following list

367490Alphanumeric characters and `|#;:*~_` are reserved; all others (the

368491above list, and `\/!?({<`) can be manually assigned.

369492

370−###### `;bind + /urbit-test`

493+For example, `-` the glyph at the end of the prompt below might indicates that

494+messages sent from this prompt will go to some circle with that glyph:

495+

496+```

497+~sampel-palnet:talk-

498+```

499+

500+To see what circle is bound to a glyph, use the `;what` command followed by the

501+glyph in question. For example, to see `=`:

502+

503+```

504+~sampel-palnet:talk> ;what =

505+/urbit-meta

506+```

507+

508+Not every audience has a glyph, however. When the audience doesn't have a glyph,

509+such as in the case of direct-messaging a ship, we see their name at the end of

510+the prompt instead. Here we're talking directly to `~dannum-mitryl`:

511+

512+```

513+~sampel-palnet:talk[~dannum-mitryl]

514+```

515+

516+###### Bind

371517

372−Assigns the `+` glyph to `/urbit-test`.

518+Syntax: `;bind [glyph] /circle-name`

373519

374−###### `;unbind + /urbit-test`

520+Assigns the chosen glyph to a circle owned by your ship.

375521

376−Unassigns the `+` glyph from `/urbit-test`.

522+For example:

377523

378−To see what circle is bound to a glyph:

524+```

525+~sampel-palnet:talk> ;bind + /my-circle

526+```

527+

528+###### Unbind

529+

530+Syntax: `;unbind [glyph] /circle-name`

531+

532+Unassigns the chosen glyph from a circle owned by your ship.

533+

534+For example:

379535

380536```

381−;what +

382−/urbit-test

537+~sampel-palnet:talk> ;unbind + /my-circle

383538```

384539

385540### Prefixes

@@ -395,44 +550,39 @@ There are a few special-purpose glyphs:

395550- `;` - Posts to you and others (a multiparty conversation)

396551- `*` - Posts to a complex audience that doesn't directly include you.

397552

398−#### Prompt

399553

400−The audience you're sending to is always shown in your prompt. If

401−there's a glyph for it, it's shown as the glyph.

554+### Configuration

402555

403−Here we're talking to the station bound to `=`:

556+###### Set Audience

404557

405−```

406−~your-urbit:talk=

407−```

408−

409−Here we're talking directly to `~dannum-mitryl`:

558+`;~ship/circle`

410559

411−```

412−~your-urbit:talk[~dannum-mitryl]

413−```

560+Set audience to `~ship/circle`.

414561

415−#### Configuration

562+###### Set Audience by Glyph

416563

417−###### `;~urbit/circle`

564+Syntax: `;[glyph]`

418565

419−Set audience to `~urbit/circle`.

566+Set audience to the circle previously bound to the chosen glyph.

420567

421−###### `;=`

568+###### Set Audience to Ship

422569

423−Set audience to the station bound to the `=` glyph

570+syntax `;~ship`

424571

425−###### `;~dannum-mitryl`

572+Set audience to another ship.

426573

427−Set audience to `~dannum-mitryl` (a direct post).

574+###### Set Audience to Own Circle

428575

429−###### `;%circle`

576+Syntax: `;%circle`

430577

431578Set audience to a circle on your own ship

432579

433−###### `;~dannum-mitryl this is a private message`

580+###### Set Audience + Send Message

581+

582+Syntax: `;~dannum-mitryl this is a private message`

434583

435−Set the audience and send a post in the same line. This works for all of the above.

584+Set the audience and send a post in the same line. This works for all of the

585+above audience commands.

436586

437587Your audience is configured with regard to the following rules (in order):

438588

@@ -442,34 +592,48 @@ Your audience is configured with regard to the following rules (in order):

442592

443593### Local nicknames

444594

445−###### `;nick`

595+###### See Nicknames

596+

597+Syntax: `;nick`

446598

447599List all local nicknames.

448600

449−###### `;nick ~some-urbit`

601+###### Find Nickname

602+

603+Syntax: `;nick ~some-urbit`

604+

605+Look up a nickname using the known ship-name.

606+

607+###### Reverse Find Nickname

450608

451−Look up a nickname.

609+syntax: `;nick plato`

452610

453−###### `;nick plato`

611+Find a ship's name using its nickname.

454612

455−Search in reverse.

613+###### Set Nickname

456614

457−###### `;nick ~some-urbit plato`

615+Syntax: `;nick ~some-urbit plato`

458616

459−Create a nickname.

617+Create a new nickname.

460618

461−###### `;nick ~some-urbit ~`

619+###### Clear Nickname

620+

621+Syntax: `;nick ~some-urbit ~`

462622

463623Clear an assigned nickname.

464624

465−###### `;set nicks`

625+###### Display Nicks, Not Ship-Names

626+

627+Syntax: `;set nicks`

466628

467−Show nicknames instead of urbit names. If no local nickname is set, uses

629+Show nicknames instead of ship-names. If no local nickname is set, uses

468630that user's handle. If the user has no handle, just the urbit name.

469631

470−###### `;unset nicks`

632+###### Display Ship-Names, Not Nicks

633+

634+Syntax: `;unset nicks`

471635

472−Show urbit names instead of nicknames.

636+Show ship-names instead of nicknames.

473637

474638Nicknames and handles longer than 14 character will be truncated in

475639output. Nicknames are strictly local - like the names on entries in a

@@ -477,28 +641,40 @@ phonebook.

477641

478642### Miscellaneous configuration

479643

480−###### `;set showtime`

644+###### Show Timestamps

645+

646+Syntax: `;set showtime`

481647

482648Show the timestamp for each message.

483649

484−###### `;unset showtime`

650+###### Hide Timestamps

651+

652+Syntax: `;unset showtime`

485653

486654Stop showing the timestamp for each message.

487655

488−###### `;set timezone [+/-][hours]`

656+###### Change Time Zone

657+

658+Syntax: `;set timezone [+/-][hours]`

489659

490660Adjust the display of the timestamps to a specific timezone. Relative to UTC.

491661

492−###### `;set notify`

662+###### Sound Notification On

663+

664+Syntax: `;set notify`

493665

494666Emit a terminal bell sound if your six-syllable ship name is mentioned in

495667a message.

496668

497−###### `;unset notify`

669+###### Sound Notification Off

670+

671+Syntax `;unset notify`

498672

499673Do not notify when your ship name is mentioned.

500674

501−###### `;set width [number]`

675+###### Set Width

676+

677+Syntax: `;set width [number]`

502678

503679Set the rendering width of `:talk` to a specific number of characters.

504680(Minimum of 30.)

docs/using/setup.umd+91−66

@@ -8,18 +8,18 @@

99# Getting started

1010

11−On disk your urbit is an append-only log and a checkpoint. Or, in

12−simpler terms, a directory where we keep your urbit’s state. We call

13−this a _pier_.

11+On disk, your urbit - also referred to as your _ship_ - is an append-only log

12+and a checkpoint. Or, in simpler terms, a directory where we keep your urbit’s

13+state. We call this a _pier_.

1414

1515## Initialize

1616

17−To create an urbit, we need an identity. This identity is both a network

17+To create a ship, we need an identity. This identity is both a network

1818address and a memorable name.

1919

20−You are probably creating one of two kinds of urbit: a 32-bit _planet_

20+You are probably creating one of two kinds of ships: a 32-bit _planet_

2121or a 128-bit _comet_. For a quick terminology guide and high-level

22−refresher, refer to this [handy reference sheet](../../about/glossary/).

22+refresher, refer to this [handy reference sheet](../../reference/glossary/).

2323

2424If you have an Urbit invitation, you'll have a planet like

2525`~sampel-palnet` and `~sampel-sompel-simpel-sampel`. To create your

@@ -29,37 +29,58 @@ pier:

2929$ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel

3030```

3131

32−This will create a directory `sampel-palnet/` and begin building your

33−urbit. This may take a few minutes.

32+This will create a directory (pier) `sampel-palnet/` and begin building your

33+ship. You can feel free to rename the directory, or append a `-c <piername>`

34+to the end of it to give it a custom name from the start:

35+

36+```

37+$ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel -c myplanet

38+```

39+

40+Booting may take a few minutes. Note that your planet will begin as a

41+_comet_, a wild ship drifting through cyberspace. So don't be alarmed if it

42+doesn't have the name you expected - all ships begin as such, at least for now.

43+This step exists because you need to communicate with the Urbit network to

44+authenticate your planet, and you need to have a ship of some sort to

45+communicate with the Urbit network.

3446

3547> If you are booting a star, the process is the same as above, with your

36−> respective star name and ticket.

37−> If you are booting a galaxy, see

38−> [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).

48+ respective star name and ticket.

49+ If you are booting a galaxy, see

50+ [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).

3951

40−If you do not have a ticket, you can still make a _comet_, a wild urbit

41−drifting through cyberspace. Pick your own directory name, it doesn't

42−matter:

52+If you do not have a ticket, you can still make a comet that stays as a comet.

53+Pick your own directory name, it doesn't matter:

4354

4455```

4556$ urbit -c mycomet

4657```

4758

4859This will create the directory `mycomet/` and generate a 128-bit

49−identity for your urbit.

60+identity for your urbit. The identity of your comet will be random, but it

61+will look like `~lantug-fitsum-tinrum-fitnys--silwes-docnet-solteb-lopten` in

62+terms of length and structure.

5063

5164## Orientation

5265

53−After about five to ten minutes, when your urbit is finished booting,

54−you should see a `dojo>` prompt. Welcome!

66+Booting your urbit takes about ten minutes. After that, you should see a `dojo>`

67+prompt. Welcome!

68+

69+Note that "booting," in our usage, refers to starting a ship for the

70+first time; a ship is considered "booted" if it has connected to the network.

71+Its state is a pure function of its events, meaning that it has no concept of

72+shutting down. While you can end an Urbit process, that termination won't be

73+reflected in the state. When you start it up again, it will begin exactly where

74+it left off, as if nothing happened.

5575

56−By default your urbit is quite bare-bones. Let's stroll through what's

57−already running:

76+Your ship is quite bare-bones by default. A few user-facing apps are running by

77+default: *Dojo*, our shell; *Talk*, our messaging app; *Clay*, our filesystem;

78+*Tree*, our web interface. Let's stroll through them.

5879

5980### Shell — Dojo

6081

61−The command prompt in front of you is a simple shell and Hoon REPL.

62−Let's make sure it works:

82+The command prompt in front of you is a simple shell and Hoon REPL. Let's make

83+sure it works:

6384

6485```

6586~your-urbit:dojo> (add 2 2)

@@ -74,10 +95,33 @@ Should produce:

7495

7596Good.

7697

98+### Filesystem — Clay

99+

100+Clay, the Urbit filesystem, isn't mounted to Unix by default. From the Dojo

101+prompt, run:

102+

103+```

104+~your-urbit:dojo> |mount %

105+```

106+

107+This should produce:

108+

109+```

110+> |mount %

111+>=

112+```

113+

114+which indicates that the command was processed.

115+

116+`|mount %` will cause a `home/` directory to appear inside your pier

117+folder in Unix. Changes to the contained files are automatically synced from

118+Unix into your ship, and vice versa.

119+

120+For more information on Tree, check out the [Clay](../filesystem) section.

77121

78122### Messaging — Talk

79123

80−Use `ctrl-x` to change your prompt. Let's join the main Urbit chat

124+Use `ctrl-x` to toggle your prompt. Let's join the main Urbit chat

81125channel, `/urbit-meta`:

82126

83127```

@@ -88,18 +132,24 @@ Talk is stateful, so your urbit will download a backlog.

88132`/urbit-meta` is the place to ask questions, get help, talk about

89133anything Urbit-related, and meet everyone on here.

90134

135+For more information on the Dojo, check out the [Shell](../shell) section.

136+

91137### Web — Tree

92138

93−Your Urbit is also accessible through its own web interface. If you're

139+Your ship is also accessible through its own web interface. If you're

94140running Urbit locally on your own machine, try opening:

95141

96142```

97143http://localhost:8080/~~/

98144```

99145

100−in your favorite browser.

146+in your favorite browser. The actual port that's being used depends

147+if other things (including other urbits) are running on port `8080` and

148+its succeeding ports when your when your ship was turned on. To see what port is

149+being used be a given ship, look for a message like

150+`http: live (insecure, public) on 8081` when you start it up.

101151

102−Or if you're running your urbit on a cloud instance with a static IP

152+Or if you're running your ship on a cloud instance with a static IP

103153address (which we recommend!), something like `212.131.240.20`, assuming

104154you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443`

105155by default), try opening:

@@ -109,10 +159,10 @@ by default), try opening:

109159http://212.131.240.20:8080/~~/

110160```

111161

112−This way, if you keep your urbit running securely in the cloud (usually

162+This way, if you keep your ship running securely in the cloud (usually

113163in a [`screen`](https://www.gnu.org/software/screen/) or

114164[`tmux`](https://github.com/tmux/tmux/wiki) session), you can always

115−access your urbit's web interface in any browser on any device, so long

165+access your ship's web interface in any browser on any device, so long

116166as you have your password on hand.

117167

118168The `/~~/` in the URL will redirect you to a login page, which was

@@ -124,40 +174,24 @@ to your home page, authenticated, where you can then use the navigation

124174bar at the top of the page to visit your Talk web interface and static

125175files.

126176

127−You can also access your urbit through

128−`https://your-urbit.urbit.org/~~/`. Note that this latter approach is

129−slower for the time being because we proxy over the Urbit network, Ames,

130−but a better, faster solution for this is in the works.

131−

132−### Filesystem — Clay

133−

134−Clay, the Urbit filesystem, isn't mounted to Unix by default. Switch

135−to the Dojo prompt and run:

136−

137−```

138−~your-urbit:dojo> |mount %

139−```

140−

141−This should produce:

177+You can also access your ship through `https://your-urbit.urbit.org/~~/`. Note

178+that this latter approach is slower for the time being because we proxy over the

179+Urbit network, Ames, but a better, faster solution for this is in the works.

142180

143−```

144−> |mount %

145−>=

146−```

181+For more information on Tree, check out the [Web](../web) section.

147182

148−which indicates the command was processed.

149183

150−`|mount %` will cause a `home/` directory to appear inside your pier

151−folder. Changes to these files are automatically synced into your urbit.

184+---

152185

153−<br />

154186

155187Here are a few other things you can do to get up and running:

156188

189+

157190### Discussion — Fora

158191

159−Fora is the place for long-form Urbit discussion. It's hosted on an

160−Urbit and served over HTTP via Eyre, Urbit's web server.

192+Fora is the place for long-form Urbit discussion, our take on the message

193+board. It's hosted on an Urbit and served over HTTP via [Eyre](../web), Urbit's

194+web server.

161195

162196Head on over to:

163197

@@ -166,7 +200,7 @@ https://fora.urbit.org/~~/

166200```

167201

168202Like on your own web interface, you'll be redirected to a login page and

169−prompted to run `+code` in your Dojo to retrive your password and log

203+prompted to run `+code` in your Dojo to retrieve your password and log

170204in.

171205

172206After loading, you'll get redirected to the Fora home page where you

@@ -178,8 +212,8 @@ see what's going on.

178212

179213We host our docs on `urbit.org`, but it's faster to view them locally

180214through your own ship's web interface. So we also host the docs on a

181−Clay desk on one of our `urbit.org` planets, which you can merge and

182−sync onto your live ship over the network.

215+Clay desk on one of our `urbit.org` planets named `~ladnub-lorwyn`, which you

216+can merge and sync onto your live ship over the network.

183217

184218Run in your Dojo:

185219

@@ -209,18 +243,9 @@ http://localhost:8080/~~/docs

209243We'll update our planet's desk with new doc changes as they happen. You

210244should get sync updates automatically through Clay over Ames.

211245

212−### Examples

213−

214−Similarly, we host some Urbit examples on our same `urbit.org` planet as

215−above. Head to our [examples repo](https://github.com/urbit/examples) for

216−full instructions if you're interested, though you may want to start

217−with the [Urbyte](../../urbyte/), [Nock](../../nock/),

218−[Hoon](../../hoon/) or [Arvo](../../arvo/) sections so you can really

219−understand the example code.

220−

221246## Learn more

222247

223−If you're eager to get started programming you're ready to head over to

224−[the Hoon section](../../hoon/mission/).

248+If you're eager to get started programming, you're ready to head over to

249+[the Hoon tutorial](../../tutorials/hoon-ch1/).

225250

226251To learn more about using the system, let's keep going:

docs/using/shell.umd+71−25

@@ -11,23 +11,29 @@

1111;div(class "row")

1212 ;div(class "col-md-8")

1313

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

16−system for operating on and transforming data in Urbit.

14+The Dojo is our shell; it processes system commands and returns output. It's a

15+good place to quickly experiment with Urbit. On the surface the Dojo is just a

16+Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

17+data in Urbit.

1718

1819 ==

1920==

2021

2122## Quickstart

2223

23−Evaluate a hoon expression (whitespace matters):

24+You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system

25+commands.

26+

27+##### Math

28+

29+Evaluate a Hoon expression (whitespace matters):

2430

2531```

2632~your-urbit:dojo> (add 2 2)

2733~your-urbit:dojo> %+ add 2 2

2834```

2935

30−Tall form Hoon may require multiple lines:

36+Tall-form Hoon may require multiple lines:

3137

3238```

3339~your-urbit:dojo> %+ add

@@ -35,19 +41,30 @@ Tall form Hoon may require multiple lines:

3541~your-urbit:dojo< 2

3642```

3743

38−Use `=var` to save a shell variable:

44+Hoon uses something called [the subject](/../../tutorials/hoon-ch1/hoon-ch1-3).

45+The Dojo has its own subject, and that's where Hoon's equivalent of variables

46+are stored.

47+

48+Use `=var` to save variable to the Dojo subject.

3949

4050```

4151~your-urbit:dojo> =foo (add 2 2)

4252```

4353

54+Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

55+variable in a `.hoon` file in this way.

56+

57+##### System Commands

58+

59+

4460Use `=dir` to set the current working directory:

4561

4662```

4763~your-urbit:dojo> =dir %/web

4864```

4965

50−(`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/filesystem))

66+(`%` represents your current directory. For a complete explanation on urbit

67+paths, see the [filesystem section](/docs/using/filesystem))

5168

5269Generators (files in `/gen`) are run with `+`:

5370

@@ -67,54 +84,76 @@ Run system commands from `:hood`, like `reload`, using `|`:

6784~your-urbit:dojo> |reload %eyre

6885```

6986

87+`_See the [Clay](../fileystem) page for more information on system commands.`

88+

7089### Generators

7190

72−**`+cat`** - Similar to Unix `cat`. Accepts a path.

91+Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`

92+directory. Many Dojo commands exist in the form of generators. The syntax for

93+running a generator is `+genname` for a generator saved as `genname.hoon`.

94+

95+`+cat` - Accepts a path and displays the file. Similar to Unix `cat`.

7396

7497```

7598~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon

7699```

77100

78−**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.

101+`+code` - Generates a code to remotely log into your ship.

102+

103+```

104+~your-urbit:dojo> +code

105+```

106+

107+`+curl` - Retrives data from a URL. Accepts a `tape`. Similar to Unix

108+`curl`.

79109

80110```

81111~your-urbit:dojo> +curl "http://nyt.com"

82112```

83113

84−**`+hello`** - Just prints the argument. Accepts a `@ta`.

114+`+hello` - Just prints the argument. Accepts a `@ta`.

85115

86116```

87117~your-urbit:dojo> +hello 'mars'

88118```

89119

90−**`+ls`** - Similar to Unix `ls`. Accepts a path.

120+`+ls` - Similar to Unix `ls`. Accepts a path.

91121

92122```

93123~your-urbit:dojo> +ls %/web

94124~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

95125```

96126

97−**`+moon`** - Generate a random moon from a planet. No arguments.

127+`+moon` - Generates a random moon from a planet. No arguments.

98128

99129```

100130~your-urbit:dojo> +moon

101131```

102132

103−**`+solid`** - Compile the current state of the kernel and output a

133+`+solid` - Compile the current state of the kernel and output a

104134noun. Usually downloaded to a file in unix. No arguments.

105135

136+

106137```

107138~your-urbit:dojo> .urbit/pill +solid

108139```

109140

110−**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name

141+`+test` - Testrunner. Can test multiple generators at once, conventionally ones

142+in the `/test` folder. Accepts a path.

143+

144+```

145+~your-urbit:dojo> +test /lib

146+```

147+

148+`+ticket` - Generate a ticket for an Urbit plot. Takes an Urbit name

111149(`@p`).

112150

151+

113152```

114153~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

115154```

116155

117−**`+tree`** - Generate a recursive directory listing. Takes a path.

156+`+tree` - Generate a recursive directory listing. Takes a path.

118157

119158```

120159~your-urbit:dojo> +tree %/web

@@ -124,28 +163,28 @@ noun. Usually downloaded to a file in unix. No arguments.

124163

125164The hood is the system daemon. See `gen/hood` and `app/hood`.

126165

127−**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts

166+`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts

128167an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

129168

130169```

131170~your-urbit:dojo> |hi ~binzod "you there?"

132171```

133172

134−**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an

173+`|link` / `|unlink - Link / unlink a remote app. Accepts an

135174Urbit name and an app name.

136175

137176```

138177~your-urbit:dojo> |link ~talsur-todres %octo

139178```

140179

141−**`|mass`** - Prints the current memory usage of all the kernel modules.

180+`|mass` - Prints the current memory usage of all the kernel modules.

142181No arguments.

143182

144183```

145184~your-urbit:dojo> |mass

146185```

147186

148−**`|reload`** - Reloads a kernel module (vane) from source. Accepts any

187+`|reload` - Reloads a kernel module (vane) from source. Accepts any

149188number of vane names.

150189

151190```

@@ -180,9 +219,9 @@ command.

180219

181220### Sinks

182221

183−#### `=` - Set variable

222+##### `=` - Set variable

184223

185−Set any envronment variable:

224+Set any environment variable:

186225

187226```

188227~your-urbit:dojo> =foo 42

@@ -191,7 +230,12 @@ Set any envronment variable:

19123044

192231```

193232

194−(There are a few special variables that the dojo maintains. See below.)

233+Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

234+variable in a `.hoon` file in this way.

235+

236+#### Special Variables

237+

238+There are a few special variables that the dojo maintains.

195239

196240#### `:` - Send to app

197241

@@ -203,7 +247,7 @@ Send a `helm-hi` message to `hood`:

203247~your-urbit:dojo> :hood &helm-hi 'hi'

204248```

205249

206−App usually expect marked data, so `&` is often used here.

250+Apps usually expect marked data, so `&` is often used here.

207251

208252#### `*` - Save in `%clay`

209253

@@ -360,14 +404,16 @@ The current urbit plot. Read-only.

360404

361405#### `eny`

362406

363−256 bits of entropy. Read-only.

407+512 bits of entropy. Read-only.

364408

365409**Example:**

366410

367411```

368412~your-urbit:dojo> eny

369413:: produces

370−0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o

414+\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/

415+ 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn

416+\/

371417```

372418

373419## Troubleshooting

docs/using/web.umd+164−47

@@ -11,32 +11,73 @@

1111;div(class "row")

1212 ;div(class "col-md-8")

1313

14−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.

14+Your Urbit runs its own webserver, Eyre, that handles all things HTTP. Here

15+we'll cover the features of Eyre that most resemble a traditional web server.

1516

16−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.

17+By default Eyre uses *Tree*. Tree is a simple ui for browsing the contents of

18+the filesystem, statically publishing a blog or any kind of content and for

19+running single-page apps.

1720

18−Tree 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.

21+Tree was built primarily to display both our documentation and the contents of

22+`urbit.org`. If you're interested in doing anything complex, it's worth

23+checking out the [docs source](https://github.com/urbit/docs) and the

24+[urbit.org](https://github.com/urbit/urbit.org) source.

1925

20−We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its own repo [here](https://github.com/urbit/tree).

26+We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its

27+own repo [here](https://github.com/urbit/tree).

2128

2229 ==

2330==

2431

2532## Quickstart

2633

27−Your 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/`.

34+Your urbit runs a web server and can be found locally at

35+`http://localhost:8080/` This is the fastest and easiest way

36+to find your urbit's web server. Note that the port that a given urbit uses

37+might be `8081`, `8082`, or so on if you're running other processes that might

38+be occupying `8080`, such as another urbit. Upon the starting of a ship, it will

39+print a message telling you which port it's using.

2840

29−;span(class "red")

30−; (Make sure you have a desk mounted to unix, as covered in the [filesystem walkthrough](/docs/using/filesystem)).

31−==

41+Your urbit's web server can be accessed remotely at

42+`http://your-urbit.urbit.org/`. You'll need to enter a code to access it in this

43+way, one that is generated by running the `+code` command in the Dojo.

44+

45+_(Make sure you have a desk mounted to unix, as covered in the

46+[setup section](/../../using/setup))._

47+

48+##### Serving

49+

50+The `/web` directory of the `%home` desk is served by default. You can change

51+which desk you're serving by using the command `|serve` in the Dojo.

3252

33−To switch the desk you're serving from:

53+Let's create a desk for development called `%sandbox`.

54+

55+Use `|merge` to create the new desk containing the contents of `%home`:

3456

3557```

36−|serve %sandbox

58+~your-urbit:dojo> |merge %home our %sandbox

59+```

60+

61+And use `|sync` to continuously update based on changes to `%home`:

62+

63+~your-urbit:dojo> |sync %home our %sandbox

64+

65+Now let's mount it to unix so that we can save files to it:

66+

67+```

68+~your-urbit:dojo> |mount /=sandbox=

3769```

3870

39−To host a file on the web try putting the following in `/sandbox/web/test.umd` (from Unix):

71+And now, to switch the desk you're serving from:

72+

73+```

74+~your-planet:dojo> |serve %sandbox

75+```

76+

77+##### Hosting files

78+

79+To host a file on the web, save the following in `/sandbox/web/test.umd` in your

80+ship's pier through unix.

4081

4182```

4283# Hello

@@ -44,9 +85,20 @@ To host a file on the web try putting the following in `/sandbox/web/test.umd` (

4485This is a simple Urbit markdown file.

4586```

4687

47−Create the directory `/sandbox/web/test/` and add two more Urbit markdown files in it.

88+Our Tree system allows for pages to be designated as children of other pages.

89+To do this for any given page, simply make a new folder in the directory that

90+contains the page that will be the parent, and give that directory the same

91+name. So, the children of a page `/home/web/foo.umd` will live in a directory

92+called `/home/web/foo.umd`.

93+

94+Let's continue our with our `test.umd` example. Create `/sandbox/web/test/` and

95+add two more Urbit Markdown files in `/sandbox/web/test/daughter.umd`

96+`/sandbox/web/test/son.umd`, respectively. Make sure that they contain valid

97+Urbit Markdown!

4898

49−NOTE: Due to a bug in Urbit you may have to create the directory and the file in it in rapid succession using something like `mkdir sandbox/web/test && touch sandbox/web/test/first.md`.

99+> NOTE: Due to a bug in Urbit, you may have to create the directory and the file

100+ in it in rapid succession using something like `mkdir sandbox/web/test && touch

101+ sandbox/web/test/first.md`.

50102

51103Now modify `/sandbox/web/test.umd` to list the children using `;list;`:

52104

@@ -76,21 +128,28 @@ To view your file as raw `html`:

76128http://localhost:8080/test.html

77129```

78130

79−You may have noticed that we just created both `test.umd` and `test/`. In Urbit, there is no distinction between a directory and a file. So, if you're adding files directly from unix, simply `mkdir test` and Urbit will treat the file and directory as the same entity.

131+Now navigate to the "daughter" file that you created:

80132

81−You can use this feature to change your homepage at `your-urbit.urbit.org` with the page `/home/web.umd`, where `home` is the current mounted desk. By default, `web.umd` will display some info about your urbit, but you can customize it to your heart's content.

133+```

134+http://localhost:8080/test/daughter.umd

135+```

82136

83−## Examples

137+In Urbit, there is no distinction between a directory and a file. So, if you're

138+adding files directly from unix, simply `mkdir test` and Urbit will treat the

139+file and directory as the same entity.

84140

85−We've created a few simple examples of how to get set up publishing content from your Urbit. Feel free to ask questions in the comments.

141+You can use this feature to change your homepage at `your-urbit.urbit.org` with

142+the page `/home/web.umd`, where `home` is the current mounted desk. By default,

143+`web.umd` will display some info about your urbit, but you can customize it to

144+your heart's content.

86145

87−;list;

88146

89147## Manual

90148

91149## `/web`

92150

93−This is the equivalent of a `public_html` directory. Your Urbit looks in this directory to serve content to the world. You can change what desk you're serving from using `|serve`.

151+This is the equivalent of a `public_html` directory. Your Urbit looks in this

152+directory to serve content to the world. You can change what desk you're serving from using `|serve`.

94153

95154Switch to the `%sandbox` desk:

96155

@@ -116,27 +175,46 @@ Let's quickly step through the default contents of `web/`:

116175

117176## Tree

118177

119−Tree is a simple publishing tool for files that live on your Urbit. You're probably reading this file using Tree right now. The main driving use-case for Tree has been for us to host our own documentation and the surrounding discussion. Tree remains a pretty simple and flexible tool for getting content online. We think it's pretty great.

178+Tree is a simple publishing tool for files that live on your Urbit. You're

179+probably reading this file using Tree right now. The main driving use-case for

180+Tree has been for us to host our own documentation and the surrounding

181+discussion. Tree remains a pretty simple and flexible tool for getting content

182+online. It resembles a cross between [Jekyll](https://jekyllrb.com/),

183+[Kirby](https://getkirby.com/) and macOS's Finder. We think it's pretty great.

120184

121−Tree is a simple static publishing tool and the basic UI for browsing the filesystem. We take it one step further and make it possible to write modules (tiny little apps), like Talk and Dojo, that can be run directly inside of Tree.

185+Tree is also the basic UI for browsing the filesystem. We take it one step

186+further and make it possible to write modules (tiny little apps), like Talk and

187+Dojo, that can be run directly inside of Tree.

122188

123−In the browser Tree is a [React](https://facebook.github.io/react/) / [Flux](https://facebook.github.io/react/blog/2014/05/06/flux.html) app that uses a slightly modifed version of [Bootstrap](http://getbootstrap.com/). On your Urbit Tree is a renderer that translates data in `%clay`, our filesystem, into JSON / JSX that can be read by the client.

189+In the browser Tree is a [React](https://facebook.github.io/react/) /

190+[Flux](https://facebook.github.io/react/blog/2014/05/06/flux.html) app that uses

191+a slightly modifed version of [Bootstrap](http://getbootstrap.com/). On your

192+Urbit Tree is a renderer that translates data in `%clay`, our filesystem, into

193+JSON / JSX that can be read by the client.

124194

125−Your Urbit comes with a pre-built copy of the tree (as a single `.js` file). If you're interested in helping to develop tree or learning about how it works, it has its own GitHub repo [here](https://github.com/urbit/tree). We have our own fork of Bootstrap, which lives [here](https://github.com/urbit/bootstrap).

195+Your Urbit comes with a pre-built copy of the tree (as a single `.js` file). If

196+you're interested in helping to develop tree or learning about how it works, it

197+has its own GitHub repo [here](https://github.com/urbit/tree). We have our own

198+fork of Bootstrap, which lives [here](https://github.com/urbit/bootstrap).

126199

127200## `/web/pages`

128201

129−To render content without the Tree put it in `/web/pages`. Files in this directory aren't wrapped by Tree. For some examples check out [`web/` in the examples repo](https://github.com/urbit/examples/tree/master/web).

202+To render content without the Tree put it in `/web/pages`. Files in this

203+directory aren't wrapped by Tree.

130204

131205## Publishing files

132206

133−Publishing files in Tree is simple. Try dropping a file in `/web` (as covered in the Quickstart) and navigating to it.

207+Publishing files in Tree is simple. Try dropping a file in `/web` (as covered

208+in the Quickstart) and navigating to it.

134209

135−The best example of more complicated usage of Tree is covered by the Urbit docs themselves. See anything while perusing the docs that you'd like to use yourself? The docs are all on GitHub [here](https://github.com/urbit/docs).

210+The best example of more complicated usage of Tree is covered by the Urbit docs

211+themselves. See anything while perusing the docs that you'd like to use

212+yourself? The docs are all on GitHub [here](https://github.com/urbit/docs).

136213

137214## Frontmatter

138215

139−Most `.umd` files begin with some frontmatter, which determines the title and other settings for rendering the file correctly. E.g.:

216+Most `.umd` files begin with some frontmatter, which determines the title and

217+other settings for rendering the file correctly. E.g.:

140218

141219```

142220:- :~ navhome/'/home/'

@@ -149,36 +227,50 @@ Most `.umd` files begin with some frontmatter, which determines the title and ot

149227

150228Here are the fields we support:

151229

152−### `title`

230+##### title

153231

154232String. Example: `title/'Tree manual'`.

155233

156234This sets the title in the nav or in lists as distinct from the filename.

157235

158−### `next`

236+##### next

159237

160238Boolean. Example: `next/'true'`

161239

162240Adds a 'next' link at the bottom of the page that links to the next item as decided by the sort order.

163241

164−### `sort`

242+##### sort

165243

166244Integer. Example: `sort/'7'`

167245

168−User-defined sort. Indicates the sort order as distinct from alphabetical sort. These numbers should not be overlapping.

246+User-defined sort. Indicates the sort order as distinct from alphabetical sort.

247+These numbers should not be overlapping.

169248

170−### `hide`

249+##### hide

171250

172251Boolean. Example: `hide/'true'`

173252

174253Whether or not to hide the item from the tree.

175254

176−### `date`

255+##### date

177256

178257Urbit date. Example: `date/'~2016.2.22'`

179258

180259Used for sorting posts by date.

181260

261+##### Arbitrary Frontmatter

262+

263+Any arbitrary category can be used as long as it's given data of valid types.

264+Arbitrary categories can be used with the ones mentioned above. Below is

265+valid front matter:

266+

267+```

268+:- :~ date/~2018.9.12

269+ author/~lodleb-ritrul

270+ music/'rad'

271+ ==

272+```

273+

182274## Using components

183275

184276Tree is built using React with a small library of components that you can add to your pages using [JSX](https://facebook.github.io/jsx/) tags.

@@ -252,15 +344,25 @@ To make this clearer let's look at some HTML and its JSON representation:

252344]}

253345```

254346

255−To see the mechanics of how this is handled on the frontend, checkout `components/Reactify.coffee` in the `urbit/tree` repo.

347+To see the mechanics of how this is handled on the frontend, checkout

348+`components/Reactify.coffee` in the `urbit/tree` repo.

256349

257350### Async component

258351

259−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.

352+Each of our components (even those we fetched from the server) can depend on

353+data that may not exist in our stores, so we wrap our components in a

354+general-purpose Async component. You can find the component in

355+`components/Async.coffee` in the `urbit/tree` repo.

260356

261−When 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`.

357+When we say that we just fetch HTML as JSON it's actually slightly more

358+complicated. When we fetch a node in the filesystem we might not want to fetch

359+its entire contents. Sometimes we just get the title as a part of a list of

360+children, sometimes we might get a snippet (in a list with previews), and

361+sometimes we get the whole thing. On the Urbit side these results are provided

362+by `ren/tree/json`.

262363

263−From the perspective of the frontend we just send queries on a path that obey a simple API. To see this in action, here's our `BodyComponent`:

364+From the perspective of the frontend we just send queries on a path that obey a

365+simple API. To see this in action, here's our `BodyComponent`:

264366

265367```

266368query {

@@ -272,11 +374,13 @@ query {

272374}

273375```

274376

275−Here we're asking for the body, name, path, metadata and parent of the current path. When it loads that data gets passed to our component as props.

377+Here we're asking for the body, name, path, metadata and parent of the current

378+path. When it loads that data gets passed to our component as props.

276379

277380### Module basics

278381

279−A module is a special component that can kind of 'take over' the page. It can change properties of the nav bar as well as load custom scripts / css.

382+A module is a special component that can kind of 'take over' the page. It can

383+change properties of the nav bar as well as load custom scripts / css.

280384

281385Talk, for example, looks like this:

282386

@@ -289,29 +393,42 @@ Talk, for example, looks like this:

289393</module>

290394```

291395

292−A module will first download all the scripts and styles that it specifies before trying to load any contained components. This means that you can define React components in external scripts and a module can be entirely self contained. The `<talk>` component isn't a part of Tree — it's loaded first before it's executed.

396+A module will first download all the scripts and styles that it specifies before

397+trying to load any contained components. This means that you can define React

398+components in external scripts and a module can be entirely self contained.

399+The `<talk>` component isn't a part of Tree — it's loaded first before it's

400+executed.

293401

294−If you're interested in seeing how a module works you can check out the source for Talk [here](https://github.com/urbit/talk). Dojo also ships on your Urbit, its source is [here](https://github.com/urbit/sole).

402+If you're interested in seeing how a module works you can check out the source

403+for Talk [here](https://github.com/urbit/talk). Dojo also ships on your Urbit,

404+its source is [here](https://github.com/urbit/sole).

295405

296406## `urb.js`

297407

298−The most basic interface between your browser and your Urbit is `urb.js`. This small library provides the basic utilities for sending and receiving messages from an Urbit.

408+The most basic interface between your browser and your Urbit is `urb.js`. This

409+small library provides the basic utilities for sending and receiving messages

410+from an Urbit.

299411

300412### `window.urb.appl`

301413

302−Each JSON message sent to your Urbit needs an app endpoint. Can be set as a global `window.urb.appl` or set on a per-request basis in the payload to `send()`.

414+Each JSON message sent to your Urbit needs an app endpoint. Can be set as a

415+global `window.urb.appl` or set on a per-request basis in the payload to

416+`send()`.

303417

304418### `window.urb.oryx`

305419

306−CSRF token. Written to the page by Eyre, our webserver, when logged in. Required part of any authenticated request and included by default.

420+CSRF token. Written to the page by Eyre, our webserver, when logged in.

421+Required part of any authenticated request and included by default.

307422

308423### `window.urb.req(method,url,params,json,cb)`

309424

310−Our basic request wrapper. You can see here how a request needs to be packaged to be properly understood by your Urbit.

425+Our basic request wrapper. You can see here how a request needs to be packaged

426+to be properly understood by your Urbit.

311427

312428### `window.urb.subscribe({path:"string"})`

313429

314−Subscribe to an endpoint. Subscription data is returned through the continuous long poll.

430+Subscribe to an endpoint. Subscription data is returned through the continuous

431+long poll.

315432

316433### `window.urb.unsubscribe({path:"string"})`

317434

@@ -319,7 +436,7 @@ Close subscription on specified path.

319436

320437### `window.urb.poll()`

321438

322−Mechanics of the continuous long poll. Used mostly internally.

439+Mechanics of the continuous long poll. Used mostly internally.

323440

324441### `window.urb.util`

325442