d414950 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

tutorials/*.md: text, typographic, and formatting corrections (#821)

* tutorials/sail-and-udon: typographic corrections, mostly `’` and `…` * tutorials/sail-and-udon: consistenly prepend `localhost` with `http://` * tutorials/sail-and-udon: text/typo, formatting, and indentation corrections * tutorials/sail-and-udon: fix tag in Linking section (`img` -> `a`) * tutorials/ship-troubleshooting: typographic corrections, mostly `’` * tutorials/ship-troubleshooting: text/typo corrections * tutorials/creating-an-invite-pool: typographic corrections (`’`) * tutorials/guide-to-breaches: text/typo, capitalisation and typographic corrections * tutorials/hoon-errors: text/typo and typographic corrections * tutorials/sail-and-udon: correct double spaces in copy text * tutorials/ship-troubleshooting: correct double spaces in copy text * tutorials/_index: typographic corrections (`’`) Co-authored-by: fakezod <fakezod@users.noreply.github.com>

commitd41495071c219093a08374beb53e9bbdb961e962 authorfakezod <62216503+fakezod@users.noreply.github.com> dateMon 16 Mar 2020, 23:42 (7 years ago) parent7e013fc

6 files changed+233−224

compare with master

unifiedsplit

tutorials/_index.md+3−3 tutorials/creating-an-invite-pool.md+1−1 tutorials/guide-to-breaches.md+8−8 tutorials/hoon-errors.md+44−44 tutorials/sail-and-udon.md+145−137 tutorials/ship-troubleshooting.md+32−31

tutorials/_index.md+3−3

@@ -14,14 +14,14 @@ Arvo is a clean-slate system software stack defined as a deterministic computer.

1414

1515## [Hoon Tutorial](@/docs/tutorials/hoon/_index.md)

1616

17−Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics. The Hoon Tutorial is the best place to start if you want to learn Urbit.

17+Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn’t require knowing any advanced mathematics. The Hoon Tutorial is the best place to start if you want to learn Urbit.

1818

1919## [Nock](@/docs/tutorials/nock/_index.md)

2020

21−Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.

21+Nock is the low-level functional programming language that is interpreted by Vere. You don’t need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.

2222

2323## [Vere](@/docs/tutorials/vere/_index.md)

2424

2525The Nock runtime system, written in C.

2626

27−Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.

27+Keep reading if you’re planning to work on the Urbit interpreter, you’re a language implementation geek, or you don’t really understand anything until you’ve seen the actual structs.

tutorials/creating-an-invite-pool.md+1−1

@@ -22,7 +22,7 @@ Giving your friends a piece of Urbit only takes a few minutes: send an invite po

2222

23231. Log into Bridge using your ownership address for your star.

2424

25−2. Get the name (like `~poldec-tonteg`) of the planet to whom you'd like to give invites, it can be one you control or a friend's.

25+2. Get the name (like `~poldec-tonteg`) of the planet to whom you’d like to give invites, it can be one you control or a friend’s.

2626

27273. Click “Manage Invite Pools” to assign an invite pool to the planet. You may receive a notification that you need to assign your spawn proxy to the address of the Delegated Sending contract. This is so that the contract can send invites on your behalf when the recipient claims them.

2828

tutorials/guide-to-breaches.md+8−8

@@ -10,9 +10,9 @@ There are two kinds of breaches: **personal breaches** and **network breaches**.

1010

1111## Personal Breaches

1212

13−Ships on the Ames network sometimes need to reset their continuity. A personal breach is when an individual ship announces to the network: "I forgot who I am, let's start over from scratch." That is, it clears its own event log and sends an announcement to the network, asking all ships that have communicated with it to reset its networking information in their state. This makes it as though the ship was just started for the first time again, since everyone has network has forgotten about it.

13+Ships on the Ames network sometimes need to reset their continuity. A personal breach is when an individual ship announces to the network: “I forgot who I am, let’s start over from scratch.” That is, it clears its own event log and sends an announcement to the network, asking all ships that have communicated with it to reset its networking information in their state. This makes it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.

1414

15−Personal breaches often fix connectivity issues, but should only be used as a last resort. Before performing a personal breach, look at alternative fixes in the [Ship Troubleshooting](../ship-troubleshooting) guide. Also reach out for help in `~dopzod/urbit-help`, or, failing that, in the #ship-starting-support channel in our [Discord server](https://discord.gg/n9xhMdz) to see if there is another option.

15+Personal breaches often fix connectivity issues, but should only be used as a last resort. Before performing a personal breach, look at alternative fixes in the [Ship Troubleshooting](../ship-troubleshooting) guide. Also reach out for help in `~dopzod/urbit-help`, or, failing that, in the `#ship-starting-support` channel in our [Discord server](https://discord.gg/n9xhMdz) to see if there is another option.

1616

1717To perform a personal breach, follow the steps below.

1818

@@ -28,17 +28,17 @@ There are two types of personal breaches: changing private keys, and changing

2828the Ethereum address that holds the Urbit ID.

2929

3030Performing a personal breach on your ship increments an integer value called

31−your ship's _life_ by one, which refers to your ship's [Azimuth](@/docs/tutorials/concepts/azimuth.md) _key

31+your ship’s _life_ by one, which refers to your ship’s [Azimuth](@/docs/tutorials/concepts/azimuth.md) _key

3232revision number_. This value is utilized by

3333Ames and Jael to ensure that you are

3434communicating with a ship created using its most recent set of keys. Your

35−ship's life is written at the end of the name of its keyfile, e.g.

36−`sampel-palnet4.key`. Changing the Etherum address that holds the Urbit ID,

37−called _reticketing_, also increments a number called the ship's _rift_ by one.

38−Rift refers to your ship's Azimuth _continuity number_.

35+ship’s life is written at the end of the name of its keyfile, e.g.

36+`sampel-palnet-4.key`. Changing the Etherum address that holds the Urbit ID,

37+called _reticketing_, also increments a number called the ship’s _rift_ by one.

38+Rift refers to your ship’s Azimuth _continuity number_.

3939

4040You can check your current life and rift number by running the

41−`+keys our` generator in dojo. You can inspect another ship's life and rift can be checked by

41+`+keys our` generator in Dojo. You can inspect another ship’s life and rift can be checked by

4242running `+keys ~sampel-palnet`.

4343

4444

tutorials/hoon-errors.md+44−44

@@ -5,25 +5,25 @@ template = "doc.html"

55+++

77In this section we explore strategies for debugging and understanding what your

8−Hoon code is doing. We cover common errors that dojo may spit out, how to turn

8+Hoon code is doing. We cover common errors that Dojo may spit out, how to turn

99on debugging and verbose mode, and how to use debugging printfs.

1010

1111## Syntax errors

1212

13−When you get a syntax error, you'll see a message like

13+When you get a syntax error, you’ll see a message like:

1414

1515```

1616syntax error at [10 12]

1717```

1818

1919This is a line and column number; more exactly, the line and

20−column of the first byte the parser couldn't interpret as part of

21−a correct Hoon file. These values are always correct.

20+column of the first byte the parser couldn’t interpret as part of

21+a correct Hoon file. These values are always correct.

2222

2323Usually, the line and column tell you everything you need to

24−know. But the worst-case scenario for a syntax error is that,

25−somewhere above, you've confused Hoon's tall form by using the

26−wrong fanout for a rune. For example, `%+` ([**cenlus**](@/docs/reference/hoon-expressions/rune/cen.md#cenlus),

24+know. But the worst-case scenario for a syntax error is that,

25+somewhere above, you’ve confused Hoon’s tall form by using the

26+wrong fanout for a rune. For example, `%+` ([**cenlus**](@/docs/reference/hoon-expressions/rune/cen.md#cenlus),

2727a function call whose sample is a cell) has three subhoons:

2828

2929```hoon

@@ -32,44 +32,44 @@ a function call whose sample is a cell) has three subhoons:

3232baz

3333```

3434

35−But if you make a mistake and write

35+But if you make a mistake and write …

3636

3737```hoon

3838%+ foo

3939bar

4040```

4141

42−the parser will eat the next reference below and try to treat it as a

43−part of the `%+`. This can cause a cascading error somewhere

42+… the parser will eat the next reference below and try to treat it as a

43+part of the `%+`. This can cause a cascading error somewhere

4444below, usually stopped by a `==` or `--`.

4545

46−When this happens, don't panic! Binary search actually works

47−quite well. Any reference can be stubbed out as `!!`. Find the

46+When this happens, don’t panic! Binary search actually works

47+quite well. Any reference can be stubbed out as `!!`. Find the

4848prefix of your file that compiles, then work forward until

4949the actual error appears.

5050

5151## Semantic errors

5252

53−Now your code parses but doesn't compile.

53+Now your code parses but doesn’t compile.

5454

5555### Turn on debugging or verbose mode

5656

57−Your first step should be to put a `!:` ("zapcol") rune at the

58−top of the file. This is like calling the C compiler with `-g`;

57+Your first step should be to put a `!:` (“zapcol”) rune at the

58+top of the file. This is like calling the C compiler with `-g`;

5959it tells the Hoon compiler to generate tracing references.

6060

61−Bear in mind that `!:` breaks tail-call optimization. This is a

62−bug, but a relatively low-priority bug. `!.` turns off `!:`.

61+Bear in mind that `!:` breaks tail-call optimization. This is a

62+bug, but a relatively low-priority bug. `!.` turns off `!:`.

6363Note that `!:` and `!.` are reference-level, not file-level; you can

6464wrap any reference in either.

6565

66−You may also find it helpful to turn on verbose mode by entering `|verb` into dojo, which prints (almost)

66+You may also find it helpful to turn on verbose mode by entering `|verb` into Dojo, which prints (almost)

6767everything happening in the kernel to the console. This is useful for performing

6868stack trace. An extensive stack trace tutorial is [below](#stack-trace-tutorial).

6969

7070### Error trace

7171

72−If you have `!:` on, you'll see an error trace, like

72+If you have `!:` on, you’ll see an error trace, like:

7373

7474```

7575/~zod/home/0/gen/hello:<[7 3].[11 21]>

@@ -85,31 +85,31 @@ The bottom of this trace is the line and column of the reference which

8585failed to compile, then the cause of the error (`nest-fail`).

8686

8787Hoon does not believe in inundating you with possibly irrelevant

88−debugging information. Your first resort is always to just look

89−at the code and try to figure out what's wrong. This practice

88+debugging information. Your first resort is always to just look

89+at the code and try to figure out what’s wrong. This practice

9090strengthens your Hoon muscles.

9191

9292(Consider the opposite extreme; imagine if you had a magic bot

93−that always fixed your compiler errors for you. Pro: no time

94−wasted on compiler errors. Con: you never learn Hoon.)

93+that always fixed your compiler errors for you. Pro: no time

94+wasted on compiler errors. Con: you never learn Hoon.)

9595

9696## Common errors

9797

98−Moral fiber is all very well and good, but sometimes you're

99−stumped. Couldn't the compiler help a little? These messages do

100−mean something. Here are the three most common:

98+Moral fiber is all very well and good, but sometimes you’re

99+stumped. Couldn’t the compiler help a little? These messages do

100+mean something. Here are the three most common:

101101

102102### `nest-fail`

103103

104−This is a type mismatch (`nest` is the Hoon typechecker). It

104+This is a type mismatch (`nest` is the Hoon typechecker). It

105105means you tried to pound a square peg into a round hole.

106106

107−What was the peg and what was the hole? Hoon doesn't tell you by

107+What was the peg and what was the hole? Hoon doesn’t tell you by

108108default, because moral fiber, and also because in too many cases

109−trivial errors lead to large intimidating dumps. However, you

109+trivial errors lead to large intimidating dumps. However, you

110110can use the `~!` rune ([**sigzap**](@/docs/reference/hoon-expressions/rune/sig.md#sigzap)) to print the type of any hoon in your stack trace.

111111

112−For instance, you wrote `(foo bar)` and got a `nest-fail`. Change

112+For instance, you wrote `(foo bar)` and got a `nest-fail`. Change

113113your code to be:

114114

115115```hoon

@@ -118,16 +118,16 @@ your code to be:

118118(foo bar)

119119```

120120

121−You'll get the same `nest-fail`, but this will show the type of

121+You’ll get the same `nest-fail`, but this will show the type of

122122`bar`, then the type of the sample of the `foo` gate.

123123

124124### `find.foo`

125125

126−A `find.foo` error means limb `foo` wasn't found in the subject.

127−In other words, "undeclared variable."

126+A `find.foo` error means limb `foo` wasn’t found in the subject.

127+In other words, “undeclared variable.”

128128

129129The most common subspecies of `find` error is `find.$`, meaning

130−the empty name `$` was not found. This often happens when you

130+the empty name `$` was not found. This often happens when you

131131use a reference that does not produce a gate/mold, as a gate/mold. For

132132instance, `(foo bar)` will give `find.$` if `foo` is not actually a

133133function.

@@ -135,17 +135,17 @@ function.

135135### `mint-vain` and `mint-lost`

136136

137137These are errors caused by type inference in pattern matching.

138−`mint-vain` means this hoon is never executed. `mint-lost` means there's a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn't handled.

138+`mint-vain` means this hoon is never executed. `mint-lost` means there’s a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn’t handled.

139139

140140## Runtime crashes

141141

142−If your code crashes at runtime or overflows the stack, you'll

143−see a stack trace that looks just like the trace above. Don't

142+If your code crashes at runtime or overflows the stack, you’ll

143+see a stack trace that looks just like the trace above. Don’t

144144confuse runtime crashes with compilation errors, though.

145145

146−If your code goes into an infinite loop, kill it with `ctrl-c` (you'll

146+If your code goes into an infinite loop, kill it with `ctrl-c` (you’ll

147147need to be developing on the local console; otherwise, the

148−infinite loop will time out either too slowly or too fast). The

148+infinite loop will time out either too slowly or too fast). The

149149stack trace will show what your code was doing when interrupted.

150150

151151The counterpart of `~!` for runtime crashes is `~|`

@@ -157,15 +157,15 @@ The counterpart of `~!` for runtime crashes is `~|`

157157```

158158

159159If `(foo bar)` crashes, the value of `foo` is printed in the

160−stack trace. Otherwise, the `~|` has no effect.

160+stack trace. Otherwise, the `~|` has no effect.

161161

162162## Debugging printfs

163163

164164The worst possibility, of course, is that your code runs but does

165−the wrong thing. This is relatively unusual in a typed

165+the wrong thing. This is relatively unusual in a typed

166166functional language, but it still happens.

167167

168−`~&` ([**sigpam**](@/docs/reference/hoon-expressions/rune/sig.md#sigpam)) is Hoon's debugging printf.

168+`~&` ([**sigpam**](@/docs/reference/hoon-expressions/rune/sig.md#sigpam)) is Hoon’s debugging printf.

169169This pretty-prints its argument:

170170

171171```hoon

@@ -173,7 +173,7 @@ This pretty-prints its argument:

173173(foo bar)

174174```

175175

176−will always print `foo` every time it executes. A variant is

176+will always print `foo` every time it executes. A variant is

177177`~?` ([**sigwut**](@/docs/reference/hoon-expressions/rune/sig.md#sigwut)), which prints only if a condition is

178178true:

179179

@@ -183,7 +183,7 @@ true:

183183```

184184

185185For now, you need to be on the local console to see these debug

186−printfs (which are implemented by interpreter hints). This is a

186+printfs (which are implemented by interpreter hints). This is a

187187bug and, like all bugs, will be fixed at some point.

188188

189189

tutorials/sail-and-udon.md+145−137

@@ -7,7 +7,7 @@ aliases = ["docs/using/sail-and-udon/"]

88Sail is Hoon markup that’s used to render a web page with XML. But what makes it special is that you can run arbitrary Hoon code within such a web page without using a separate markup language.

10−Udon is a way to write content for the web. It's a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It's integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.

10+Udon is a way to write content for the web. It’s a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It’s integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.

1111

1212This document will be divided into two main sections: the Sail guide and the Udon guide. Also, you should read the Getting Started section below, which applies to both Udon and Sail.

1313

@@ -25,9 +25,9 @@ Before starting with either Sail or Udon, make sure that your ship is

2525[mounted to Unix](@/using/install.md).

2626

2727To host that output, your ship also has a web-server that can be found at

28−`localhost` (default port 80) if it’s your first ship that’s running on the

28+`http://localhost/` (default port 80) if it’s your first ship that’s running on the

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

30−and so on. In the startup messages, a ship will tell you which HTTP port it's

30+and so on. In the startup messages, a ship will tell you which HTTP port it’s

3131using.

3232

3333Udon and Sail files are often run as independent files (`.udon` and `.hoon`

@@ -35,7 +35,7 @@ respectively), but for the purpose of this guide, we will run them out of the

3535`frontpage.hoon` file located in the `/gen` directory. The default content of

3636`frontpage.hoon` is Sail code.

3737

38−To use `frontpage.hoon`, we use a `|serve` command like this one in your ship's

38+To use `frontpage.hoon`, we use a `|serve` command like this one in your ship’s

3939Dojo:

4040

4141```

@@ -44,17 +44,17 @@ Dojo:

4444

4545This command has three arguments:

4646- The first is the URL we want to bind our site to. We chose `/test`, so the URL

47−we will find our site at is `localhost/test`.

47+we will find our site at is `http://localhost/test`.

4848- The second is the desk we want to serve. We will be serving from `%home` in

4949this tutorial.

5050- The third is the file that we want to serve. In this tutorial, we will be

51−using `/gen/frontpage/hoon`, which refers to `frontpage.hoon`.

51+using `/gen/frontpage/hoon`, which refers to `/gen/frontpage.hoon`.

5252

5353Run the command `|serve /test %home /gen/frontpage/hoon`. Now navigate to

54−`localhost/test` (or `localhost:8081/test` if your ship is on that port) in your

54+`http://localhost/test` (or `http://localhost:8081/test` if your ship is on that port) in your

5555browser, and you should see the rendered Sail.

5656

57−**Note:** Important to remember that every time you edit a file in your ship's

57+**Note:** Important to remember that every time you edit a file in your ship’s

5858pier (Unix directory), including `frontpage.hoon`, you need to run `|commit %home`

5959to copy those changes to Urbit.

6060

@@ -72,7 +72,7 @@ It’s easy to see how Sail can directly translate to HTML:

7272 ;body

7373 ;h1: Welcome!

7474 ; Hello, world!

75− ; We're on the web.

75+ ; We’re on the web.

7676 ;div;

7777 ;script@"http://unsafely.tracking.you/cookiemonster.js";

7878 ==

@@ -98,10 +98,10 @@ It’s easy to see how Sail can directly translate to HTML:

9898

9999You can test above Sail code by placing it

100100under `^- manx` in your `frontpage.hoon` file, and then running `|commit %home`

101−in the Dojo. If you've already run the `|serve` command code from the first

102−section, the new content should appear at `localhost/test`.

101+in the Dojo. If you’ve already run the `|serve` command code from the first

102+section, the new content should appear at `http://localhost/test`.

103103

104−It shouldn't be hard to see the similarities between Sail and HTML. So let's go

104+It shouldn’t be hard to see the similarities between Sail and HTML. So let’s go

105105into more detail about what the differences are.

106106

107107### Tags and Closing

@@ -147,7 +147,7 @@ with `==`, because they expect a list of sub-tags. If we nest a line of plain

147147text with no tag, a `<p>` is prepended.

148148

149149Sail, like Hoon, is white-space sensitive. Unlike in Hoon, however, two spaces

150−(called a "gap") is not necessarily equivalent to a line-break in Sail.

150+(called a `gap`) is not necessarily equivalent to a line-break in Sail.

151151

152152```

153153;body

@@ -160,12 +160,11 @@ Equals:

160160

161161```

162162<body>

163− <h1>Blog title</h1>

164− <p>This is some good content.</p>

163+ <h1>Blog title</h1>

164+ <p>This is some good content.</p>

165165</body>

166166```

167167

168−

169168Conversely, if we want to write a string with no tag at all, then we can prepend

170169those untagged lines with `;`.

171170

@@ -187,25 +186,23 @@ Equals:

187186</body>

188187```

189188

190−

191189#### Attributes

192190

193191Attributes are key-value pairs that go into an HTML node.

194192

195193Adding attributes is simple: just add the desired attribute between parentheses,

196−right after the tag name without a space. We separate different attributes of

194+right after the tag name without a space. We separate different attributes of

197195the same node by using `,`.

198196

199197Attributes can be used in two forms: flat, which uses one line; and tall, which

200198uses multiple lines, when a single line would not be practical. Flat forms and

201−flat forms are two syntaxes of semantically equivalent expressions.

202−

199+tall forms are two syntaxes of semantically equivalent expressions.

203200

204201#### Generic

205202

206203The code below produces a “Submit” button on the page.

207204

208−Wide-form Sail:

205+Flat-form Sail:

209206

210207```

211208;input(type "submit", value "Submit");

@@ -223,7 +220,7 @@ Tall-form Sail:

223220Equals:

224221

225222```

226−<input type="submit" value="Submit">`

223+<input type="submit" value="Submit">

227224```

228225

229226#### IDs

@@ -242,27 +239,34 @@ Add `#` after tag name to add an ID.

242239

243240#### Classes

244241

245−`;h1.text-blue: Title` equals `<h1 class="text-blue">Title</h1>`

242+`;h1.text-blue: Title`

243+

244+Equals:

245+

246+`<h1 class="text-blue">Title</h1>`

246247

247−Add `.` after tag name to add a class. However, if you want a class name that

248+Add `.` after tag name to add a class. However, if you want a class list that

248249contains a space, you will need to use use the syntax of a generic attribute:

249250

250−`;div(class "logo inverse");` equals `<div class="logo inverse"></div>`

251+`;div(class "logo inverse");`

252+

253+Equals:

251254

255+`<div class="logo inverse"></div>`

252256

253257#### Image

254258

255259`;img@"example.png";`

256260

257−Equals

261+Equals:

258262

259−`<img src="example.png"/>`

263+`<img src="example.png" />`

260264

261265Add `@` after the tag name to link your source.

262266

263267To add attributes to the image, like size specifications, add the

264−desired attribute after the `"` of the image name and before the final `;` of

265−the `img` tag.

268+desired attribute after the closing `"` of the image name and before the final

269+`;` of the `img` tag.

266270

267271For example:

268272

@@ -272,12 +276,20 @@ For example:

272276

273277`;a/"urbit.org": A link to Urbit.org`

274278

275−Equals

279+Equals:

276280

277281`<a href="urbit.org">A link to Urbit.org</a>`

278282

279283Add `/` after tag name to start an href.

280284

285+To add attributes to the link, like target specifications, add the

286+desired attribute after the closing `"` of the link url and before the `:` of

287+the `a` tag.

288+

289+For example:

290+

291+`;a/"urbit.org"(target "_blank"): A link to Urbit.org`

292+

281293### Hoon in Sail

282294

283295Our first example is useful to understand how Sail syntax translates to HTML

@@ -320,7 +332,7 @@ interpolate with something that results in an atom. Try this now:

320332```

321333

322334We get a similar result, but we know that it’s a tape because it’s wrapped in

323−`""`. Bingo! With this knowledge, let’s perform a successful interpolation:

335+`""`. Bingo! With this knowledge, let’s perform a successful interpolation:

324336

325337```

326338> "I am a l{<(mul 3 11)>}t Urbit user."

@@ -353,7 +365,7 @@ Then enter the following command in the Dojo:

353365> .

354366```

355367

356−You'll notice that the Sail subject is like a stripped-down version of the Dojo

368+You’ll notice that the Sail subject is like a stripped-down version of the Dojo

357369subject. Its final line should match the Dojo subject.

358370

359371Now swap the code below into your Sail file.

@@ -368,9 +380,9 @@ Now swap the code below into your Sail file.

368380==

369381```

370382

371−You'll find that the resulting Sail subject is much larger. If you look closely,

372−you'll see that there's some new similarities with the Dojo subject, such as

373−containing the name of your ship. There's also some new differences, since

383+You’ll find that the resulting Sail subject is much larger. If you look closely,

384+you’ll see that there’s some new similarities with the Dojo subject, such as

385+containing the name of your ship. There’s also some new differences, since

374386`fuel:html` contains things that are specifically useful for performing

375387web-related operations.

376388

@@ -402,13 +414,13 @@ example we saw before.

402414 ;span: Check it out!

403415 ;+ ?: show-list

404416 ;ol

405− ;li(style "color: green"): We're doing interesting stuff now.

406− ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.

417+ ;li(style "color: green"): We’re doing interesting stuff now.

418+ ;li: We’re pretty-printing this sum with Hoon: {<(add 50 50)>}.

407419 ;li: The code above is shorthand for {(scow %ud (add 50 50))}.

408420 ;li: I am {(trip '~lodleb-ritrul')}.

409− ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.

421+ ;li: Actually, my name is {<p.bem.gas>}. I’m a {what-kind}.

410422 ==

411− ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.

423+ ;div: My name is {<p.bem.gas>}. I’m a {what-kind}.

412424 ==

413425==

414426```

@@ -424,15 +436,15 @@ piece.

424436/= gas /$ fuel:html

425437```

426438

427−Later in this code we want produce the name of the ship is hosting it, something

428−that looks like ~lodleb-ritrul. In a generator, we could produce our ship name

429−by writing `our` -- try it in the Dojo. But remember that Sail is rendered

439+Later in this code we want to produce the name of the ship which is hosting it,

440+something that looks like ~lodleb-ritrul. In a generator, we could produce our ship

441+name by writing `our` -- try it in the Dojo. But remember that Sail is rendered

430442against its own subject, `our` is not part of the default subject. To augment

431443our subject with the information that we need, we use `/= gas /$ fuel:html`.

432444

433445The above expression uses two Ford runes, `/=` and `/$`, to add the relevant

434446information to the current subject. We can pull the ship’s name out of this

435−augmented subject later. It's important to note that these runes are not part of

447+augmented subject later. It’s important to note that these runes are not part of

436448Hoon. They are part of Ford, our build system.

437449

438450`/$` is used to get data from the environment, and `/=` adds that data to

@@ -481,7 +493,7 @@ subject and gives it the face `wid`. This noun is produced by the the

481493standard-library function [`met`](/docs/reference/library/2c), which measures the number of

482494[blocks](/docs/reference/library/1c/) of size `a` within `b`. Blocks are units that have a

483495bitwidth of `2^a`. So, in this case, it measures how many bytes (blocks of size

484−3 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship's address.

496+3 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship’s address.

485497

486498Galaxies contain zero to one 3-blocks; stars contain two 3-blocks; planets

487499contain three to four 3-blocks; moons contain five to eight 3-blocks; comets

@@ -505,7 +517,7 @@ perform less-than tests to see what kind of ship is running the web-server.

505517Sail proper begins here. These four lines are four nodes. The `;html` node

506518indicates that the contained code should be rendered as HTML; this tag is closed

507519on the final line. The `;head` node contains metadata, and is closed three lines

508−later. The `;meta` node sets the character set to UTF-8, and the `;title` node

520+later. The `;meta` node sets the character set to UTF-8, and the `;title` node

509521sets the title of the page that shows up in the browser tab.

510522

511523```

@@ -532,7 +544,7 @@ attributes, it continues the line without formatting. Following `;span:` with

532544**two** spaces causes there to be single space following the produced `<span>`

533545element, because one of those spaces is syntactically necessary.

534546

535−In the following lines, we beginning to use some Hoon expressions again.

547+In the following lines, we begin to use some Hoon expressions again.

536548

537549```

538550 ;+ ?: show-list

@@ -542,14 +554,14 @@ In the following lines, we beginning to use some Hoon expressions again.

542554In the top line in the chunk above, we use the `;+` Sail rune, which

543555resolves an expression to a single node. That expression, in this case, is

544556`?:`, which tests the truth value of `show-list`, which we assigned the value

545−`&` (meaning “true”) at the beginning of the program. It’s closed by the `==` on

557+`&` (meaning `true`) at the beginning of the program. It’s closed by the `==` on

546558the last line.

547559

548560Thus, this program resolves to the first child of `show-list`, the node `;ol`.

549561That node creates an ordered list, and the items contained within that node.

550562

551563```

552− ;li(style "color: green"): We're doing more interesting stuff now.

564+ ;li(style "color: green"): We’re doing more interesting stuff now.

553565```

554566

555567The line above is the only element of this list that does not use

@@ -560,14 +572,13 @@ The next items in the list use `{}`. Recall that these braces, pronounced “lob

560572and “rob” in Hoon-speak, allow for the interpolation of code within a string.

561573

562574```

563− ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.

575+ ;li: We’re pretty-printing this sum with Hoon: {<(add 50 50)>}.

564576```

565577

566578The line above is interpolated with Hoon code that produces the sum of 50 plus

56757950, which is wrapped in `<>` to put the product in double quotes to make it a

568580tape, like the rest of the line.

569581

570−

571582```

572583 ;li: The code above is shorthand for {(scow %ud (add 50 50))}.

573584```

@@ -577,7 +588,6 @@ writing the `{<(add 50 50)>}` expression. `scow` is a Hoon function that turns a

577588noun into a `tape`, Hoon’s string type. `%ud` tells `scow` that its argument

578589should be displayed in the form of an unsigned decimal.

579590

580−

581591```

582592 ;li: I am {(trip '~lodleb-ritrul')}.

583593```

@@ -589,28 +599,28 @@ tape. So, by converting `~lodleb-ritrul` to a tape, it can be included in the

589599tape that we are trying to insert it into without getting a type error.

590600

591601```

592− ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.

602+ ;li: Actually, my name is {<p.bem.gas>}. I’m a {what-kind}.

593603 ==

594604```

595605

596606The line above has interpolated code that uses a wing expression to access the

597−name of the host ship, and then accesses the face `what-kind` contains a string

598−describing what type of ship it is. We declared `gas` on the very first line so

599−that we could add that sort of information to the subject that our Sail is

600−rendered against. The wing expression `p.bem.gas` looks for `p` within `bem`

607+name of the host ship, and then accesses the face `what-kind` that contains a

608+string describing what type of ship it is. We declared `gas` on the very first

609+line so that we could add that sort of information to the subject that our Sail

610+is rendered against. The wing expression `p.bem.gas` looks for `p` within `bem`

601611within `gas`, which happens to be where the name of the ship is located.

602612

603613Note that `{what-kind}` does not have a `<>` wrapper. Why do you think this is?

604614

605615```

606− ;div; My name is {<p.bem.gas>}. I'm a {ship}.

616+ ;div; My name is {<p.bem.gas>}. I’m a {ship}.

607617 ==

608618==

609619```

610620

611621The `;div;` node above is only rendered, as an alternative to the above list,

612−if `show-list` is evaluated as true. This means it won’t be shown with your

613−default code. To show this line, change the `&` on line 2 to `|` (“false”).

622+if `show-list` is evaluated as `true`. This means it won’t be shown with your

623+default code. To show this line, change the `&` on line 2 to `|` (`false`).

614624

615625### Sail Runes

616626

@@ -627,7 +637,6 @@ is the expression that we use.

627637

628638`;=` turns a tuple of nodes into a list of nodes.

629639

630−

631640To see how these runes work, let’s take a chunk of our previous code starting at

632641line 20 and modify it a bit:

633642

@@ -638,7 +647,7 @@ line 20 and modify it a bit:

638647 ;li: Actually, my name is {<p.bem.gas>}.

639648 ==

640649 ;=

641− ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.

650+ ;div: My name is {<p.bem.gas>}. I’m a {what-kind}.

642651 ;div: No list here!

643652 ==

644653 ==

@@ -661,21 +670,21 @@ You should now have foundational knowledge for making web pages with Sail. There

661670is, of course, more to learn.

662671

663672The [Ford manual](https://urbit.org/docs/arvo/internals/ford/runes/)

664−can show you how to access various ship resources for user in your pages. To

673+can show you how to access various ship resources for use in your pages. To

665674learn more about how the renderer works, take a look at the

666−`/home/ren/urb.hoon` file inside your urbit.

675+`/home/ren/urb.hoon` file inside your pier.

667676

668677## Udon: A Guide {#udon}

669678

670−Udon is a way to write content for the web. It's a minimalist

679+Udon is a way to write content for the web. It’s a minimalist

671680markup language for creating and rendering text documents, with a

672−Markdown-inspired syntax. It's integrated with our Hoon programming language,

681+Markdown-inspired syntax. It’s integrated with our Hoon programming language,

673682allowing it to be used as standalone prose in its own file or embedded inside a

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

675−using Hoon's XML-templating syntax, Sail.

684+using Hoon’s XML-templating syntax, Sail.

676685

677686There are quite a few similarities between Udon and the

678−CommonMark standard, but there are enough differences that you shouldn't rely on

687+CommonMark standard, but there are enough differences that you shouldn’t rely on

679688existing knowledge of the latter. Udon generally supports only one

680689syntax for each type of HTML node it emits. Udon is also stricter than

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

@@ -687,8 +696,8 @@ will use the `frontpage.hoon` method that we are already familiar with.

687696

688697To test out Udon, put a `;>` under the `^- manx` in your `frontpage.hoon` file,

689698and then put all your Udon code under that `;>`. Then run `|commit %home`

690−in the Dojo. If you've already run the `|serve` command code from the first

691−section, the new content should appear at `localhost/test`.

699+in the Dojo. If you’ve already run the `|serve` command code from the first

700+section, the new content should appear at `http://localhost/test`.

692701

693702## Udon Syntax

694703

@@ -701,32 +710,32 @@ The first thing on a `.udon` file is a chunk of code called the front matter. It

701710contains metadata about your page, such as date, title, and position relative

702711to sibling pages.

703712

704−As an example, let's look at the front matter of this very page:

713+As an example, let’s look at the front matter of this very page:

705714

706715```

707716:- :~ navhome/'/docs/'

708− sort/'11'

717+ sort/'28'

709718 title/'Udon'

710719 ==

711720;>

712721```

713722

714−What's going on here?

723+What’s going on here?

715724

716725`:-`, the Hoon rune for creating a cell, creates a cell composed of

717726the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune

718727for Udon.

719728

720729`:~` creates a list out of the three elements: `navhome/'/docs/'`, which

721−indicates that navigating "home" will bring you to the urbit.org/docs section

722−of the website; `sort/'28',` which assigns it the 28th position of the

730+indicates that navigating “home” will bring you to the urbit.org/docs section

731+of the website; `sort/'28'`, which assigns it the 28th position of the

723732immediate section that contains it, the one you see in the sidebar;

724733and `title/'Udon'`, which gives the page its title. The `==` digraph

725734terminates the list.

726735

727736`;>` is a Sail rune that creates a node that contains everything that follows

728−it, telling the parser that that text should be interpreted as Udon.

729−It's not technically front matter, but you'll always find it following the

737+it, telling the parser that this text should be interpreted as Udon.

738+It’s not technically front matter, but you’ll always find it following the

730739front matter, since all Udon must come after this rune.

731740

732741The categories listed in the example above -- `navhome`, `sort`, and `title` --

@@ -749,16 +758,18 @@ parsing.

749758

750759Headers in Udon begin the line with one or more `#` characters,

751760followed by a single space. After that space comes the actual text to be

752−displayed. The number of leading `#`s corresponds to the resulting HTML

761+displayed. The number of leading `#` characters corresponds to the resulting HTML

753762header-size element: `#` yields an `<h1>`, `##` yields an `<h2>`, and so on,

754763through `<h6>`. The header for this section is `### Headers`.

755764

756765**Example:**

766+

757767```

758768#### Header (h4)

759769

760770##### Header (h5)

761771```

772+

762773**Produces:**

763774

764775#### Header (h4)

@@ -773,7 +784,6 @@ element.

773784Enclosing text with `*` will cause that text to appear bolded, using a `<b>`

774785element.

775786

776−

777787**Example:**

778788

779789```

@@ -793,35 +803,37 @@ the _same line_.

793803**Example:**

794804

795805```

796−Here's the first line.

806+Here’s the first line.

797807

798−This second line is separated by two newlines, so it's a separate paragraph.

808+This second line is separated by two newlines, so it’s a separate paragraph.

799809

800−This line looks like a distinct paragraph, but...

801−It's only separated by a single newline, so it's included in the same paragraph.

810+This line looks like a distinct paragraph, but …

811+It’s only separated by a single newline, so it’s included in the same paragraph.

802812```

803−**Produces:**

804813

814+**Produces:**

805815

806−Here's the first line.

816+Here’s the first line.

807817

808−This second line is separated by two newlines, so it's a separate paragraph.

818+This second line is separated by two newlines, so it’s a separate paragraph.

809819

810−This line looks like a distinct paragraph, but...

811−It's only separated by a single newline, so it's included in the same paragraph.

820+This line looks like a distinct paragraph, but …

821+It’s only separated by a single newline, so it’s included in the same paragraph.

812822

813823#### Backslash Line Break

814824

815825A backslash at the end of a line inserts a line break (`<br>`)

816−after that line. This contrasts with the normal udon behavior of

826+after that line. This contrasts with the normal Udon behavior of

817827converting newlines to spaces.

818828

819829**Example:**

830+

820831```

821832I wonder how long each line

822833will be if I put backslashes\

823834at the ends of the lines.

824835```

836+

825837**Produces:**

826838

827839I wonder how long each line

@@ -837,14 +849,13 @@ as an escape character, causing it to be rendered raw.

837849

838850```

839851Here is some *bold* text.

840−Here is some \*not bold* text.

852+Here is some \*not bold\* text.

841853```

842854

843855**Produces:**

844856

845857Here is some **bold** text.

846−Here is some \*not bold* text.

847−

858+Here is some \*not bold\* text.

848859

849860### List

850861

@@ -859,18 +870,18 @@ a number corresponding to its position in that list.

859870New list elements are delineated by newlines beginning with list symbols of

860871the appropriate type (`-` or `+`).

861872

862−Just as with non-list text, text on a bare newline will appear on line before,

863−separated by a space. A `\\` is used to create a line-break that isn't the list

864−itself and isn't a list. Both of these kinds of newlines must be indented by two

873+Just as with non-list text, text on a bare newline will appear on the line before,

874+separated by a space. A `\\` is used to create a line-break that isn’t the list

875+itself and isn’t a list. Both of these kinds of newlines must be indented by two

865876spaces, or else the page will not parse.

866877

867878Indentation is also used for creating nested sub-lists. Sub-lists of one kind

868−can be used with parent lists of the other kind. Sub-lists can't be nested

869−directly after either kind of aforementioned newline that isn't a list element;

879+can be used with parent lists of the other kind. Sub-lists can’t be nested

880+directly after either kind of aforementioned newline that isn’t a list element;

870881only lines that are themselves list elements can nest sub-lists.

871882

872883A newline after a blank line is interpreted as a new paragraph in normal text.

873−Between to list elements, however, a blank line is semantically equivalent to

884+Between two list elements, however, a blank line is semantically equivalent to

874885a bare newline. To separate two lists with blank space, create a blank line

875886followed by a `\\` on its own line.

876887

@@ -884,15 +895,15 @@ followed by a `\\` on its own line.

884895- Chicken\

885896 Make sure that you get enough for the barbecue

886897- Bread

887− + Ask the baker what's fresh

898+ + Ask the baker what’s fresh

888899 + Buy the second-freshest batch

889900- Cereal

890901

891902\

892903+ First, separate eggs into a bowl

893904+ Then, add a splash of cream

894− - If you don't have cream, you can use milk, but cream is preferred

895− + If you don't have milk or cream, melt an eighth of a stick of butter on

905+ - If you don’t have cream, you can use milk, but cream is preferred

906+ + If you don’t have milk or cream, melt an eighth of a stick of butter on

896907 a skillet

897908 + Scramble the eggs in the bowl

898909 + Pour the eggs onto the skillet before the butter browns

@@ -914,15 +925,15 @@ Produces

914925- Chicken\

915926 Make sure that you get enough for the barbecue

916927- Bread

917− 1. Ask the baker what's fresh

928+ 1. Ask the baker what’s fresh

918929 1. Buy the second-freshest batch

919930- Cereal

920931

921932\

9229331. First, separate eggs into a bowl

9239341. Then, add a splash of cream

924− - If you don't have cream, you can use milk, but cream is preferred

925− 1. If you don't have milk or cream, melt an eighth of a stick of butter on

935+ - If you don’t have cream, you can use milk, but cream is preferred

936+ 1. If you don’t have milk or cream, melt an eighth of a stick of butter on

926937 a skillet

927938 1. Scramble the eggs in the bowl

928939 1. Pour the eggs onto the skillet before the butter browns

@@ -945,26 +956,26 @@ destination.

945956**Example:**

946957

947958```

948−[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)

959+[I’m an inline-style link](https://urbit.org/operations/#using-the-shell)

949960```

950961

951962**Produces:**

952963

953−[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)

964+[I’m an inline-style link](https://urbit.org/operations/#using-the-shell)

954965

955966The second type is a reference-style link, which uses a relative path, based on

956−the current page's location. Instead of the full url, we use `..` to fill in

957−the all of the URL that the destination has in common with the origin page.

967+the current page’s location. Instead of the full url, we use `..` to fill in

968+all of the URL that the destination has in common with the origin page.

958969

959970**Example:**

960971

961972```

962−[I'm a reference-style link](../shell)

973+[I’m a reference-style link](../shell)

963974```

964975

965976**Produces:**

966977

967−[I'm a reference-style link](../shell)

978+[I’m a reference-style link](../shell)

968979

969980If this page is located at `https://www.urbit.org/docs/reference/`, then these two

970981examples should have the same destination.

@@ -979,14 +990,16 @@ so we need to use some [Sail](#sail). If there are two or more anchors with

979990the same `id` on the page, you will arrive at the earliest instance of the the

980991anchor.

981992

993+Note that each HTML element `id` should be unique and not be used more than once.

994+

982995**Example:**

983996

984997```

985998Check out this [section](#here-we-are) that we want to jump to.

986999

987−Four score and seven years ago....

1000+Four score and seven years ago …

9881001

989−It was the best of times, it was the worst of times...

1002+It was the best of times, it was the worst of times …

9901003

9911004## Here we are!

9921005```

@@ -995,9 +1008,9 @@ It was the best of times, it was the worst of times...

9951008

9961009Check out this [section](#here-we-are) that we want to jump to.

9971010

998−Four score and seven years ago....

1011+Four score and seven years ago …

9991012

1000−It was the best of times, it was the worst of times...

1013+It was the best of times, it was the worst of times …

10011014

10021015## Here we are!

10031016

@@ -1015,7 +1028,6 @@ opening and closing quotes -- that is, `“` and `”`.

10151028

10161029“Yes,” he said. “That is the way with him.”

10171030

1018−

10191031### Code Literal

10201032

10211033There are two ways to show the literal text of code without running it: inline

@@ -1035,20 +1047,22 @@ Enclosing some text in `` ` `` characters will cause it to be displayed as code,

10351047inside a `<code>` HTML element with monospace font and highlighted with a

10361048different background color.

10371049

1038−Using `` ` `` is useful when you want to designated only part of a line as code.

1039−Since this page is written in Udon, we've been using this operation

1040−throughout this guide to `format text` to distinguish code from prose.

1050+Using `` ` `` is useful when you want to designate only part of a line as code.

1051+Since this page is written in Udon, we’ve been using this operation

1052+throughout this guide to _format text_ to distinguish `code` from prose.

10411053

10421054**Example:**

1055+

10431056```

1044−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.

1057+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp’s `apply`.

10451058```

1059+

10461060**Produces:**

10471061

1048−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.

1062+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp’s `apply`.

10491063

10501064Also, using the `++` prefix before a word will cause the word to be rendered as

1051−code with the `++` displayed, since that's the standard notation for an arm in

1065+code with the `++` displayed, since that’s the standard notation for an arm in

10521066Hoon.

10531067

10541068**Example:**

@@ -1070,7 +1084,6 @@ Most of our examples so far have used.

10701084

10711085**Example:**

10721086

1073−

10741087 ```

10751088 (def Y (fn [f]

10761089 ((fn [x]

@@ -1094,7 +1107,7 @@ Most of our examples so far have used.

10941107### Hoon Constants

10951108

10961109Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)

1097−that can be used in udon as well. Udon detects such code, and so these

1110+that can be used in Udon as well. Udon detects such code, and so these

10981111forms will automatically appear inside a `<code>` element like inline code.

10991112

11001113Example:

@@ -1105,17 +1118,16 @@ Example:

11051118%term

11061119```

11071120

1108−produces:\

1121+Produces:\

11091122

11101123`~2017.8.29` \

11111124`0xdead.beef` \

11121125`%term`

11131126

1114−

11151127### Horizontal Rule

11161128

11171129Three or more hyphens, such as `---`, on their own line produce an `<hr>`

1118−element, the 'horizontal rule'. This is rendered as a horizontal line the

1130+element, the “horizontal rule”. This is rendered as a horizontal line the

11191131width of its containing paragraph.

11201132

11211133**Example:**

@@ -1130,7 +1142,6 @@ And below this line, too

11301142

11311143**Produces:**

11321144

1133−

11341145Above the line

11351146

11361147---

@@ -1144,7 +1155,7 @@ And below this line, too

11441155### Block Quote

11451156

11461157A section of text with the first line beginning with `>` and a space,

1147−and each successive newline indented by two spaces yields a

1158+and each successive newline indented by two spaces, yields a

11481159`<blockquote>` HTML element. This block quote can itself contain more Udon,

11491160including more block quotes to render nested levels of quotation.

11501161

@@ -1175,10 +1186,9 @@ Quote break.

11751186

11761187> He is pale and thin, he wears a thin and ragged linen shirt.

11771188

1178−

11791189### Poem

11801190

1181−A poem is a section of text with meaningful newlines. Recall that,

1191+A poem is a section of text with meaningful newlines. Recall that,

11821192normally in Udon, newlines are treated as spaces and do not create a

11831193new line of text. If you want to embed text where newlines are retained, then

11841194indent the text in question with **eight spaces**.

@@ -1191,6 +1201,7 @@ indent the text in question with **eight spaces**.

11911201 Is moving its slow thighs, while all about it

11921202 Reel shadows of the indignant desert birds.

11931203```

1204+

11941205**Produces:**

11951206

11961207 A shape with lion body and the head of a man,

@@ -1198,14 +1209,12 @@ indent the text in question with **eight spaces**.

11981209 Is moving its slow thighs, while all about it

11991210 Reel shadows of the indignant desert birds.

12001211

1201−

12021212## Sail Expressions

12031213

1204−It's possible to use Udon as an HTML templating language akin to

1214+It’s possible to use Udon as an HTML templating language akin to

12051215PHP, ERB, JSP, or Handlebars templates. This facility derives

12061216in part from the support for embedding Hoon code inside the markup.

12071217

1208−

12091218Sail is a domain-specific language within Hoon for creating XML nodes,

12101219including HTML. It can be used directly within Udon to provide

12111220scripting capability with Hoon and also to provide more precise control over the

@@ -1217,7 +1226,7 @@ Example:

12171226```

12181227;=

12191228 ;p

1220− ;strong: Don't panic!

1229+ ;strong: Don’t panic!

12211230 ;br;

12221231 ;small: [reactive publishing intensifies]

12231232 ==

@@ -1226,9 +1235,8 @@ Example:

12261235

12271236Produces:

12281237

1229−

12301238<p>

1231− <strong>Don't panic!</strong>

1232− <br>

1233− <small>[reactive publishing intensifies]</small>

1239+ <strong>Don’t panic!</strong>

1240+ <br />

1241+ <small>[reactive publishing intensifies]</small>

12341242</p>

tutorials/ship-troubleshooting.md+32−31

@@ -5,7 +5,7 @@ template = "doc.html"

55aliases = ["docs/using/ship-troubleshooting/"]

66+++

8−Urbit is still in the development stage, so there's a chance that your ship won't start properly, or will stop working properly when you're running it. That's ok! This document is intended to help you in such an event.

8+Urbit is still in the development stage, so there’s a chance that your ship won’t start properly, or will stop working properly when you’re running it. That’s ok! This document is intended to help you in such an event.

1010## Table of Contents

1111

@@ -17,32 +17,33 @@ Urbit is still in the development stage, so there's a chance that your ship won'

1717

1818## Best Practices {#best-practices}

1919

20−An ounce of prevention is worth a pound of cure, so let's first go over some best practices to keep your ship in working order.

20+An ounce of prevention is worth a pound of cure, so let’s first go over some best practices to keep your ship in working order.

2121

2222### Only boot with your keyfile once

2323

2424Once your ship is booted with your keyfile, you should never use that same keyfile again. If you do boot with the same keyfile twice, any other ship on the network that your ship has communicated with will not be able to talk to your ship.

2525

26−If you accidentally booted with the same keyfile twice, the only remedy is performing a [personal breach](#personal-breach), which is explained in the next section.

26+If you accidentally booted with the same keyfile twice, the only remedy is performing a [personal breach](#personal-breach), which is explained in the next section.

2727

2828### Do not delete your pier

2929

30−Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won't be able to talk to any ship you've talked to before. The only solution to this is performing a [personal breach](#personal-breach)

30+Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won’t be able to talk to any ship you’ve talked to before. The only solution to this is performing a [personal breach](#personal-breach)

3131

3232### Keep track of the directory that you put your ship in

3333

34−When you first start your ship, you should make sure you put it a place where you can find it again and where it won't get accidentally deleted. Remember that you must perform `|mount %` in your ship's Dojo to make your ship visible as a directory in the Unix file system.

34+When you first start your ship, you should make sure you put it a place where you can find it again and where it won’t get accidentally deleted. Remember that you must perform `|mount %` in your ship’s Dojo to make your ship visible as a directory in the Unix file system.

35+

36+### Avoid killing the urbit process directly

3537

36−### Avoid killing the Urbit process directly

3738The best way to end an urbit process is to use `ctrl-d` from the Dojo. Unix methods to kill the process, such as with `ctrl-z` or with the `kill` Bash command, or simply closing the window, should only be used if `ctrl-d` does not work.

3839

3940### Keep up-to-date builds

4041

41−Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you're behind, update using [this guide](@using/install.md).

42+Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you’re behind, update using [this guide](@using/install.md).

4243

43−### `|hi` your star to see if you're connected

44+### `|hi` your star to see if you’re connected

4445

45−Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star's name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you're in a Talk channel with.

46+Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star’s name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you’re in a Chat channel with.

4647

4748### Turn your ship off and on again

4849

@@ -50,11 +51,11 @@ Use `ctrl-d` to gracefully exit your ship, and then start it again. This can sol

5051

5152### Use the `|knob` command to customize your error messages

5253

53−Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It's used to silence errors that aren't important.

54+Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It’s used to silence errors that aren’t important.

5455

5556The command takes two arguments, and comes in the form of `|knob %error-tag %level`.

5657

57−`%error-tag` is the name of the error in question. It's usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.

58+`%error-tag` is the name of the error in question. It’s usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.

5859

5960`%level` determines how much you will see of errors with your chosen `%error-tag`. There are three levels:

6061

@@ -66,9 +67,9 @@ So for example, to silence all Ames packet-related errors, try `|knob %hole %hus

6667

6768### Perform a personal breach. {#personal-breach}

6869

69−A personal breach is when a ship tells all the other ships that have communicated with it to treat it as though the ship was just started for the first time again, since everyone has network has forgotten about it.

70+A personal breach is when a ship tells all the other ships that have communicated with it to treat it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.

7071

71−Personal breaches often fix connectivity issues, but should only be used as a last resort. To find out how to perform a personal breach, check out our [Guide to Breaches](../guide-to-breaches). Before taking such a drastic measure, try other methods in this guide. You can also ask for help on `~dopzod/urbit-help`, or, failing that, in the #ship-starting-support channel in our [Discord server](https://discord.gg/n9xhMdz).

72+Personal breaches often fix connectivity issues, but should only be used as a last resort. To find out how to perform a personal breach, check out our [Guide to Breaches](../guide-to-breaches). Before taking such a drastic measure, try other methods in this guide. You can also ask for help on `~dopzod/urbit-help`, or, failing that, in the `#ship-starting-support` channel in our [Discord server](https://discord.gg/n9xhMdz).

7273

7374## Operation Issues {#operation-issues}

7475

@@ -78,21 +79,21 @@ Run `|wash-gall`. This clears caches in Gall, and may result in steep performanc

7879

7980### My urbit is frozen

8081

81−Sometimes this happens if you're processing a very large event, or if you're in an infinite loop, or for a variety of other reasons.

82+Sometimes this happens if you’re processing a very large event, or if you’re in an infinite loop, or for a variety of other reasons.

8283

83−Before doing anything, try waiting for a minute: an event might finish processing. If it doesn't clear up, then use Unix kill-command, `ctrl-z`, to end your ship's process. Then restart your ship.

84+Before doing anything, try waiting for a minute: an event might finish processing. If it doesn’t clear up, then use the Unix kill-command, `ctrl-z`, to end your ship’s process. Then restart your ship.

8485

8586### When I try to type into the Dojo, it prints `dy-noprompt`

8687

8788This happens when your Dojo is waiting on a request, such as an HTTP request. You can fix it simply by typing `backspace` or (`delete` on Mac).

8889

89−### My ship doesn't recognize file changes that I make in my pier

90+### My ship doesn’t recognize file changes that I make in my pier

9091

91−Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you'd like to sync.

92+Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you’d like to sync.

9293

9394## Connectivity Issues {#connectivity-issues}

9495

95−### I can't communicate with anyone

96+### I can’t communicate with anyone

9697

9798You may have booted a ship with your keyfile twice in the same era. To fix this, you must perform a [personal breach](#personal-breach).

9899

@@ -100,15 +101,15 @@ You may have booted a ship with your keyfile twice in the same era. To fix this,

100101

101102You may see a message like this one: `/~zod/home/~2019.7.22..18.55.46..83a3/sys/vane/ames:<[line column].[line column]>`. This is a clay path to a Hoon file, pointing to the line and column where an expression crashed. This kind of error might be accompanied by a `crud` message.

102103

103−This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship's "life number," which is the number that starts at one and increments every time that ship performs a personal breach.

104+This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship’s “life number,” which is the number that starts at one and increments every time that ship performs a personal breach.

104105

105−This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship's name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship's `@p`. You can find the hexadecimal representation by running...

106+This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship’s name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship’s `@p`. You can find the hexadecimal representation by running …

106107

107108```

108109`@ux`~sampel-palnet

109110```

110111

111−in the Dojo, where `~sampel-palnet` is the other ship's name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn't** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:

112+… in the Dojo, where `~sampel-palnet` is the other ship’s name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn’t** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:

112113

113114```

114115:azimuth-tracker|listen ~ %app %azimuth-tracker

@@ -124,13 +125,13 @@ The last line above syncs from an Ethereum node for _all_ ships on the network.

124125

125126The above commands work if you have the wrong keys of other ships. If other ships have wrong keys of _yours_, you need to somehow ask them to to run such a command.

126127

127−### I can talk to some ships, but I can't talk to my sponsor and some other ships

128+### I can talk to some ships, but I can’t talk to my sponsor and some other ships

128129

129130This is the result of deleting your pier and starting your ship again. To fix this, you must perform a [personal breach](#personal-breach).

130131

131132## Booting Issues {#booting-issues}

132133

133−### My ship won't boot and gets a `terminals database is inaccessible` message

134+### My ship won’t boot and gets a `terminals database is inaccessible` message

134135

135136This happens when you try to run the Urbit binary through your `$PATH`. When running the command, you need to be explicit and specify the actual path to it in the filesystem. This is a side-effect of the way we build the release binaries, which will be fixed.

136137

@@ -138,7 +139,7 @@ This happens when you try to run the Urbit binary through your `$PATH`. When run

138139

139140You may have used the wrong arguments when booting your ship for the first time. Delete this comet and try again.

140141

141−### My development ship ("fakezod") gets a `boot: malformed` failure

142+### My development ship (“fakezod”) gets a `boot: malformed` failure

142143

143144This means that you gave your development ship an invalid `@p`. So, you will get this error if you write, for example, `urbit -F zodzod` instead of `urbit -F zod`.

144145

@@ -146,17 +147,17 @@ This means that you gave your development ship an invalid `@p`. So, you will get

146147

147148### I got a `bail` error and my ship crashed

148149

149−Try just bringing it back up; it will often start working just fine again.

150+Try bringing it back up; it will often start working just fine again.

150151

151−However, if you get a `bail` error again, you should perform a personal breach.

152+However, if you get a `bail` error again, you should perform a [personal breach](#personal-breach).

152153

153154#### Making a GitHub issue out of your `bail`

154155

155−You can get help with you problem by creating an issue at github.com/urbit/urbit. But to make a good issue, you need to include some information.

156+You can get help with you problem by creating an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues). But to make a good issue, you need to include some information.

156157

157−When your urbit crashes with a `bail`, you'll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.

158+When your urbit crashes with a `bail`, you’ll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.

158159

159−Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you'll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:

160+Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you’ll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:

160161

161162```

162163(lldb) bt

@@ -175,11 +176,11 @@ Copy this stack trace and include it in your GitHub issue.

175176

1761771. Make sure you are running version to `0.8.2` if you are not already on it.

177178

178−2. Restart your ship. If you don't crash again, everything may be fine. If you **do** crash again, then you should perform a [personal breach](#personal-breach).

179+2. Restart your ship. If you don’t crash again, everything may be fine. If you **do** crash again, then you should perform a [personal breach](#personal-breach).

179180

180181### My ship crashed with a `bail: oops` error

181182

182−Restart your ship. These issues often just go away on their own. If this error repeats after restart two or more times, post the messages in an issue at github.com/urbit/urbit/issues.

183+Restart your ship. These issues often just go away on their own. If this error repeats after restart two or more times, post the messages in an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues).

183184

184185This same error might also appear with a message like `Assertion '0'`.

185186