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`.
-
-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.
 
+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.
 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>`).
 
+  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
@@ -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 subsection heading
+- If the paragraph begins with `❦`, it is a subsection heading
     (`<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
@@ -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.
 
-- 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
@@ -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 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
@@ -178,9 +239,9 @@ Multiple codepoints may be provided separated by periods, as in
 
 ## 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
-  ⛩️📰 书社 as an additional parser, and `magic` as an additional
+  ⛩📰 书社 as an additional parser, and `magic` as an additional
   magic file.
 
 ## License