aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README53
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>