Update README

2 files changed, 192 insertions, 152 deletions

diff --git a/README b/README
index 1f6e238..c57618a 100644
--- a/README
+++ b/README
@@ -17,39 +17,78 @@ For examples, see the source code for this text [a] or the test file [b].
  [a] ../tree/README
  [b] ../tree/test.em
 
-== Implementation ==
-
 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.
 
-== Syntax ==
-
 Em's complete and exact syntax is defined by its implementation [c],
-but this section contains a general description.
+but a general description follows below.
 
  [c] ../tree/emparse
 
-=== Block-level formatting ===
+---
 
-_A single empty line_ always marks a block break.  There is
-no exception to this rule.  The line is removed in the final output.
+== Inline formatting ==
 
-All blocks support inline formatting, except headings,
-preformatted blocks and terms in definition lists.
+=== Font style ===
 
-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:
+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 [a].
+	
+	 [a] 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.
 
-	1. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
-	sed do eiusmod tempor incididunt ut labore et dolore
-	magna aliqua.
+---
 
-	2. Ut enim ad minim veniam, quis nostrud exercitation
-	ullamco laboris nisi ut aliquip ex ea commodo consequat.
+== 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 ===
 
 Headings begin and end with the same number of equal signs:
 
@@ -57,37 +96,53 @@ Headings begin and end with the same number of equal signs:
 	
 	== Second-level heading ==
 
-==== Lists ====
+---
 
-Lists start with a single space.  There are four types of lists:
+=== 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
-	
-	 this is: a definition list
+
+_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
 
-Unordered and ordered lists can be nested.  An additional space
+==== Nesting ====
+
+Unordered and ordered lists can be nested.  _An additional space_
 at the beginning of the line increases the item level by one:
 
-	 - First level
+	 1. First level
 	  - Second level
-	 - First level
+	 2. First level
+
+==== Reference lists ====
 
-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:
+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 ...
 
-There is a special type of reference list item called a *hyperlink
-reference*.  It contains only a single word, without whitespace:
+_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
 
@@ -96,53 +151,22 @@ but you can still reference them inline:
 
 	You can download the file here [1].
 
-==== Preformatted blocks ====
+---
+
+=== Preformatted blocks ===
 
-Preformatted blocks start with a single tab:
+__Preformatted blocks start with a single tab:__
 
 		#include <stdio.h>
 		main() { puts("Hello world!\n"); }
 
-==== Paragraphs ====
+---
+
+=== Paragraphs ===
 
-Paragraphs start with no space:
+__Paragraphs start with no space:__
 
 	This is a paragraph
 	with two lines.
 
 	This is another paragraph.
-
-=== Inline formatting ===
-
-_Italic, bold and teletype text_ is marked with the asterisk,
-the underscore and the backtick, respectively:
-
-	Example of *italic 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_ are created with square brackets:
-
-	Example of an inline reference [12].
-
-They are valid in positions 1, 3 and 4.
-
-When referencing a hyperlink reference (see above),
-the reference is replaced with a link.  For example:
-
-	It is available for download [1].
-	
-	 [1] v1.tgz
-
-translates into 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.
diff --git a/README.html b/README.html
index f0c5676..576b50d 100644
--- a/README.html
+++ b/README.html
@@ -22,43 +22,86 @@ For examples, see the source code for this text (<a href="../tree/README">link</
 </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>
 <p>
 Em's complete and exact syntax is defined by its implementation (<a href="../tree/emparse">link</a>),
-but this section contains a general description.
+but a general description follows below.
 </p>
 <ol class="reflist" style="font-size: small;">
 </ol>
-<h3>Block-level formatting</h3>
+<hr/>
+<h2>Inline formatting</h2>
+<h3>Font style</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.
+Italic, bold and teletype text is marked with the asterisk,
+the underscore and the backtick, respectively:
 </p>
+<pre>
+Example of *italic text*, _bold text_ and `teletype text`.
+</pre>
 <p>
-All blocks support inline formatting, except headings,
-preformatted blocks and terms in definition lists.
+The marks are only valid in certain positions:
 </p>
+<ol>
+<li value="1">At word borders
+</li><li value="2">At the beginning of a word after an opening parenthesis
+</li><li value="3">At the end of a word before any of <tt>.,:;?!)</tt>
+</li><li value="4">At the end of a word before a closing parenthesis followed by any of <tt>.,:;?!</tt>
+</li>
+</ol>
+<hr/>
+<h3>Inline references</h3>
 <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:
+Inline references are created with square brackets:
 </p>
 <pre>
-1. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
-sed do eiusmod tempor incididunt ut labore et dolore
-magna aliqua.
+Example of an inline reference [1].
+
+ [1] The quick brown fox ...
 </pre>
+<p>
+For more information about references, see <i>Reference lists</i> below.
+</p>
+<hr/>
+<h3>Hyperlinks</h3>
+<p>
+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.
+</p>
 <pre>
-2. Ut enim ad minim veniam, quis nostrud exercitation
-ullamco laboris nisi ut aliquip ex ea commodo consequat.
+It is available for download [a].
+
+ [a] v1.tgz
 </pre>
-<h4>Headings</h4>
+<p>
+The above example translates to the following HTML:
+</p>
+<pre>
+&lt;p&gt;It is available for download (&lt;a href="v1.tgz"&gt;link&lt;/a&gt;).
+&lt;/p&gt;
+</pre>
+<p>
+The default link text ("link") can be changed by setting
+the <tt>linktext</tt> environment variable.
+</p>
+<hr/>
+<h2>Block-level formatting</h2>
+<ul>
+<li><b>A single empty line marks a block break.</b> There is
+no exception to this rule. The line is removed in the final output.
+</li><li>All blocks support inline formatting, except headings,
+preformatted blocks and terms in definition lists.
+</li><li>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.
+</li>
+</ul>
+<h3>Headings</h3>
 <p>
 Headings begin and end with the same number of equal signs:
 </p>
@@ -67,44 +110,62 @@ Headings begin and end with the same number of equal signs:
 
 == Second-level heading ==
 </pre>
-<h4>Lists</h4>
+<hr/>
+<h3>Lists</h3>
+<p>
+<b>_All lists start with a single space_</b>, followed by some marker.
+</p>
 <p>
-Lists start with a single space. There are four types of lists:
+<b>Unordered lists</b> are created with <tt>- </tt>:
 </p>
 <pre>
  - This is an unordered list
  - With two items
+</pre>
+<p>
+<b>Ordered lists</b> are created with <tt>n. </tt>:
 
- 1. This is an ordered list
- 2. With an item that spans
+1. This is an ordered list
+2. With an item that spans
 two lines
-
- this is: a definition list
+</p>
+<p>
+<b>Definition lists</b> are created with <tt>term: </tt>:
+</p>
+<pre>
+ dinosaur: an animal
 </pre>
+<p>
+<b>Reference lists</b> are created with <tt>[n]. </tt>:
+</p>
 <pre>
  [1] This is a reference list
  [2] With two items
 </pre>
+<h4>Nesting</h4>
 <p>
-Unordered and ordered lists can be nested. An additional space
+Unordered and ordered lists can be nested. <b>An additional space</b>
 at the beginning of the line increases the item level by one:
 </p>
 <pre>
- - First level
+ 1. First level
   - Second level
- - First level
+ 2. First level
 </pre>
+<h4>Reference lists</h4>
 <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:
+A reference list is a special type of list. It is a type of footnote list,
+to which you can make inline references:
 </p>
 <pre>
 See footnote [1].
+
+ [1] The quick brown fox ...
 </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:
+<b>Note:</b> 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
@@ -116,17 +177,19 @@ but you can still reference them inline:
 <pre>
 You can download the file here [1].
 </pre>
-<h4>Preformatted blocks</h4>
+<hr/>
+<h3>Preformatted blocks</h3>
 <p>
-Preformatted blocks start with a single tab:
+<b>_Preformatted blocks start with a single tab:_</b>
 </p>
 <pre>
 	#include &lt;stdio.h&gt;
 	main() { puts("Hello world!\n"); }
 </pre>
-<h4>Paragraphs</h4>
+<hr/>
+<h3>Paragraphs</h3>
 <p>
-Paragraphs start with no space:
+<b>_Paragraphs start with no space:_</b>
 </p>
 <pre>
 This is a paragraph
@@ -135,50 +198,3 @@ with two lines.
 <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">At the beginning of a word after an opening parenthesis
-</li><li value="3">At the end of a word before any of <tt>.,:;?!)</tt>
-</li><li value="4">At the end of a word before a closing parenthesis followed by 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>
-&lt;p&gt;It is available for download (&lt;a href="v1.tgz"&gt;link&lt;/a&gt;).
-&lt;/p&gt;
-</pre>
-<p>
-The default link text ("link") can be changed by setting
-the <tt>linktext</tt> environment variable.
-</p>