Add information about literal hyperlinks to README

1 files changed, 47 insertions, 22 deletions

diff --git a/README.html b/README.html
index d23957d..05dd7b8 100644
--- a/README.html
+++ b/README.html
@@ -12,16 +12,16 @@ never more than a single possible em representation.
 <p>
 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 <i>Hyperlinks</i> below).
+form of inline links are supported (see <i>Hyperlinks</i> [<a href="#hyperlinks">1</a>]).
 </p>
 <p>
 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.
 </p>
 <p>
-Em's complete and exact syntax is defined by its implementation [<a href="../tree/emparse">1</a>], but a
+Em's complete and exact syntax is defined by its implementation [<a href="../tree/emparse">2</a>], but a
 general description follows below. For longer examples, see the source
-code for this text [<a href="../tree/README">2</a>] or the test file [<a href="../tree/test.em">3</a>].
+code for this text [<a href="../tree/README">3</a>] or the test file [<a href="../tree/test.em">4</a>].
 </p>
 <p>
 Em is implemented in portable awk, with an rc script to bind it together.
@@ -38,9 +38,9 @@ of them on standard output. Supports Latin-1.
 </dd>
 </dl>
 <hr/>
-<h2>Inline formatting</h2>
+<h2 id="inline-formatting">Inline formatting</h2>
 <hr/>
-<h3>Font style</h3>
+<h3 id="font-style">Font style</h3>
 <p>
 Italic, bold and teletype text is marked with the asterisk,
 the underscore and the backtick, respectively:
@@ -59,7 +59,7 @@ The marks are only valid in certain positions:
 </li>
 </ol>
 <hr/>
-<h3>Inline references</h3>
+<h3 id="inline-references">Inline references</h3>
 <p>
 Inline references are created with square brackets:
 </p>
@@ -84,11 +84,35 @@ reference item later in the document:
 For more information about references, see <i>Reference lists</i> below.
 </p>
 <hr/>
-<h3>Hyperlinks</h3>
+<h3 id="hyperlinks">Hyperlinks</h3>
 <p>
-Hyperlinks are a special case of inline references. When an inline
-reference refers to a reference containing a single link, the inline
-reference points directly to that link, rather than at the reference.
+Em provides two types of hyperlinks: literal hyperlinks and hyperlink
+references.
+</p>
+<p>
+<b>Literal hyperlinks</b> are wrapped in less-than and greater-than signs:
+</p>
+<pre>
+&lt;http://example.com&gt;
+</pre>
+<p>
+Most links are recognized, as long as they are free of spaces and
+contain a slash or start with a hash:
+</p>
+<pre>
+&lt;/page&gt;
+&lt;./page&gt;
+&lt;#section&gt;
+</pre>
+<p>
+The less-than and greater-than signs are valid in the same places
+as the font style formatting marks.
+</p>
+<p>
+<b>Hyperlink references</b> 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.
 </p>
 <pre>
 It is available for download [1].
@@ -107,7 +131,7 @@ The above example translates to the following HTML:
 &lt;/ol&gt;
 </pre>
 <hr/>
-<h2>Block-level formatting</h2>
+<h2 id="block-level-formatting">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.
@@ -119,7 +143,7 @@ inside a list item.
 </li>
 </ul>
 <hr/>
-<h3>Headings</h3>
+<h3 id="headings">Headings</h3>
 <p>
 Headings begin and end with the same number of equal signs:
 </p>
@@ -129,7 +153,7 @@ Headings begin and end with the same number of equal signs:
 == Second-level heading ==
 </pre>
 <hr/>
-<h3>Lists</h3>
+<h3 id="lists">Lists</h3>
 <p>
 <b>All lists start with a single space</b>, followed by some marker.
 </p>
@@ -161,7 +185,7 @@ two lines
  [1] This is a reference list
  [2] With two items
 </pre>
-<h4>Nesting</h4>
+<h4 id="nesting">Nesting</h4>
 <p>
 Unordered and ordered lists can be nested. <b>An additional space</b>
 at the beginning of the line increases the item level by one:
@@ -171,7 +195,7 @@ at the beginning of the line increases the item level by one:
   - Second level
  2. First level
 </pre>
-<h4>Reference lists</h4>
+<h4 id="reference-lists">Reference lists</h4>
 <p>
 A reference list is a special type of list. It is a type of footnote list,
 to which you can make inline references:
@@ -194,7 +218,7 @@ inline references to them link directly to the link rather than the
 reference item.
 </p>
 <hr/>
-<h3>Blockquotes</h3>
+<h3 id="blockquotes">Blockquotes</h3>
 <p>
 Blockquotes are, in terms of syntax and behavior, actually another
 type of list, started with an initial space, followed by <tt>&gt; </tt>:
@@ -205,7 +229,7 @@ The paragraph continues on the next line.
  &gt; Here begins a new quoted paragraph.
 </pre>
 <hr/>
-<h3>Preformatted blocks</h3>
+<h3 id="preformatted-blocks">Preformatted blocks</h3>
 <p>
 <b>Preformatted blocks start with a single tab:</b>
 </p>
@@ -214,7 +238,7 @@ The paragraph continues on the next line.
 	main() { puts("Hello world!\n"); }
 </pre>
 <hr/>
-<h3>Paragraphs</h3>
+<h3 id="paragraphs">Paragraphs</h3>
 <p>
 <b>Paragraphs start with no space:</b>
 </p>
@@ -226,10 +250,11 @@ with two lines.
 This is another paragraph.
 </pre>
 <hr/>
-<h2>References</h2>
+<h2 id="references">References</h2>
 <ol class="reflist">
-<li value="1" id="ref1"><a href="../tree/emparse">../tree/emparse</a>
-</li><li value="2" id="ref2"><a href="../tree/README">../tree/README</a>
-</li><li value="3" id="ref3"><a href="../tree/test.em">../tree/test.em</a>
+<li value="1" id="ref1"><a href="#hyperlinks">#hyperlinks</a>
+</li><li value="2" id="ref2"><a href="../tree/emparse">../tree/emparse</a>
+</li><li value="3" id="ref3"><a href="../tree/README">../tree/README</a>
+</li><li value="4" id="ref4"><a href="../tree/test.em">../tree/test.em</a>
 </li>
 </ol>