Support “comment” paragraphs

[LesML] / README.markdown

diff --git a/README.markdown b/README.markdown
index 994d911ad1a1f2227eb1d477ffd7180edd6e4b2a..2901a5d2a727f574dae63254416971dfb138597c 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -28,19 +28,76 @@ 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.
 Documents are broken into paragraphs by blank lines.

+Empty paragraphs are ignored.

 Non·empty paragraphs are classified as follows :⁠—
 
 Non·empty paragraphs are classified as follows :⁠—
 

-- If the paragraph consists of only the characters
-    `#*-=_~⁂─━┄┅┈┉╌╍═╴╶╸╺☙❧` plus any amount of white·space, then it is
+- If the paragraph consists of only the following section‐break
+    characters, plus any amount of white·space, then it is

     considered to be a section break (`<html:hr>`).
 
     considered to be a section break (`<html:hr>`).
 

+  The section break characters are :⁠—
+
+  | Character | Codepoint | Unicode Name |
+  | --------- | --------- | ------------ |
+  | `*` | `U+002A` | `ASTERISK` |
+  | `-` | `U+002D` | `HYPHEN-MINUS` |
+  | `.` | `U+002E` | `FULL STOP` |
+  | `=` | `U+003D` | `EQUALS SIGN` |
+  | `_` | `U+005F` | `LOW LINE` |
+  | `~` | `U+007E` | `TILDE` |
+  | `·` | `U+00B7` | `MIDDLE DOT` |
+  | `․` | `U+2024` | `ONE DOT LEADER` |
+  | `‥` | `U+2025` | `TWO DOT LEADER` |
+  | `…` | `U+2026` | `HORIZONTAL ELLIPSIS` |
+  | `⁂` | `U+2042` | `ASTERISM` |
+  | `⋯` | `U+22EF` | `MIDLINE HORIZONTAL ELLIPSIS` |
+  | `─` | `U+2500` | `BOX DRAWINGS LIGHT HORIZONTAL` |
+  | `━` | `U+2501` | `BOX DRAWINGS HEAVY HORIZONTAL` |
+  | `┄` | `U+2504` | `BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL` |
+  | `┅` | `U+2505` | `BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL` |
+  | `┈` | `U+2508` | `BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL` |
+  | `┉` | `U+2509` | `BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL` |
+  | `╌` | `U+254C` | `BOX DRAWINGS LIGHT DOUBLE DASH HORIZONTAL` |
+  | `╍` | `U+254D` | `BOX DRAWINGS HEAVY DOUBLE DASH HORIZONTAL` |
+  | `═` | `U+2550` | `BOX DRAWINGS DOUBLE HORIZONTAL` |
+  | `╴` | `U+2574` | `BOX DRAWINGS LIGHT LEFT` |
+  | `╶` | `U+2576` | `BOX DRAWINGS LIGHT RIGHT` |
+  | `╸` | `U+2578` | `BOX DRAWINGS HEAVY LEFT` |
+  | `╺` | `U+257A` | `BOX DRAWINGS HEAVY RIGHT` |
+  | `☙` | `U+2619` | `REVERSED ROTATED FLORAL HEART BULLET` |
+  | `❧` | `U+2767` | `ROTATED FLORAL HEART BULLET` |
+  | `　` | `U+3000` | `IDEOGRAPHIC SPACE` |
+  | `・` | `U+30FB` | `KATAKANA MIDDLE DOT` |
+  | `＊` | `U+FF0A` | `FULLWIDTH ASTERISK` |
+  | `－` | `U+FF0D` | `FULLWIDTH HYPHEN-MINUS` |
+  | `．` | `U+FF0E` | `FULLWIDTH FULL STOP` |
+  | `＝` | `U+FF1D` | `FULLWIDTH EQUALS SIGN` |
+  | `＿` | `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
 - 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


@@ -58,10 +115,10 @@ After this classification, each quoted or unquoted paragraph is further
 - If the paragraph begins with `§`, it is a section heading
     (`<html:h2>`).
 
 - If the paragraph begins with `§`, it is a section heading
     (`<html:h2>`).
 

-- If the paragraph begins with `✠`, it is a subsection heading
+- If the paragraph begins with `❦`, it is a subsection heading

     (`<html:h3>`).
 
     (`<html:h3>`).
 

-- If the paragraph begins with `❦`, it is a subsubsection heading
+- If the paragraph begins with `✠`, it is a subsubsection heading

     (`<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


@@ -74,7 +131,7 @@ After this classification, each quoted or unquoted paragraph is further
   Secondary list items are considered to be nested inside of primary
     list items which precede them.
 
   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
+- 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">`).
   Tertiary list items are considered to be nested inside of primary
     or ordered list item (`<html:li class="unordered" data-level="3">`
     or `<html:li class="ordered" data-level="3">`).
   Tertiary list items are considered to be nested inside of primary


@@ -102,6 +159,10 @@ 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 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
     (`<html:div class="continuation">`).
   Continuation paragraphs may be used to continue a preceding list item
 - 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


@@ -178,9 +239,9 @@ Multiple codepoints may be provided separated by periods, as in
 
 ## Usage
 
 
 ## Usage
 

-💄📝 Les·M·L is designed for usage with [⛩️📰 书社][Shushe].
+💄📝 Les·M·L is designed for usage with [⛩📰 书社][Shushe].

 Simply include the `parser.xslt` provided by this repository to
 Simply include the `parser.xslt` provided by this repository to

-  ⛩️📰 书社 as an additional parser, and `magic` as an additional
+  ⛩📰 书社 as an additional parser, and `magic` as an additional

   magic file.
 
 ## License
   magic file.
 
 ## License