Add support for footnotes

[LesML] / README.markdown

diff --git a/README.markdown b/README.markdown
index adb7e26afc8587ca66e5f5a9566664345a4ed32c..35f5a53727f6b3adbcccf1eacb4b363010c29d9d 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,5 +1,5 @@
 <!--
 <!--

-SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady>
+SPDX-FileCopyrightText: 2024, 2025 Lady <https://www.ladys.computer/about/#lady>

 SPDX-License-Identifier: CC0-1.0
 -->
 # 💄📝 Les·M·L
 SPDX-License-Identifier: CC0-1.0
 -->
 # 💄📝 Les·M·L


@@ -28,14 +28,38 @@ It is implemented as an X·S·L·T transformation from a
 
 The first line of any 💄📝 Les·M·L document should be the string
   `#!lesml`.
 
 The first line of any 💄📝 Les·M·L document should be the string
   `#!lesml`.

-
-Following the shebang, document metadata may be provided in the [Record
-  Jar][draft-phillips-record-jar-01] format.
+A language tag may follow this, beginning with `@` and terminated with
+  `$`, like so:
+`#!lesml@en$`.
+Regardless of whether a language tag is present, the shebang line may
+  be terminated by a space‐separated list of properties of the form
+  `key=value`.
+Only one property is currently permitted: `profile`, whose value should
+  be a U·R·I and is translated to the `@data-lesml-profile` attribute
+  on the resulting `<html:article>` element.
+
+Following the shebang line, document metadata may be provided in the
+  [Record Jar][draft-phillips-record-jar-01] format.

 The body of the document begins after the last line which begins with
   the string `%%`, or after the shebang line if none exists.
 
 The body of the document begins after the last line which begins with
   the string `%%`, or after the shebang line if none exists.
 

+Multiple documents can be catenated into a single file; a new document
+  is begun on any line which starts with `#!lesml` or `##`.
+Documents in the later case inherit the latest preceding `#!lesml`
+  declaration.
+`##` may be followed by other text; this is treated as an interdocument
+  comment.
+

 Documents are broken into paragraphs by blank lines.
 Empty paragraphs are ignored.
 Documents are broken into paragraphs by blank lines.
 Empty paragraphs are ignored.

+
+If every line in the paragraph begins with (optional white·space
+  followed by) `»` it is quoted (`<html:blockquote>`); if every line
+  begins with `]` it is bracketed.
+The lines, minus this leading, are then re‐analysed.
+Bracketed paragraphs which end quotes are treated as captions
+  (`<html:figcaption>`); otherwise, they are footers (`<html:footer>`).
+

 Non·empty paragraphs are classified as follows :⁠—
 
 - If the paragraph consists of only the following section‐break
 Non·empty paragraphs are classified as follows :⁠—
 
 - If the paragraph consists of only the following section‐break


@@ -46,7 +70,6 @@ Non·empty paragraphs are classified as follows :⁠—
 
   | Character | Codepoint | Unicode Name |
   | --------- | --------- | ------------ |
 
   | Character | Codepoint | Unicode Name |
   | --------- | --------- | ------------ |

-  | `#` | `U+0023` | `NUMBER SIGN` |

   | `*` | `U+002A` | `ASTERISK` |
   | `-` | `U+002D` | `HYPHEN-MINUS` |
   | `.` | `U+002E` | `FULL STOP` |
   | `*` | `U+002A` | `ASTERISK` |
   | `-` | `U+002D` | `HYPHEN-MINUS` |
   | `.` | `U+002E` | `FULL STOP` |


@@ -83,16 +106,18 @@ Non·empty paragraphs are classified as follows :⁠—
   | `＿` | `U+FF3F` | `FULLWIDTH LOW LINE` |
   | `～` | `U+FF5E` | `FULLWIDTH TILDE` |
 
   | `＿` | `U+FF3F` | `FULLWIDTH LOW LINE` |
   | `～` | `U+FF5E` | `FULLWIDTH TILDE` |
 

-- If every line in the paragraph begins with at least one space, then
-    it is considered to be a quoted paragraph (`<html:blockquote>`).
-  There is only one level of paragraph quoting; quoted paragraphs may
-    not be quoted again.
+- If every line in the paragraph begins with zero or more white·space
+    characters followed by `|`, it is a “preformatted” paragraph and
+    white·space is not collapsed (`<html:pre>`).

 
 

-- Otherwise, the paragraph is unquoted.
+- Otherwise, the paragraph is ordinary.

 
 

-After this classification, each quoted or unquoted paragraph is further
+After this classification, each ordinary paragraph is further

   classified by type based on its first character (which is must be
   classified by type based on its first character (which is must be

-   followed by white·space to be recognized) :⁠—
+  followed by white·space, a pilcrow, or else the only thing on the
+  line) :⁠—
+
+- If the paragraph is preformatted, it is an ordinary paragraph.

 
 - If the paragraph begins with `⁌`, it is a chapter heading
     (`<html:h1>`).
 
 - If the paragraph begins with `⁌`, it is a chapter heading
     (`<html:h1>`).


