aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README42
1 files changed, 22 insertions, 20 deletions
diff --git a/README b/README
index 4ec2956..8dd0f01 100644
--- a/README
+++ b/README
@@ -1,30 +1,32 @@
-Em is a limited hypertext markup language.
-
-It is similar to Markdown, but it has a few key advantages:
+_Em is a limited hypertext markup language that is designed to be
+maximally readable._ It is similar to Markdown, but it has a few key advantages:
1. It is more readable.
2. It is simpler to parse.
- 3. There is *not* more than one way to do it (forgive me, Larry).
+ 3. There is *not* more than one way to do it: for any given HTML, there is
+never more than a single possible em representation.
-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 *Lists* and *Inline formatting*).
+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*).
-For examples, see the source code for this text [a] or the test file [b].
+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.
- [a] ../tree/README
- [b] ../tree/test.em
+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].
-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.
+ [1] ../tree/README
+ [2] ../tree/test.em
+ [3] ../tree/emparse
-Em's complete and exact syntax is defined by its implementation [c],
-but a general description follows below.
+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.
- [c] ../tree/emparse
+Em also includes the rc script *htwrap*, which can be used to create a
+standalone HTML document from em output.
---
@@ -66,9 +68,9 @@ 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.
- It is available for download [a].
+ It is available for download [2].
- [a] v1.tgz
+ [2] v1.tgz
The above example translates to the following HTML: