WIP docs

web/unmark/doc.umd

@@ -0,0 +1,165 @@
+::   :-  :*  title+"urbit-flavored markdown docs"
+::           author+"ted blackman"
+::           date+~2017.8.25
+::       ==
+::  
+;>
+
+# udon: urbit-flavored markdown
+
+## overview
+
+Udon is a minimal markup language for creating and rendering text documents,
+with a markdown-inspired syntax. It's integrated with the hoon programming
+language, allowing it to be used as standalone prose in its own file or inside
+a hoon source file, in which case it will be parsed into a tree of XML nodes
+(hoon's `sail` datatype).
+
+## syntax
+
+Udon is stricter than markdown and generally supports only one syntax for each
+type of HTML node it emits.
+
+### headers
+
+Headers in udon begin with one or more `#` characters, followed by a space. The
+number of leading `#`s corresponds to the resulting HTML element: `#` yields an
+`<h1>`, `##` yields an `<h2>`, and so on through `<h6>`.
+
+Example:
+```
+### Header (h3)
+
+##### Header (h5)
+```
+> produces:
+
+  ### Header (h3)
+
+  ##### Header (h5)
+
+### lists
+
+A line beginning with a `-` or `+` followed by a space is interpreted as an
+element of a list. `-` means unordered list (`<ul>`) and `+` means ordered list
+(`<ol>`).
+
+Example:
+
+```
+- unordered 1
+  text on newline shows up on same line
+- unordered 2\
+  text on newline after `\` puts in <br> line break
+
+- unordered after 1 blank line
+  - nested
+    - double-nested
+
++ leading '+'
++ leading '+'
+- unordered '-'
+  + nested ordered '+' item 1
+  + nested ordered '+' item 2
+
++ ordered '+'
+  + nested item 1
+  + nested item 2
+```
+
+> produces:
+
+  - unordered 1
+    text on newline shows up on same line
+  - unordered 2\
+    text on newline after `\` puts in <br> line break
+
+  - unordered after 1 blank line
+    - nested
+      - double-nested
+
+  + leading '+'
+  + leading '+'
+  - unordered '-'
+    + nested ordered '+' item 1
+    + nested ordered '+' item 2
+
+  + ordered '+'
+    + nested item 1
+    + nested item 2
+
+### blockquotes
+
+A section of text beginning with `> ` and indented by two spaces yields a
+`<blockquote>` element. This blockquote can itself turn contain more udon,
+including more blockquotes to render nested levels of quotation.
+
+Example:
+
+```
+> As Gregor Samsa awoke one morning from uneasy dreams 
+  he found himself _transformed_ in his bed into a *monstrous* vermin.
+```
+
+> produces:
+
+  > As Gregor Samsa awoke one morning from uneasy dreams 
+    he found himself _transformed_ in his bed into a *monstrous* vermin.
+
+### code blocks
+
+By enclosing a block of text in `\`\`\` on their own lines
+before and after the block, the text will be treated as a code block.
+
+Example:
+
+```
+> ```
+  (def Y (fn [f]
+         ((fn [x]
+            (x x))
+          (fn [x]
+            (f (fn [y]
+                 ((x x) y)))))))
+  ```
+```
+
+> produces:
+  ```
+  (def Y (fn [f]
+         ((fn [x]
+            (x x))
+          (fn [x]
+            (f (fn [y]
+                 ((x x) y)))))))
+  ```
+
+### poems
+
+A poem is a section of text with meaningful newlines.  Normally in udon,
+newlines are treated as spaces and do not create a new line of text. If you
+want to embed text where newlines are retained, then indent the text by
+question with eight spaces.
+
+Example:
+```
+        A shape with lion body and the head of a man,
+        A gaze blank and pitiless as the sun,
+        Is moving its slow thighs, while all about it
+        Reel shadows of the indignant desert birds.
+```
+> produces:
+          A shape with lion body and the head of a man,
+          A gaze blank and pitiless as the sun,
+          Is moving its slow thighs, while all about it
+          Reel shadows of the indignant desert birds.
+
+### sail expressions
+
+It's possible to use udon as an HTML templating language akin to
+PHP, ERB, JSP, or Handlebars templates. This facility derives
+in part from the support for embedding hoon code inside the markup.
+There are two ways to do embed hoon in udon: inline expressions and sail.
+Sail is a DSL within hoon for creating XML nodes, including HTML. It can
+be used directly within udon to provide scripting capability and also to
+provide more fine-grained control over the resulting HTML.