@@ -107,25 +132,25 @@ After this classification, each quoted or unquoted paragraph is further
     (`<html:h4>`).
 
 - If the paragraph begins with `•` or `🔢`, it is a primary unordered
     (`<html:h4>`).
 
 - If the paragraph begins with `•` or `🔢`, it is a primary unordered

-    or ordered list item (`<html:li class="unordered" data-level="1">`
-    or `<html:li class="ordered" data-level="1">`).
+    or ordered list item (`<html:li class="unordered" aria-level="1">`
+    or `<html:li class="ordered" aria-level="1">`).

 
 - If the paragraph begins with `◦` or `🔠`, it is a secondary unordered
 
 - If the paragraph begins with `◦` or `🔠`, it is a secondary unordered

-    or ordered list item (`<html:li class="unordered" data-level="2">`
-    or `<html:li class="ordered" data-level="2">`).
+    or ordered list item (`<html:li class="unordered" aria-level="2">`
+    or `<html:li class="ordered" aria-level="2">`).

   Secondary list items are considered to be nested inside of primary
     list items which precede them.
 
 - If the paragraph begins with `▪` or `🔡`, it is a tertiary unordered
   Secondary list items are considered to be nested inside of primary
     list items which precede them.
 
 - If the paragraph begins with `▪` or `🔡`, it is a tertiary unordered

-    or ordered list item (`<html:li class="unordered" data-level="3">`
-    or `<html:li class="ordered" data-level="3">`).
+    or ordered list item (`<html:li class="unordered" aria-level="3">`
+    or `<html:li class="ordered" aria-level="3">`).

   Tertiary list items are considered to be nested inside of primary
     and secondary list items which precede them.
 
 - If the paragraph begins with `⁃` or `🔣`, it is a quaternary
     unordered or ordered list item
   Tertiary list items are considered to be nested inside of primary
     and secondary list items which precede them.
 
 - If the paragraph begins with `⁃` or `🔣`, it is a quaternary
     unordered or ordered list item

-    (`<html:li class="unordered" data-level="4">` or
-    `<html:li class="ordered" data-level="4">`).
+    (`<html:li class="unordered" aria-level="4">` or
+    `<html:li class="ordered" aria-level="4">`).

   Quaternary list items are considered to be nested inside of primary,
     secondary, and tertiary list items which precede them.
 
   Quaternary list items are considered to be nested inside of primary,
     secondary, and tertiary list items which precede them.
 


@@ -144,24 +169,61 @@ After this classification, each quoted or unquoted paragraph is further
 - If the paragraph begins with `⚠︎`, it is a warning note
     (`<html:div role="note" class="warn">`).
 
 - If the paragraph begins with `⚠︎`, it is a warning note
     (`<html:div role="note" class="warn">`).
 

-- If the paragraph begins with `⋯`, it is a continuation paragraph
-    (`<html:div class="continuation">`).
-  Continuation paragraphs may be used to continue a preceding list item
-    or quote.
-  Note, however, that an unquoted paragraph cannot continue a quoted
-    one, or vice·versa.
+- If the paragraph begins with `^`, it is a footnote
+    (`<html:li class="ordered footnote" aria-level="1">`).
+  Footnotes are ignored unless their first paragraph has an i·d
+    (specified with `¶`) which is referenced by one or more footnote
+    references.
+  Footnotes are treated as level 1 ordered list items, so they can
+    contain nested lists.
+
+  Footnotes are removed from the normal document flow and placed in a
+    footer (`<html:section role="doc-endnotes">`) in order of first
+    reference.
+  It is recommended that the i·d¦s you choose are kept stable, so that
+    links to footnotes do not break.
+
+- If the paragraph begins with `#`, it is a comment.
+  Comments produce X·M·L comment nodes and can be used to break up list
+    items into separate lists.
+
+- If the paragraph begins with `⋯`, it is a continuation paragraph.
+  Continuation paragraphs may be used to continue a preceding note,
+    footnote, or list item.
+  If there is no such preceding note, footnote, or list item, they will
+    attach to adjacent heading elements to form heading groups
+    (`<html:hgroup>`).
+  Otherwise, they will be treated as ordinary paragraphs.

 
 - Otherwise, it is an ordinary paragraph.
 
 
 - Otherwise, it is an ordinary paragraph.
 

-Following this sigil (if any, including trailing white·space) there may
-  be a `¶` followed by zero or more non·white·space characters.
+Following this sigil (if any) there may be a `¶` followed by zero or
+  more non·white·space characters.

 The characters following the `¶` give the identifier for the paragraph,
   which is expected to be unique within a document.
 The characters following the `¶` give the identifier for the paragraph,
   which is expected to be unique within a document.

