From 4d51dc76d08e80c0a5ac0abf31d8e1ced153d161 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= Date: Sat, 30 Jan 2021 23:38:11 +0000 Subject: Update README --- README | 42 ++++++++++++++++++++++-------------------- README.html | 39 ++++++++++++++++++++------------------- 2 files changed, 42 insertions(+), 39 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: diff --git a/README.html b/README.html index 1c7707c..c6fa908 100644 --- a/README.html +++ b/README.html @@ -1,38 +1,39 @@

-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). +
  4. 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). +

+

+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.

-For examples, see the source code for this text (link) or the test file (link). +Em's complete and exact syntax is defined by its implementation (link), but a +general description follows below. For longer examples, see the source +code for this text (link) or the test file (link).

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.

-Em's complete and exact syntax is defined by its implementation (link), -but a general description follows below. +Em also includes the rc script htwrap, which can be used to create a +standalone HTML document from em output.

-
    -

Inline formatting

@@ -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. 

-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: -- cgit v1.2.3