Add information about literal hyperlinks to README

3 files changed, 76 insertions, 32 deletions

diff --git a/README b/README
index 471ebce..a434797 100644
--- a/README
+++ b/README
@@ -8,14 +8,14 @@ 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* below).
+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 [1], but a
+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 [2] or the test file [3].
+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)
@@ -73,9 +73,27 @@ 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 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.
+
+_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].
 	
@@ -200,6 +218,7 @@ _Paragraphs start with no space:_
 
 == References ==
 
- [1] <../tree/emparse>
- [2] <../tree/README>
- [3] <../tree/test.em>
+ [1] <#hyperlinks>
+ [2] <../tree/emparse>
+ [3] <../tree/README>
+ [4] <../tree/test.em>
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>
diff --git a/mkfile b/mkfile
index 7c528bc..21e11ae 100644
--- a/mkfile
+++ b/mkfile
@@ -7,7 +7,7 @@ test.html:
 
 README.html: README
 	path=(. /bin)
-	em README > README.html
+	em README | htindex -s > README.html
 
 install:
 	cp em emcollect emparse htwrap htindex /rc/bin/