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

git.iko.soy/urbit.org

on master help sign in

fixes dead links, updates using

5b9c970Robert8 years ago

docs/about/contributing.umd+3−1

compare with master

unifiedsplit

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

16Our official guide to contributing can be found

17[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 @@

9# Technical overview

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.

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

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

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

18- 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.

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

20+ includes a Hoon-to-Nock compiler.

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

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

22+ bytes.

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

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

24+ each urbit and the Unix software layer.

20## Anatomy of a personal server

26## Anatomy of a personal server

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

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).

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

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.

26```

38```

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

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

28```

40```

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

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.

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

31−

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

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.

46+urbit's event history.

33−

47+

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?

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

35−

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

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.

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

37−

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

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.

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.

40### Arvo

75### Arvo

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.

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.

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

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

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.

49- Behn: manages timer events for other vanes.

93- Behn: manages timer events for other vanes.

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

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

51- Dill: terminal driver.

95- Dill: terminal driver.

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

101

58### Hoon

102### Hoon

103

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.

108

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.

114

64### Nock

115### Nock

116

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.

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

67−

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+

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.

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.

131

70### Vere

132### Vere

133

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.

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

73−

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

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.

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

75−

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

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.

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

77−

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

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.

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

79−

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

153+

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.

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

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

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

188

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

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

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

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

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

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

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

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

193this means).

194

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

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

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

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

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

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

198

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

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

docs/reference/basic.umd+38−12

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

8# 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.

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.

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.)

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.

18## `$type`

29## `$type`

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.)

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

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

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

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

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

38 ==

53 ==

39```

54```

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.

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

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

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`.

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

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

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

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

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`.

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

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

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

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`.

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`.

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.

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

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

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

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`."

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`."

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

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

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

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.

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.

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

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

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

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

23This 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).

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:

28```

29```

29!: :: turn on debugging printfs

30!: :: turn on debugging printfs

docs/reference/glossary.umd+28−29

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

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

48 context.

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

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

53;h3

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

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

75More in-depth information on Arvo can be found

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

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

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

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

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

88 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).

91- ##### Behn

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

112 Basic information on using Clay can be found

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

114 of the architecture can be found

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

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

116

117- ##### Dill

118

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

130

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

132

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

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

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

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

135

136- ##### Eyre

137

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

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

161

162 More in-depth information on Ford can be found

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

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

164

165- ##### Gall

166

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

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

177

178 More in-depth information on Ford can be found

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

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

180

181### atom

182

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

195

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

197

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

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

199

200;h3

201 ;div(id "aura"): aura

202==

203

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

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

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

207

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

253 @ux unsigned hexadecimal 0x5f5.e138

254```

255

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).

257

258### blocksize

259

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

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

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

362

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

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

364

365

366### flag

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

377

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

379analog 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`

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

382

383The 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]`.

390

391 The subject in which the gate was defined.

392

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

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

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

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

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

396

397### generator

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

412

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

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

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

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

416

417### glyph

418

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

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

519```

520

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

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

522−full of hoons.

523

522

524### irregular form

523### irregular form

525

524

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

592 a search path into the subject, composed of

591 a search path into the subject, composed of

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

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

594

593

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

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

596

595

597

596

598;h3

597;h3

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

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

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

666 ==

665 ==

667

666

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

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

669

668

670

669

671;h3

670;h3

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

694- `zinc`: _covariant_

693- `zinc`: _covariant_

695- `iron`: _contravariant_

694- `iron`: _contravariant_

696

695

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

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

698

697

699### ship

698### ship

700

699

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

780

779

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

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

782

781

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

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

784

783

785;h3

784;h3

786 ;div(id "rune"): rune

785 ;div(id "rune"): rune

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

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

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

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

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

791

790

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

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

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

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

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

793symbol 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.

796

795

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

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

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

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

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

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

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

828forms are flat.

827forms are flat.

829

828

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

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

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

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

832

831

833### Sail

832### Sail

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

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

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

840to userspace.

839to userspace.

841

840

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

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

843

842

844### slot

843### slot

845

844

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

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

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

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

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

862

861

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

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

864

863

865### type

864### type

866

865

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

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

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

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

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

884

883

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

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

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

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

887

886

888

887

889### Unit

888### Unit

docs/reference/irregular.umd+6−6

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

38R: `.=(p q)`

39I: `=(p q)`

41−## ; sem (make)

41+## ; mic (make)

43Miscellaneous useful macros.

45−### ;: semcol

45+### ;: miccol

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

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

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

50R: `;:(p q)`

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

217- `|` loobean false.

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

219

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

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

221

222### List addressing

223

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

226

227### Limbs

228

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

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

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

231

232- `+15` is slot 15

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

249

250### Wings

251

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

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

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

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

255

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

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

6;>

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

9−

10# 1b: tree addressing

8# 1b: tree addressing

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

10Check 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.

421

422Wrap value in a unit

423

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`.

425

426#### Accepts

427

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

428+`a` is a noun.

429

430#### Produces

431

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

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

189

190To lowercase

191

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

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

193

194#### Accepts

195

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

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

74Parse backslash

76Parses 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

78character, `\`.

80#### Source

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

800Parse single quote

801

802Parses 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`.

804

805#### Source

806

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

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

61List of XML nodes

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

63+A list of `++manx`.

65#### Source

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

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

8# Cores `|` "bar"

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

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.

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

12+needed to run those formulas correctly.

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

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

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

15core 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

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

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

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

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

30−> the subject.

30+ the subject.

32## Examples

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

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

8# 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.

12## Overview

17## Overview

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

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

18### Syntax

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

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

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

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

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

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

8# Limbs and wings

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

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.

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

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

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

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.

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.

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

19;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.)

13## Overview

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.

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

16−

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

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]`.

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

18−

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+

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

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

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

21## Runes

28## Runes

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

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

8# 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.

12## Overview

16## Overview

docs/tutorials/gall.umd+4−1

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

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

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

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.

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.

14;list;

17;list;

docs/tutorials/hall.umd+2−1

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

9# Hall

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.

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

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

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

15architecture, 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

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

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

19−

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

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

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

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

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

21it 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

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

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

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

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

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

31+Urbit Markdown files using our web interface.

32+

32### Getting Started

34### Getting Started

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

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

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

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

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

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

43and 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.

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

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

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

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

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

613 ;small: [reactive publishing intensifies]

616 ;small: [reactive publishing intensifies]

614 ==

617 ==

615==

618==

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 @@

8# A simple blog

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

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

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

11−very simple blog and publish our first posts.

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

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

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

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

46;list(dataType "post");

47;list(dataType "post");

47```

