Remove (linktext) links, add <link> links

1 files changed, 33 insertions, 20 deletions

diff --git a/README b/README
index 8dd0f01..b93212b 100644
--- a/README
+++ b/README
@@ -8,7 +8,7 @@ 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 *Lists* and *Inline formatting*).
+form of inline links are supported (see *Hyperlinks* below).
 
 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.
@@ -17,10 +17,6 @@ Em's complete and exact syntax is defined by its implementation [1], but a
 general description follows below.  For longer examples, see the source
 code for this text [2] or the test file [3].
 
- [1] ../tree/README
- [2] ../tree/test.em
- [3] ../tree/emparse
-
 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.
@@ -58,6 +54,16 @@ Inline references are created with square brackets:
 	
 	 [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* below.
 
 ---
@@ -65,20 +71,21 @@ 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.
+reference refers to a reference containing a single link, the inline
+reference points directly to that link, rather than at the reference.
 
-	It is available for download [2].
+	It is available for download [1].
 	
-	 [2] v1.tgz
+	 [1] <./v1.tgz>
 
 The above example translates to the following HTML:
 
-	<p>It is available for download (<a href="v1.tgz">link</a>).
+	<p>It is available for download [<a href="./v1.tgz">1</a>].
 	</p>
-
-The default link text ("link") can be changed by setting
-the `linktext` environment variable.
+	<ol class="reflist">
+	<li value="1" id="ref1"><a href="./v1.tgz">./v1.tgz</a>
+	</li>
+	</ol>
 
 ---
 
@@ -147,15 +154,13 @@ to which you can make inline references:
 	 [1] The quick brown fox ...
 
 _Note:_ There is a special type of reference list item called a
-*hyperlink reference*.  It contains only a single word,
-without whitespace:
+*hyperlink reference*.  It contains only a single link:
 
-	 [1] http://example.com
+	 [1] <http://example.com>
 
-Hyperlink reference items are removed in the final output,
-but you can still reference them inline:
-
-	You can download the file here [1].
+Hyperlink references behave just like normal references, except
+inline references to them link directly to the link rather than the
+reference item.
 
 ---
 
@@ -176,3 +181,11 @@ _Paragraphs start with no space:_
 	with two lines.
 
 	This is another paragraph.
+
+---
+
+== References ==
+
+ [1] <../tree/README>
+ [2] <../tree/test.em>
+ [3] <../tree/emparse>