git.iko.soy/urbit.org
on master help sign in
Merge remote-tracking branch 'origin/cleanorg' into cleanorg

Conflicts: docs/hoon/exercises.md

commit3fae695245a3f92116db5f9179fdd2f87684461d authorC. Guy Yarvin <cgyarvin@gmail.com> dateFri 22 Apr 2016, 22:34 (11 years ago) parent7b5629ab1ac9c1
13 files changed+644−243
compare with master
unifiedsplit
docs/hoon/exercises.md+4−155 docs/hoon/library.md+2−2 docs/programming/hoon/exercises/data-structures.md+22 docs/programming/hoon/exercises/fizzbuzz.md+37 docs/programming/hoon/exercises/life.md+120 docs/programming/hoon/exercises/lists.md+39 docs/programming/hoon/exercises/math.md+26 docs/using/filesystem.md+90−63 docs/using/messaging.md+11−5 docs/using/web.md+30−18 docs/using/web/blog.md+94 docs/using/web/comments.md+42 docs/using/web/static.md+127
docs/hoon/exercises.md+4−155
@@ -8,159 +8,8 @@ The best way to cement this knowledge in your mind is to do
88exercises. These are roughly in order of ascending difficulty,
99and they are intended to form a sort of primer to Hoon.
1010
11−## Friends of FizzBuzz
11+Feel free to ask questions in the comments. You can subscribe to the
12+`/comments` `:talk` channel on this ship to keep abreast of the
13+conversation.
1214
13−1. Consider the following implementation of FizzBuzz, which is
14− equivalent to the one in the [Demo](demo) section.
15−
16− ```
17− |= end/atom
18− =+ count=1
19− |-
20− ^- (list tape)
21− ?: =(end count)
22− ~
23− :-
24− ?: =(0 (mod count 15))
25− "FizzBuzz"
26− ?: =(0 (mod count 5))
27− "Fizz"
28− ?: =(0 (mod count 3))
29− "Buzz"
30− (pave !>(count))
31− $(count (add 1 count))
32− ```
33−
34− Modify this to produce "Fuzz" when the number is divisible by
35− 7, "Fuzz" when divisible by 21, "FuzzFizz" when divisble by 35,
36− and "FuzzFizzBuzz" when divisble by 105.
37−
38−1. Modify FizzBuzz from the previous exercise to take both a
39− start and an end number.
40−
41−1. Modify FizzBuzz from the previous exercise to count down
42− instead of up.
43−
44−## Math
45−
46−1. Write a function that produces a list of the first `n`
47− triangular numbers. The `n`th triangular number is the sum
48− of the first `n` positive integers.
49−
50−1. Using the program from the previous exercise, write a
51− function that produces the first `n` tetrahedral numbers.
52− The `n`th tetrahedral number is the sum of the first `n`
53− triangular numbers.
54−
55−## Conway's Game of Life
56−
57−Conway's Game of Life is a zero-player game played on an `n`x`n`
58−grid of spaces, each of which is either "alive" or "dead". Every
59−iteration, some or all of the spaces change from alive to dead or
60−from dead to alive.
61−
62−Specifically, for each iteration, each dead space becomes alive
63−if and only if it is adjacent to exactly three live spaces. Each
64−live remains alive if and only if it is adjacent to either two or
65−three live spaces. In this context, "adjacent to" includes the
66−eight spaces that share either a side or a corner with the space.
67−Thus, in the following map, the center space (dead) is adjacent
68−to exactly three live spaces, so it will be alive in the next
69−iteration. `#` signifies a live space and `.` signifies a dead
70−space.
71−
72− ..#
73− ...
74− ##.
75−
76−
77−1. Write a function that takes nine loobean inputs, `nw`, `nc`,
78− `ne`, `cw`, `cc`, `ce`, `sw`, `sc`, and `se`. Produce 'yes'
79− if the center space will be alive in the next generation and
80− 'no' if it will be dead.
81−
82−1. Write a function that takes an integer `n` and produces an
83− `n` by `n` grid of loobeans, (hereafter, "board"),
84− initialized to 'no'. This grid should be represented as a
85− list of `n` lists of length `n`.
86−
87−1. Write a function that takes a board, a row index, and a
88− column index, and produces a new board, identical to the old
89− except that the state of the space referred to by the row and
90− column indices has been toggled.
91−
92−1. Use the following function to pretty-print the board. For
93− bonus points, try to follow what it's doing.
94−
95− ```
96− :: XX test
97− |= board/(list (list ?))
98− ^- tang
99− %+ turn board
100− |= row/(list ?)
101− :- %leaf
102− ^- tape
103− %+ turn row
104− |= space/?
105− ?: space
106− '# '
107− '. '
108− ```
109−
110− If you run this function with a board, you'll get a
111− pretty-printable object (a `tang`), but it won't be
112− pretty-printed. When running the generator from the dojo,
113− run `&tang +generator arguments` to mark the result as a
114− `tang`, which will tell the dojo to intelligently
115− pretty-print it.
116−
117−1. Using the functions created in the previous exercises, create
118− a 10 by 10 board, and flip the states of the spaces at
119− coordinates (counting from the top left, indexed from 0)
120− `(2,1)`, `(3,2)`, `(1,3)`, `(2,3)`, and `(3,3)`. Use the
121− pretty printer to print out the board. Your output should be
122− the following:
123−
124− ```
125− . . . . . . . . . .
126− . . # . . . . . . .
127− . . . # . . . . . .
128− . # # # . . . . . .
129− . . . . . . . . . .
130− . . . . . . . . . .
131− . . . . . . . . . .
132− . . . . . . . . . .
133− . . . . . . . . . .
134− . . . . . . . . . .
135− ```
136−
137−1. Write a function that iterates every space on the board.
138− Print out the new board. It should look like this:
139−
140− ```
141− . . . . . . . . . .
142− . . . . . . . . . .
143− . # . # . . . . . .
144− . . # # . . . . . .
145− . . # . . . . . . .
146− . . . . . . . . . .
147− . . . . . . . . . .
148− . . . . . . . . . .
149− . . . . . . . . . .
150− . . . . . . . . . .
151− ```
152−
153− > Note that the spaces on the edge don't have the full nine
154− > neighbors. For now, assume that they're always dead.
155−
156−1. Write a function that runs the above function `n` times on
157− the board. Observe the board as the game progresses.
158− Congratulations, you've written Conway's Game of Life in
159− Hoon!
160−
161−1. One common way to handle the edge of the board is to pretend
162− that it "wraps around", forming a torus. In other words, say
163− that the spaces on the left edge of the map are adjacent to
164− the ones on the right edge, and the spaces on the top edge
165− are adjacent to the spaces on the bottom edge. Pay special
166− attention to the corners.
15+<list />
docs/hoon/library.md+2−2
@@ -1,8 +1,8 @@
11---
22sort: 11
3−title: Library
3+title: Std Library reference
44---
55
6−# Library
6+# Library reference
77
88<list dataPreview="true" titlesOnly="true"></list>
docs/programming/hoon/exercises/data-structures.mdnew file+22
@@ -0,0 +1,22 @@
1+---
2+sort: 4
3+comments: true
4+---
5+
6+# Sets, Maps, and Queues
7+
8+Sets are constructed with `++silt`. A set is a non-ordered
9+collection of unique elements.
10+
11+```
12+(silt `(list @t)`['urbit' 'arvo' 'hoon' 'arvo' ~])
13+```
14+
15+We'll refer to this particular set as `s` in the exercises. It
16+is of type `(set @t)` since each element is a `@t`.
17+
18+The `++in` core contains library functions for dealing with sets.
19+For example, `++has:in` checks whether an element is in the set.
20+Thus, `(~(has in s) 'arvo')` returns yes.
21+
22+
docs/programming/hoon/exercises/fizzbuzz.mdnew file+37
@@ -0,0 +1,37 @@
1+---
2+sort: 1
3+comments: true
4+---
5+
6+# Friends of FizzBuzz
7+
8+1. Consider the following implementation of FizzBuzz, which is
9+ equivalent to the one in the [Demo](../../demo) section.
10+
11+ ```
12+ |= end/atom
13+ =+ count=1
14+ |-
15+ ^- (list tape)
16+ ?: =(end count)
17+ ~
18+ :-
19+ ?: =(0 (mod count 15))
20+ "FizzBuzz"
21+ ?: =(0 (mod count 5))
22+ "Fizz"
23+ ?: =(0 (mod count 3))
24+ "Buzz"
25+ (text !>(count))
26+ $(count (add 1 count))
27+ ```
28+
29+ Modify this to produce "Fuzz" when the number is divisible by
30+ 7, "Fuzz" when divisible by 21, "FuzzFizz" when divisble by 35,
31+ and "FuzzFizzBuzz" when divisble by 105.
32+
33+1. Modify FizzBuzz from the previous exercise to take both a
34+ start and an end number.
35+
36+1. Modify FizzBuzz from the previous exercise to count down
37+ instead of up.
docs/programming/hoon/exercises/life.mdnew file+120
@@ -0,0 +1,120 @@
1+---
2+sort: 5
3+comments: true
4+---
5+
6+# Conway's Game of Life
7+
8+Conway's Game of Life is a zero-player game played on an `n`x`n`
9+grid of spaces, each of which is either "alive" or "dead". Every
10+iteration, some or all of the spaces change from alive to dead or
11+from dead to alive.
12+
13+Specifically, for each iteration, each dead space becomes alive
14+if and only if it is adjacent to exactly three live spaces. Each
15+live remains alive if and only if it is adjacent to either two or
16+three live spaces. In this context, "adjacent to" includes the
17+eight spaces that share either a side or a corner with the space.
18+Thus, in the following map, the center space (dead) is adjacent
19+to exactly three live spaces, so it will be alive in the next
20+iteration. `#` signifies a live space and `.` signifies a dead
21+space.
22+
23+ ..#
24+ ...
25+ ##.
26+
27+
28+1. Write a function `next-generation` that takes nine loobean
29+ inputs, `nw`, `nc`, `ne`, `cw`, `cc`, `ce`, `sw`, `sc`, and
30+ `se`. Produce 'yes' if the center space will be alive in the
31+ next generation and 'no' if it will be dead.
32+
33+1. Write a function `create-board` that takes an integer `n` and
34+ produces an `n` by `n` grid of loobeans, (hereafter,
35+ "board"), initialized to 'no'. This grid should be
36+ represented as a list of `n` lists of length `n`.
37+
38+1. Write a function `toggle-space` that takes a board, a row
39+ index, and a column index, and produces a new board,
40+ identical to the old except that the state of the space
41+ referred to by the row and column indices has been toggled.
42+
43+1. Use the following function `print-board` to pretty-print the
44+ board. For bonus points, try to follow what it's doing.
45+
46+ ```
47+ :: XX test
48+ |= board/(list (list ?))
49+ ^- tang
50+ %+ turn board
51+ |= row/(list ?)
52+ :- %leaf
53+ ^- tape
54+ %+ turn row
55+ |= space/?
56+ ?: space
57+ '# '
58+ '. '
59+ ```
60+
61+ If you run this function with a board, you'll get a
62+ pretty-printable object (a `tang`), but it won't be
63+ pretty-printed. When running the generator from the dojo,
64+ run `&tang +generator arguments` to mark the result as a
65+ `tang`, which will tell the dojo to intelligently
66+ pretty-print it.
67+
68+1. Using the functions created in the previous exercises, create
69+ a 10 by 10 board, and flip the states of the spaces at
70+ coordinates (counting from the top left, indexed from 0)
71+ `(2,1)`, `(3,2)`, `(1,3)`, `(2,3)`, and `(3,3)`. Use the
72+ pretty printer to print out the board. Your output should be
73+ the following:
74+
75+ ```
76+ . . . . . . . . . .
77+ . . # . . . . . . .
78+ . . . # . . . . . .
79+ . # # # . . . . . .
80+ . . . . . . . . . .
81+ . . . . . . . . . .
82+ . . . . . . . . . .
83+ . . . . . . . . . .
84+ . . . . . . . . . .
85+ . . . . . . . . . .
86+ ```
87+
88+1. Write a function `step` that iterates every space on the
89+ board. Print out the new board. It should look like this:
90+
91+ ```
92+ . . . . . . . . . .
93+ . . . . . . . . . .
94+ . # . # . . . . . .
95+ . . # # . . . . . .
96+ . . # . . . . . . .
97+ . . . . . . . . . .
98+ . . . . . . . . . .
99+ . . . . . . . . . .
100+ . . . . . . . . . .
101+ . . . . . . . . . .
102+ ```
103+
104+ > Note that the spaces on the edge don't have the full nine
105+ > neighbors. For now, assume that they're always dead.
106+
107+1. Write a function `life` that runs the above function `n`
108+ times on the board. Observe the board as the game
109+ progresses. Congratulations, you've written Conway's Game of
110+ Life in Hoon!
111+
112+1. One common way to handle the edge of the board is to pretend
113+ that it "wraps around", forming a torus. In other words, say
114+ that the spaces on the left edge of the map are adjacent to
115+ the ones on the right edge, and the spaces on the top edge
116+ are adjacent to the spaces on the bottom edge. Modify `step`
117+ to act this way. Pay special attention to the corners.
118+
119+1. Modify `create-board` to use `++og` to randomly initialize
120+ the board with live or dead spaces.
docs/programming/hoon/exercises/lists.mdnew file+39
@@ -0,0 +1,39 @@
1+---
2+sort: 3
3+comments: true
4+---
5+
6+# Lists
7+
8+In the following exercises, let `l` be `` `(list @t)`['u' 'r' 'b'
9+'i' 't' ~]``
10+
11+1. A list is a null-terminated tuple of values. For example,
12+ `[1 2 3 ~]` is a list of three integers, and
13+ `['a' 'b' 'c' ~]` is a list of three cords. Try casting
14+ `['a' 'b' 'c' ~]` to `(list @t)` and to `(list @)`. Lists
15+ are parameterized with the type of the values.
16+
17+1. `++flop` takes a list and produces its reverse. Use it to
18+ reverse `l`.
19+
20+1. Repeat the above exercise without using `++flop`.
21+
22+1. `++sort` takes a list and a comparison function to sort a
23+ list. The function must take two elements of the list and
24+ produce true if the first element is "less than" the other.
25+ Sort `l` alphabetically. Sort it reverse alphabetically.
26+
27+1. `++turn` takes a list and a function and applies the function
28+ to each element in the list, forming a new list of the
29+ results. This is called "map" in many functional languages.
30+ The function must accept an element of the list. Use the
31+ fact that subtracting 32 from a lowercase letter gives the
32+ equivalent uppercase letter (i.e. `(sub 'a' 'A')` is 32) to
33+ change every character in `l` to uppercase.
34+
35+1. `++welp` concatentates two lists. Concatenate `l` with the
36+ reverse of `l`.
37+
38+1. `++snag` takes a number `n` and a list and produces the
39+ element at index `n`. Pull out the `'i'` in `l`.
docs/programming/hoon/exercises/math.mdnew file+26
@@ -0,0 +1,26 @@
1+---
2+sort: 2
3+comments: true
4+---
5+
6+# Math
7+
8+1. Write a function that produces a list of the first `n`
9+ triangular numbers. The `n`th triangular number is the sum
10+ of the first `n` positive integers.
11+
12+1. Using the program from the previous exercise, write a
13+ function that produces the first `n` tetrahedral numbers.
14+ The `n`th tetrahedral number is the sum of the first `n`
15+ triangular numbers.
16+
17+1. The Fibonacci numbers are defined on the natural numbers as
18+ follows:
19+
20+ ```
21+ fib(0) = 0
22+ fib(1) = 1
23+ fib(n) = fib(n-1) + fib(n-2)
24+ ```
25+
26+ Write a function that computes the `nth` Fibonacci number.
docs/using/filesystem.md+90−63
@@ -6,18 +6,18 @@ title: Filesystem
66
77# Filesystem (`%clay`)
88
9−<div class="row">
10−<div class="col-md-8">
9+<div class="row"> <div class="col-md-8">
1110
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.
11+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
12+a typed, global, referentially transparent namespace. An easy way to
13+think about it is like typed `git` with continuous sync.
1314
14−The most common way to use `%clay` is to mount a `%clay` node in
15−a Unix directory. The Urbit process will watch this directory
16−and automatically record edits as changes, Dropbox style. The
17−mounted directory is always at the root of your pier directory.
15+The most common way to use `%clay` is to mount a `%clay` node in a
16+Unix directory. The Urbit process will watch this directory and
17+automatically record edits as changes, Dropbox style. The mounted
18+directory is always at the root of your pier directory.
1819
19−</div>
20−</div>
20+</div> </div>
2121
2222## Quickstart
2323
@@ -33,7 +33,8 @@ Mount the entire contents of your `sandbox` desk to Unix:
3333
3434 ~your-urbit:dojo> |mount /=sandbox=
3535
36−To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
36+To explore the filesystem from inside Urbit `+ls` and `+cat` are
37+useful:
3738
3839 ~your-urbit:dojo> +ls /=sandbox=/web
3940
@@ -41,7 +42,8 @@ Let's see the contents of `/=sandbox=/web/md`:
4142
4243 ~your-urbit:dojo> +cat /=sandbox=/web/md
4344
44−Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
45+Sync from your friend `~some-ship`'s `%experiment` desk to your
46+`%sandbox` desk:
4547
4648 |sync %sandbox ~some-ship %experiment
4749
@@ -49,21 +51,31 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
4951
5052<h3 class="first child">Paths</h3>
5153
52−A path in `%clay` is a list of URL-safe text, restricted to `[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)` where each segment is a `@ta`.
54+A path in `%clay` is a list of URL-safe text, restricted to `[a
55+z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
56+where each segment is a `@ta`.
5357
54−Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`. The first three segments of an urbit path are `/plot/desk/case`, for example `/~doznec/home/1`.
58+Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
59+The first three segments of an urbit path are `/plot/desk/case`, for
60+example `/~doznec/home/1`.
5561
5662#### Relative paths
5763
58−Relative paths are expressed using `%` which is roughly equivalent to Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be. There are no local relative paths. `foo/bar` must be written `%/foo/bar`.
64+Relative paths are expressed using `%` which is roughly equivalent to
65+Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
66+be. There are no local relative paths. `foo/bar` must be written
67+`%/foo/bar`.
5968
6069#### Substitution
6170
62−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
63−and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
64−`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
71+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
72+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
73+or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
6574
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`.
75+Most commonly this is used to avoid having to know the current
76+revision number in the `dojo`. Instead of writing
77+`/~your-urbit/home/4/path/to/file` you can just write
78+`/=home=/path/to/file`.
6779
6880### Revision-control
6981
@@ -99,7 +111,8 @@ Unmounts the Unix path `/generators`.
99111
100112Merges a `beak` into a `desk` using an optional merge `strategy`.
101113
102−A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec %home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
114+A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec
115+%home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
103116
104117**Examples:**
105118
@@ -113,16 +126,21 @@ Merge the `%examples` desk from `~waxbex-ribmex`
113126
114127### `|sync desk plot [plot-desk]`
115128
116−Subscribe to continuous updates from remote `plot` on local `desk`. `plot-desk` can specify the remote `desk` name. When omitted it's assumed to be the same as `desk`. Moons have `|sync %home ~parent %kids` automatically set up (where `~parent` is the planet that issued the moon).
129+Subscribe to continuous updates from remote `plot` on local `desk`.
130+`plot-desk` can specify the remote `desk` name. When omitted it's
131+assumed to be the same as `desk`. Moons have `|sync %home ~parent
132+%kids` automatically set up (where `~parent` is the planet that issued
133+the moon).
117134
118135**Examples:**
119136
120− |sync %home-local ~doznec %home
121− |sync %home ~doznec
137+ |sync %home-local ~doznec %home |sync %home ~doznec
122138
123139### `|unsync desk plot [plot-desk]`
124140
125−Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
141+Unsubscribe from updates from remote `plot` on local `desk` with
142+optional `plot-desk`. Arguments must match original `|sync` command
143+exactly.
126144
127145Example:
128146
@@ -136,72 +154,81 @@ Example:
136154
137155 |label %home release
138156
139−
140157### Merge strategies
141158
142159`%init` - Used iff it's the first commit to a desk.
143160
144161`%this` - Keep what's in Bob's desk, but join the ancestry.
145162
146−`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
147−
148−`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
149−
150−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
151−
152−A `%meet` merge only succeeds if the changes from the merge base
153−to Alice's head (hereafter, "Alice's changes") are in different
154−files than Bob's changes. In this case, the parents are both
155−Alice's and Bob's heads, and the data is the merge base plus
156−Alice's changed files plus Bob's changed files.
157−
158−A `%mate` merge attempts to merge changes to the same file when
159−both Alice and Bob change it. If the merge is clean, we use it;
160−otherwise, we fail. A merge between different types of changes --
161−for example, deleting a file vs changing it -- is always a
162−conflict. If we succeed, the parents are both Alice's and Bob's
163−heads, and the data is the merge base plus Alice's changed files
164−plus Bob's changed files plus the merged files.
165−
166−A `%meld` merge will succeed even if there are conflicts. If
167−there are conflicts in a file, then we use the merge base's
168−version of that file, and we produce a set of files with
169−conflicts. The parents are both Alice's and Bob's heads, and the
170−data is the merge base plus Alice's changed files plus Bob's
171−changed files plus the successfully merged files plus the merge
172−base's version of the conflicting files.
173−
174−`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it doesn't we use an `%init` merge. Otherwise, we progressively try `%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we merge Bob's desk into a scratch desk. Then, we merge Alice's desk into the scratch desk with the `%meld` option to force the merge.
163+`%that` - take what's in Alice's desk, but join the ancestry. This is
164+the reverse of `%this`.
165+
166+`%fine` - "fast-forward" merge. This succeeds iff one head is in the
167+ancestry of the other.
168+
169+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
170+to use as our merge base.
171+
172+A `%meet` merge only succeeds if the changes from the merge base to
173+Alice's head (hereafter, "Alice's changes") are in different files
174+than Bob's changes. In this case, the parents are both Alice's and
175+Bob's heads, and the data is the merge base plus Alice's changed files
176+plus Bob's changed files.
177+
178+A `%mate` merge attempts to merge changes to the same file when both
179+Alice and Bob change it. If the merge is clean, we use it; otherwise,
180+we fail. A merge between different types of changes -- for example,
181+deleting a file vs changing it -- is always a conflict. If we succeed,
182+the parents are both Alice's and Bob's heads, and the data is the
183+merge base plus Alice's changed files plus Bob's changed files plus
184+the merged files.
185+
186+A `%meld` merge will succeed even if there are conflicts. If there are
187+conflicts in a file, then we use the merge base's version of that
188+file, and we produce a set of files with conflicts. The parents are
189+both Alice's and Bob's heads, and the data is the merge base plus
190+Alice's changed files plus Bob's changed files plus the successfully
191+merged files plus the merge base's version of the conflicting files.
192+
193+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
194+doesn't we use an `%init` merge. Otherwise, we progressively try
195+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
196+merge Bob's desk into a scratch desk. Then, we merge Alice's desk
197+into the scratch desk with the `%meld` option to force the merge.
175198
176199### Manipulation
177200
178201<h3 class="first child"><code>|rm path</code></h3>
179202
180−Remove the data at `path`. `path` must be a path to actual node, not a 'directory'
203+Remove the data at `path`. `path` must be a path to actual node, not
204+a 'directory'
181205
182206### `|cp to from how`
183207
184−Copy the subtree `from` into the subtree `to`, committing it with
185−the specified merge strategy `how`.
208+Copy the subtree `from` into the subtree `to`, committing it with the
209+specified merge strategy `how`.
186210
187211#### `|mv to from how`
188212
189−Move the subtree `from` into the subtree `to`, committing it with
190−the specified merge strategy `how`.
213+Move the subtree `from` into the subtree `to`, committing it with the
214+specified merge strategy `how`.
191215
192−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
193−`|rm` doesn't happen unless the `|cp` succeeds.
216+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
217+doesn't happen unless the `|cp` succeeds.
194218
195219### Generators
196220
197−<h3 class="first child"><code>+cat path</code> / <code>+cal [path ...]</code></h3>
221+<h3 class="first child"><code>+cat path</code> / <code>+cal [path
222+...]</code></h3>
198223
199−Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of paths.
224+Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of
225+paths.
200226
201227Produces the contents of the file at the given `path`.
202228
203229### `+ls path` / `+ll [path ...]`
204230
205−Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of paths.
231+Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of
232+paths.
206233
207234Produces a list of names at the `path`.
docs/using/messaging.md+11−5
@@ -59,10 +59,16 @@ To set your audience back to `/urbit-meta`:
5959
6060 ~your-urbit:talk> ;~doznec/urbit-meta
6161
62−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`).
62+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`).
6363
6464The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
6565
66+Last, let's create a channel we can invite some friends to:
67+
68+ ~your-urbit:talk> ;create channel %my-channel 'some description'
69+
70+Now you can your friends to `;join ~your-urbit/my-channel`.
71+
6672## Manual
6773
6874`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet.
@@ -87,7 +93,7 @@ will be posted in multiple lines.
8793
8894#### URLs
8995
90−A URL is any valid URL.
96+A URL is any valid URL.
9197
9298### Commands
9399
@@ -111,7 +117,7 @@ stations you're subscribed to.
111117### Station Glyphs
112118
113119Glyphs are assigned by station hash out of the following list
114−
120+
115121 > = + - } ) , . " ' ^ $ % & @
116122
117123Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists, and `\/!?({<`) can be manually assigned.
@@ -138,11 +144,11 @@ The audience you're sending to is always shown in your prompt. If there's a gly
138144
139145Here we're talking to the station bound to `=`:
140146
141− ~your-urbit:talk=
147+ ~your-urbit:talk=
142148
143149Here we're talking directly to `~dannum-mitryl`:
144150
145− ~your-urbit:talk(~dannum-mitryl)
151+ ~your-urbit:talk(~dannum-mitryl)
146152
147153#### Configuration
148154
docs/using/web.md+30−18
@@ -11,7 +11,9 @@ title: Web
1111
1212Your 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.
1313
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+By default `%eyre` uses Tree, which is sort of like a combination of [Jekyll](https://jekyllrb.com/) or [Kirby](https://getkirby.com/) and Finder on OSX. Tree is a simple ui for browsing the contents of the filesystem, statically publishing a blog or any kind of content and for running single-page apps.
15+
16+Tree was built primarily to display both our documentation and the contents of `urbit.org`. We provide a few simple examples [here](#-examples) of how to publish using Tree. If you're interested in doing anything complex it's worth checking out the [docs source](https://github.com/urbit/docs) and the [urbit.org](https://github.com/urbit/urbit.org) source.
1517
1618We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its own repo [here](https://github.com/urbit/tree).
1719
@@ -29,7 +31,7 @@ To switch the desk you're serving from:
2931 |serve %sandbox
3032
3133To host a file on the web try putting the following in `/home/web/test.md` (from Unix):
32−
34+
3335 # Hello
3436
3537 This is a simple markdown file.
@@ -42,7 +44,7 @@ Now modify `/home/web/test.md` to list the children using the `<list/>` JSX:
4244
4345 This is a simple markdown file.
4446
45− <div><list / />
47+ <div><list /><div/>
4648
4749To view your file as raw `md`:
4850
@@ -52,6 +54,12 @@ To view your file as raw `html`:
5254
5355 http://localhost:8080/test.html
5456
57+## Examples
58+
59+We've created a few simple examples of how to get set up publishing content from your Urbit. Feel free to ask questions in the comments.
60+
61+<list/>
62+
5563## Manual
5664
5765## `/web`
@@ -64,19 +72,19 @@ Switch to the `%sandbox` desk:
6472
6573Let's quickly step through the default contents of `web/`:
6674
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.
75+- `404.hoon` - The default 404 page.
76+- `dojo.hoon` - Page body that loads the `dojo` React module.
77+- `lib/css/bootstrap.css` - The Urbit-flavored bootstrap
78+- `lib/css/codemirror.css` - Syntax highlighting
79+- `lib/css/fonts.css` - The Urbit custom fonts
80+- `lib/js/hoon.js` - Hoon syntax highlighting
81+- `lib/js/sole.js` - `dojo` operational transformation JS
82+- `lib/js/urb.js` - Base Urbit JS library. Handles AJAX and polling.
83+- `static.md` - Sample static file
84+- `talk/` - Talk compiled JS / CSS
85+- `talk.hoon` - Page body that loads the `dojo` React module.
86+- `tree/` - Tree compiled JS / CSS
87+- `tree.hoon` - Page body that loads the `tree` React module.
8088
8189## Tree
8290
@@ -88,6 +96,10 @@ In the browser Tree is a [React](https://facebook.github.io/react/) / [Flux](htt
8896
8997Your 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).
9098
99+## `/web/pages`
100+
101+To render content without the Tree put it in `/web/pages`. Files in this directory aren't wrapped by Tree. For some examples check out [`web/` in the examples repo](https://github.com/urbit/examples/tree/master/web).
102+
91103## Publishing files
92104
93105Publishing files in Tree is simple. Try dropping a file in `/web` (as covered in the Quickstart) and navigating to it.
@@ -112,7 +124,7 @@ and appears at the top of a file. YAML values can't contain newlines but can co
112124
113125String. Example: `title: Tree manual`.
114126
115−This sets the title in the nav or in lists as distinct from the filename.
127+This sets the title in the nav or in lists as distinct from the filename.
116128
117129### `next`
118130
@@ -150,7 +162,7 @@ For those familiar with React / Flux each JSX tag corresponds to a component in
150162
151163Example: `<list src="/posts" titlesOnly="true" />`
152164
153−Creates a list of children at a path. Defaults to the current path.
165+Creates a list of children at a path. Defaults to the current path.
154166
155167Optional properties:
156168
docs/using/web/blog.mdnew file+94
@@ -0,0 +1,94 @@
1+---
2+sort: 1
3+title: A simple blog
4+next: true
5+---
6+
7+# A simple blog
8+
9+Publishing markdown using Urbit is really easy. Here we'll create a
10+very simple blog and publish our first posts.
11+
12+First, let's setup a desk to serve our posts from:
13+
14+ |merge %site ~your-urbit %home
15+
16+Then let's mount that desk to unix:
17+
18+ |mount /=site=
19+
20+You should now be able to find a `/site` folder inside of your pier
21+directory (either `comet/` or `your-urbit/`).
22+
23+To begin serving files from this new desk use `|serve`:
24+
25+ |serve %site
26+
27+First let's create the landing page for our blog. Create the file
28+`site/web/blog.md`:
29+
30+ ---
31+ anchor: none
32+ ---
33+
34+ # Hello
35+
36+ This is a simple blog I built on Urbit.
37+
38+ <list dataType="post"></list>
39+
40+Try viewing this file at `http://your-urbit.urbit.org/blog`. The only
41+special thing about this page is the `anchor: none` YAML which simply
42+turns off the Tree navigation. Normally Tree gives navigation
43+controls for walking around the filesystem, but taking them away makes
44+the page seem more like a landing page.
45+
46+The page looks pretty boring now. Let's add our first post. From
47+unix run `mkdir your-urbit/site/web/blog; touch
48+your-urbit/site/web/blog/post-1.md`. (Currently [there's a
49+bug](https://github.com/urbit/urbit/issues/321) that prevents empty
50+directories from getting created, so we have to `touch` a file inside
51+them first.) In `blog/post-1.md` let's add some filler content:
52+
53+ ---
54+ date: ~2016.4.20
55+ title: My first post!
56+ type: post
57+ navhome: /blog
58+ ---
59+
60+ Is this a decentralized Medium? Let's find out.
61+
62+ But first, how about a long quote from Paramenides:
63+
64+ > True, he said; and therefore when ideas are what they are in
65+ relation to one another, their essence is determined by a relation
66+ among themselves, and has nothing to do with the resemblances, or
67+ whatever they are to be termed, which are in our sphere, and from
68+ which we receive this or that name when we partake of them. And
69+ the things which are within our sphere and have the same names
70+ with them, are likewise only relative to one another, and not to
71+ the ideas which have the same names with them, but belong to
72+ themselves and not to them.
73+
74+ Good to get that out of the way.
75+
76+
77+
78+You should be able to view this file at:
79+`http://your-urbit.urbit.org/blog/post-1.md`. You'll also notice that
80+now the list of posts here: `http://your-urbit.urbit.org/blog` has
81+updated.
82+
83+Here we use two pieces of YAML worth noting: `type` and `navhome`.
84+
85+- `type` implies that the page has some special handling by Tree.
86+When `type` is `post` we automatically put in the `date`, `title`
87+and `author` when they're specified and add some styles.
88+
89+- `navhome` sets the path used by the home button (the circle in the
90+ top left). Since we want to send people back to the root of our
91+ blog, we set this to `/blog`
92+
93+Adding posts is as easy as dropping markdown files into the `blog/`
94+directory. Pretty easy!
docs/using/web/comments.mdnew file+42
@@ -0,0 +1,42 @@
1+---
2+sort: 2
3+title: Blog comments
4+next: true
5+---
6+
7+# Blog comments
8+
9+If you followed [our previous example](./blog) you should have a
10+simple blog accessible at `your-urbit.urbit.org/blog`. Here we'll
11+enable comments on a post.
12+
13+First, turn comments on by editing the YAML in `post-1.md`. Your YAML
14+should look like this:
15+
16+ ---
17+ date: ~2016.4.20
18+ title: My first post!
19+ type: post
20+ navhome: /blog
21+ comments: true
22+ ---
23+
24+Now try loading your post here: `your-urbit.urbit.org/blog/post-1`.
25+You should see a comments box at the bottom of the page.
26+
27+Try posting a comment! When you do you should see the following in
28+your console:
29+
30+ + /~your-urbit/home/55/web/blog/post-1/comments/~2016.4.20..23.20.54..0b88/md
31+ ------------[0]
32+ ~your-urbit[tree]: receiving comments, ;join %comments for details
33+
34+Comments are written into the filesystem in the `comments/` folder
35+relative to the page they're enabled on. When a new comment is posted
36+a notification is also posted to the `/comments` `:talk` channel.
37+
38+Use `;join` to keep up with comments as they get posted:
39+
40+ ;join ~your-urbit/comments
41+
42+That's it! Easy.
docs/using/web/static.mdnew file+127
@@ -0,0 +1,127 @@
1+---
2+sort: 3
3+title: A static site
4+next: true
5+---
6+
7+# A static site
8+
9+Hosting a static tree of content is easy. Let's put together a really
10+simple site for an imaginary Urbit meetup group.
11+
12+We assume you have at least followed the beginning of [our first
13+example](./blog) and created a desk called `site` and mounted it to
14+unix.
15+
16+In `site/web/meet.md` put:
17+
18+ ---
19+ navdpad: false
20+ navmode: navbar
21+ navpath: /meet
22+ navhome: /meet
23+ ---
24+
25+ # Neo-Tokyo Urbit meetup
26+
27+ <img src="https://ofheroesandcliches.files.wordpress.com/2014/06/neo-tokyo.png" width="100%"/>
28+
29+ Hi there! We meet once a week at The Chat to work on Urbit projects
30+ together.
31+
32+ You can find out more about the group on the [about](about) page and
33+ follow our projects in [projects](projects).
34+
35+This is our landing page. Here we're using a few new bits of YAML:
36+`navdpad`, `navmode` and `navpath`. `navdpad` just turns off the nav
37+arrows. `navmode` can be set to 'navbar' to switch to a horizontal top
38+nav instead of a left bar. `navpath` sets the path to load the nav
39+items from.
40+
41+Let's create `about.md` and `projects.md`. From Unix use the
42+technique from before to create a new directory: `mkdir
43+your-urbit/site/web/meet/; touch your-urbit/site/web/meet/about.md`.
44+Then put the following in `site/web/about.md`:
45+
46+ ---
47+ navdpad: false
48+ navmode: navbar
49+ navpath: /meet
50+ navhome: /meet
51+ title: About
52+ ---
53+
54+ # About
55+
56+ ## Mission statement
57+
58+ The existing framework cannot subdue the new human force that is increasing day by day alongside the irresistible development of technology and the dissatisfaction of its possible uses in our senseless social life.
59+
60+ ## Members
61+
62+ Membership is open to anyone. Just send a message to `~talsur-todres`.
63+
64+ - Shōtarō Kaneda
65+ - Motoko Kusanagi
66+ - Ishikawa
67+ - Faye Valentine
68+ - Spike Spiegel
69+
70+And `site/web/projects.md`:
71+
72+ ---
73+ navdpad: false
74+ navmode: navbar
75+ navpath: /meet
76+ navhome: /meet
77+ title: Projects
78+ ---
79+
80+ # Projects
81+
82+ ## Active
83+
84+ <list />
85+
86+ ## Discussion
87+
88+ <div class="mini-module">
89+ <script src="/~/at/lib/js/urb.js"/>
90+ <script src="https://cdn.rawgit.com/seatgeek/react-infinite/0.8.0/dist/react-infinite.js"/>
91+ <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.11.2/moment-with-locales.js"/>
92+ <script src="https://cdnjs.cloudflare.com/ajax/libs/moment-timezone/0.5.1/moment-timezone.js"/>
93+ <script src="/talk/main.js"/>
94+ <link href="/talk/main.css" rel="stylesheet" />
95+ <talk readonly="" chrono="reverse" station="comments" />
96+ </div>
97+
98+This page introduces a new thing: the `:talk` module. Inside of the
99+`mini-module` div we load the scripts needed by the `<talk>`
100+component. The `<talk>` component is a static component for
101+displaying a feed from a talk channel inline. Here we're going to
102+display the discussion from our active projects inline.
103+
104+We'll need a few active projects though. From unix: `mkdir
105+your-urbit/site/web/meet/projects; touch
106+your-urbit/site/web/meet/projects/bike.md`.
107+
108+In `site/web/meet/projects/bike.md`:
109+
110+ ---
111+ navdpad: false
112+ navmode: navbar
113+ navpath: /meet
114+ navhome: /meet
115+ title: Kaneda's Bike
116+ comments: true
117+ ---
118+
119+ # Urbit on a Motorcycle
120+
121+ Discussion on getting urbit to power Kaneda's motorcycle.
122+
123+Here we just use the `comments` YAML to enable comments on the page.
124+Adding other imaginary projects is left to the reader.
125+
126+Building a static site takes only a few minutes and a few markdown
127+files. Have fun!