48```

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

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+

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

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

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

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

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

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

53the page seem more like a landing page.

57the page seem more like a landing page.

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

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

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

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

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

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

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

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

80+ 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

81+ 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

82+ 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

83+ 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

84+ 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

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

82−themselves and not to them.

86+ themselves and not to them.

84Good to get that out of the way.

88Good to get that out of the way.

85```

89```

87You should be able to view this file at:

91You should be able to view this file at:

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

93+

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

94+You'll also notice that

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

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

90updated.

96updated.

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`.

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.

103

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

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`

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

106

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

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

99directory. Pretty easy!

108directory. Pretty easy!

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

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

8# 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

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

12enable comments on a post.

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

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

15−should look like this:

15+frontmatter should look like this:

17```

18:- :~ navhome/'/blog'

19 type/'post'

20− date/'~2016.6.20'

20+ date/'~2018.6.20'

21 title/'Blog comments'

22 comments/'true'

23 ==

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

10simple site for an imaginary Urbit meetup group.

12We 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

14unix.

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.

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

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

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

61## Mission statement

65## Mission statement

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.

65## Members

71## Members

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

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

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

134Adding other imaginary projects is left to the reader.

140Adding other imaginary projects is left to the reader.

135

141

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

137files. Have fun!

143files. Have fun!

docs/using.umd+2−1

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

8# 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.

12;list;

13;list;

docs/using/admin.umd+55−22

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

9# Admin and operation

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

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

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

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

14## Shutdown

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.

18## Restart

20## Restart

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

40## Moving your pier

42## Moving your pier

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

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

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

44of the same Urbit in two places.

46of the same Urbit in two places.

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

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

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

49To 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

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

49−inside `urbit/`) should work:

51```

52```

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

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

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

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

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

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.

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

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

87`↑` / `↓` - History navigation

91`↑` / `↓` - History navigation

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

109

113

110## Web

114## Web

111

115

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

116+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.

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

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

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

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

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

116

121

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

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

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

123`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.

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

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

121running something on `8443`.

126running something on `8443`.

122

127

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

125

130

126## Moons

131## Moons

127

132

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.

129

138

130To generate a random moon from your planet run:

139To generate a random moon from your planet run:

131

140

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

133~your-urbit:dojo> +moon

142~your-urbit:dojo> +moon

134```

143```

135

144

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+

137

162

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.

139

167

140

168

141## Continuity breaches

169## Continuity breaches

142

170

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

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

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

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

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

146

174

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

154

182

155## Creating SSL certificates

183## Creating SSL certificates

156

184

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

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

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

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

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:

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

189+commands:

160

190

161```

191```

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

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

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

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

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

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

165```

195```

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

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.

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.

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 @@

9# Filesystem (Clay)

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

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.

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

14+`git` with continuous sync.

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

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.

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.

17## Quickstart

22## Quickstart

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:

21```

27```

22|merge %sandbox ~your-urbit %home

28|merge %sandbox ~your-urbit %home

23```

29```

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+

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

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

40+your `sandbox` desk to Unix:

27```

42```

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

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

29```

44```

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.

33```

62```

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

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

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

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

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

41```

70```

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+

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

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

44`%sandbox` desk:

86`%sandbox` desk:

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

52### Paths

94### Paths

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

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

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

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

56where each segment is a `@ta`.

98where each segment is a `@ta`.

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

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

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

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

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

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

103

62−#### Relative paths

104+##### Relative paths

105

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

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

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

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

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

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

67`%/foo/bar`.

109`%/foo/bar`.

110

69−#### Substitution

111+##### Substitution

112

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

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

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

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

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

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

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

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

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

121

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:

133

82```

134```

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

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

84```

136```

137

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+

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

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

151

88*Examples:*

152*Examples:*

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

190

254

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

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

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

256"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

194version, allowing merges to be rerun.

258version, allowing merges to be rerun.

195

259

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

260`%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

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

22> 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

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

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

25−> sensitive data.

25+ sensitive data.

27## Build from source

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

54### Instructions

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.

58For 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:

63For 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:

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

65> 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)

66+ - 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)

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

64#### macOS

69#### macOS

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

318$ urbit

323$ urbit

319Urbit: a personal server operating function

324Urbit: a personal server operating function

320https://urbit.org

325https://urbit.org

321−Version 0.5.1

326+Version 0.6.0

322

327

323Usage: urbit [options...] ship_name

328Usage: urbit [options...] ship_name

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

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

docs/using/layout.umd+61−24

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

9# Arvo source

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

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

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

14through the structure of a base Arvo desk.

16Looking at the top level of