+This may be suffixed with a language tag beginning with `@` and
+  terminated with `$`.

 
 The remaining characters in a paragraph form its contents.
 Markup within paragraphs is delimited with·out exception by pairs of
   characters, with the following precedence :⁠—
 
 
 The remaining characters in a paragraph form its contents.
 Markup within paragraphs is delimited with·out exception by pairs of
   characters, with the following precedence :⁠—
 

+- The characters `⌦` and `⌫` indicate inline comments.
+  A single character `⌧` may be used to indicate an “empty” comment
+    (consisting of `U+034F COMBINING GRAPHEME JOINER` for X·M·L
+    compatibility).
+
+- The characters `{@` and `"}` indicate attribute specifications.
+  The attribute specification must contain at least one `="` which
+    separates the key of the attribute from the value.
+  Attributes attach to the previous element or text node, with
+    white·space‐only text nodes after elements ignored; if there is no
+    such previous element or text node, an empty text node is used
+    instead.
+  Multiple attributes can be given in sequence using multiple
+    specifications.
+  Text nodes with attributes are wrapped in `<html:span>`.
+

 - The characters `{🔗` and `>}` indicate a hyperlink to a U·R·L
     (`<html:a>`).
   The hyperlink must contain at least one `<`; the content before the
 - The characters `{🔗` and `>}` indicate a hyperlink to a U·R·L
     (`<html:a>`).
   The hyperlink must contain at least one `<`; the content before the


@@ -179,32 +241,32 @@ Markup within paragraphs is delimited with·out exception by pairs of
 - The characters `⸨` and `⸩` indicate parenthetical content
     (`<html:small>`).
 
 - The characters `⸨` and `⸩` indicate parenthetical content
     (`<html:small>`).
 

-- The characters `☞︎` and `☜︎` indicate strong importance
-    (`<html:strong>`).
-
-- The characters `⹐` and `⹑` indicate emphasis (`<html:em>`).
+- The characters `` ` `` and `´` indicate code (`<html:code>`).

 
 - The characters `⟪` and `⟫` indicate titles (`<html:cite>`).
 
 
 - The characters `⟪` and `⟫` indicate titles (`<html:cite>`).
 

+- The characters `⸶` and `⸷` indicate names (`<html:u class="name">`).
+

 - The characters `⟨` and `⟩` indicate offset text (`<html:i>`).
 - The characters `⟨` and `⟩` indicate offset text (`<html:i>`).

-  This may be followed by a `@`, a language tag, and a `$` to provide
-    the language of the text.

 
 - The characters `⦃` and `⦄` indicate keyword highlighting
     (`<html:b>`).
 
 
 - The characters `⦃` and `⦄` indicate keyword highlighting
     (`<html:b>`).
 

-- The characters `` ` `` and `´` indicate code (`<html:code>`).
+- The characters `☞︎` and `☜︎` indicate strong importance
+    (`<html:strong>`).
+
+- The characters `⹐` and `⹑` indicate emphasis (`<html:em>`).
+
+- The characters `^` and `.` indicate a footnote reference
+    (`<html:a role="doc-noteref">`).
+  The characters between these sigils must match the i·d of the first
+    paragraph of some footnote in the same document.

 
 Once the tree is built as above, it is remediated into its final form
   by the following steps :⁠—
 
 
 Once the tree is built as above, it is remediated into its final form
   by the following steps :⁠—
 

-- Successive quoted paragraphs are joined into one quote.
-  If the final quoted paragraph is an ordinary paragraph which begins
-    with `—` and a space, the quote is wrapped in a `<html:figure>`
-    and the final paragraph becomes its `<html:figcaption>`.
-

 - Continuation paragraphs are joined with the preceding list items or
 - Continuation paragraphs are joined with the preceding list items or

-    quotes.
+    divs.

 
 - List items of a higher level are nested in preceding list items, when
     present.
 
 - List items of a higher level are nested in preceding list items, when
     present.


@@ -212,11 +274,15 @@ Once the tree is built as above, it is remediated into its final form
 - Successive list items of the same level and class are joined into
     a single list.
 
 - Successive list items of the same level and class are joined into
     a single list.
 

+- Linebreaks in preformatted paragraphs are replaced with `<html:br>`.
+

 Finally, any character can be escaped by instead providing its Unicode
 Finally, any character can be escaped by instead providing its Unicode

-  codepoint in the form `<U+NNNN>`, where `NNNN` is one or more
+  codepoint in the form `{U+NNNN}`, where `NNNN` is one or more

   hexadecimal digits.
 Multiple codepoints may be provided separated by periods, as in
   hexadecimal digits.
 Multiple codepoints may be provided separated by periods, as in

-  `<U+WWWW.ZZZZ>`
+  `{U+WWWW.ZZZZ}`.
+Due to limitations in X·S·L·T, characters cannot be escaped in
+  attributes (including link targets).

 
 ## Usage
 
 
 ## Usage