_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 *Lists* and *Inline formatting*).

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 [1], but a
general description follows below.  For longer examples, see the source
code for this text [2] or the test file [3].

 [1] ../tree/README
 [2] ../tree/test.em
 [3] ../tree/emparse

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 also includes the rc script *htwrap*, which can be used to create a
standalone HTML document from em output.

---

== 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 ...

For more information about references, see *Reference lists* below.

---

=== Hyperlinks ===

Hyperlinks are a special case of inline references.  When an inline
reference refers to a reference containing only a web address,
the inline reference is replaced with a hyperlink to that address.

	It is available for download [2].
	
	 [2] v1.tgz

The above example translates to the following HTML:

	<p>It is available for download (<a href="v1.tgz">link</a>).
	</p>

The default link text ("link") can be changed by setting
the `linktext` environment variable.

---

== 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 word,
without whitespace:

	 [1] http://example.com

Hyperlink reference items are removed in the final output,
but you can still reference them inline:

	You can download the file here [1].

---

=== Preformatted blocks ===

_Preformatted blocks start with a single tab:_

		#include <stdio.h>
		main() { puts("Hello world!\n"); }

---

=== Paragraphs ===

_Paragraphs start with no space:_

	This is a paragraph
	with two lines.

	This is another paragraph.