97e0cdf · urbit.org · git.iko.soy

git.iko.soy/urbit.org

looks ok in an editor

commit97e0cdf87322b8d96cf47396d0b756d3fc4bb9f4 authorGalen Wolfe-Pauly <mailroom@office-for.com> dateTue 22 Mar 2016, 22:49 (11 years ago) parented82126

6 files changed+189−129

compare with master

unifiedsplit

docs/walkthroughs/admin.md+9−10 docs/walkthroughs/filesystem.md+20−24 docs/walkthroughs/shell.md+57−51 docs/walkthroughs/source.md+12−8 docs/walkthroughs/talk.md+23−21 docs/walkthroughs/web.md+68−15

docs/walkthroughs/admin.md+9−10

@@ -9,7 +9,7 @@ title: Basic operation

99<div class="row">

1010<div class="col-md-8">

1111

12−Here we'll cover the basic administrative tasks you'll encounter running your Urbit and the primary interfaces to control it.

12+Your Urbit is a persistent Unix process that you mainly control from the console. For some things, a browser will also work.

1313

1414</div>

1515</div>

@@ -32,7 +32,7 @@ or

3232

3333Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.

3434

35−One unusual part of the Urbit command line is that apps can process your input before you hit return. In general, invalid input is rejected with a beep. To see this in action try entering `)` as the first character at the `:dojo` prompt.

35+In the CLI Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the `:dojo` prompt.

3636

3737`^X` - Switches the prompt between running console apps

3838

@@ -58,15 +58,14 @@ The following emacs-style key bindings are available:

5858 ^U kill to beginning of line

5959 ^Y yank from kill buffer

6060

61−Full coverage of the Urbit shell is covered in the [Shell walkthrough](/docs/walkthroughs/dojo).

61+Full coverage of the Urbit shell, the `:dojo` is covered in the [Shell walkthrough](/docs/walkthroughs/dojo).

6262

6363## Web

6464

65−On startup Urbit tries to bind to `localhost:8080`. If you're already running something on `8080` you'll find your Urbit on `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~fintud-macrep` is also at

66−`fintud-macrep.urbit.org`. Please use this proxy as little as

67−possible; it's not well-optimized.

65+On startup Urbit tries to bind to `localhost:8080`. If you're already running something on `8080` you'll find your Urbit on `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~your-urbit` is also at

66+`your-urbit.urbit.org`.

6867

69−Your Urbit serves a simple homepage from `http://localhost:8080` or `https://fintud-macrep.urbit.org` that should be self-explanatory. Since our HTTPS isn't audited / battle tested we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.

68+Your Urbit serves a simple homepage from `http://localhost:8080` or `https://your-urbit.urbit.org` that should be self-explanatory. Since our HTTPS isn't audited / battle tested we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.

7069

7170A complete walkthrough of the Urbit web interface is [here](/docs/walkthroughs/web).

7271

@@ -76,7 +75,7 @@ Urbit namespace is distributed by having parent nodes sign the keys for child no

7675

7776To generate a random moon from your planet run:

7877

79− ~fintud-macrep:dojo> +moon

78+ ~your-urbit:dojo> +moon

8079

8180You can use the resulting output in the same installation flow from [install](/install).

8281

@@ -86,9 +85,9 @@ Moons are automatically synced to their parent `%kids` desk, and can control app

8685

8786Piers are designed to be portable, but it *must* be done while the Urbit is turned off. Urbit networking is stateful, so you can't run two copies of the same Urbit in two places.

8887

89−To move a pier, simply move the contents of the directory it lives in. To keep these files as small as possible we usually use the `--sparse` option in `tar`. With a pier `fintud-macrep/` something like this (from inside `urbit/`) should work:

88+To move a pier, simply move the contents of the directory it lives in. To keep these files as small as possible we usually use the `--sparse` option in `tar`. With a pier `your-urbit/` something like this (from inside `urbit/`) should work:

9089

91− tar -Scvzf fintud-macrep.tar.gz ./fintud-macrep/

90+ tar -Scvzf your-urbit.tar.gz ./your-urbit/

9291

9392## Continuity breaches

9493

docs/walkthroughs/filesystem.md+20−24

@@ -4,48 +4,44 @@ sort: 3

44title: Filesystem

55---

7−# `%clay` (Filesystem)

