From 4d51dc76d08e80c0a5ac0abf31d8e1ced153d161 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Sat, 30 Jan 2021 23:38:11 +0000
Subject: Update README

---
 README.html | 39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)

(limited to 'README.html')

diff --git a/README.html b/README.html
index 1c7707c..c6fa908 100644
--- a/README.html
+++ b/README.html
@@ -1,38 +1,39 @@
 <p>
-Em is a limited hypertext markup language.
-</p>
-<p>
-It is similar to Markdown, but it has a few key advantages:
+<b>Em is a limited hypertext markup language that is designed to be
+maximally readable.</b> It is similar to Markdown, but it has a few key advantages:
 </p>
 <ol>
 <li value="1">It is more readable.
 </li><li value="2">It is simpler to parse.
-</li><li value="3">There is <i>not</i> more than one way to do it (forgive me, Larry).
+</li><li value="3">There is <i>not</i> more than one way to do it: for any given HTML, there is
+never more than a single possible em representation.
 </li>
 </ol>
 <p>
-Em takes plain-text readability seriously. You should be able to
-write em in a plain-text e-mail message without the recipient noticing.
-On the other hand, that means that it is limited in terms of what HTML
-it can produce. Most noticeably, only a very limited form of inline links
-are supported (see <i>Lists</i> and <i>Inline formatting</i>).
+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>Lists</i> and <i>Inline formatting</i>).
+</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>
-For examples, see the source code for this text (<a href="../tree/README">link</a>) or the test file (<a href="../tree/test.em">link</a>).
+Em's complete and exact syntax is defined by its implementation (<a href="../tree/README">link</a>), but a
+general description follows below. For longer examples, see the source
+code for this text (<a href="../tree/test.em">link</a>) or the test file (<a href="../tree/emparse">link</a>).
 </p>
 <ol class="reflist" style="font-size: small;">
 </ol>
 <p>
 Em is implemented in portable awk, with an rc script to bind it together.
-The rc script can (more or less) trivially be translated to POSIX shell,
-but the work has not been done yet.
+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.
 </p>
 <p>
-Em's complete and exact syntax is defined by its implementation (<a href="../tree/emparse">link</a>),
-but a general description follows below.
+Em also includes the rc script <i>htwrap</i>, which can be used to create a
+standalone HTML document from em output.
 </p>
-<ol class="reflist" style="font-size: small;">
-</ol>
 <hr/>
 <h2>Inline formatting</h2>
 <hr/>
@@ -75,9 +76,9 @@ reference refers to a reference containing only a web address,
 the inline reference is replaced with a hyperlink to that address.
 </p>
 <pre>
-It is available for download [a].
+It is available for download [2].
 
- [a] v1.tgz
+ [2] v1.tgz
 </pre>
 <p>
 The above example translates to the following HTML:
-- 
cgit v1.2.3