17[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:

20```

21app/

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

27sec/

28sur/

29sys/

30+tests/

30web/

31web/

31web.md

32web.md

32```

33```

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+

34−Let's step through directory by directory.

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

36## `sys/`

44## `sys/`

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

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

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

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

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

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

43−language is actually specified in this source file.

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

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

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

47Zuse is the Arvo standard library.

55Zuse is the Arvo standard library.

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

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

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

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

53−### `sys/vane`

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

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

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

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

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

59Ames is our network protocol.

67Ames is our network protocol.

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

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

63Behn is a simple timer.

71Behn is a simple timer.

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

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

67Clay is our filesystem.

75Clay is our filesystem.

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

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

71Dill is our terminal driver.

79Dill is our terminal driver.

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

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

75Eyre is our webserver.

83Eyre is our webserver.

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

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

79Ford is our build system.

87Ford is our build system.

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

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

83Gall is our application model.

91Gall is our application model.

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

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

87Jael is our secret vault.

95Jael is our secret vault.

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

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

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

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

100

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

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

102

103+---

104+

95## `app/`

105## `app/`

106

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

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

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

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

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

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

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

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

111+

112+---

101

113

102## `gen/`

114## `gen/`

103

115

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

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

105

117

118+---

119+

106## `lib/`

120## `lib/`

107

121

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

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

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

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

110command line, and the Dojo web client.

124command line, and the Dojo web client.

111

125

126+---

127+

112## `mar/`

128## `mar/`

113

129

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

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

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

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

116

132

133+---

134+

117## `ren/`

135## `ren/`

118

136

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

137These 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

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

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

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

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

125

143

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+

126## `sur/`

153## `sur/`

127

154

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

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

129files in C.

156files in C.

130

157

158+---

159+

160+## `tests/`

161+

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

163+

164+---

165+

131## `web/`

166## `web/`

132

167

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

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

134−Eyre.

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

170+

171+---

135

172

136## `web.md`

173## `web.md`

137

174

docs/using/messaging.umd+274−98

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

9# Messaging (Talk and Hall)

11−

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

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

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

12protocol, 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.

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

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

17'quickstart' section below.

16'quickstart' section below.

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

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

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

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

23streams 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,

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

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

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

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

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

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

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

29to 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).

33## Quickstart

32## Quickstart

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

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

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

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

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

38Urbit in general.

37Urbit in general.

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

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.

44−To join `/urbit-meta`:

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

51+Then, :

46```

53```

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

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

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

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

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

56--------------| new = /urbit-meta

63--------------| new = /urbit-meta

57--------------| /urbit-meta: cap: For Urbit-related discussion. Politically

64--------------| /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.

59--------------| /urbit-meta: fit: caps:n unic:n

66--------------| /urbit-meta: fit: caps:n unic:n

60~your-urbit:talk=

67~your-urbit:talk=

61```

68```

70+Scrolling down your terminal window, you'll probably also see the playback of

71+previous `/urbit-meta` messages that you missed.

72+

63Post a line to `/urbit-meta`:

73Post a line to `/urbit-meta`:

65```

75```

66~your-urbit:talk= Hello, world!

76~your-urbit:talk= Hello, world!

67```

77```

69−You'll see, echoed back at you:

79+You'll see your message printed below messages from others that came before it:

71```

81```

72~your-urbit= Hello, world!

82~your-urbit= Hello, world!

73```

83```

85+##### Direct Messaging

86+

75To send a direct message to someone, first set your audience:

87To send a direct message to someone, first set your audience:

77```

89```

@@ -117,10 +129,6 @@ Use `;leave` to unsubscribe from a channel:

117~your-urbit:talk= ;leave /urbit-meta

129~your-urbit:talk= ;leave /urbit-meta

118```

130```

119

131

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−

124The web UI ships as compiled JavaScript on your Urbit, but has its own

132The web UI ships as compiled JavaScript on your Urbit, but has its own

125source repo [here](https://github.com/urbit/talk).

133source repo [here](https://github.com/urbit/talk).

126

134

@@ -132,7 +140,9 @@ Last, let's create a channel we can invite some friends to:

132

140

133Now you can tell your friends to `;join ~your-urbit/my-channel`.

141Now you can tell your friends to `;join ~your-urbit/my-channel`.

134

142

143+;h2

135−## Manual

144+ ;div(id "manual"): Manual

145+==

136

146

137Hall's design is similar in spirit to

147Hall's design is similar in spirit to

138[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),

148[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),

@@ -149,16 +159,15 @@ general use.

149### Posts

159### Posts

150

160

151A post can be a variety of different data structures. Let's look at the

161A 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

162+ones you can use from within Talk: lines, URLs, Hoon and replies.

153−replies.

154

163

155−#### Lines

164+##### Lines

156

165

157A line is simply a string of text. Depending on the filtering rules set

166A line is simply a string of text. Depending on the filtering rules set

158by the circle's host, these may or may not include uppercase and Unicode

167by the circle's host, these may or may not include uppercase and Unicode

159characters.

168characters.

160

169

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).

162

171

163```

172```

164~your-urbit:talk= @sends a message.

173~your-urbit:talk= @sends a message.

@@ -170,7 +179,7 @@ will print as

170~your-urbit sends a message.

179~your-urbit sends a message.

171```

180```

172

181

173−#### URLs

182+##### URLs

174

183

175A URL is any valid URL.

184A URL is any valid URL.

176

185

@@ -178,7 +187,7 @@ A URL is any valid URL.

178~your-urbit:talk= https://example.com/

187~your-urbit:talk= https://example.com/

179```

188```

180

189

181−### Hoon

190+##### Hoon

182

191

183You can use Talk to evaluate Hoon code and share the result with everyone in a

192You can use Talk to evaluate Hoon code and share the result with everyone in a

184Hall circle. To do so, preface your Hoon with `#`.

193Hall circle. To do so, preface your Hoon with `#`.

@@ -194,7 +203,7 @@ will print as

1944

2034

195```

204```

196

205

197−### Replies

206+##### Replies

198

207

199To indicate what you're saying is in direct response to a specific

208To indicate what you're saying is in direct response to a specific

200message, select the message (see Activating Lines below) and type your

209message, select the message (see Activating Lines below) and type your

@@ -246,7 +255,7 @@ in reply to: ~your-urbit:

246That's my message!

255That's my message!

247```

256```

248

257

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,

250or if there's additional information available — as is the case with

259or if there's additional information available — as is the case with

251replies and attachments — activating the message will show you all the

260replies and attachments — activating the message will show you all the

252details.

261details.

@@ -256,7 +265,13 @@ with `;;`, and so on.

256

265

257### Creating and managing circles

266### Creating and managing circles

258

267

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+

259−###### `;create [type] %name 'description'`

274+Syntax: `;create [type] %name 'description'`

260

275

261Creates and joins a circle, where `[type]` is any of the following:

276Creates and joins a circle, where `[type]` is any of the following:

262- `channel`: public circle. Has a blacklist for write control.

277- `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:

264- `journal`: publicly readable, invite-only for writing.

279- `journal`: publicly readable, invite-only for writing.

265- `mailbox`: publicly writeable, can only be read by its host.

280- `mailbox`: publicly writeable, can only be read by its host.

266

281

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+

267−###### `;delete %name 'optional reason'`

302+Syntax: `;delete %name 'optional reason'`

268

303

269Deletes a circle. If a reason is specified, that gets sent to all

304Deletes a circle. If a reason is specified, that gets sent to all

270subscribers before the circle gets deleted.

305subscribers before the circle gets deleted.

271

306

307+To delete our example above:

308+

309+```

310+sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'

311+```

312+

313+###### Change Description

314+

272−###### `;depict %name 'description'`

315+Syntax: `;depict %name 'description'`

273

316

274−Changes the description of circle `%name`.

317+Changes the description of an existing circle `%name`.

275

318

319+For example:

320+

321+```

322+sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'

323+```

324+

325+###### Filter

326+

276−###### `;filter %name [capitals] [unicode]`

327+Syntax: `;filter %name [capitals] [unicode]`

277

328

278Configures the message filter for circle `%name`: whether to allow

329Configures the message filter for circle `%name`: whether to allow

279capital and/or unicode characters. `y`/`&`/`true` for allowed,

330capital and/or unicode characters. `y`/`&`/`true` for allowed,

280`n`/`|`/`false` for disallowed.

331`n`/`|`/`false` for disallowed.

281

332

282−###### `;invite %name ~someone`

333+So, to allow capital letters and disallow unicode in the circle `%coolbox`:

283

334

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+

284−Invite someone into your circle `%name`. If they were previously banished,

354+Invites someone into your circle `%name`. If they were previously banished,

285removes them from the blacklist.

355removes them from the blacklist.

286Can also invite multiple ships at once, `~comma, ~separated`.

356Can also invite multiple ships at once, `~comma, ~separated`.

287

357

358+For example:

359+

360+```

361+~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul

362+```

363+

364+###### Banish

365+

288−###### `;banish %name ~someone`

366+Syntax: `;banish %name ~someone`

289

367

290−Banish someone from your circle `%name`. If they were previously invited,

368+Removes someone from your circle `%name`. If they were previously invited,

291removes them from the whitelist.

369removes them from the whitelist.

292Can also banish multiple ships at once, `~comma, ~separated`.

370Can also banish multiple ships at once, `~comma, ~separated`.

293

371

372+###### Source

373+

294−###### `;source %name ~other/circle`

374+Syntax: `;source %name ~other/circle`

295

375

296Adds `~other/circle` as a source for circle `%name`. This causes all

376Adds `~other/circle` as a source for circle `%name`. This causes all

297messages sent to `~other/circle` to also appear in `%name`.

377messages sent to `~other/circle` to also appear in `%name`.

298

378

379+For example:

380+

381+```

382+~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-meta

383+```

384+

385+###### Unsource

386+

299−###### `;unsource %name ~other/circle`

387+Syntax: `;unsource %name ~other/circle`

300

388

301Removes `~other/circle` as a source for circle `%name`.

389Removes `~other/circle` as a source for circle `%name`.

302

390

391+For example:

392+

393+```

394+~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-meta

395+```

396+

303−### Membership

397+### Circle Membership

304

398

305If you have joined a circle, you can make this information publicly

399If you have joined a circle, you can make this information publicly

306available to help others find that circle as well.

400available to help others find that circle as well.

307

401

402+###### Show Membership

403+

308−###### `;show ~some/circle`

404+Syntax: `;show ~some/circle`

309

405

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.

311

408

312−###### `;hide ~some/circle`

409+###### Hide Membership

313

410

411+Syntax: `;hide ~some/circle`

412+

314−Removes a circle from your public membership list.

413+Removes a circle from your public membership list on your Hall profile. Hall

414+profiles are not used yet.

315

415

316### Status

416### Status

317

417

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

319

422

320−###### `;set quiet`

423+Syntax: `;set quiet`

321

424

322Turn off status (and config) notifications.

425Turn off status (and config) notifications.

323

426

427+###### Notifications On

428+

324−###### `;unset quiet`

429+Syntax: `;unset quiet`

325

430

326Turn on status (and config) notifications.

431Turn on status (and config) notifications.

327

432

433+###### Who

434+

328−###### `;who`

435+Syntax: `;who`

329

436

330List everyone in all your subscribed circles. Optionally specify a

437List 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`

332

439

333−You'll see presence notifications when people enter or leave stations

440+For example:

334−you're subscribed to.

441+

442+```

443+~sampel-palnet:talk> ;who ~marzod/urbit-meta

444+```

335

445

446+###### Attend

447+

336−###### `;attend ~some/circle [presence]`

448+Syntax: `;attend ~some/circle [presence]`

337

449

338Manually set your presence to show up as one of the following. (In the

450Manually set your presence to show up as one of the following. (In the

339future, a sufficiently advanced client can automatically set these for

451future, a sufficiently advanced client can automatically set these for

@@ -344,21 +456,32 @@ you.)

344- `idle` - inactive

456- `idle` - inactive

345- `gone` - not present

457- `gone` - not present

346

458

459+For example:

460+

461+```

462+~sampel-palnet:talk> ;attend ~marzod/urbit-meta idle

463+```

464+

465+###### Set Display Name

466+

347−###### `;name ~some/circle 'my handle'`

467+Syntax: `;name ~some/circle 'my handle'`

348

468

349Set a handle ("name") for yourself in a specific circle. It will display

469Set a handle ("name") for yourself in a specific circle. It will display

350to users who have done `;set nicks`, but gets truncated if it's longer

470to users who have done `;set nicks`, but gets truncated if it's longer

351than 14 characters.

471than 14 characters.

352

472

353−### Audience

473+## Audience

354

474

355An audience consists of one or more messaging targets. These can be

475An audience consists of one or more messaging targets. These can be

356circles or ships. (In the latter case, it's secretly the `~ship/inbox`

476circles or ships. (In the latter case, it's secretly the `~ship/inbox`

357circle.)

477circle.)

358

478

359−### Circle glyphs

479+#### Circle Glyphs

360

480

481+Glyphs are found at the end of your prompt to as a quick indicator of where

482+your messages will be sent.

483+

361−Glyphs are assigned by circle hash out of the following list

484+Glyphs are assigned by circle hash out of the following list:

362

485

363```

486```

364> = + - } ) , . " ' ^ $ % & @