8−

9−Urbit has its own revision-controlled filesystem, the `%clay`

10−vane. `%clay` is a typed, global revision-control system. Or in other

11−words, a typed, global referentially transparent namespace.

7+<div class="row">

8+<div class="col-md-8">

129

13−In kernel and userspace code, you can use the Hoon `.^` rune

14−to *dereference* this namespace and treat any data in it as a constant. In userspace code, a

15−generator will even *block* until the resource is available.

10+# `%clay` (Filesystem)

1611

17−Another global immutable namespace is IPFS. But IPFS is

18−distributed, whereas `%clay` is just decentralized. IPFS stores

19−resources around the network in a DHT, like Freenet or

20−Bittorrent; `%clay` stores resources on the publisher's server,

21−like HTTP or git.

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.

2213

2314The most common way to use `%clay` is to mount a `%clay` node in

2415a Unix directory. The Urbit process will watch this directory

2516and automatically record edits as changes, Dropbox style. The

2617mounted directory is always at the root of your pier directory.

2718

19+</div>

20+</div>

21+

2822## Quickstart

2923

30−Most of the time we want to use `%clay` from Unix.

24+When developing it's a good idea to use a separate desk.

3125

32−Mount the entire contents of your `home` desk to Unix:

26+Create a `%sandbox` desk based on the `%home` desk:

3327

34− ~fintud-macrep:dojo>|mount %

28+ |merge %sandbox ~your-urbit %home

3529

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

30+Most of the time we want to use `%clay` from Unix.

31+

32+Mount the entire contents of your `sandbox` desk to Unix:

3733

38− ~fintud-macrep:dojo> +ls /=home=/web

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

3935

40−Let's see the contents of `/=home=/web/md`:

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

4137

42− ~fintud-macrep:dojo> +cat /=home=/web/md

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

4339

44−Create a new desk:

40+Let's see the contents of `/=sandbox=/web/md`:

4541

46− |merge %sandbox ~fintud-macrep %sandbox

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

4743

48−Sync it with a remote desk on the network:

44+Sync with a remote desk on the network:

4945

5046 |sync %sandbox ~wactex-ribmex %examples

5147

@@ -67,7 +63,7 @@ If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,

6763and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of

