_Em is a limited hypertext markup language that is designed to be maximally readable._ It is similar to Markdown, but it has a few key advantages: 1. It is more readable. 2. It is simpler to parse. 3. There is *not* more than one way to do it: for any given HTML, there is never more than a single possible em representation. Em values readability over expressiveness. This means that it is rather limited in terms of what HTML it can produce. Most noticeably, only a very limited form of inline links are supported (see *Hyperlinks* [1]). Em also values consistency and predictability. As such, the syntax is rather strict. This makes it a bit harder to learn, but much more predictable. Em's complete and exact syntax is defined by its implementation [2], but a general description follows below. For longer examples, see the source code for this text [3] or the test file [4]. Em is implemented in portable awk, with an rc script to bind it together. It is written on and for Plan 9 primarily, but the rc code can (more or less) trivially be translated to POSIX shell; the work just hasn't been done yet. Em includes two additional rc scripts: htwrap: Creates a standalone HTML document from em output. htindex: Adds appropriate ids to HTML headings and prints an index of them on standard output. Supports Latin-1. --- == Inline formatting == --- === Font style === Italic, bold and teletype text is marked with the asterisk, the underscore and the backtick, respectively: Example of *italic text*, _bold text_ and `teletype text`. The marks are only valid in certain positions: 1. At word borders 2. At the beginning of a word after an opening parenthesis 3. At the end of a word before any of `.,:;?!)` 4. At the end of a word before a closing parenthesis followed by any of `.,:;?!` --- === Inline references === Inline references are created with square brackets: Example of an inline reference [1]. [1] The quick brown fox ... In the final output, the inline reference becomes a link to the reference item later in the document:

Example of an inline reference [1].

  1. The quick brown fox ...
For more information about references, see *Reference lists* [5]. --- === Hyperlinks === Em provides two types of hyperlinks: literal hyperlinks and hyperlink references. _Literal hyperlinks_ are wrapped in less-than and greater-than signs: Most links are recognized, as long as they are free of spaces and contain a slash or start with a hash: <./page> <#section> The less-than and greater-than signs are valid in the same places as the font style formatting marks. _Hyperlink references_ are a special case of inline references. When an inline reference refers to a reference containing a literal hyperlink and nothing else, the inline reference points directly to that link, rather than at the reference. It is available for download [1]. [1] <./v1.tgz> The above example translates to the following HTML:

It is available for download [1].

  1. ./v1.tgz
--- == Block-level formatting == - _A single empty line marks a block break._ There is no exception to this rule. The line is removed in the final output. - All blocks support inline formatting, except headings, preformatted blocks and terms in definition lists. - One block cannot be put within another block. For example, it is impossible to put a paragraph or a preformatted block inside a list item. --- === Headings === Headings begin and end with the same number of equal signs: = First-level heading = == Second-level heading == --- === Lists === _All lists start with a single space_, followed by some marker. _Unordered lists_ are created with `- `: - This is an unordered list - With two items _Ordered lists_ are created with `n. `: 1. This is an ordered list 2. With an item that spans two lines _Definition lists_ are created with `term: `: dinosaur: an animal _Reference lists_ are created with `[n] `: [1] This is a reference list [2] With two items ==== Nesting ==== Unordered and ordered lists can be nested. _An additional space_ at the beginning of the line increases the item level by one: 1. First level - Second level 2. First level ==== Reference lists ==== A reference list is a special type of list. It is a type of footnote list, to which you can make inline references: See footnote [1]. [1] The quick brown fox ... _Note:_ There is a special type of reference list item called a *hyperlink reference*. It contains only a single link: [1] Hyperlink references behave just like normal references, except inline references to them link directly to the link rather than the reference item. --- === Blockquotes === Blockquotes are, in terms of syntax and behavior, actually another type of list, started with an initial space, followed by `> `: > This is a quoted paragraph. The paragraph continues on the next line. > Here begins a new quoted paragraph. --- === Preformatted blocks === _Preformatted blocks start with a single tab:_ #include main() { puts("Hello world!\n"); } --- === Paragraphs === _Paragraphs start with no space:_ This is a paragraph with two lines. This is another paragraph. --- == References == [1] <#hyperlinks> [2] <../tree/emparse> [3] <../tree/README> [4] <../tree/test.em> [5] <#reference-lists>