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

git.iko.soy/urbit.org

on master help sign in

looks ok in an editor

97e0cdfGalen Wolfe-Pauly11 years ago

docs/walkthroughs/admin.md+9−10

compare with master

unifiedsplit

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

9<div class="row">

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

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.

14</div>

15</div>

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

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

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.

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

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

58 ^U kill to beginning of line

59 ^Y yank from kill buffer

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

63## Web

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

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−`fintud-macrep.urbit.org`. Please use this proxy as little as

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

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

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

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

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

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

77To generate a random moon from your planet run:

76To generate a random moon from your planet run:

79− ~fintud-macrep:dojo> +moon

78+ ~your-urbit:dojo> +moon

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

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

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

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

86Piers 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.

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:

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

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

93## Continuity breaches

92## Continuity breaches

docs/walkthroughs/filesystem.md+20−24

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

4title: Filesystem

5---

7−# `%clay` (Filesystem)

7+<div class="row">

8−

8+<div class="col-md-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.

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

10+# `%clay` (Filesystem)

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.

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

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.

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.

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

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

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

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

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

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

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

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

19+</div>

20+</div>

21+

28## Quickstart

22## Quickstart

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.

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

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

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

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

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:

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

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

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

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

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

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

44−Create a new desk:

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

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

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

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

44+Sync with a remote desk on the network:

50 |sync %sandbox ~wactex-ribmex %examples

46 |sync %sandbox ~wactex-ribmex %examples

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

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

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

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

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

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

72### Revision-control

68### Revision-control

docs/walkthroughs/shell.md+57−51

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

4title: Shell

5---

7+<div class="row">

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

7# `:dojo` (Shell)

10# `:dojo` (Shell)

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>

11## Quickstart

17## Quickstart

13Evaluate a hoon expression:

19Evaluate a hoon expression:

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

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

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

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

18Tall form Hoon will be prompted for:

24Tall form Hoon will be prompted for:

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

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

21− ~fintud-macrep:dojo< 2

27+ ~your-urbit:dojo< 2

22− ~fintud-macrep:dojo< 2

28+ ~your-urbit:dojo< 2

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

44## Manual

50## Manual

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

56Set any envronment variable:

62Set any envronment variable:

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

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

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

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

61 44

67 44

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

85Download a noun to Unix with `.`:

91Download a noun to Unix with `.`:

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

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

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

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

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

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

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

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

100

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

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

102

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

100

106

101Convert between marks using `&`:

107Convert between marks using `&`:

102

108

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

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

104 :: produces

110 :: produces

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

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

106

112

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

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

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

110

116

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

117 :: 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

113 :: produces

119 :: produces

114 9

120 9

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

121 :: 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

117 :: produces

123 :: produces

118 301

124 301

119

125

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

131

137

132Create a random moon (from any planet):

138Create a random moon (from any planet):

133

139

134− ~fintud-macrep:dojo> +moon

140+ ~your-urbit:dojo> +moon

135 :: produces

141 :: produces

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

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

137

143

138### Variables

144### Variables

139

145

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

145

151

146**Examples:**

152**Examples:**

147

153

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

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

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

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

150

156

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

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

152

158

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

156

162

157**Examples:**

163**Examples:**

158

164

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

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

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

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

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

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

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

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

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

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

164

170

165#### `sur`

171#### `sur`

166

172

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

168

174

169**Examples:**

175**Examples:**

170

176

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

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

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

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

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

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

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

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

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

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

176

182

177#### `now`

183#### `now`

178

184

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

180

186

181**Example:**

187**Example:**

182

188

183− ~fintud-macrep:dojo> now

189+ ~your-urbit:dojo> now

184 :: produces

190 :: produces

185 ~2016.3.21..21.10.57..429a

191 ~2016.3.21..21.10.57..429a

186

192

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

190

196

191**Example:**

197**Example:**

192

198

193− ~fintud-macrep:dojo> our

199+ ~your-urbit:dojo> our

194 :: produces

200 :: produces

195− ~fintud-macrep

201+ ~your-urbit

196

202

197#### `eny`

203#### `eny`

198

204

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

200

206

201**Example:**

207**Example:**

202

208

203− ~fintud-macrep:dojo> eny

209+ ~your-urbit:dojo> eny

204 :: produces

210 :: produces

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

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

206

212

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

208

214

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

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

210

216

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

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

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

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

213

219

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

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

215

221

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

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

217

223

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

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

219

225

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

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

221

227

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

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

223

229

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

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

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

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

226

232

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

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

228

234

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

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

230

236

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

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

232

238

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

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

234

240

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

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

236

242

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

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

238

244

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

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

240

246

241### Hood

247### Hood

242

248

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

244

250

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

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

246

252

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

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

248

254

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

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

250

256

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

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

252

258

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

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

254

260

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

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

256

262

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

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

258

264

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

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

260

266

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

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

262

268

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

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

docs/walkthroughs/source.md+12−8

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

3title: Arvo source

4---

6+<div class="row">

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

6# Arvo source

9# Arvo source

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

11When 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.

13+</div>

14+</div>

15+

10Looking 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:

16Looking 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:

12 app/

18 app/

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

25## `app/`

31## `app/`

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.

29## `arvo/`

35## `arvo/`

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

61### `arvo/hoon.hoon`

67### `arvo/hoon.hoon`

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.

65### `arvo/zuse.hoon`

71### `arvo/zuse.hoon`

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

71## `gen/`

77## `gen/`

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

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

75## `lib/`

81## `lib/`

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

79## `mar/`

85## `mar/`

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.

83## `ren/`

89## `ren/`

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

89## `sur/`

95## `sur/`

91−`sur/` contains shared data structures.

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

92−

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

95## `web/`

99## `web/`

100

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

102

99## `web.md`

103## `web.md`

100

104

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

102

106

docs/walkthroughs/talk.md+23−21

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

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

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.

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.

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

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

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.

22</div>

20</div>

23</div>

21</div>

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

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

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

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

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

33You'll see:

31You'll see:

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

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

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

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

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

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

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

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

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

40− ~fintud-macrep:talk>

38+ ~your-urbit:talk>

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

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

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

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

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

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

48− ~fintud-macrep> hello, world

46+ ~your-urbit> hello, world

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

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

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

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

54You'll see your prompt change:

52You'll see your prompt change:

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

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

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

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

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

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

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

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

63−

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

66## Manual

62## Manual

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+

68### Posts

70### Posts

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

72For 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

132

134

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

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

134

136

135− ~fintud-macrep:talk=

137+ ~your-urbit:talk=

136

138

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

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

138

140

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

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

140

142

141#### Configuration

143#### Configuration

142

144

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

167

169

168`;nick` - list all nicknames

170`;nick` - list all nicknames

169

171

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

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

171

173

172`;nick plato` - search in reverse

174`;nick plato` - search in reverse

173

175

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

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

175

177

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

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

177

179

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

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

179

181

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

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

181

183

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

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

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.

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.

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

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>

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

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.

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>

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

26## `/web`

57## `/web`

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

30−## Publishing files

61+Switch to the `%sandbox` desk:

62+

63+ |serve %sandbox

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

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.

36−### Simple blog

81+## Tree

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

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.

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

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