@@ -1,1242 +0,0 @@
1−+++
2−title = "Sail and Udon"
3−weight = 7
4−template = "doc.html"
5−aliases = ["docs/using/sail-and-udon/"]
6−+++
7−
8−Sail is Hoon markup that's used to render a web page with XML. But what makes it special is that you can run arbitrary Hoon code within such a web page without using a separate markup language.
9−
10−Udon is a way to write content for the web. It's a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It's integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.
11−
12−This document will be divided into two main sections: the Sail guide and the Udon guide. Also, you should read the Getting Started section below, which applies to both Udon and Sail.
13−
14−## Table of Contents
15−
16−- [Getting Started](#getting-started)
17−
18−- [Sail: A Guide](#sail)
19−
20−- [Udon: A Guide](#udon)
21−
22−## Getting Started {#getting-started}
23−
24−Before starting with either Sail or Udon, make sure that your ship is
25−[mounted to Unix](@/using/install.md).
26−
27−To host that output, your ship also has a web-server that can be found at
28−`http://localhost/` (default port 80) if it's your first ship that's running on the
29−machine, `http://localhost:8081/` if it's the second ship on that same machine,
30−and so on. In the startup messages, a ship will tell you which HTTP port it's
31−using.
32−
33−Udon and Sail files are often run as independent files (`.udon` and `.hoon`
34−respectively), but for the purpose of this guide, we will run them out of the
35−`frontpage.hoon` file located in the `/gen` directory. The default content of
36−`frontpage.hoon` is Sail code.
37−
38−To use `frontpage.hoon`, we use a `|serve` command like this one in your ship's
39−Dojo:
40−
41−```
42−|serve /test %home /gen/frontpage/hoon
43−```
44−
45−This command has three arguments:
46−- The first is the URL we want to bind our site to. We chose `/test`, so the URL
47−we will find our site at is `http://localhost/test`.
48−- The second is the desk we want to serve. We will be serving from `%home` in
49−this tutorial.
50−- The third is the file that we want to serve. In this tutorial, we will be
51−using `/gen/frontpage/hoon`, which refers to `/gen/frontpage.hoon`.
52−
53−Run the command `|serve /test %home /gen/frontpage/hoon`. Now navigate to
54−`http://localhost/test` (or `http://localhost:8081/test` if your ship is on that port) in your
55−browser, and you should see the rendered Sail.
56−
57−**Note:** Important to remember that every time you edit a file in your ship's
58−pier (Unix directory), including `frontpage.hoon`, you need to run `|commit %home`
59−to copy those changes to Urbit.
60−
61−## <a name="sail"></a>Sail: A Guide
62−
63−It's easy to see how Sail can directly translate to HTML:
64−
65−### Sail code
66−
67−```
68−;html
69− ;head
70− ;title: My first webpage
71− ==
72− ;body
73− ;h1: Welcome!
74− ; Hello, world!
75− ; We're on the web.
76− ;div;
77− ;script@"http://unsafely.tracking.you/cookiemonster.js";
78− ==
79−==
80−```
81−
82−### HTML code
83−
84−```
85−<html>
86− <head>
87− <title>My first webpage</title>
88− </head>
89− <body>
90− <h1>Welcome!</h1>
91− Hello, world!
92− We're on the web.
93− <div></div>
94− <script src="http://unsafely.tracking.you/cookiemonster.js"></script>
95− </body>
96−</html>
97−```
98−
99−You can test above Sail code by placing it
100−under `^- manx` in your `frontpage.hoon` file, and then running `|commit %home`
101−in the Dojo. If you've already run the `|serve` command code from the first
102−section, the new content should appear at `http://localhost/test`.
103−
104−It shouldn't be hard to see the similarities between Sail and HTML. So let's go
105−into more detail about what the differences are.
106−
107−### Tags and Closing
108−
109−In Sail, tag heads are written with the tag name prepended by `;`. Unlike in
110−HTML, there are different ways on closing tags, depending on the needs of the
111−tag. One of the nice things about Hoon is that you don't have to be constantly
112−closing expressions; Sail inherits this convenience.
113−
114−#### Empty
115−
116−Empty tags are closed with a `;` following the tag. Example:
117−
118−```
119−;div;
120−```
121−
122−Equals:
123−
124−```
125−<div></div>
126−```
127−
128−#### Filled
129−
130−Filled tags are closed via line-break. To fill text inside, add `:` after the
131−tag name, then insert your plain text following a space. Example:
132−
133−```
134−;h1: The title
135−```
136−
137−Equals:
138−
139−```
140−<h1>The title</h1>
141−```
142−
143−#### Nested
144−
145−To nest tags, simply create a new line. Nested tags need to be closed
146−with `==`, because they expect a list of sub-tags. If we nest a line of plain
147−text with no tag, a `<p>` is prepended.
148−
149−Sail, like Hoon, is white-space sensitive. Unlike in Hoon, however, two spaces
150−(called a `gap`) is not necessarily equivalent to a line-break in Sail.
151−
152−```
153−;body
154− ;h1: Blog title
155− This is some good content.
156−==
157−```
158−
159−Equals:
160−
161−```
162−<body>
163− <h1>Blog title</h1>
164− <p>This is some good content.</p>
165−</body>
166−```
167−
168−Conversely, if we want to write a string with no tag at all, then we can prepend
169−those untagged lines with `;`.
170−
171−```
172−;body
173− ;h1: Welcome!
174− ; Hello, world!
175− ; We're on the web.
176−==
177−```
178−
179−Equals:
180−
181−```
182−<body>
183− <h1>Welcome!</h1>
184− Hello, world!
185− We're on the web.
186−</body>
187−```
188−
189−#### Attributes
190−
191−Attributes are key-value pairs that go into an HTML node.
192−
193−Adding attributes is simple: just add the desired attribute between parentheses,
194−right after the tag name without a space. We separate different attributes of
195−the same node by using `,`.
196−
197−Attributes can be used in two forms: wide, which uses one line; and tall, which
198−uses multiple lines, when a single line would not be practical. Wide forms and
199−tall forms are two syntaxes of semantically equivalent expressions.
200−
201−#### Generic
202−
203−The code below produces a "Submit" button on the page.
204−
205−Wide-form Sail:
206−
207−```
208−;input(type "submit", value "Submit");
209−```
210−
211−Tall-form Sail:
212−
213−```
214−;input
215− =type "submit"
216− =value "Submit";
217−==
218−```
219−
220−Equals:
221−
222−```
223−<input type="submit" value="Submit">
224−```
225−
226−#### IDs
227−
228−```
229−;nav#header: Menu
230−```
231−
232−Equals:
233−
234−```
235−<nav id="header">Menu</nav>
236−```
237−
238−Add `#` after tag name to add an ID.
239−
240−#### Classes
241−
242−`;h1.text-blue: Title`
243−
244−Equals:
245−
246−`<h1 class="text-blue">Title</h1>`
247−
248−Add `.` after tag name to add a class. However, if you want a class list that
249−contains a space, you will need to use use the syntax of a generic attribute:
250−
251−`;div(class "logo inverse");`
252−
253−Equals:
254−
255−`<div class="logo inverse"></div>`
256−
257−#### Image
258−
259−`;img@"example.png";`
260−
261−Equals:
262−
263−`<img src="example.png" />`
264−
265−Add `@` after the tag name to link your source.
266−
267−To add attributes to the image, like size specifications, add the
268−desired attribute after the closing `"` of the image name and before the final
269−`;` of the `img` tag.
270−
271−For example:
272−
273−`;img@"https://urbit.org/example.png"(width "100%");`
274−
275−#### Linking
276−
277−`;a/"urbit.org": A link to Urbit.org`
278−
279−Equals:
280−
281−`<a href="urbit.org">A link to Urbit.org</a>`
282−
283−Add `/` after tag name to start an href.
284−
285−To add attributes to the link, like target specifications, add the
286−desired attribute after the closing `"` of the link url and before the `:` of
287−the `a` tag.
288−
289−For example:
290−
291−`;a/"urbit.org"(target "_blank"): A link to Urbit.org`
292−
293−### Hoon in Sail
294−
295−Our first example is useful to understand how Sail syntax translates to HTML
296−syntax, but Sail finds its usefulness in the fact that it can be used seamlessly
297−with Hoon code.
298−
299−One place where Sail diverges from HTML is that it supports string
300−interpolation. In Sail, the contents of all tags are a string type called `tape`
301−unless otherwise designated. Tapes are delineated by the double quotes `""`.
302−That's important, because tapes can be interpolated with Hoon expressions,
303−provided that those expressions produce something a tape as well. Interpolation
304−is done by wrapping the code to be inserted in `{}`. In your Dojo prompt, try
305−the command below (without the `>`):
306−
307−```
308−> "I am a l{(mul 3 11)}t Urbit user."
309−! exit
310−```
311−
312−Oh no! That command produced a nest-fail error, which indicates that there was
313−a problem related to Hoon type-system. We used the proper `{}` syntax for
314−interpolation, and we used the proper function-call syntax inside of it. So
315−what happened?
316−
317−Trying the `mul` function on its own will help answer this question. Try the
318−following command in your Dojo:
319−
320−```
321−> (mul 3 11)
322−33
323−```
324−
325−This should work, producing `33`, an atom. That's our problem. The
326−interpolation expression expects a tape, but our first command tried to
327−interpolate with something that results in an atom. Try this now:
328−
329−```
330−> <(mul 3 11)>
331−"33"
332−```
333−
334−We get a similar result, but we know that it's a tape because it's wrapped in
335−`""`. Bingo! With this knowledge, let's perform a successful interpolation:
336−
337−```
338−> "I am a l{<(mul 3 11)>}t Urbit user."
339−"I am a l33t Urbit user."
340−```
341−
342−Great!
343−
344−### The Subject
345−
346−The default subject of a Sail file is different from the subject that
347−expressions in the Dojo or a Hoon generator are evaluated against.
348−
349−To see this difference, first save the code below to a file at
350−`home/web/pages/sub.hoon` and view the rendering at
351−`http://localhost:8080/pages/sub`.
352−
353−```
354−;html
355− ;head;
356− ;body
357− {<.>}
358− ==
359−==
360−```
361−
362−Then enter the following command in the Dojo:
363−
364−```
365−> .
366−```
367−
368−You'll notice that the Sail subject is like a stripped-down version of the Dojo
369−subject. Its final line should match the Dojo subject.
370−
371−Now swap the code below into your Sail file.
372−
373−```
374−/= gas /$ fuel:html
375−;html
376− ;head;
377− ;body
378− {<.>}
379− ==
380−==
381−```
382−
383−You'll find that the resulting Sail subject is much larger. If you look closely,
384−you'll see that there's some new similarities with the Dojo subject, such as
385−containing the name of your ship. There's also some new differences, since
386−`fuel:html` contains things that are specifically useful for performing
387−web-related operations.
388−
389−### A More Interesting Example
390−
391−Now let's apply knowledge of string interpolation and the Sail subject in a Sail
392−source file. The following code produces more interesting things than the
393−example we saw before.
394−
395−```
396−/= gas /$ fuel:html
397−=/ show-list &
398−=+ wid=(met 3 p.bem.gas)
399−=/ what-kind
400−?: (lte wid 1) "galaxy"
401−?: =(2 wid) "star"
402−?: (lte wid 4) "planet"
403−?: (lte wid 8) "moon"
404− "comet"
405−;html
406− ;head
407− ;meta(charset "utf-8");
408− ;title: A more advanced page
409− ==
410− ;body
411− ;h1: This is the Title
412− ; This is a
413− ;a/"http://urbit.org": link to Urbit.org.
414− ;span: Check it out!
415− ;+ ?: show-list
416− ;ol
417− ;li(style "color: green"): We're doing interesting stuff now.
418− ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.
419− ;li: The code above is shorthand for {(scow %ud (add 50 50))}.
420− ;li: I am {(trip '~lodleb-ritrul')}.
421− ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.
422− ==
423− ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.
424− ==
425−==
426−```
427−
428−Save the above Sail code in to `home/web/pages/secondsail.hoon` and access the
429−resulting page by navigating to `http://localhost:8080/pages/secondsail` in
430−your browser.
431−
432−There are some interesting things here. Let's go through this code piece by
433−piece.
434−
435−```
436−/= gas /$ fuel:html
437−```
438−
439−Later in this code we want to produce the name of the ship which is hosting it,
440−something that looks like ~lodleb-ritrul. In a generator, we could produce our ship
441−name by writing `our` -- try it in the Dojo. But remember that Sail is rendered
442−against its own subject, `our` is not part of the default subject. To augment
443−our subject with the information that we need, we use `/= gas /$ fuel:html`.
444−
445−The above expression uses two Ford runes, `/=` and `/$`, to add the relevant
446−information to the current subject. We can pull the ship's name out of this
447−augmented subject later. It's important to note that these runes are not part of
448−Hoon. They are part of Ford, our build system.
449−
450−`/$` is used to get data from the environment, and `/=` adds that data to
451−subject in the face `gas`. The
452−[Ford user manual](https://urbit.org/docs/arvo/internals/ford/runes/) has
453−details on these and other Ford runes, but understanding these runes isn't
454−necessary for the purposes of this tutorial.
455−
456−`fuel:html` gets extra data from your ship's Eyre module, which handles all
457−things HTTP, and sticks it in the subject when Eyre renders a page. This
458−includes the name of the ship, which is what we look for in the next line, but
459−it includes much more.
460−
461−`p.bem.gas` is an expression that looks for `p` within `bem` within `gas`, the
462−face that we stored the above `fuel:html` expression in. That wing happens to
463−resolve to the name of the ship that is hosting the web-server. If we wanted to
464−access the current desk, we would use the wing expression `q.bem.gas`.
465−
466−You can take a look at what you can access by typing `fuel:html` in the Dojo,
467−and then explore it by modifying your wing expression in your Sail file
468−accordingly.
469−
470−```
471−=/ show-list &
472−```
473−
474−The above line of code stores a variable used later for a conditional. `&` means
475−`true`, meaning that any evaluation of `show-list` will be true until changed in
476−the source code.
477−
478−```
479−=+ wid=(met 3 p.bem.gas)
480−=/ what-kind
481− ?: (lte wid 1) "galaxy"
482− ?: =(2 wid) "star"
483− ?: (lte wid 4) "planet"
484− ?: (lte wid 8) "moon"
485− "comet"
486−```
487−
488−This code chunk is a series of conditionals that checks the host ship's name to
489−see what its value is.
490−
491−The first line, `=+ wid=(met 3 p.bem.gas)`, combines a new noun with the
492−subject and gives it the face `wid`. This noun is produced by the the
493−standard-library function [`met`](/docs/reference/library/2c), which measures the number of
494−[blocks](/docs/reference/library/1c/) of size `a` within `b`. Blocks are units that have a
495−bitwidth of `2^a`. So, in this case, it measures how many bytes (blocks of size
496−3 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship's address.
497−
498−Galaxies contain zero to one 3-blocks; stars contain two 3-blocks; planets
499−contain three to four 3-blocks; moons contain five to eight 3-blocks; comets
500−contain nine to sixteen 3-blocks. Each test uses `lte`, the
501−less-than-or-equal-to function, to determine if `wid` is of a given size. The
502−result of this series of tests is added to the subject and given the face
503−`what-kind`.
504−
505−Ship names are simply another representation of atoms, and ship
506−categories are different ranges of possible atomic values. Because of this, we
507−perform less-than tests to see what kind of ship is running the web-server.
508−
509−```
510−;html
511− ;head
512− ;meta(charset "utf-8");
513− ;title: A more advanced page
514− ==
515−```
516−
517−Sail proper begins here. These four lines are four nodes. The `;html` node
518−indicates that the contained code should be rendered as HTML; this tag is closed
519−on the final line. The `;head` node contains metadata, and is closed three lines
520−later. The `;meta` node sets the character set to UTF-8, and the `;title` node
521−sets the title of the page that shows up in the browser tab.
522−
523−```
524− ;body
525− ;h1: This is the Title
526− ; This is a
527− ;a/"http://urbit.org": link to Urbit.org.
528− ;span: Check it out!
529−```
530−
531−The first line here opens, of course, the body node. The second line creates
532−header text.
533−
534−The third, fourth, and fifth lines of code here construct a single line with an
535−inline link.
536−`; This is a` begins the rendered line with plain text.
537−
538−`;a/"http://urbit.org": link to Urbit.org.` continues that same rendered line,
539−and creates hyperlinked text out of `link to Urbit.org.`
540−
541−`;span: Check it out!` continues that same rendered line further. `;span:`
542−has the same use as `<span>` in HTML, and by following it with just a `:` and no
543−attributes, it continues the line without formatting. Following `;span:` with
544−**two** spaces causes there to be single space following the produced `<span>`
545−element, because one of those spaces is syntactically necessary.
546−
547−In the following lines, we begin to use some Hoon expressions again.
548−
549−```
550− ;+ ?: show-list
551− ;ol
552−```
553−
554−In the top line in the chunk above, we use the `;+` Sail rune, which
555−resolves an expression to a single node. That expression, in this case, is
556−`?:`, which tests the truth value of `show-list`, which we assigned the value
557−`&` (meaning `true`) at the beginning of the program. It's closed by the `==` on
558−the last line.
559−
560−Thus, this program resolves to the first child of `show-list`, the node `;ol`.
561−That node creates an ordered list, and the items contained within that node.
562−
563−```
564− ;li(style "color: green"): We're doing more interesting stuff now.
565−```
566−
567−The line above is the only element of this list that does not use
568−Hoon proper. The line renders as green, as interpreted by the browser,
569−because of the Sail attribute.
570−
571−The next items in the list use `{}`. Recall that these braces, pronounced "lob"
572−and "rob" in Hoon-speak, allow for the interpolation of code within a string.
573−
574−```
575− ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.
576−```
577−
578−The line above is interpolated with Hoon code that produces the sum of 50 plus
579−50, which is wrapped in `<>` to put the product in double quotes to make it a
580−tape, like the rest of the line.
581−
582−```
583− ;li: The code above is shorthand for {(scow %ud (add 50 50))}.
584−```
585−
586−The `{(scow %ud (add 50 50)}` on this line is just a different way
587−writing the `{<(add 50 50)>}` expression. `scow` is a Hoon function that turns a
588−noun into a `tape`, Hoon's string type. `%ud` tells `scow` that its argument
589−should be displayed in the form of an unsigned decimal.
590−
591−```
592− ;li: I am {(trip '~lodleb-ritrul')}.
593−```
594−
595−`trip` is a function that takes a `cord` and produces a `tape`. A piece of
596−data of the cord type is one big atom formed from adjacent unicode bytes and
597−delineated by `''`. Remember that all text rendered in Sail is treated as a
598−tape. So, by converting `~lodleb-ritrul` to a tape, it can be included in the
599−tape that we are trying to insert it into without getting a type error.
600−
601−```
602− ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.
603− ==
604−```
605−
606−The line above has interpolated code that uses a wing expression to access the
607−name of the host ship, and then accesses the face `what-kind` that contains a
608−string describing what type of ship it is. We declared `gas` on the very first
609−line so that we could add that sort of information to the subject that our Sail
610−is rendered against. The wing expression `p.bem.gas` looks for `p` within `bem`
611−within `gas`, which happens to be where the name of the ship is located.
612−
613−Note that `{what-kind}` does not have a `<>` wrapper. Why do you think this is?
614−
615−```
616− ;div; My name is {<p.bem.gas>}. I'm a {ship}.
617− ==
618−==
619−```
620−
621−The `;div;` node above is only rendered, as an alternative to the above list,
622−if `show-list` is evaluated as `true`. This means it won't be shown with your
623−default code. To show this line, change the `&` on line 2 to `|` (`false`).
624−
625−### Sail Runes
626−
627−In the previous example, we used a few special runes that aren't used in typical
628−Hoon code. But there are others that are worth learning about at this point.
629−
630−`;+` is an expression that resolves to a single node. We saw this on line 20
631−in our Sail example above: `;+ ?: show-list` resolves to the node `;ol` and
632−all of that node's children.
633−
634−`;*` is an expression that resolves to a list of nodes. If we want to render
635−multiple nodes side-by-side, and not just the children of a single node, this
636−is the expression that we use.
637−
638−`;=` turns a tuple of nodes into a list of nodes.
639−
640−To see how these runes work, let's take a chunk of our previous code starting at
641−line 20 and modify it a bit:
642−
643−```
644− ;* ?: show-list
645− ;=
646− ;li: I am {(trip '~lodleb-ritrul')}.
647− ;li: Actually, my name is {<p.bem.gas>}.
648− ==
649− ;=
650− ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.
651− ;div: No list here!
652− ==
653− ==
654−```
655−
656−We changed the conditional branches so that each contains two Sail nodes,
657−side-by-side -- notice that the `;ol` is absent from the first branch.
658−
659−We begin with the `;*` rune, which resolves to a list of nodes, instead of the
660−`;+` rune, which only resolves to a single node.
661−
662−But that's not enough on its own. `;*` needs to resolve to a list, and a few
663−Sail nodes aren't lists until they are explicitly made into lists. Until we wrap
664−those nodes in `;=`, the nodes treated as mere tuples. All branches must be
665−valid lists for the `;* ?: show-list` expression to resolve.
666−
667−### Further Reading
668−
669−You should now have foundational knowledge for making web pages with Sail. There
670−is, of course, more to learn.
671−
672−The [Ford manual](https://urbit.org/docs/arvo/internals/ford/runes/)
673−can show you how to access various ship resources for use in your pages. To
674−learn more about how the renderer works, take a look at the
675−`/home/ren/urb.hoon` file inside your pier.
676−
677−## Udon: A Guide {#udon}
678−
679−Udon is a way to write content for the web. It's a minimalist
680−markup language for creating and rendering text documents, with a
681−Markdown-inspired syntax. It's integrated with our Hoon programming language,
682−allowing it to be used as standalone prose in its own file or embedded inside a
683−Hoon source file, in which case it will be parsed into a tree of HTML nodes
684−using Hoon's XML-templating syntax, Sail.
685−
686−There are quite a few similarities between Udon and the
687−CommonMark standard, but there are enough differences that you shouldn't rely on
688−existing knowledge of the latter. Udon generally supports only one
689−syntax for each type of HTML node it emits. Udon is also stricter than
690−Markdown: some syntax errors will prevent the file from being parsed at all.
691−
692−## Testing Udon
693−
694−Udon files use the `.udon` file extension, but for this entry-level guide, we
695−will use the `frontpage.hoon` method that we are already familiar with.
696−
697−To test out Udon, put a `;>` under the `^- manx` in your `frontpage.hoon` file,
698−and then put all your Udon code under that `;>`. Then run `|commit %home`
699−in the Dojo. If you've already run the `|serve` command code from the first
700−section, the new content should appear at `http://localhost/test`.
701−
702−## Udon Syntax
703−
704−### Front Matter
705−
706−> Note: The Front Matter section only applies to .udon files, and not the
707−frontpage.hoon testing method.
708−
709−The first thing on a `.udon` file is a chunk of code called the front matter. It
710−contains metadata about your page, such as date, title, and position relative
711−to sibling pages.
712−
713−As an example, let's look at the front matter of this very page:
714−
715−```
716−:- :~ navhome/'/docs/'
717− sort/'28'
718− title/'Udon'
719− ==
720−;>
721−```
722−
723−What's going on here?
724−
725−`:-`, the Hoon rune for creating a cell, creates a cell composed of
726−the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune
727−for Udon.
728−
729−`:~` creates a list out of the three elements: `navhome/'/docs/'`, which
730−indicates that navigating "home" will bring you to the urbit.org/docs section
731−of the website; `sort/'28'`, which assigns it the 28th position of the
732−immediate section that contains it, the one you see in the sidebar;
733−and `title/'Udon'`, which gives the page its title. The `==` digraph
734−terminates the list.
735−
736−`;>` is a Sail rune that creates a node that contains everything that follows
737−it, telling the parser that this text should be interpreted as Udon.
738−It's not technically front matter, but you'll always find it following the
739−front matter, since all Udon must come after this rune.
740−
741−The categories listed in the example above -- `navhome`, `sort`, and `title` --
742−make sense to Eyre by default, but any arbitrary category can be used. The code
743−below is valid front matter.
744−
745−```
746−:- :~ date/~2018.9.12
747− author/~lodleb-ritrul
748− music/'rad'
749− ==
750−```
751−
752−Note that `~2018.9.12`, `~lodleb-ritrul`, and `'rad'` are all of of atom
753−types: `@da`(date), `@p` (ship name), and `@t` (cord), respectively. Only atom
754−types work here. Having `music/"rad"` would prevent the source file from
755−parsing.
756−
757−### Headers
758−
759−Headers in Udon begin the line with one or more `#` characters,
760−followed by a single space. After that space comes the actual text to be
761−displayed. The number of leading `#` characters corresponds to the resulting HTML
762−header-size element: `#` yields an `<h1>`, `##` yields an `<h2>`, and so on,
763−through `<h6>`. The header for this section is `### Headers`.
764−
765−**Example:**
766−
767−```
768−#### Header (h4)
769−
770−##### Header (h5)
771−```
772−
773−**Produces:**
774−
775−#### Header (h4)
776−
777−##### Header (h5)
778−
779−### Italics and Bold
780−
781−Enclosing text with `_` will cause that text to appear italicized, using an `<i>`
782−element.
783−
784−Enclosing text with `*` will cause that text to appear bolded, using a `<b>`
785−element.
786−
787−**Example:**
788−
789−```
790−To get their *attention*, you need that _je ne sais quoi_.
791−```
792−
793−**Produces:**
794−
795−To get their **attention**, you need that _je ne sais quoi_.
796−
797−### Line Break
798−
799−A blank line is interpreted as a line break, creating a distinct
800−paragraph. However, a newline on its own is merely interpreted as a space on
801−the _same line_.
802−
803−**Example:**
804−
805−```
806−Here's the first line.
807−
808−This second line is separated by two newlines, so it's a separate paragraph.
809−
810−This line looks like a distinct paragraph, but ...
811−It's only separated by a single newline, so it's included in the same paragraph.
812−```
813−
814−**Produces:**
815−
816−Here's the first line.
817−
818−This second line is separated by two newlines, so it's a separate paragraph.
819−
820−This line looks like a distinct paragraph, but ...
821−It's only separated by a single newline, so it's included in the same paragraph.
822−
823−#### Backslash Line Break
824−
825−A backslash at the end of a line inserts a line break (`<br>`)
826−after that line. This contrasts with the normal Udon behavior of
827−converting newlines to spaces.
828−
829−**Example:**
830−
831−```
832−I wonder how long each line
833−will be if I put backslashes\
834−at the ends of the lines.
835−```
836−
837−**Produces:**
838−
839−I wonder how long each line
840−will be if I put backslashes\
841−at the ends of the lines.
842−
843−### Escape
844−
845−A backslash directly _before_ a word (with no spaces) will be interpreted
846−as an escape character, causing it to be rendered raw.
847−
848−**Example:**
849−
850−```
851−Here is some *bold* text.
852−Here is some \*not bold\* text.
853−```
854−
855−**Produces:**
856−
857−Here is some **bold** text.
858−Here is some \*not bold\* text.
859−
860−### List
861−
862−A line beginning with a `-` followed by a space is interpreted as an
863−element of an **unordered list** (`<ul>`). Each line in an unordered list is
864−prepended with a bullet point.
865−
866−A line beginning with a `+` followed by a space is interpreted as an element
867−of an **ordered list** (`<ol>`). Each line in an ordered list is prepended with
868−a number corresponding to its position in that list.
869−
870−New list elements are delineated by newlines beginning with list symbols of
871−the appropriate type (`-` or `+`).
872−
873−Just as with non-list text, text on a bare newline will appear on the line before,
874−separated by a space. A `\\` is used to create a line-break that isn't the list
875−itself and isn't a list. Both of these kinds of newlines must be indented by two
876−spaces, or else the page will not parse.
877−
878−Indentation is also used for creating nested sub-lists. Sub-lists of one kind
879−can be used with parent lists of the other kind. Sub-lists can't be nested
880−directly after either kind of aforementioned newline that isn't a list element;
881−only lines that are themselves list elements can nest sub-lists.
882−
883−A newline after a blank line is interpreted as a new paragraph in normal text.
884−Between two list elements, however, a blank line is semantically equivalent to
885−a bare newline. To separate two lists with blank space, create a blank line
886−followed by a `\\` on its own line.
887−
888−**Example:**
889−
890−```
891−- Eggs
892− (cage-free)
893−- Milk
894−- Butter
895−- Chicken\
896− Make sure that you get enough for the barbecue
897−- Bread
898− + Ask the baker what's fresh
899− + Buy the second-freshest batch
900−- Cereal
901−
902−\
903−+ First, separate eggs into a bowl
904−+ Then, add a splash of cream
905− - If you don't have cream, you can use milk, but cream is preferred
906− + If you don't have milk or cream, melt an eighth of a stick of butter on
907− a skillet
908− + Scramble the eggs in the bowl
909− + Pour the eggs onto the skillet before the butter browns
910−+ Heat the skillet
911−
912−+ Scramble eggs and put them into skillet
913−
914−\
915−+ Cool
916−+ Alright
917−```
918−
919−Produces
920−
921−- Eggs
922− (cage-free)
923−- Milk
924−- Butter
925−- Chicken\
926− Make sure that you get enough for the barbecue
927−- Bread
928− 1. Ask the baker what's fresh
929− 1. Buy the second-freshest batch
930−- Cereal
931−
932−\
933−1. First, separate eggs into a bowl
934−1. Then, add a splash of cream
935− - If you don't have cream, you can use milk, but cream is preferred
936− 1. If you don't have milk or cream, melt an eighth of a stick of butter on
937− a skillet
938− 1. Scramble the eggs in the bowl
939− 1. Pour the eggs onto the skillet before the butter browns
940−1. Heat the skillet
941−
942−1. Scramble eggs and put them into skillet
943−
944−\
945−1. Cool
946−1. Alright
947−
948−### Link
949−
950−There are two ways to create links, but both contain the text be hyperlinked
951−in `[]` followed by the destination in `()`.
952−
953−The first type is an inline-style link, which simply uses the full URL as its
954−destination.
955−
956−**Example:**
957−
958−```
959−[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)
960−```
961−
962−**Produces:**
963−
964−[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)
965−
966−The second type is a reference-style link, which uses a relative path, based on
967−the current page's location. Instead of the full url, we use `..` to fill in
968−all of the URL that the destination has in common with the origin page.
969−
970−**Example:**
971−
972−```
973−[I'm a reference-style link](../shell)
974−```
975−
976−**Produces:**
977−
978−[I'm a reference-style link](../shell)
979−
980−If this page is located at `https://www.urbit.org/docs/reference/`, then these two
981−examples should have the same destination.
982−
983−#### Anchor Link
984−
985−A link to a section of the same page is in the style of
986−`[text to be linked](#the-destination)`.
987−
988−The destination for the anchor link is designated with the HTML element `id`,
989−so we need to use some [Sail](#sail). If there are two or more anchors with
990−the same `id` on the page, you will arrive at the earliest instance of the the
991−anchor.
992−
993−Note that each HTML element `id` should be unique and not be used more than once.
994−
995−**Example:**
996−
997−```
998−Check out this [section](#here-we-are) that we want to jump to.
999−
1000−Four score and seven years ago ...
1001−
1002−It was the best of times, it was the worst of times ...
1003−
1004−## Here we are!
1005−```
1006−
1007−**Produces:**
1008−
1009−Check out this [section](#here-we-are) that we want to jump to.
1010−
1011−Four score and seven years ago ...
1012−
1013−It was the best of times, it was the worst of times ...
1014−
1015−## Here we are!
1016−
1017−### Double Quote
1018−
1019−Text enclosed in double quotes (`"`) will be rendered with
1020−opening and closing quotes -- that is, `"` and `"`.
1021−
1022−**Example:**
1023−```
1024−"Yes," he said. "That is the way with him."
1025−```
1026−
1027−**Produces:**
1028−
1029−"Yes," he said. "That is the way with him."
1030−
1031−### Code Literal
1032−
1033−There are two ways to show the literal text of code without running it: inline
1034−and block. Both highlight the contained text in another color.
1035−
1036−Note that the backslash, due to its role as the escape character, can only be
1037−displayed in a code block literal and not as inline code literal. This is a
1038−bug.
1039−
1040−```
1041−\
1042−```
1043−
1044−#### Inline Code Literal
1045−
1046−Enclosing some text in `` ` `` characters will cause it to be displayed as code,
1047−inside a `<code>` HTML element with monospace font and highlighted with a
1048−different background color.
1049−
1050−Using `` ` `` is useful when you want to designate only part of a line as code.
1051−Since this page is written in Udon, we've been using this operation
1052−throughout this guide to _format text_ to distinguish `code` from prose.
1053−
1054−**Example:**
1055−
1056−```
1057−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
1058−```
1059−
1060−**Produces:**
1061−
1062−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
1063−
1064−Also, using the `++` prefix before a word will cause the word to be rendered as
1065−code with the `++` displayed, since that's the standard notation for an arm in
1066−Hoon.
1067−
1068−**Example:**
1069−
1070−```
1071−The ++add arm is used to sum two numbers.
1072−```
1073−
1074−**Produces:**
1075−
1076−The `++add` arm is used to sum two numbers.
1077−
1078−#### Block Code Literal
1079−
1080−By enclosing a block of text in a tick on their own lines
1081−before and after the contained text, the text will be treated as a code block.
1082−
1083−Most of our examples so far have used.
1084−
1085−**Example:**
1086−
1087− ```
1088− (def Y (fn [f]
1089− ((fn [x]
1090− (x x))
1091− (fn [x]
1092− (f (fn [y]
1093− ((x x) y)))))))
1094− ```
1095−
1096−**Produces:**
1097−
1098−```
1099−(def Y (fn [f]
1100− ((fn [x]
1101− (x x))
1102− (fn [x]
1103− (f (fn [y]
1104− ((x x) y)))))))
1105−```
1106−
1107−### Hoon Constants
1108−
1109−Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
1110−that can be used in Udon as well. Udon detects such code, and so these
1111−forms will automatically appear inside a `<code>` element like inline code.
1112−
1113−Example:
1114−
1115−```
1116−~2017.8.29 \
1117−0xdead.beef \
1118−%term
1119−```
1120−
1121−Produces:\
1122−
1123−`~2017.8.29` \
1124−`0xdead.beef` \
1125−`%term`
1126−
1127−### Horizontal Rule
1128−
1129−Three or more hyphens, such as `---`, on their own line produce an `<hr>`
1130−element, the "horizontal rule". This is rendered as a horizontal line the
1131−width of its containing paragraph.
1132−
1133−**Example:**
1134−
1135−```
1136−Above the line
1137−---
1138−Below the line
1139−-----
1140−And below this line, too
1141−```
1142−
1143−**Produces:**
1144−
1145−Above the line
1146−
1147−---
1148−
1149−Below the line
1150−
1151−-----
1152−
1153−And below this line, too
1154−
1155−### Block Quote
1156−
1157−A section of text with the first line beginning with `>` and a space,
1158−and each successive newline indented by two spaces, yields a
1159−`<blockquote>` HTML element. This block quote can itself contain more Udon,
1160−including more block quotes to render nested levels of quotation.
1161−
1162−Blank newlines do not end the block quote, but a blank newline followed by an
1163−unindented line of text _will_ end the quote.
1164−
1165−**Example:**
1166−
1167−```
1168−> As Gregor Samsa awoke one morning from uneasy dreams, he
1169− found himself transformed in his bed into a *monstrous* vermin.
1170−
1171−Quote break.
1172−
1173−> _See_ the child.
1174−
1175− He is pale and thin, he wears a thin and ragged linen shirt.
1176−```
1177−
1178−**Produces:**
1179−
1180−> As Gregor Samsa awoke one morning from uneasy dreams
1181− he found himself transformed in his bed into a **monstrous** vermin.
1182−
1183−Quote break.
1184−
1185−> _See_ the child.
1186−
1187−> He is pale and thin, he wears a thin and ragged linen shirt.
1188−
1189−### Poem
1190−
1191−A poem is a section of text with meaningful newlines. Recall that,
1192−normally in Udon, newlines are treated as spaces and do not create a
1193−new line of text. If you want to embed text where newlines are retained, then
1194−indent the text in question with **eight spaces**.
1195−
1196−**Example:**
1197−
1198−```
1199− A shape with lion body and the head of a man,
1200− A gaze blank and pitiless as the sun,
1201− Is moving its slow thighs, while all about it
1202− Reel shadows of the indignant desert birds.
1203−```
1204−
1205−**Produces:**
1206−
1207− A shape with lion body and the head of a man,
1208− A gaze blank and pitiless as the sun,
1209− Is moving its slow thighs, while all about it
1210− Reel shadows of the indignant desert birds.
1211−
1212−## Sail Expressions
1213−
1214−It's possible to use Udon as an HTML templating language akin to
1215−PHP, ERB, JSP, or Handlebars templates. This facility derives
1216−in part from the support for embedding Hoon code inside the markup.
1217−
1218−Sail is a domain-specific language within Hoon for creating XML nodes,
1219−including HTML. It can be used directly within Udon to provide
1220−scripting capability with Hoon and also to provide more precise control over the
1221−resulting HTML. The [Sail guide](#sail) is a good place to learn the
1222−specifics.
1223−
1224−Example:
1225−
1226−```
1227−;=
1228− ;p
1229− ;strong: Don't panic!
1230− ;br;
1231− ;small: [reactive publishing intensifies]
1232− ==
1233−==
1234−```
1235−
1236−Produces:
1237−
1238−<p>
1239− <strong>Don't panic!</strong>
1240− <br />
1241− <small>[reactive publishing intensifies]</small>
1242−</p>