From 6fa6614b3a7e87e42fb39217fa20e96e74e9ebf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= Date: Sun, 31 Jan 2021 13:18:23 +0000 Subject: Add information about literal hyperlinks to README --- README | 37 +++++++++++++++++++++++++-------- README.html | 69 +++++++++++++++++++++++++++++++++++++++++-------------------- mkfile | 2 +- 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: + + + +Most links are recognized, as long as they are free of spaces and +contain a slash or start with a hash: + + + <./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.

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. @@ -38,9 +38,9 @@ of them on standard output. Supports Latin-1.

-

Inline formatting

+

Inline formatting

-

Font style

+

Font style

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:

-

Inline references

+

Inline references

Inline references are created with square brackets:

@@ -84,11 +84,35 @@ reference item later in the document: 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].
@@ -107,7 +131,7 @@ The above example translates to the following HTML:
 </ol>
-

Block-level formatting

+

Block-level formatting

-

Headings

+

Headings

Headings begin and end with the same number of equal signs:

@@ -129,7 +153,7 @@ Headings begin and end with the same number of equal signs: == Second-level heading ==
-

Lists

+

Lists

All lists start with a single space, followed by some marker.

@@ -161,7 +185,7 @@ two lines [1] This is a reference list [2] With two items -

Nesting

+

Nesting

Unordered and ordered lists can be nested. An additional space 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 -

Reference lists

+

Reference lists

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.

-

Blockquotes

+

Blockquotes

Blockquotes are, in terms of syntax and behavior, actually another type of list, started with an initial space, followed by > : @@ -205,7 +229,7 @@ The paragraph continues on the next line. > Here begins a new quoted paragraph.

-

Preformatted blocks

+

Preformatted blocks

Preformatted blocks start with a single tab:

@@ -214,7 +238,7 @@ The paragraph continues on the next line. main() { puts("Hello world!\n"); }
-

Paragraphs

+

Paragraphs

Paragraphs start with no space:

@@ -226,10 +250,11 @@ with two lines. This is another paragraph.
-

References

+

References

    -
  1. ../tree/emparse -
  2. ../tree/README -
  3. ../tree/test.em +
  4. #hyperlinks +
  5. ../tree/emparse +
  6. ../tree/README +
  7. ../tree/test.em
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/ -- cgit v1.2.3