487> = + - } ) , . " ' ^ $ % & @

@@ -367,19 +490,51 @@ Glyphs are assigned by circle hash out of the following list

367Alphanumeric characters and `|#;:*~_` are reserved; all others (the

490Alphanumeric characters and `|#;:*~_` are reserved; all others (the

368above list, and `\/!?({<`) can be manually assigned.

491above list, and `\/!?({<`) can be manually assigned.

369

492

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 =

370−###### `;bind + /urbit-test`

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

371

517

372−Assigns the `+` glyph to `/urbit-test`.

518+Syntax: `;bind [glyph] /circle-name`

373

519

374−###### `;unbind + /urbit-test`

520+Assigns the chosen glyph to a circle owned by your ship.

375

521

376−Unassigns the `+` glyph from `/urbit-test`.

522+For example:

377

523

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:

379

535

380```

536```

381−;what +

537+~sampel-palnet:talk> ;unbind + /my-circle

382−/urbit-test

383```

538```

384

539

385### Prefixes

540### Prefixes

@@ -395,44 +550,39 @@ There are a few special-purpose glyphs:

395- `;` - Posts to you and others (a multiparty conversation)

550- `;` - Posts to you and others (a multiparty conversation)

396- `*` - Posts to a complex audience that doesn't directly include you.