6864`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.

6965

70−Most commonly this is used to avoid having to know the current revision number in the `dojo`. Instead of writing `/~fintud-macrep/home/4/path/to/file` you can just write `/=home=/path/to/file`.

66+Most commonly this is used to avoid having to know the current revision number in the `dojo`. Instead of writing `/~your-urbit/home/4/path/to/file` you can just write `/=home=/path/to/file`.

7167

7268### Revision-control

7369

docs/walkthroughs/shell.md+57−51

@@ -4,42 +4,48 @@ sort: 2

44title: Shell

55---

7+<div class="row">

8+<div class="col-md-8">

710# `:dojo` (Shell)

811

9−The dojo is a typed functional shell.

12+The `:dojo` is the place to quickly experiment with Urbit. At first glance the `:dojo` is just a Hoon REPL. Looking a bit deeper the `:dojo` is set up to make operating on and transforming data in Urbit easy.

13+

14+</div>

15+</div>

1016

1117## Quickstart

1218

1319Evaluate a hoon expression:

1420

15− ~fintud-macrep:dojo> (add 2 2)

16− ~fintud-macrep:dojo> %+ add 2 2

21+ ~your-urbit:dojo> (add 2 2)

22+ ~your-urbit:dojo> %+ add 2 2

1723

1824Tall form Hoon will be prompted for:

1925

20− ~fintud-macrep:dojo> %+ add

21− ~fintud-macrep:dojo< 2

22− ~fintud-macrep:dojo< 2

26+ ~your-urbit:dojo> %+ add

27+ ~your-urbit:dojo< 2

28+ ~your-urbit:dojo< 2

2329

2430Use `=var` to save a shell variable:

2531

26− ~fintud-macrep:dojo> =foo (add 2 2)

32+ ~your-urbit:dojo> =foo (add 2 2)

2733

2834Use `=dir` to set the current working directory:

2935

30− ~fintud-macrep:dojo> =dir %/web

36+ ~your-urbit:dojo> =dir %/web

3137

3238Generators (files in `/gen`) are run with `+`:

3339

34− ~fintud-macrep:dojo> +hello 'world'

40+ ~your-urbit:dojo> +hello 'world'

3541

3642Save output to a file in `%clay` with `*`:

3743

38− ~fintud-macrep:dojo> *foo/bar/hoon 'hello world'

44+ ~your-urbit:dojo> *foo/bar/hoon 'hello world'

3945

4046Run system commands from `:hood`, like `reload`, using `|`:

4147

42− ~fintud-macrep:dojo> |reload %eyre

48+ ~your-urbit:dojo> |reload %eyre

4349

4450## Manual

4551

@@ -55,8 +61,8 @@ Sources can be chained together, but we can only produce one effect per command.

5561

5662Set any envronment variable:

5763

58− ~fintud-macrep:dojo> =foo 42

59− ~fintud-macrep:dojo> (add 2 foo)

64+ ~your-urbit:dojo> =foo 42

65+ ~your-urbit:dojo> (add 2 foo)

6066

6167 44

6268

@@ -68,7 +74,7 @@ Set any envronment variable:

6874

6975Send a `helm-hi` message to `hood`:

7076

71− ~fintud-macrep:dojo> :hood &helm-hi 'hi'

77+ ~your-urbit:dojo> :hood &helm-hi 'hi'

7278

7379App usually expect marked data, so `&` is often used here.

7480

@@ -76,7 +82,7 @@ App usually expect marked data, so `&` is often used here.

7682

7783Save a new `md` file in `web`:

7884

79− ~fintud-macrep:dojo> *%/web/foo/md '# hello'

85+ ~your-urbit:dojo> *%/web/foo/md '# hello'

8086

8187The last component of the path is expected to be the mark (or mime type).

8288

@@ -84,13 +90,13 @@ The last component of the path is expected to be the mark (or mime type).

8490

8591Download a noun to Unix with `.`:

8692

87− ~fintud-macrep:dojo> .foo/bar/baz (add 2 2)

93+ ~your-urbit:dojo> .foo/bar/baz (add 2 2)

8894

8995Which creates a file at `pier/.urb/put/foo/bar.baz`.

9096

9197This is very often used with `+solid`:

9298

93− ~fintud-macrep:dojo> .urbit/pill +solid

99+ ~your-urbit:dojo> .urbit/pill +solid

94100

95101Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

96102

@@ -100,7 +106,7 @@ Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

100106

101107Convert between marks using `&`:

102108

103− ~fintud-macrep:dojo> &html &md '# hello'

109+ ~your-urbit:dojo> &html &md '# hello'

104110 :: produces

105111 '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'

106112

@@ -109,11 +115,11 @@ Convert between marks using `&`:

109115Use `_` to run a gate (or function):

110116

111117 :: assign an arbitrary function and pass data to it

112− ~fintud-macrep:dojo> _|=({a/@} (mul a 3)) 3

118+ ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3

113119 :: produces

114120 9

115121 :: assign an arbitrary function to get the status code from an http request

116− ~fintud-macrep:dojo> _|=({p/@ud q/* r/*} p) +http://google.com

122+ ~your-urbit:dojo> _|=({p/@ud q/* r/*} p) +http://google.com

117123 :: produces

118124 301

119125

@@ -131,9 +137,9 @@ Generators are simple hoon scripts loaded from the filesystem. They live in `ge

131137

132138Create a random moon (from any planet):

133139

134− ~fintud-macrep:dojo> +moon

140+ ~your-urbit:dojo> +moon

135141 :: produces

136− "moon: ~docsun-tamtem-fintud-macrep; ticket: ~bartug-hodbyr-fognum-ralmud"

142+ "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"

137143

138144### Variables

139145

@@ -145,8 +151,8 @@ Current working `%clay` desk and revision. Read / write.

145151

146152**Examples:**

147153

148− ~fintud-macrep:dojo> =dir %/web

149− ~fintud-macrep:dojo> +ls %

154+ ~your-urbit:dojo> =dir %/web

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

150156

151157 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/

152158

