git.iko.soy/urbit.org
on master help sign in
Merge pull request #41 from asgardiator/master

Create contributing.md (& minor fixes)

commit7440e08c41cdb26915af86e4d249d349ad195b17 authorGalen Wolfe-Pauly <galen@office-for.com> dateThu 16 Jun 2016, 12:42 (10 years ago) parentb85ab9b4fb26a4
5 files changed+65−27
compare with master
unifiedsplit
docs/about/contributing.md+38 docs/arvo/basic.md+8−6 docs/arvo/marks.md+5−3 docs/arvo/web-apps.md+13−17 docs/hoon/twig/buc-mold/hep-lamb.md+1−1
docs/about/contributing.mdnew file+38
@@ -0,0 +1,38 @@
1+---
2+navhome: '/docs'
3+next: True
4+sort: 4
5+title: Contributing to Urbit
6+---
7+
8+# Contributing to Urbit
9+
10+It's always a good day for pull requests! We gladly accept submissions
11+for improving our [code](https://github.com/urbit/urbit/) and
12+[documentation](https://github.com/urbit/docs/) alike.
13+
14+## Code guidelines
15+
16+Our official guide to contributing can be found
17+[here](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md),
18+which is most useful for large and low-level changes. For simpler
19+revisions, refer to [Hoon Syntax](/hoon/syntax) for an in-depth guide to
20+good Hoon. Alternatively, [browse the
21+source](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon).
22+
23+## Docs guidelines
24+
25+For documentation pull requests, acquire [pandoc](http://pandoc.org) and
26+format your edited files with the following flags:
27+
28+ $ pandoc --standalone \
29+ --from=markdown+yaml_metadata_block \
30+ --atx-headers \
31+ -o output.md \
32+ input.md
33+
34+**Note:** Pandoc will convert the terminating `---` in YAML metadata to
35+`...`, which is grounds for termination. Run the following one-liner to
36+atone.
37+
38+ $ sed '1,/^$/ s/^\.\.\./---/g' input.md > output.md
docs/arvo/basic.md+8−6
@@ -157,13 +157,13 @@ Instead of:
157157
158158You can write:
159159
160− if(=(1 2) 'this is true' 'this is false')
160+ :if(=(1 2) 'this is true' 'this is false')
161161 'this is false'
162162
163163### Lines 12-34
164164
165165Now let's quickly walk through this code line-by-line. Lines 12-34 are
166−wrapped in a `|%` ('barcen'), which produces a core. Cores are a
166+wrapped in a `|%` ('[barcen](/hoon/twig/bar-core/cen-core/)'), which produces a core. Cores are a
167167fundamental datatype in Hoon, similar to a struct, class, or object. A
168168core is just a map of names to any kind of code, whether it be functions
169169or data. Each element in this map begins with a `++` followed by the
@@ -182,7 +182,7 @@ Let's step into each of the three arms within our core.
182182 (add (five a) (three a))
183183 --
184184
185−`|=` ('bartis') produces a function, much like a lambda in lisp. It
185+`|=` ('[bartis](/hoon/twig/bar-core/tis-gate/)') produces a function, much like a lambda in lisp. It
186186takes two children:
187187
1881881. A set of argument(s). In this case our argument set only contains
@@ -207,7 +207,7 @@ takes two children:
207207As above, `++three` takes an integer argument, `a`, and then executes
208208the remainder of the code with `a` set to the actual arguments.
209209
210−Similarly, `=|` ('tisbar') pushes its first child, `b` into our context
210+Similarly, `=|` ('[tisbar](/hoon/twig/tis-flow/bar-new/)') pushes its first child, `b` into our context
211211(in other words, it declares a variable `b`) and executes the remainder
212212of the code. However, `b` is not an argument; `=|` sets `b` to the
213213default value of whatever type it is declared as. Since the default
@@ -225,10 +225,10 @@ value of an atom is `0`, b is set to `0`.
225225So now we have two variables: `a` is set to our input, and `b` is
226226initialized to `0`.
227227
228−One way to think about `|-` ('barhep') is that it lays down a recursion
228+One way to think about `|-` ('[barhep](/hoon/twig/bar-core/hep-loop/)') is that it lays down a recursion
229229point. More on this later.
230230
231−`^-` ('kethep') is just a cast that sets the result of the remainder of
231+`^-` ('[kethep](/hoon/core/ket-cast/hep-cast/)') is just a cast that sets the result of the remainder of
232232the code to an unsigned integer, `@u`.
233233
234234In pseudocode, the last three lines read like this: if `a` is less than
@@ -272,6 +272,8 @@ our cheatsheat at the bottom.
272272 =(a b) test equality
273273 (function args ...) call function with args
274274
275+Lookup each of these expressions (and all others!) in the [Twig Expressions](/hoon/twig/) definition.
276+
275277### New material
276278
2772791. There are two syntaxes for writing Hoon: tallform and wideform.
docs/arvo/marks.md+5−3
@@ -5,6 +5,8 @@ sort: 6
55title: Marks
66---
77
8+# Marks
9+
810We've used predefined marks already, but we haven't yet created
911our own marks. Let's write a sample mark of our own, then chain
1012it together with some preexisting ones to have fun with type
@@ -28,14 +30,14 @@ text, but there's no predefined mark for it. Let's put the following code in:
2830--
2931```
3032
31−Let's go through this line by line. `/? 314` is the required
33+`/? 314` is the required
3234version number, just like in apps. After that everything's in a
3335`|_`, which is a `|%` core, but with input arguments. In our
3436case, the argument is the marked data.
3537
3638There are three possible top-level arms in the `|_` core,
37−`++grab`, `++grow`, and `++grad`. `++grad` is used for revision
38−controlv (it contains diff/patch logic), and is covered elsewhere. `++grab` specifies
39+`++grab`, `++grow`, and `++grad` (which is used for revision
40+control, covered elsewhere). `++grab` specifies
3941functions to convert from another mark to the current mark.
4042`++grow` specifies how to convert from the current mark to
4143another one.
docs/arvo/web-apps.md+13−17
@@ -72,18 +72,16 @@ asserting the parsing succeeded with `need`, and asserting the
7272result was 'click' with `?>`, which asserts that its first child
7373is true.
7474
75−<blockquote class="blockquote">
76−Note the argument to `++json`is `jon/^json`. Why `^json`?
77−`++json` shadows the type definition, so if we want to refer to
78−the type, we have to prepend a `^`. This extends to multiple
79−levels: `^^^foo` means the fourth most innermost instance of `foo`.
80−
81−`++jo` in `zuse` is a useful library for parsing complex json
82−into hoon structures. In this case, the `:` between `so` and
83−`jo` means 'inside of', because `so` is an arm contained within
84−the core `jo`. Our case is actually simple enough that the
85−`?>` line could have been `?> =([%s 'click'] jon)`.
86−</blockquote>
75+> Note the argument to `++json`is `jon/^json`. Why `^json`?
76+> `++json` shadows the type definition, so if we want to refer to
77+> the type, we have to prepend a `^`. This extends to multiple
78+> levels: `^^^foo` means the fourth most innermost instance of `foo`.
79+
80+> `++jo` in `zuse` is a useful library for parsing complex json
81+> into hoon structures. In this case, the `:` between `so` and
82+> `jo` means 'inside of', because `so` is an arm contained within
83+> the core `jo`. Our case is actually simple enough that the
84+> `?>` line could have been `?> =([%s 'click'] jon)`.
8785
8886We can test this mark from the command line (don't forget to start your app with `|start %click`)
8987
@@ -115,11 +113,9 @@ And `/mar/clicks.hoon`:
115113`clicks` is just an atom. We convert to json by creating an
116114object with a single field "clicks" with our value.
117115
118−<blockquote class="blockquote">
119−Be sure to checkout section 3bD, JSON and XML, in zuse.hoon
120−`++joba` is just a function that takes a key-value pair and
121−produces a JSON object with one element.
122−</blockquote>
116+> Be sure to checkout section 3bD, JSON and XML, in zuse.hoon
117+> `++joba` is just a function that takes a key-value pair and
118+> produces a JSON object with one element.
123119
124120```
125121~fintud-macrep:dojo> &json &clicks 6
docs/hoon/twig/buc-mold/hep-lamb.md+1−1
@@ -4,7 +4,7 @@ sort: 8
44
55---
66
7−# `:lamb $-, "buchep"`
7+# `:lamb $- "buchep"`
88
99`{$lamb p/moss q/moss}`: mold which normalizes to an example gate.
1010