551- `*` - Posts to a complex audience that doesn't directly include you.

397

552

398−#### Prompt

399

553

400−The audience you're sending to is always shown in your prompt. If

554+### Configuration

401−there's a glyph for it, it's shown as the glyph.

402

555

403−Here we're talking to the station bound to `=`:

556+###### Set Audience

404

557

405−```

558+`;~ship/circle`

406−~your-urbit:talk=

407−```

408−

409−Here we're talking directly to `~dannum-mitryl`:

410

559

411−```

560+Set audience to `~ship/circle`.

412−~your-urbit:talk[~dannum-mitryl]

413−```

414

561

415−#### Configuration

562+###### Set Audience by Glyph

416

563

417−###### `;~urbit/circle`

564+Syntax: `;[glyph]`

418

565

419−Set audience to `~urbit/circle`.

566+Set audience to the circle previously bound to the chosen glyph.

420

567

421−###### `;=`

568+###### Set Audience to Ship

422

569

423−Set audience to the station bound to the `=` glyph

570+syntax `;~ship`

424

571

425−###### `;~dannum-mitryl`

572+Set audience to another ship.

426

573

427−Set audience to `~dannum-mitryl` (a direct post).

574+###### Set Audience to Own Circle

428

575

429−###### `;%circle`

576+Syntax: `;%circle`

430

577

431Set audience to a circle on your own ship

578Set audience to a circle on your own ship

432

579

580+###### Set Audience + Send Message

581+

433−###### `;~dannum-mitryl this is a private message`

582+Syntax: `;~dannum-mitryl this is a private message`

434

583

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.

436

586

437Your audience is configured with regard to the following rules (in order):

587Your audience is configured with regard to the following rules (in order):

438

588

@@ -442,34 +592,48 @@ Your audience is configured with regard to the following rules (in order):

442

592

443### Local nicknames

593### Local nicknames

444

594

595+###### See Nicknames

596+

445−###### `;nick`

597+Syntax: `;nick`

446

598

447List all local nicknames.

599List all local nicknames.

448

600

601+###### Find Nickname

602+

449−###### `;nick ~some-urbit`

603+Syntax: `;nick ~some-urbit`

604+

605+Look up a nickname using the known ship-name.

606+

607+###### Reverse Find Nickname

450

608

451−Look up a nickname.

609+syntax: `;nick plato`

452

610

453−###### `;nick plato`

611+Find a ship's name using its nickname.

454

612

455−Search in reverse.

613+###### Set Nickname

456

614

457−###### `;nick ~some-urbit plato`

615+Syntax: `;nick ~some-urbit plato`

458

616

459−Create a nickname.

617+Create a new nickname.

460

618

619+###### Clear Nickname

620+

461−###### `;nick ~some-urbit ~`

621+Syntax: `;nick ~some-urbit ~`

462

622

463Clear an assigned nickname.

623Clear an assigned nickname.

464

624

625+###### Display Nicks, Not Ship-Names

626+

465−###### `;set nicks`

627+Syntax: `;set nicks`

466

628

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

468that user's handle. If the user has no handle, just the urbit name.

630that user's handle. If the user has no handle, just the urbit name.

469

631

632+###### Display Ship-Names, Not Nicks

633+

470−###### `;unset nicks`

634+Syntax: `;unset nicks`

471

635

472−Show urbit names instead of nicknames.

636+Show ship-names instead of nicknames.

473

637

474Nicknames and handles longer than 14 character will be truncated in

638Nicknames and handles longer than 14 character will be truncated in

475output. Nicknames are strictly local - like the names on entries in a

639output. Nicknames are strictly local - like the names on entries in a

@@ -477,28 +641,40 @@ phonebook.

477

641

478### Miscellaneous configuration

642### Miscellaneous configuration

479

643

644+###### Show Timestamps

645+

480−###### `;set showtime`

646+Syntax: `;set showtime`

481

647

482Show the timestamp for each message.

648Show the timestamp for each message.

483

649

650+###### Hide Timestamps

651+

484−###### `;unset showtime`

652+Syntax: `;unset showtime`

485

653

486Stop showing the timestamp for each message.

654Stop showing the timestamp for each message.

487

655

656+###### Change Time Zone

657+

488−###### `;set timezone [+/-][hours]`

658+Syntax: `;set timezone [+/-][hours]`

489

659

490Adjust the display of the timestamps to a specific timezone. Relative to UTC.

660Adjust the display of the timestamps to a specific timezone. Relative to UTC.

491

661

662+###### Sound Notification On

663+

492−###### `;set notify`

664+Syntax: `;set notify`

493

665

494Emit a terminal bell sound if your six-syllable ship name is mentioned in

666Emit a terminal bell sound if your six-syllable ship name is mentioned in

495a message.

667a message.

496

668

669+###### Sound Notification Off

670+

497−###### `;unset notify`

671+Syntax `;unset notify`

498

672

499Do not notify when your ship name is mentioned.

673Do not notify when your ship name is mentioned.

500

674

675+###### Set Width

676+

501−###### `;set width [number]`

677+Syntax: `;set width [number]`

502

678

503Set the rendering width of `:talk` to a specific number of characters.

679Set the rendering width of `:talk` to a specific number of characters.

504(Minimum of 30.)

680(Minimum of 30.)

docs/using/setup.umd+91−66

@@ -8,18 +8,18 @@

9# Getting started

11−On disk your urbit is an append-only log and a checkpoint. Or, in

11+On disk, your urbit - also referred to as your _ship_ - is an append-only log

12−simpler terms, a directory where we keep your urbit’s state. We call

12+and a checkpoint. Or, in simpler terms, a directory where we keep your urbit’s

13−this a _pier_.

13+state. We call this a _pier_.

15## Initialize

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

18address and a memorable name.

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_

21or 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/).

24If you have an Urbit invitation, you'll have a planet like

25`~sampel-palnet` and `~sampel-sompel-simpel-sampel`. To create your

@@ -29,37 +29,58 @@ pier:

29$ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel

30```

32−This will create a directory `sampel-palnet/` and begin building your

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+

33−urbit. This may take a few minutes.

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.

35> If you are booting a star, the process is the same as above, with your

47> If you are booting a star, the process is the same as above, with your

36−> respective star name and ticket.

48+ respective star name and ticket.

37−> If you are booting a galaxy, see

49+ If you are booting a galaxy, see

38−> [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).

50+ [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).

40−If you do not have a ticket, you can still make a _comet_, a wild urbit

52+If you do not have a ticket, you can still make a comet that stays as a comet.

41−drifting through cyberspace. Pick your own directory name, it doesn't

53+Pick your own directory name, it doesn't matter:

42−matter:

44```