@@ -156,11 +162,11 @@ Current set of libraries (`/lib`) in your environment. Can also be set with `/+

156162

157163**Examples:**

158164

159− ~fintud-macrep:dojo> =lib ~[[%react ~]]

160− ~fintud-macrep:dojo> :: this also works:

161− ~fintud-macrep:dojo> /+ react

162− ~fintud-macrep:dojo> :: now we can use arms from lib/react.hoon

163− ~fintud-macrep:dojo> (react-vale:react %div)

165+ ~your-urbit:dojo> =lib ~[[%react ~]]

166+ ~your-urbit:dojo> :: this also works:

167+ ~your-urbit:dojo> /+ react

168+ ~your-urbit:dojo> :: now we can use arms from lib/react.hoon

169+ ~your-urbit:dojo> (react-vale:react %div)

164170

165171#### `sur`

166172

@@ -168,11 +174,11 @@ Current set of structures (`/sur`) in your environment. Can also be set with `/

168174

169175**Examples:**

170176

171− ~fintud-macrep:dojo> =sur ~[[%sole ~]]

172− ~fintud-macrep:dojo> :: this also works:

173− ~fintud-macrep:dojo> /- sole

174− ~fintud-macrep:dojo> :: now we can use arms in sur/sole.hoon

175− ~fintud-macrep:dojo> `sole-effect:sole`[%bel ~]

177+ ~your-urbit:dojo> =sur ~[[%sole ~]]

178+ ~your-urbit:dojo> :: this also works:

179+ ~your-urbit:dojo> /- sole

180+ ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon

181+ ~your-urbit:dojo> `sole-effect:sole`[%bel ~]

176182

177183#### `now`

178184

@@ -180,7 +186,7 @@ The current (128-bit `@da`) time. Read-only.

180186

181187**Example:**

182188

183− ~fintud-macrep:dojo> now

189+ ~your-urbit:dojo> now

184190 :: produces

185191 ~2016.3.21..21.10.57..429a

186192

@@ -190,9 +196,9 @@ The current urbit plot. Read-only.

190196

191197**Example:**

192198

193− ~fintud-macrep:dojo> our

199+ ~your-urbit:dojo> our

194200 :: produces

195− ~fintud-macrep

201+ ~your-urbit

196202

197203#### `eny`

198204

@@ -200,7 +206,7 @@ The current urbit plot. Read-only.

200206

201207**Example:**

202208

203− ~fintud-macrep:dojo> eny

209+ ~your-urbit:dojo> eny

204210 :: produces

205211 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o

206212

@@ -208,35 +214,35 @@ The current urbit plot. Read-only.

208214

209215**`+cat`** - Similar to Unix `cat`. Accepts a path.

210216

211− ~fintud-macrep:dojo> +cat %/web/md

212− ~fintud-macrep:dojo> +cat /~talsur-todres/home/2/web/notes/md

217+ ~your-urbit:dojo> +cat %/web/md

218+ ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md

213219

214220**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.

215221

216− ~fintud-macrep:dojo> +curl "http://nyt.com"

222+ ~your-urbit:dojo> +curl "http://nyt.com"

217223

218224**`+hello`** - Just prints the argument. Accepts a `@ta`.

219225

220− ~fintud-macrep:dojo> +hello 'mars'

226+ ~your-urbit:dojo> +hello 'mars'

221227

222228**`+ls`** - Similar to Unix `ls`. Accepts a path.

223229

224− ~fintud-macrep:dojo> +ls %/web

225− ~fintud-macrep:dojo> +ls /~talsur-todres/home/2/web/notes

230+ ~your-urbit:dojo> +ls %/web

231+ ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

226232

227233**`+moon`** - Generate a random moon from a planet. No arguments.

228234

229235**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.

230236

231− ~fintud-macrep:dojo> .urbit/pill +solid

237+ ~your-urbit:dojo> .urbit/pill +solid

232238

233239**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).

234240

235− ~fintud-macrep:dojo> +ticket ~talsur-todres-fintud-macrep

241+ ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

236242

237243**`+tree`** - Generate a recursive directory listing. Takes a path.

238244

239− ~fintud-macrep:dojo> +tree %/web

245+ ~your-urbit:dojo> +tree %/web

240246

241247### Hood

242248

@@ -244,20 +250,20 @@ The hood is the system daemon. See `gen/hood` and `app/hood`.

244250

245251**`|hi`** - Sends a direct message. Sort of like `finger`. Accepts an urbit name (`@p`) and a string (`cord`).

246252

247− ~fintud-macrep:dojo> |hi ~doznec 'you there?'

