aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README37
-rw-r--r--README.html69
-rw-r--r--mkfile2
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/