X-Git-Url: https://git.ladys.computer/LesML/blobdiff_plain/342c03ea7bfd599adb9f5bee07433b156379f521..edd3e261cf6e99a747137211256f94fbaefd6e0f:/README.markdown diff --git a/README.markdown b/README.markdown index 14716c2..99ff8ba 100644 --- a/README.markdown +++ b/README.markdown @@ -1,5 +1,5 @@ # šŸ’„šŸ“Ā LesĀ·MĀ·L @@ -52,7 +52,16 @@ Documents in the later case inherit the latest preceding `#!lesml` Documents are broken into paragraphs by blank lines. Empty paragraphs are ignored. -NonĀ·empty paragraphs are classified as followsā€Æ:ā ā€” + +If every line in the paragraph begins with (optional whiteĀ·space + followed by) `Ā»` it is quoted (``); 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 + (``); otherwise, they are footers (``). + +NonĀ·empty paragraphs (which, to be clear, may still result in empty + `` elements) are classified as followsā€Æ:ā ā€” - If the paragraph consists of only the following sectionā€break characters, plus any amount of whiteĀ·space, then it is @@ -98,16 +107,18 @@ NonĀ·empty paragraphs are classified as followsā€Æ:ā ā€” | `ļ¼æ` | `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 (``). - 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 (``). + +- Otherwise, the paragraph is ordinary. -- Otherwise, the paragraph is unquoted. +After this classification, each ordinary paragraph is further + classified by type based on its first character (which must be + followed by whiteĀ·space or a pilcrow, or else be the only thing on + the line)ā€Æ:ā ā€” -After this classification, each quoted or unquoted paragraph is further - classified by type based on its first character (which is must be - followed by whiteĀ·space, 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 (``). @@ -122,65 +133,112 @@ After this classification, each quoted or unquoted paragraph is further (``). - If the paragraph begins with `ā€¢` or `šŸ”¢`, it is a primary unordered - or ordered list item (`` - or ``). + or ordered list item (`` + or ``). - If the paragraph begins with `ā—¦` or `šŸ” `, it is a secondary unordered - or ordered list item (`` - or ``). + or ordered list item (`` + or ``). 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 (`` - or ``). + or ordered list item (`` + or ``). 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 - (`` or - ``). + (`` or + ``). Quaternary list items are considered to be nested inside of primary, secondary, and tertiary list items which precede them. - If the paragraph begins with `ā€»`, it is an ordinary note - (``). + (``). - If the paragraph begins with `ā˜”`, it is a cautionary note - (``). - -- If the paragraph begins with `šŸ›ˆ`, it is an informative note - (``). + (``). - If the paragraph begins with `āƑ`, it is a questioning note - (``). + (``). + +- If the paragraph begins with `@`, it is an abstract + (``). + +- If the paragraph begins with `šŸ›ˆ`, it is a (informative) tip + (``). -- If the paragraph begins with `āš ļøŽ`, it is a warning note - (``). +- If the paragraph begins with `āš ļøŽ`, it is a (warning) notice + (``). + +- If the paragraph begins with `^`, it is a footnote + (``). + 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 (``) 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 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 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 + (``). + Otherwise, they will be treated as ordinary paragraphs. - 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. +This may be suffixed with a language tag beginning with `@` and + terminated with `$`. + +When a paragraph produces an `` element ā€œwrapped inā€ another + kind of element (eĀ·g, a blockquote, section, or list item), the + identifier and language of the first paragraph are applied to the + wrapping element. +If the first paragraph has no other contents, it is deleted. +To apply the identifier or language to the `` element itself, + and not its wrapper, one can simply make the first paragraph empty + (using a literal `Ā¶` with no other contents). +This paragraph will be dropped, but the following paragraphs will still + be processed as nonĀ·initial. 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 ``. + - The characters `{šŸ”—` and `>}` indicate a hyperlink to a UĀ·RĀ·L (``). The hyperlink must contain at least one `<`; the content before the @@ -198,44 +256,50 @@ Markup within paragraphs is delimited withĀ·out exception by pairs of - The characters `āøØ` and `āø©` indicate parenthetical content (``). -- The characters `ā˜žļøŽ` and `ā˜œļøŽ` indicate strong importance - (``). - -- The characters `ā¹` and `ā¹‘` indicate emphasis (``). +- The characters `` ` `` and `Ā“` indicate code (``). - The characters `āŸŖ` and `āŸ«` indicate titles (``). +- The characters `āø¶` and `āø·` indicate names (``). + - The characters `āŸØ` and `āŸ©` indicate offset text (``). - This may be followed by a `@`, a language tag, and a `$` to provide - the language of the text. - The characters `ā¦ƒ` and `ā¦„` indicate keyword highlighting (``). -- The characters `` ` `` and `Ā“` indicate code (``). +- The characters `ā˜žļøŽ` and `ā˜œļøŽ` indicate strong importance + (``). + +- The characters `ā¹` and `ā¹‘` indicate emphasis (``). + +- The characters `^` and `.` indicate a footnote reference + (``). + 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ā€Æ:ā ā€” -- 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 `` - and the final paragraph becomes its ``. - - Continuation paragraphs are joined with the preceding list items or - quotes. + sections. - List items of a higher level are nested in preceding list items, when present. + List items of a level greater than 1 can also be nested in preceding + sections (notes, abstracts, āŠĀ·cā€¦). - Successive list items of the same level and class are joined into a single list. +- Linebreaks in preformatted paragraphs are replaced with ``. + Finally, any character can be escaped by instead providing its Unicode - codepoint in the form ``, 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 - `` + `{U+WWWW.ZZZZ}`. +Due to limitations in XĀ·SĀ·LĀ·T, characters cannot be escaped in + attributes (including link targets). ## Usage