git.iko.soy/urbit.org
on master help sign in
Merge remote-tracking branch 'origin/cleanorg' into cleanorg
3fae695C. Guy Yarvin
docs/hoon/exercises.md+4−155
compare with master
unifiedsplit
@@ -8,159 +8,8 @@ The best way to cement this knowledge in your mind is to do
8exercises. These are roughly in order of ascending difficulty,
8exercises. These are roughly in order of ascending difficulty,
9and they are intended to form a sort of primer to Hoon.
9and they are intended to form a sort of primer to Hoon.
10
10
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.
12
14
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)
15+<list />
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.
docs/hoon/library.md+2−2
@@ -1,8 +1,8 @@
1---
1---
2sort: 11
2sort: 11
3−title: Library
3+title: Std Library reference
4---
4---
5
5
6−# Library
6+# Library reference
7
7
8<list dataPreview="true" titlesOnly="true"></list>
8<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
6
6
7# Filesystem (`%clay`)
7# Filesystem (`%clay`)
8
8
9−<div class="row">
10−<div class="col-md-8">
9+<div class="row"> <div class="col-md-8">
11
10
11+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
12−Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a typed, global, referentially transparent namespace. An easy way to think about it is like typed `git` with continuous sync.
12+a typed, global, referentially transparent namespace. An easy way to
13+think about it is like typed `git` with continuous sync.
13
14
14−The most common way to use `%clay` is to mount a `%clay` node in
15+The most common way to use `%clay` is to mount a `%clay` node in a
15−a Unix directory. The Urbit process will watch this directory
16+Unix directory. The Urbit process will watch this directory and
16−and automatically record edits as changes, Dropbox style. The
17+automatically record edits as changes, Dropbox style. The mounted
17−mounted directory is always at the root of your pier directory.
18+directory is always at the root of your pier directory.
18
19
19−</div>
20+</div> </div>
20−</div>
21
21
22## Quickstart
22## Quickstart
23
23
@@ -33,7 +33,8 @@ Mount the entire contents of your `sandbox` desk to Unix:
33
33
34 ~your-urbit:dojo> |mount /=sandbox=
34 ~your-urbit:dojo> |mount /=sandbox=
35
35
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:
37
38
38 ~your-urbit:dojo> +ls /=sandbox=/web
39 ~your-urbit:dojo> +ls /=sandbox=/web
39
40
@@ -41,7 +42,8 @@ Let's see the contents of `/=sandbox=/web/md`:
41
42
42 ~your-urbit:dojo> +cat /=sandbox=/web/md
43 ~your-urbit:dojo> +cat /=sandbox=/web/md
43
44
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:
45
47
46 |sync %sandbox ~some-ship %experiment
48 |sync %sandbox ~some-ship %experiment
47
49
@@ -49,21 +51,31 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
49
51
50<h3 class="first child">Paths</h3>
52<h3 class="first child">Paths</h3>
51
53
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`.
53
57
58+Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
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`.
59+The first three segments of an urbit path are `/plot/desk/case`, for
60+example `/~doznec/home/1`.
55
61
56#### Relative paths
62#### Relative paths
57
63
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`.
59
68
60#### Substitution
69#### Substitution
61
70
62−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
71+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
63−and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
72+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
64−`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
73+or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
65
74
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`.
67
79
68### Revision-control
80### Revision-control
69
81
@@ -99,7 +111,8 @@ Unmounts the Unix path `/generators`.
99
111
100Merges a `beak` into a `desk` using an optional merge `strategy`.
112Merges a `beak` into a `desk` using an optional merge `strategy`.
101
113
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`)
103
116
104**Examples:**
117**Examples:**
105
118
@@ -113,16 +126,21 @@ Merge the `%examples` desk from `~waxbex-ribmex`
113
126
114### `|sync desk plot [plot-desk]`
127### `|sync desk plot [plot-desk]`
115
128
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).
117
134
118**Examples:**
135**Examples:**
119
136
120− |sync %home-local ~doznec %home
137+ |sync %home-local ~doznec %home |sync %home ~doznec
121− |sync %home ~doznec
122
138
123### `|unsync desk plot [plot-desk]`
139### `|unsync desk plot [plot-desk]`
124
140
141+Unsubscribe from updates from remote `plot` on local `desk` with
125−Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
142+optional `plot-desk`. Arguments must match original `|sync` command
143+exactly.
126
144
127Example:
145Example:
128
146
@@ -136,72 +154,81 @@ Example:
136
154
137 |label %home release
155 |label %home release
138
156
139−
140### Merge strategies
157### Merge strategies
141
158
142`%init` - Used iff it's the first commit to a desk.
159`%init` - Used iff it's the first commit to a desk.
143
160
144`%this` - Keep what's in Bob's desk, but join the ancestry.
161`%this` - Keep what's in Bob's desk, but join the ancestry.
145
162
146−`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
163+`%that` - take what's in Alice's desk, but join the ancestry. This is
147−
164+the reverse of `%this`.
165+
148−`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
166+`%fine` - "fast-forward" merge. This succeeds iff one head is in the
149−
167+ancestry of the other.
168+
150−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
169+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
151−
170+to use as our merge base.
171+
152−A `%meet` merge only succeeds if the changes from the merge base
172+A `%meet` merge only succeeds if the changes from the merge base to
153−to Alice's head (hereafter, "Alice's changes") are in different
173+Alice's head (hereafter, "Alice's changes") are in different files
154−files than Bob's changes. In this case, the parents are both
174+than Bob's changes. In this case, the parents are both Alice's and
155−Alice's and Bob's heads, and the data is the merge base plus
175+Bob's heads, and the data is the merge base plus Alice's changed files
156−Alice's changed files plus Bob's changed files.
176+plus Bob's changed files.
157−
177+
158−A `%mate` merge attempts to merge changes to the same file when
178+A `%mate` merge attempts to merge changes to the same file when both
159−both Alice and Bob change it. If the merge is clean, we use it;
179+Alice and Bob change it. If the merge is clean, we use it; otherwise,
160−otherwise, we fail. A merge between different types of changes --
180+we fail. A merge between different types of changes -- for example,
161−for example, deleting a file vs changing it -- is always a
181+deleting a file vs changing it -- is always a conflict. If we succeed,
162−conflict. If we succeed, the parents are both Alice's and Bob's
182+the parents are both Alice's and Bob's heads, and the data is the
163−heads, and the data is the merge base plus Alice's changed files
183+merge base plus Alice's changed files plus Bob's changed files plus
164−plus Bob's changed files plus the merged files.
184+the merged files.
165−
185+
166−A `%meld` merge will succeed even if there are conflicts. If
186+A `%meld` merge will succeed even if there are conflicts. If there are
167−there are conflicts in a file, then we use the merge base's
187+conflicts in a file, then we use the merge base's version of that
168−version of that file, and we produce a set of files with
188+file, and we produce a set of files with conflicts. The parents are
169−conflicts. The parents are both Alice's and Bob's heads, and the
189+both Alice's and Bob's heads, and the data is the merge base plus
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
190+Alice's changed files plus Bob's changed files plus the successfully
172−base's version of the conflicting files.
191+merged files plus the merge base's version of the conflicting files.
173−
192+
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.
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.
175
198
176### Manipulation
199### Manipulation
177
200
178<h3 class="first child"><code>|rm path</code></h3>
201<h3 class="first child"><code>|rm path</code></h3>
179
202
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'
181
205
182### `|cp to from how`
206### `|cp to from how`
183
207
184−Copy the subtree `from` into the subtree `to`, committing it with
208+Copy the subtree `from` into the subtree `to`, committing it with the
185−the specified merge strategy `how`.
209+specified merge strategy `how`.
186
210
187#### `|mv to from how`
211#### `|mv to from how`
188
212
189−Move the subtree `from` into the subtree `to`, committing it with
213+Move the subtree `from` into the subtree `to`, committing it with the
190−the specified merge strategy `how`.
214+specified merge strategy `how`.
191
215
192−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
216+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
193−`|rm` doesn't happen unless the `|cp` succeeds.
217+doesn't happen unless the `|cp` succeeds.
194
218
195### Generators
219### Generators
196
220
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>
198
223
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.
200
226
201Produces the contents of the file at the given `path`.
227Produces the contents of the file at the given `path`.
202
228
203### `+ls path` / `+ll [path ...]`
229### `+ls path` / `+ll [path ...]`
204
230
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.
206
233
207Produces a list of names at the `path`.
234Produces 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`:
59
59
60 ~your-urbit:talk> ;~doznec/urbit-meta
60 ~your-urbit:talk> ;~doznec/urbit-meta
61
61
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`).
63
63
64The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
64The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
65
65
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+
66## Manual
72## Manual
67
73
68`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet.
74`: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.
87
93
88#### URLs
94#### URLs
89
95
90−A URL is any valid URL.
96+A URL is any valid URL.
91
97
92### Commands
98### Commands
93
99
@@ -111,7 +117,7 @@ stations you're subscribed to.
111### Station Glyphs
117### Station Glyphs
112
118
113Glyphs are assigned by station hash out of the following list
119Glyphs are assigned by station hash out of the following list
114−
120+
115 > = + - } ) , . " ' ^ $ % & @
121 > = + - } ) , . " ' ^ $ % & @
116
122
117Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists, and `\/!?({<`) can be manually assigned.
123Alphanumeric 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
138
144
139Here we're talking to the station bound to `=`:
145Here we're talking to the station bound to `=`:
140
146
141− ~your-urbit:talk=
147+ ~your-urbit:talk=
142
148
143Here we're talking directly to `~dannum-mitryl`:
149Here we're talking directly to `~dannum-mitryl`:
144
150
145− ~your-urbit:talk(~dannum-mitryl)
151+ ~your-urbit:talk(~dannum-mitryl)
146
152
147#### Configuration
153#### Configuration
148
154
docs/using/web.md+30−18
@@ -11,7 +11,9 @@ title: Web
11
11
12Your 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.
12Your 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.
13
13
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.
15
17
16We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its own repo [here](https://github.com/urbit/tree).
18We ship `tree` as compiled JavaScript on your Urbit, but the source lives in its own repo [here](https://github.com/urbit/tree).
17
19
@@ -29,7 +31,7 @@ To switch the desk you're serving from:
29 |serve %sandbox
31 |serve %sandbox
30
32
31To host a file on the web try putting the following in `/home/web/test.md` (from Unix):
33To host a file on the web try putting the following in `/home/web/test.md` (from Unix):
32−
34+
33 # Hello
35 # Hello
34
36
35 This is a simple markdown file.
37 This is a simple markdown file.
@@ -42,7 +44,7 @@ Now modify `/home/web/test.md` to list the children using the `<list/>` JSX:
42
44
43 This is a simple markdown file.
45 This is a simple markdown file.
44
46
45− <div><list / />
47+ <div><list /><div/>
46
48
47To view your file as raw `md`:
49To view your file as raw `md`:
48
50
@@ -52,6 +54,12 @@ To view your file as raw `html`:
52
54
53 http://localhost:8080/test.html
55 http://localhost:8080/test.html
54
56
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+
55## Manual
63## Manual
56
64
57## `/web`
65## `/web`
@@ -64,19 +72,19 @@ Switch to the `%sandbox` desk:
64
72
65Let's quickly step through the default contents of `web/`:
73Let's quickly step through the default contents of `web/`:
66
74
67−`404.hoon` - The default 404 page.
75+- `404.hoon` - The default 404 page.
68−`dojo.hoon` - Page body that loads the `dojo` React module.
76+- `dojo.hoon` - Page body that loads the `dojo` React module.
69−`lib/css/bootstrap.css` - The Urbit-flavored bootstrap
77+- `lib/css/bootstrap.css` - The Urbit-flavored bootstrap
70−`lib/css/codemirror.css` - Syntax highlighting
78+- `lib/css/codemirror.css` - Syntax highlighting
71−`lib/css/fonts.css` - The Urbit custom fonts
79+- `lib/css/fonts.css` - The Urbit custom fonts
72−`lib/js/hoon.js` - Hoon syntax highlighting
80+- `lib/js/hoon.js` - Hoon syntax highlighting
73−`lib/js/sole.js` - `dojo` operational transformation JS
81+- `lib/js/sole.js` - `dojo` operational transformation JS
74−`lib/js/urb.js` - Base Urbit JS library. Handles AJAX and polling.
82+- `lib/js/urb.js` - Base Urbit JS library. Handles AJAX and polling.
75−`static.md` - Sample static file
83+- `static.md` - Sample static file
76−`talk/` - Talk compiled JS / CSS
84+- `talk/` - Talk compiled JS / CSS
77−`talk.hoon` - Page body that loads the `dojo` React module.
85+- `talk.hoon` - Page body that loads the `dojo` React module.
78−`tree/` - Tree compiled JS / CSS
86+- `tree/` - Tree compiled JS / CSS
79−`tree.hoon` - Page body that loads the `tree` React module.
87+- `tree.hoon` - Page body that loads the `tree` React module.
80
88
81## Tree
89## Tree
82
90
@@ -88,6 +96,10 @@ In the browser Tree is a [React](https://facebook.github.io/react/) / [Flux](htt
88
96
89Your 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).
97Your Urbit comes with a pre-built copy of the tree (as a single `.js` file). If you're interested in helping to develop tree or learning about how it works, it has its own GitHub repo [here](https://github.com/urbit/tree). We have our own fork of Bootstrap, which lives [here](https://github.com/urbit/bootstrap).
90
98
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+
91## Publishing files
103## Publishing files
92
104
93Publishing files in Tree is simple. Try dropping a file in `/web` (as covered in the Quickstart) and navigating to it.
105Publishing 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
112
124
113String. Example: `title: Tree manual`.
125String. Example: `title: Tree manual`.
114
126
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.
116
128
117### `next`
129### `next`
118
130
@@ -150,7 +162,7 @@ For those familiar with React / Flux each JSX tag corresponds to a component in
150
162
151Example: `<list src="/posts" titlesOnly="true" />`
163Example: `<list src="/posts" titlesOnly="true" />`
152
164
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.
154
166
155Optional properties:
167Optional properties:
156
168
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!