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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
_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:
<p>Example of an inline reference [<a href="#ref1">1</a>].
</p>
<ol class="reflist">
<li value="1" id="ref1">The quick brown fox ...
</li>
</ol>
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:
<http://example.com>
Most links are recognized, as long as they are free of spaces and
contain a slash or start with a hash:
</page>
<./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:
<p>It is available for download [<a href="./v1.tgz">1</a>].
</p>
<ol class="reflist">
<li value="1" id="ref1"><a href="./v1.tgz">./v1.tgz</a>
</li>
</ol>
---
== 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] <http://example.com>
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 <stdio.h>
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>
|