55```

45$ urbit -c mycomet

56$ urbit -c mycomet

46```

57```

48This will create the directory `mycomet/` and generate a 128-bit

59This 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.

51## Orientation

64## Orientation

53−After about five to ten minutes, when your urbit is finished booting,

66+Booting your urbit takes about ten minutes. After that, you should see a `dojo>`

54−you should see a `dojo>` prompt. Welcome!

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.

56−By default your urbit is quite bare-bones. Let's stroll through what's

76+Your ship is quite bare-bones by default. A few user-facing apps are running by

57−already running:

77+default: *Dojo*, our shell; *Talk*, our messaging app; *Clay*, our filesystem;

78+*Tree*, our web interface. Let's stroll through them.

59### Shell — Dojo

80### Shell — Dojo

61−The command prompt in front of you is a simple shell and Hoon REPL.

82+The command prompt in front of you is a simple shell and Hoon REPL. Let's make

62−Let's make sure it works:

83+sure it works:

64```

85```

65~your-urbit:dojo> (add 2 2)

86~your-urbit:dojo> (add 2 2)

@@ -74,10 +95,33 @@ Should produce:

75Good.

96Good.

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.

121

78### Messaging — Talk

122### Messaging — Talk

123

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

81channel, `/urbit-meta`:

125channel, `/urbit-meta`:

126

83```

127```

@@ -88,18 +132,24 @@ Talk is stateful, so your urbit will download a backlog.

88`/urbit-meta` is the place to ask questions, get help, talk about

132`/urbit-meta` is the place to ask questions, get help, talk about

89anything Urbit-related, and meet everyone on here.

133anything Urbit-related, and meet everyone on here.

134

135+For more information on the Dojo, check out the [Shell](../shell) section.

136+

91### Web — Tree

137### Web — Tree

138

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

94running Urbit locally on your own machine, try opening:

140running Urbit locally on your own machine, try opening:

141

96```

142```

97http://localhost:8080/~~/

143http://localhost:8080/~~/

98```

144```

145

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.

101

151

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

103address (which we recommend!), something like `212.131.240.20`, assuming

153address (which we recommend!), something like `212.131.240.20`, assuming

104you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443`

154you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443`

105by default), try opening:

155by default), try opening:

@@ -109,10 +159,10 @@ by default), try opening:

109http://212.131.240.20:8080/~~/

159http://212.131.240.20:8080/~~/

110```

160```

111

161

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

113in a [`screen`](https://www.gnu.org/software/screen/) or

163in a [`screen`](https://www.gnu.org/software/screen/) or

114[`tmux`](https://github.com/tmux/tmux/wiki) session), you can always

164[`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

116as you have your password on hand.

166as you have your password on hand.

117

167

118The `/~~/` in the URL will redirect you to a login page, which was

168The `/~~/` 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

124bar at the top of the page to visit your Talk web interface and static

174bar at the top of the page to visit your Talk web interface and static

125files.

175files.

126

176

127−You can also access your urbit through

177+You can also access your ship through `https://your-urbit.urbit.org/~~/`. Note

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,

178+that this latter approach is slower for the time being because we proxy over the

130−but a better, faster solution for this is in the works.

179+Urbit network, Ames, 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:

142

180

143−```

181+For more information on Tree, check out the [Web](../web) section.

144−> |mount %

145−>=

146−```

147

182

148−which indicates the command was processed.

149

183

150−`|mount %` will cause a `home/` directory to appear inside your pier

184+---

151−folder. Changes to these files are automatically synced into your urbit.

152

185

153−<br />

154

186

155Here are a few other things you can do to get up and running:

187Here are a few other things you can do to get up and running:

156

188

189+

157### Discussion — Fora

190### Discussion — Fora

158

191

159−Fora is the place for long-form Urbit discussion. It's hosted on an

192+Fora is the place for long-form Urbit discussion, our take on the message

160−Urbit and served over HTTP via Eyre, Urbit's web server.

193+board. It's hosted on an Urbit and served over HTTP via [Eyre](../web), Urbit's

194+web server.

161

195

162Head on over to:

196Head on over to:

163

197

@@ -166,7 +200,7 @@ https://fora.urbit.org/~~/

166```

200```

167

201

168Like on your own web interface, you'll be redirected to a login page and

202Like 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

170in.

204in.

171

205

172After loading, you'll get redirected to the Fora home page where you

206After loading, you'll get redirected to the Fora home page where you

@@ -178,8 +212,8 @@ see what's going on.

178

212

179We host our docs on `urbit.org`, but it's faster to view them locally

213We host our docs on `urbit.org`, but it's faster to view them locally

180through your own ship's web interface. So we also host the docs on a

214through 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

215+Clay desk on one of our `urbit.org` planets named `~ladnub-lorwyn`, which you

182−sync onto your live ship over the network.

216+can merge and sync onto your live ship over the network.

183

217

184Run in your Dojo:

218Run in your Dojo:

185

219

@@ -209,18 +243,9 @@ http://localhost:8080/~~/docs

209We'll update our planet's desk with new doc changes as they happen. You

243We'll update our planet's desk with new doc changes as they happen. You

210should get sync updates automatically through Clay over Ames.

244should get sync updates automatically through Clay over Ames.

211

245

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−

221## Learn more

246## Learn more

222

247

223−If you're eager to get started programming you're ready to head over to

248+If you're eager to get started programming, you're ready to head over to

224−[the Hoon section](../../hoon/mission/).

249+[the Hoon tutorial](../../tutorials/hoon-ch1/).

225

250

226To learn more about using the system, let's keep going:

251To learn more about using the system, let's keep going:

docs/using/shell.umd+71−25

@@ -11,23 +11,29 @@

11;div(class "row")

12 ;div(class "col-md-8")

14+The Dojo is our shell; it processes system commands and returns output. It's a

14−The Dojo is the place to quickly experiment with Urbit. On the

15+good place to quickly experiment with Urbit. On the surface the Dojo is just a

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.

16+Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

17+data in Urbit.

18 ==

19 ==

19==

20==

21## Quickstart

22## Quickstart

24+You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system

25+commands.

26+

27+##### Math

28+

23−Evaluate a hoon expression (whitespace matters):

29+Evaluate a Hoon expression (whitespace matters):

25```

31```

26~your-urbit:dojo> (add 2 2)

