1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<p>
Em is a limited hypertext markup language.
</p>
<p>
It is similar to Markdown, but it has a few key advantages:
</p>
<ol>
<li value="1">It is more readable.
</li><li value="2">It is simpler to parse.
</li><li value="3">There is <i>not</i> more than one way to do it (sorry Larry).
</li>
</ol>
<p>
Em takes plain-text readability seriously. You should be able to
write em in a plain-text e-mail message without the recipient noticing.
On the other hand, that means that it is limited in terms of what HTML
it can produce. Most noticeably, only a very limited form of inline links
are supported (see <i>Lists</i> and <i>Inline formatting</i>).
</p>
<p>
For examples, see the source code for this text (<a href="../tree/README">link</a>) or the test file (<a href="../tree/test.em">link</a>).
</p>
<ol class="reflist" style="font-size: small;">
</ol>
<h2>Implementation</h2>
<p>
Em is implemented in portable awk, with an rc script to bind it together.
The rc script can (more or less) trivially be translated to POSIX shell,
but the work has not been done yet.
</p>
<h2>Syntax</h2>
<h3>Block-level formatting</h3>
<p>
<b>A single empty line</b> always marks a block break. There is
no exception to this rule. The line is removed in the final output.
</p>
<p>
All blocks support inline formatting, except headings,
preformatted blocks and terms in definition lists.
</p>
<p>
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. If you want paragraph lists, just use paragraphs:
</p>
<pre>
1. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua.
</pre>
<pre>
2. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
</pre>
<h4>Headings</h4>
<p>
Headings begin and end with the same number of equal signs:
</p>
<pre>
= First-level heading =
== Second-level heading ==
</pre>
<h4>Lists</h4>
<p>
Lists start with a single space. There are four types of lists:
</p>
<pre>
- This is an unordered list
- With two items
1. This is an ordered list
2. With an item that spans
two lines
this is: a definition list
</pre>
<pre>
[1] This is a reference list
[2] With two items
</pre>
<p>
Unordered and ordered lists can be nested. An additional space
at the beginning of the line increases the item level by one:
</p>
<pre>
- First level
- Second level
- First level
</pre>
<p>
A reference list is a special type of list, unique to em. It is a
type of footnote list, to which you can make inline referencess
like this:
</p>
<pre>
See footnote [1].
</pre>
<p>
There is a special type of reference list item called a <i>hyperlink
reference</i>. It contains only a single word, without whitespace:
</p>
<pre>
[1] http://example.com
</pre>
<p>
Hyperlink reference items are removed in the final output,
but you can still reference them inline:
</p>
<pre>
You can download the file here [1].
</pre>
<h4>Preformatted blocks</h4>
<p>
Preformatted blocks start with a single tab:
</p>
<pre>
#include <stdio.h>
main() { puts("Hello world!\n"); }
</pre>
<h4>Paragraphs</h4>
<p>
Paragraphs start with no space:
</p>
<pre>
This is a paragraph
with two lines.
</pre>
<pre>
This is another paragraph.
</pre>
<h3>Inline formatting</h3>
<p>
<b>Italic, bold and teletype text</b> is marked with the asterisk,
the underscore and the backtick, respectively:
</p>
<pre>
Example of *italic* text.
</pre>
<p>
The marks are only valid in certain positions:
</p>
<ol>
<li value="1">At word borders
</li><li value="2">After an opening parenthesis
</li><li value="3">Before any of <tt>.,:;?!)</tt>
</li><li value="4">Before a closing parenthesis any of <tt>.,:;?!</tt>
</li>
</ol>
<p>
<b>Inline references</b> are created with square brackets:
</p>
<pre>
Example of an inline reference [12].
</pre>
<p>
They are valid in positions 1, 3 and 4.
</p>
<p>
When referencing a hyperlink reference (see above),
the reference is replaced with a link. For example:
</p>
<pre>
It is available for download [1].
[1] v1.tgz
</pre>
<p>
translates into the following HTML:
</p>
<pre>
<p>It is available for download (<a href="v1.tgz">link</a>).
</p>
</pre>
<p>
The default link text ("link") can be changed by setting
the <tt>linktext</tt> environment variable.
</p>
|