253+ ~your-urbit:dojo> |hi ~doznec 'you there?'

248254

249255**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.

250256

251− ~fintud-macrep:dojo> |link ~talsur-todres %octo

257+ ~your-urbit:dojo> |link ~talsur-todres %octo

252258

253259**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.

254260

255261**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.

256262

257− ~fintud-macrep:dojo> |reload %clay %eyre

263+ ~your-urbit:dojo> |reload %clay %eyre

258264

259265**`|reset`** - Reloads `hoon.hoon`. No arguments.

260266

261267**`|start`** - Starts an app. Accepts an app name.

262268

263− ~fintud-macrep:dojo> |start %curl

269+ ~your-urbit:dojo> |start %curl

docs/walkthroughs/source.md+12−8

@@ -3,10 +3,16 @@ sort: 6

33title: Arvo source

44---

6+<div class="row">

7+<div class="col-md-8">

69# Arvo source

710

811When you boot an Urbit we transfer the current version of the Arvo operating environment to your Urbit over our network. That is, the source for the system lives on your Urbit. Here we'll take a brief tour through the structure of a base Arvo desk.

912

13+</div>

14+</div>

15+

1016Looking at the top level of [the Arvo repo](http://github.com/urbit/arvo), or any Urbit desk that has been mounted to Unix we see something like:

1117

1218 app/

@@ -24,7 +30,7 @@ Let's step through directory by directory.

2430

2531## `app/`

2632

27−This is where `%gall` apps live. `%gall` apps are stateful servers, sort of like unix daemons. One very familiar one is `app/talk.hoon` which is the source code for `:talk` the urbit messaging transport layer. And there's also `app/dojo.hoon` — that's your shell.

33+This is where `%gall` apps live. `%gall` apps are stateful servers, sort of like unix daemons. One familiar one is `app/talk.hoon` which is the source code for `:talk` the urbit messaging transport layer. And there's also `app/dojo.hoon` — that's your shell.

2834

2935## `arvo/`

3036

@@ -60,7 +66,7 @@ This is where the `%arvo` vanes live. Vanes are sort of like kernel modules. Th

6066

6167### `arvo/hoon.hoon`

6268

63−`%hoon` is our programming langauge. Since Hoon compiles itself the language is actually specified in its source.

69+`%hoon` is our programming langauge. Since Hoon compiles itself the language is actually specified in this source file.

6470

6571### `arvo/zuse.hoon`

6672

@@ -70,7 +76,7 @@ That's it. That's the whole system.

7076

7177## `gen/`

7278

73−`gen/` holds generators. Generators are command-line scripts.

79+`gen/` holds generators. Generators are short `:dojo` scripts.

7480

7581## `lib/`

7682

@@ -78,7 +84,7 @@ That's it. That's the whole system.

7884

7985## `mar/`

8086

81−This is where marks live. Marks are data type definitions used by `%ford`. A mark is like a mime-type, but precisely specified in executable code.

87+This is where marks live. Marks are data type definitions used by `%ford`. A mark is like a mime-type, but specified in executable code.

8288

8389## `ren/`

8490

@@ -88,9 +94,7 @@ Default web requets in urbit are handled as a `.urb`, which is caught by the `ur

8894

8995## `sur/`

9096

91−`sur/` contains shared data structures.

92−

93−Files in `sur` are like headers in C.

97+`sur/` contains shared data structures. Files in `sur` are like header files in C.

9498

9599## `web/`

96100

@@ -98,5 +102,5 @@ There are the files publicly accessible to the web, as made possible by `%eyre`.

98102

99103## `web.md`

100104

101−This is the homepage for your urbit. You'll see it at `http://localhost:8080/` or `http://your-urbit.urbit.org/`.

105+This is the homepage for your urbit. You'll see it at `http://localhost:8080/` or `http://fintud-macrep.urbit.org/`.

102106

docs/walkthroughs/talk.md+23−21

@@ -11,13 +11,11 @@ title: Talk manual

1111

1212`:talk` is the Urbit messaging and notifications protocol. Today we use `:talk` to chat and coordinate. Come join us in `/urbit-meta` by using the [quickstart](#-quickstart) below.

1313

14−Today chat is sort of like a distributed, encrypted Slack that can be used from the CLI and the browser. This is the simplest, most immediate use for `:talk`, but we hope it can become much more than just persistent IRC. `:talk` is a general purpose tool for both aggregating and publishing heterogenous streams of messages. Applications can use `:talk` as their transport protcol, API connectors can push disparate data sources into `:talk`, and so on. There are lots of things a distributed message protocol can be used for that we haven't even thought of.

14+Today chat is sort of like a distributed, encrypted Slack that can be used from the CLI and the browser. There’s no central `:talk` server. Any Urbit can host one.

1515

16−`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet. Let's briefly outline the design: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations. There’s no central `:talk` server. Any Urbit can host one. There are four kinds of station: a write-only `%mailbox` for direct messages, an invite-only `%party` for private conversation, a read-only `%journal` for curated content, and a public-access `%board` for general use.

16+`:talk` is a general purpose tool for both aggregating and publishing streams of messages. Applications can use `:talk` as their transport protcol, API connectors can push disparate data sources into `:talk`, and so on. There are lots of things a distributed message protocol can be used for that we haven't even thought of.

1717

18−There are two ways of using `:talk`: from the CLI or through a web interface available at `http://localhost:8080/talk` (or equivalent). The web interface ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).

19−

20−The web interface doesn't expose *all* the functionality of the CLI, and it's more or less self-explanatory. This document pertains primarily to the CLI.

18+There are two ways of using `:talk`: from the CLI or through a web ui available at `http://your-urbit.urbit.org/talk` (or `http://localhost:8080/talk`). The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).

2119

2220</div>

2321</div>

@@ -28,7 +26,7 @@ For the most part we use `:talk` as a single-instance of Slack. There's one mai

2826

2927Let's join `/urbit-meta`:

3028

31− ~fintud-macrep: ;join ~doznec/urbit-meta

29+ ~your-urbit: ;join ~doznec/urbit-meta

3230

3331You'll see:

3432

@@ -36,35 +34,39 @@ You'll see:

3634 ---------:talk| rules of /urbit-meta:

3735 ---------:talk| don't be rude

3836 ---------:talk| urbit-meta is politically correct and safe for work

39− ~doznec= ~fintud-macrep admitted to %urbit-meta

40− ~fintud-macrep:talk>

37+ ~doznec= ~your-urbit admitted to %urbit-meta

38+ ~your-urbit:talk>

4139

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

4341

44− ~fintud-macrep:talk> hello, world

42+ ~your-urbit:talk> hello, world

4543

4644You'll see, echoed back at you through `~doznec`:

4745

48− ~fintud-macrep> hello, world

46+ ~your-urbit> hello, world

4947

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

5149

52− ~fintud-macrep:talk> ;~talsur-todres

50+ ~your-urbit:talk> ;~talsur-todres

5351

5452You'll see your prompt change:

5553

56− ~fintud-macrep:talk[~talsur-todres]

54+ ~your-urbit:talk[~talsur-todres]

5755

5856Now you and `~talsur-todres` can exchange messages directly.

5957

6058To set your audience back to `/urbit-meta`:

6159

62− ~fintud-macrep:talk> ;~doznec/urbit-meta

63−

64−Those are the basics, and the rest is covered below.

60+ ~your-urbit:talk> ;~doznec/urbit-meta

6561

6662## Manual

6763

64+`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet.

65+

66+Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.

67+

68+There are four kinds of station: a write-only `%mailbox` for direct messages, an invite-only `%party` for private conversation, a read-only `%journal` for curated content, and a public-access `%board` for general use.

69+

6870### Posts

6971

7072For the time being a post is either a line, a URL or a command.

@@ -132,11 +134,11 @@ The audience you're sending to is always shown in your prompt. If there's a gly

132134

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

134136

135− ~fintud-macrep:talk=

137+ ~your-urbit:talk=

136138

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

138140

139− ~fintud-macrep:talk(~dannum-mitryl)

141+ ~your-urbit:talk(~dannum-mitryl)

140142

141143#### Configuration

142144

@@ -167,16 +169,16 @@ configurations.

167169

168170`;nick` - list all nicknames

169171

170−`;nick ~fintud-macrep` - look up a nickname

172+`;nick ~your-urbit` - look up a nickname

171173

172174`;nick plato` - search in reverse

173175

174−`;nick ~fintud-macrep plato` create a nickname

176+`;nick ~your-urbit plato` create a nickname

175177

176−`;nick ~fintud-macrep ~` clear an assigned nickname

178+`;nick ~your-urbit ~` clear an assigned nickname

177179

178180`;set noob` show nicknames instead of urbit names

179181

180182`;unset noob` show urbit names instead of nicknames

181183

182−All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on entries in a phonebook. Sometimes in a post you want to mention someone you know by a nickname. Just type `~plato`, and `:talk` will replace it with `~fintud-macrep`.

184+All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on entries in a phonebook. Sometimes in a post you want to mention someone you know by a nickname. Just type `~plato`, and `:talk` will replace it with `~your-urbit`.

docs/walkthroughs/web.md+68−15

@@ -6,38 +6,91 @@ title: Web

77# Web

9−General coverage of Urbit on the web. Renderer -> file, main public facing files, and tree. Then:

9+<div class="row">

10+<div class="col-md-8">

1011

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

1113

12−## Tree

14+By default `%eyre` uses Tree, which is sort of like a combination of Jekyll or Kirby 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.

1315

14−Tree is a simple publishing platform 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.

16+We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its own repo [here](https://github.com/urbit/tree).

1517

16−In spirit Tree is sort of like a combination of Jekyll and Finder: 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.

18+</div>

19+</div>

1720

18−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 set of renderers that translate data in `%clay`, our filesystem, into JSON / JSX that can be read by the client.

21+## Quickstart

1922

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

23+Your Urbit runs a web server and can be found at either `http://localhost:8080/` (or `8081` if you're running something at `8080`), or `http://your-urbit.urbit.org/`.

24+

25+(Make sure you have a desk mounted to unix, as covered in the [filesystem walkthrough](/filesystem))

26+

27+To switch the desk you're serving from:

28+

29+ |serve %sandbox

30+

31+To host a file on the web try putting the following in `/home/web/test.md` (from Unix):

32+

33+ # Hello

34+

35+ This is a simple markdown file.

36+

37+Create a folder with two more markdown files in it and copy it to `/home/web/test/`.

38+

39+Now modify `/home/web/test.md` to list the children using the `<list/>` JSX:

40+

41+ # Hello

42+

43+ This is a simple markdown file.

2144

22−You don't need to know anything about the tree implementation to use it, so we'll start with that and get further into the technical details as we get down the page.

45+ <div><list /></div>

2346

24−## Renderers

47+To view your file as raw `md`:

48+

49+ http://localhost:8080/test.md

50+

51+To view your file as raw `html`:

52+

53+ http://localhost:8080/test.html

54+

55+## Manual

2556

2657## `/web`

2758

28−`|serve`

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

2960

30−## Publishing files

61+Switch to the `%sandbox` desk:

62+

63+ |serve %sandbox

3164

32−Assuming you have an Urbit desk mounted (if not see the [Filesystem Handbook](/walkthroughs/clay)), try opeing up `/web/static.md` in an editor and `http://localhost:8080/static` side by side.

65+Let's quickly step through the default contents of `web/`:

3366

34−It should be pretty obvious what's going on here. Drop a markdown file anywhere in `/web` and we'll do the rest.

67+`404.hoon` - The default 404 page.

68+`dojo.hoon` - Page body that loads the `dojo` React module.

69+`lib/css/bootstrap.css` - The Urbit-flavored bootstrap

70+`lib/css/codemirror.css` - Syntax highlighting

71+`lib/css/fonts.css` - The Urbit custom fonts

72+`lib/js/hoon.js` - Hoon syntax highlighting

73+`lib/js/sole.js` - `dojo` operational transformation JS

74+`lib/js/urb.js` - Base Urbit JS library. Handles AJAX and polling.

75+`static.md` - Sample static file

76+`talk/` - Talk compiled JS / CSS

77+`talk.hoon` - Page body that loads the `dojo` React module.

78+`tree/` - Tree compiled JS / CSS

79+`tree.hoon` - Page body that loads the `tree` React module.

3580

36−### Simple blog

81+## Tree

3782

38−From unix

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

84+

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

86+

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

88+

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

90+

91+## Publishing files

3992

40−### Going further

93+Publishing files in Tree is simple. Try dropping a file in `/web` (as covered in the Quickstart) and navigating to it.

4194

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

4396