32~your-urbit:dojo> (add 2 2)

27~your-urbit:dojo> %+ add 2 2

33~your-urbit:dojo> %+ add 2 2

28```

34```

30−Tall form Hoon may require multiple lines:

36+Tall-form Hoon may require multiple lines:

32```

38```

33~your-urbit:dojo> %+ add

39~your-urbit:dojo> %+ add

@@ -35,19 +41,30 @@ Tall form Hoon may require multiple lines:

35~your-urbit:dojo< 2

41~your-urbit:dojo< 2

36```

42```

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+

38−Use `=var` to save a shell variable:

48+Use `=var` to save variable to the Dojo subject.

40```

50```

41~your-urbit:dojo> =foo (add 2 2)

51~your-urbit:dojo> =foo (add 2 2)

42```

52```

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+

44Use `=dir` to set the current working directory:

60Use `=dir` to set the current working directory:

46```

62```

47~your-urbit:dojo> =dir %/web

63~your-urbit:dojo> =dir %/web

48```

64```

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))

52Generators (files in `/gen`) are run with `+`:

69Generators (files in `/gen`) are run with `+`:

@@ -67,54 +84,76 @@ Run system commands from `:hood`, like `reload`, using `|`:

67~your-urbit:dojo> |reload %eyre

84~your-urbit:dojo> |reload %eyre

68```

85```

87+`_See the [Clay](../fileystem) page for more information on system commands.`

88+

70### Generators

89### Generators

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+

72−**`+cat`** - Similar to Unix `cat`. Accepts a path.

95+`+cat` - Accepts a path and displays the file. Similar to Unix `cat`.

74```

97```

75~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon

98~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon

76```

99```

100

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`.

109

80```

110```

81~your-urbit:dojo> +curl "http://nyt.com"

111~your-urbit:dojo> +curl "http://nyt.com"

82```

112```

113

84−**`+hello`** - Just prints the argument. Accepts a `@ta`.

114+`+hello` - Just prints the argument. Accepts a `@ta`.

115

86```

116```

87~your-urbit:dojo> +hello 'mars'

117~your-urbit:dojo> +hello 'mars'

88```

118```

119

90−**`+ls`** - Similar to Unix `ls`. Accepts a path.

120+`+ls` - Similar to Unix `ls`. Accepts a path.

121

92```

122```

93~your-urbit:dojo> +ls %/web

123~your-urbit:dojo> +ls %/web

94~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

124~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

95```

125```

126

97−**`+moon`** - Generate a random moon from a planet. No arguments.

127+`+moon` - Generates a random moon from a planet. No arguments.

128

99```

129```

100~your-urbit:dojo> +moon

130~your-urbit:dojo> +moon

101```

131```

102

132

103−**`+solid`** - Compile the current state of the kernel and output a

133+`+solid` - Compile the current state of the kernel and output a

104noun. Usually downloaded to a file in unix. No arguments.

134noun. Usually downloaded to a file in unix. No arguments.

105

135

136+

106```

137```

107~your-urbit:dojo> .urbit/pill +solid

138~your-urbit:dojo> .urbit/pill +solid

108```

139```

109

140

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+

110−**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name

148+`+ticket` - Generate a ticket for an Urbit plot. Takes an Urbit name

111(`@p`).

149(`@p`).

112

150

151+

113```

152```

114~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

153~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

115```

154```

116

155

117−**`+tree`** - Generate a recursive directory listing. Takes a path.

156+`+tree` - Generate a recursive directory listing. Takes a path.

118

157

119```

158```

120~your-urbit:dojo> +tree %/web

159~your-urbit:dojo> +tree %/web

@@ -124,28 +163,28 @@ noun. Usually downloaded to a file in unix. No arguments.

124

163

125The hood is the system daemon. See `gen/hood` and `app/hood`.

164The hood is the system daemon. See `gen/hood` and `app/hood`.

126

165

127−**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts

166+`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts

128an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

167an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

129

168

130```

169```

131~your-urbit:dojo> |hi ~binzod "you there?"

170~your-urbit:dojo> |hi ~binzod "you there?"

132```

171```

133

172

134−**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an

173+`|link` / `|unlink - Link / unlink a remote app. Accepts an

135Urbit name and an app name.

174Urbit name and an app name.

136

175

137```

176```

138~your-urbit:dojo> |link ~talsur-todres %octo

177~your-urbit:dojo> |link ~talsur-todres %octo

139```

178```

140

179

141−**`|mass`** - Prints the current memory usage of all the kernel modules.

180+`|mass` - Prints the current memory usage of all the kernel modules.

142No arguments.

181No arguments.

143

182

144```

183```

145~your-urbit:dojo> |mass

184~your-urbit:dojo> |mass

146```

185```

147

186

148−**`|reload`** - Reloads a kernel module (vane) from source. Accepts any

187+`|reload` - Reloads a kernel module (vane) from source. Accepts any

149number of vane names.

188number of vane names.

150

189

151```

190```

@@ -180,9 +219,9 @@ command.

180

219

181### Sinks

220### Sinks

182

221

183−#### `=` - Set variable

222+##### `=` - Set variable

184

223

185−Set any envronment variable:

224+Set any environment variable:

186

225

187```

226```

188~your-urbit:dojo> =foo 42

227~your-urbit:dojo> =foo 42

@@ -191,7 +230,12 @@ Set any envronment variable:

19144

23044

192```

231```

193

232

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+

194−(There are a few special variables that the dojo maintains. See below.)

238+There are a few special variables that the dojo maintains.

195

239

196#### `:` - Send to app

240#### `:` - Send to app

197

241

@@ -203,7 +247,7 @@ Send a `helm-hi` message to `hood`:

203~your-urbit:dojo> :hood &helm-hi 'hi'

247~your-urbit:dojo> :hood &helm-hi 'hi'

204```

248```

205

249

206−App usually expect marked data, so `&` is often used here.

250+Apps usually expect marked data, so `&` is often used here.

207

251

208#### `*` - Save in `%clay`

252#### `*` - Save in `%clay`

209

253

@@ -360,14 +404,16 @@ The current urbit plot. Read-only.

360

404

361#### `eny`

405#### `eny`

362

406

363−256 bits of entropy. Read-only.

407+512 bits of entropy. Read-only.

364

408

365**Example:**

409**Example:**

366

410

367```

411```

368~your-urbit:dojo> eny

412~your-urbit:dojo> eny

369:: produces

413:: 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+\/

371```

417```

372

418

373## Troubleshooting

419## Troubleshooting

docs/using/web.umd+164−47

@@ -11,32 +11,73 @@

11;div(class "row")

12 ;div(class "col-md-8")

14+Your Urbit runs its own webserver, Eyre, that handles all things HTTP. Here

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.

15+we'll cover the features of Eyre that most resemble a traditional web server.

17+By default Eyre uses *Tree*. Tree is a simple ui for browsing the contents of

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.

18+the filesystem, statically publishing a blog or any kind of content and for

19+running single-page apps.

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.

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).

22 ==

29 ==

23==

30==

25## Quickstart

32## Quickstart

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.

29−;span(class "red")

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+

30−; (Make sure you have a desk mounted to unix, as covered in the [filesystem walkthrough](/docs/using/filesystem)).

45+_(Make sure you have a desk mounted to unix, as covered in the

31−==

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.

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`:

35```

57```

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=

37```

69```

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+

39−To host a file on the web try putting the following in `/sandbox/web/test.umd` (from Unix):

79+To host a file on the web, save the following in `/sandbox/web/test.umd` in your

80+ship's pier through unix.

41```

82```

42# Hello

83# Hello

@@ -44,9 +85,20 @@ To host a file on the web try putting the following in `/sandbox/web/test.umd` (

44This is a simple Urbit markdown file.

85This is a simple Urbit markdown file.

45```

86```

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!

99+> NOTE: Due to a bug in Urbit, you may have to create the directory and the file

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`.

100+ in it in rapid succession using something like `mkdir sandbox/web/test && touch

101+ sandbox/web/test/first.md`.

102

51Now modify `/sandbox/web/test.umd` to list the children using `;list;`:

103Now modify `/sandbox/web/test.umd` to list the children using `;list;`:

104

@@ -76,21 +128,28 @@ To view your file as raw `html`:

76http://localhost:8080/test.html

128http://localhost:8080/test.html

77```

129```

130

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:

132

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+```

136

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.

140

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.

145

87−;list;

146

89## Manual

147## Manual

148

91## `/web`

149## `/web`

150

151+This is the equivalent of a `public_html` directory. Your Urbit looks in this

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`.

152+directory to serve content to the world. You can change what desk you're serving from using `|serve`.

153

95Switch to the `%sandbox` desk:

154Switch to the `%sandbox` desk:

155

@@ -116,27 +175,46 @@ Let's quickly step through the default contents of `web/`:

116

175

117## Tree

176## Tree

118

177

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.

120

184

185+Tree is also the basic UI for browsing the filesystem. We take it one step

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.

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.

122

188

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.

124

194

195+Your Urbit comes with a pre-built copy of the tree (as a single `.js` file). If

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).

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).

126

199

127## `/web/pages`

200## `/web/pages`

128

201

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.

130

204

131## Publishing files

205## Publishing files

132

206

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.

134

209

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).

136

213

137## Frontmatter

214## Frontmatter

138

215

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.:

140

218

141```

219```

142:- :~ navhome/'/home/'

220:- :~ navhome/'/home/'

@@ -149,36 +227,50 @@ Most `.umd` files begin with some frontmatter, which determines the title and ot

149

227

150Here are the fields we support:

228Here are the fields we support:

151

229

152−### `title`

230+##### title

153

231

154String. Example: `title/'Tree manual'`.

232String. Example: `title/'Tree manual'`.

155

233

156This sets the title in the nav or in lists as distinct from the filename.

234This sets the title in the nav or in lists as distinct from the filename.

157

235

158−### `next`

236+##### next

159

237

160Boolean. Example: `next/'true'`

238Boolean. Example: `next/'true'`

161

239

162Adds a 'next' link at the bottom of the page that links to the next item as decided by the sort order.

240Adds a 'next' link at the bottom of the page that links to the next item as decided by the sort order.

163

241

164−### `sort`

242+##### sort

165

243

166Integer. Example: `sort/'7'`

244Integer. Example: `sort/'7'`

167

245

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.

169

248

170−### `hide`

249+##### hide

171

250

172Boolean. Example: `hide/'true'`

251Boolean. Example: `hide/'true'`

173

252

174Whether or not to hide the item from the tree.

253Whether or not to hide the item from the tree.

175

254

176−### `date`

255+##### date

177

256

178Urbit date. Example: `date/'~2016.2.22'`

257Urbit date. Example: `date/'~2016.2.22'`

179

258

180Used for sorting posts by date.

259Used for sorting posts by date.

181

260

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+

182## Using components

274## Using components

183

275

184Tree 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.

276Tree 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:

252]}

344]}

253```

345```

254

346

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.

256

349

257### Async component

350### Async component

258

351

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.

260

356

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`.

262

363

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`:

264

366

265```

367```

266query {

368query {

@@ -272,11 +374,13 @@ query {

272}

374}

273```

375```

274

376

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.

276

379

277### Module basics

380### Module basics

278

381

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.

280

384

281Talk, for example, looks like this:

385Talk, for example, looks like this:

282

386

@@ -289,29 +393,42 @@ Talk, for example, looks like this:

289</module>

393</module>

290```

394```

291

395

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.

293

401

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).

295

405

296## `urb.js`

406## `urb.js`

297

407

408+The most basic interface between your browser and your Urbit is `urb.js`. This

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.

409+small library provides the basic utilities for sending and receiving messages

410+from an Urbit.

299

411

300### `window.urb.appl`

412### `window.urb.appl`

301

413

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()`.

303

417

304### `window.urb.oryx`

418### `window.urb.oryx`

305

419

420+CSRF token. Written to the page by Eyre, our webserver, when logged in.

306−CSRF token. Written to the page by Eyre, our webserver, when logged in. Required part of any authenticated request and included by default.

421+Required part of any authenticated request and included by default.

307

422

308### `window.urb.req(method,url,params,json,cb)`

423### `window.urb.req(method,url,params,json,cb)`

309

424

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.

311

427

312### `window.urb.subscribe({path:"string"})`

428### `window.urb.subscribe({path:"string"})`

313

429

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.

315

432

316### `window.urb.unsubscribe({path:"string"})`

433### `window.urb.unsubscribe({path:"string"})`

317

434

@@ -319,7 +436,7 @@ Close subscription on specified path.

319

436

320### `window.urb.poll()`

437### `window.urb.poll()`

321

438

322−Mechanics of the continuous long poll. Used mostly internally.

439+Mechanics of the continuous long poll. Used mostly internally.

323

440

324### `window.urb.util`

441### `window.urb.util`

325

442