fixup! docs: WIP: Djot manual overhaul

examples/sile-and-djot.dj

@@ -125,7 +125,7 @@ Besides heading levels, it also works for various elements where you can define
 For instance we had some centered text in section [](#djot-centered).
 With appropriate class and package support,[^djot-sec-label-support] you may even refer to Gutenberg as "figure [](#djot-gutenberg)", or to some poetry verse mentioning the Sun ("Soleil"), in [](#sun){.section}, as "verse [](#sun)".
 
-[^djot-sec-label-support]: Typically, it works with the **resilient** collection of classes and packages. It won't work with non-supporting class and packages, using the fallback implementation for captioned elements, poetry, etc.
+[^djot-sec-label-support]: Typically, it works with the *resilient* collection of classes and packages. It won't work with non-supporting class and packages, using the fallback implementation for captioned elements, poetry, etc.
 
 {#djot-image}
 ### Images
@@ -169,7 +169,7 @@ An image with nonempty caption (i.e. "alternate" text), occurring alone by itsel
 Otherwise, the caption is ignored.  
 
 - If your class or previously loaded packages provide a `captioned-figure` environment, it will be wrapped around the image (and it is then assumed to take care of the caption, i.e. to extract and display it appropriately).
-- Specifically, if the **resilient** classes are used, the caption will be numbered by default, and added to the list of figures. Specify `.unnumbered`, and `.notoc` respectively, if you do not want it.
+- Specifically, if the *resilient* classes are used, the caption will be numbered by default, and added to the list of figures. Specify `.unnumbered`, and `.notoc` respectively, if you do not want it.
 - Otherwise, the converter uses its own fallback method.
 
 #### Extended image types
@@ -185,7 +185,7 @@ This inline "manicule" is obtained with:
 ```
 :::
 
-Files in Graphviz DOT graph language (`.dot`) are supported and rendered as images too, when the **embedders.sile** collection is properly installed and configured.
+Files in Graphviz DOT graph language (`.dot`) are supported and rendered as images too, when the *embedders.sile* collection is properly installed and configured.
 
 ![The *markdown.sile* ecosystem (simplified).](./markdown-sile-schema.dot){width="92%lw"}
 
@@ -198,7 +198,7 @@ This image is obtained with the following syntax.
 ```
 :::
 
-CSV files are also supported, when the **piecharts.sile** optional collection is properly installed (see §[](#recommended-additional-packages)), and are rendered as pie charts.
+CSV files are also supported, when the *piecharts.sile* optional collection is properly installed (see §[](#recommended-additional-packages)), and are rendered as pie charts.
 
 ![A pie chart.](./data-pie.csv){height="8em" cutoff="0.07"}
 
@@ -453,7 +453,7 @@ This converter recognizes a few specific pseudo-classes:
 For this converter, the three last ones are equivalent to the `{+...+}` and `{-...-}` syntaxes, and the `{=...=}` syntax, respectively.
 In other term, these Djot inline elements are mere shortcuts for the corresponding spans.
 
-Moreover, if used within in a **resilient** class, the converter uses the `md-underline`, `md-strikethrough`, `md-insertion`, `md-deletion` and `md-mark` styles, respectively, if they are defined in your style file.
+Moreover, if used within in a *resilient* class, the converter uses the `md-underline`, `md-strikethrough`, `md-insertion`, `md-deletion` and `md-mark` styles, respectively, if they are defined in your style file.
 Another way to put it is that the converter then does the same think as a `{custom-style="..."}` attribute (see §[](#djot-custom-styles)).
 You can style and fine-tune these elements as you wish, and even use them for other purposes than their original intent.[^djot-spans-hook]
 
@@ -537,16 +537,19 @@ Here is an example illustrating the use of these attributes:
 :::
 ```
 {#djot-unnumbered-heading .unnumbered .notoc}
-### Unnumbered heading
+#### Other attributes
 ```
 :::
 
+{#djot-unnumbered-heading .unnumbered .notoc}
+#### Other attributes
+
 Other attributes are passed through to the underlying heading implementation, which might do something with them.[^djot-heading-level-mapping]
 
 [^djot-heading-level-mapping]: The converter assumes it can map heading levels to SILE commands `part`, `chapter`, `section`, `subsection`, `subsubsection`.
 It uses a very basic fallback if these are not found (or if the sectioning level gets past that point).
 The implication, therefore, is that the document class or other packages have to provide the relevant implementations.
-Also note that parts are supported by the **resilient** book class as a level 0 heading, and are therefore only available when header shifting is applied.
+Also note that parts are supported by the *resilient* book class as a level 0 heading, and are therefore only available when header shifting is applied.
 
 ### Block quote
 
@@ -560,13 +563,13 @@ The contents of the block quote are parsed as block-level content.
 ```
 > This is block quote.
 >
-> > They can be nested.
+> > Such quotes can be nested.
 ```
 :::
 
 > This is block quote.
 >
-> > They can be nested.
+> > Such quotes can be nested.  
 
 If your document class or previously loaded packages provide a `blockquote` environment, it will be used.
 Otherwise, the converter uses its own fallback method, with hard-coded styling.
@@ -579,7 +582,7 @@ Otherwise, the converter uses its own fallback method, with hard-coded styling.
 ^ Jorge Luis [Borges]{.smallcaps}, "The Library of Babel"
 
 Standard Djot only honors captions on tables, and ignores them on other block elements.
-When using a **resilient** document class, however, a captioned block quote is rendered as an "epigraph", with the caption content used as its "source" (in a broad sense).
+When using a *resilient* document class, however, a captioned block quote is rendered as an "epigraph", with the caption content used as its "source" (in a broad sense).
 The caption is introduced with a `^` character, and can contain inline elements.
 For instance, the above quote was obtained with:
 
@@ -594,27 +597,28 @@ For instance, the above quote was obtained with:
 :::
 
 Attributes are passed through to an implicit "div" (so as to honor the language, a link target identifier, etc.) and eventually to the underlying epigraph environment.
-Any option supported by the **resilient.epigraph** package may thus be used.
+Any option supported by the *resilient.epigraph* package may thus be used.
 
 Be aware that this behavior is currently an extension.
 Other Djot converters will therefore likely skip the caption.
 
 ### Lists
 
-Unordered lists (a.k.a. itemized or bulleted lists) are obviously supported, or
-we would not have been able to use them in the previous sections.
-
-Ordered lists are supported as well.
-The starting number is honored, and you have the flexibility to use
-digits, roman numbers or letters (in upper or lower case).
-Djot also recognizes several delimiter styles.
+A list item consists of a list marker followed by a space (or a newline) followed by one or more lines, indented relative to the list marker.
 
- b. This list uses lowercase letters and starts at 2. Er... at "b", that is.
-
-     i) Roman number...
-     ii) ... followed by a right parenthesis rather than a period.
+{custom-style=CodeBlock}
+:::
+```
+1. Nesting...
+
+    ... works as intended.
+
+     - Fruits
+
+        - Apple
+```
+:::
 
-By the way,
 
  1. Nesting...
 
@@ -624,26 +628,171 @@ By the way,
 
         - Apple
 
-Task lists following the GitHub-Flavored Markdown (GFM) format are supported too.
 
- - [ ] Unchecked item
- - [x] Checked item
+### Unordered lists
+
+Unordered lists (a.k.a. itemized or bulleted lists) are introduced by a bullet list marker, either `-`, `+`, or `*`.
+
+With this converter, the list marker is not significant, and the supporting package is responsible for rendering nested lists with the appropriate symbol.
+
+{custom-style=CodeBlock}
+:::
+```
+ - This is a bullet list.
+
+   - It can be nested.
+
+     - And nested again.
+
+ - Another item.
+```
+:::
+
+ - This is a bullet list.
+
+   - It can be nested.
+
+     - And nested again.
+
+ - Another item.
+
+### Ordered lists
+
+Djot supports several types of ordered lists.
+
+---
+
+1. Decimal-enumerated, followed by period.
+
+1) Decimal-enumerated, followed by parenthesis.
+
+(1) Decimal-enumerated, enclosed in parentheses.
+
+a. Lower-alpha-enumerated, followed by period.
+
+a) Lower-alpha-enumerated, followed by parenthesis.
+
+(a) Lower-alpha-enumerated, enclosed in parentheses.
+
+A. Upper-alpha-enumerated, followed by period.
+
+A) Upper-alpha-enumerated, followed by parenthesis.
+
+(A) Upper-alpha-enumerated, enclosed in parentheses.
+
+i. Lower-roman-enumerated, followed by period.
+
+i) Lower-roman-enumerated, followed by parenthesis.
+
+(i) Lower-roman-enumerated, enclosed in parentheses.
+
+I. Upper-roman-enumerated, followed by period.
+
+I) Upper-roman-enumerated, followed by parenthesis.
+
+(I) Upper-roman-enumerated, enclosed in parentheses.
+
+---
 
-Definition lists are also decently supported. Note the syntax differs from Pandoc-style Markdown.
+In a given type of list, you do not have to number the items in order by yourself, as Djot automatically increments the number for you.
+Your starting number, however, is honored, would you want to start at a different number than 1 (in any numbering scheme).
 
- : apples
+{custom-style=CodeBlock}
+:::
+```
+1. Item
+1. Item
+1. Item
+```
+:::
 
-   Good for making applesauce.
+1. Item
+1. Item
+1. Item
 
- : citrus
+{custom-style=CodeBlock}
+:::
+```
+ b. This list starts at "b"
+
+     iii) This list starts a "iii" in roman numerals.
+     i) Next item is thus "iv".
+
+ a. The next item here is "c".
+```
+:::
 
-   Like oranges but yellow.
+  b. This list starts at "b"
+
+      iii) This list starts a "iii" in roman numerals.
+      i) Next item is thus "iv".
 
-Djot attributes are passed to the underlying definition environment.[^djot-resilient-defn]
+  a. The next item here is "c".
 
-[^djot-resilient-defn]: With the *resilient.defn* environment, the `variant` option may thus be used to switch to an alternate style.
+#### Definition lists
 
+In a definition list item, the first line or lines after the `:` marker is parsed as inline content and taken to be the term defined.
+Any further blocks included in the item are assumed to be the definition.
 
+{custom-style=CodeBlock}
+:::
+```
+: apples
+
+  Good for making applesauce.
+
+: citrus
+
+  Like oranges but yellow.
+```
+:::
+
+
+: apples
+
+  Good for making applesauce.
+
+: citrus
+
+  Like oranges but yellow.
+
+Block attributes are passed to the underlying definition environment.
+When not using a supporting class or package, the converter uses its own fallback method, with hard-coded styling (e.g. the term is typeset in boldface).
+When using the *resilient* classes, the converter uses the *resilient.defn* environment, and the `variant` option may thus be used to switch to an alternate style.[^djot-defn-variant] 
+For the purpose of illustration, let's say you have a "Custom" variant with an _ad hoc_ appropriate styling.
+
+{custom-style=CodeBlock}
+:::
+{variant=Custom}
+```
+: Djot
+
+  A light markup syntax.
+```
+:::
+
+{variant=Custom}
+: Djot
+
+  A light markup syntax.
+
+[^djot-defn-variant]: Within *resilient*, you can already fully style the default definition list.
+The `variant` option is intended to switch to a different style, when you need more than one for different purposes in the same document.
+
+#### Task lists
+
+A bullet list item that begins with `[ ]`, `[X]`, or `[x]` followed by a space is a task list item, either unchecked (`[ ]`) or checked (`[X]` or `[x]`).
+
+{custom-style=CodeBlock}
+:::
+```
+ - [ ] Unchecked item
+ - [x] Checked item
+```
+:::
+
+ - [ ] Unchecked item
+ - [x] Checked item
 
 {#djot-footnotes}
 ### Footnotes
@@ -684,9 +833,8 @@ caption.[^djot-numbered-caption]
 
 ^ Demonstration of a pipe table.
 
-[^djot-numbered-caption]: When using the **resilient** classes, the caption will be numbered by
-default, and added to the list of tables. Specify `.unnumbered`, and `.notoc` respectively, as
-table attributes, if you do not want it.
+[^djot-numbered-caption]: When using the *resilient* classes, the caption will be numbered by default, and added to the list of tables.
+Specify `.unnumbered`, and `.notoc` respectively, as table attributes, if you do not want it.
 
 ### Code blocks
 
@@ -777,14 +925,14 @@ The `render` attribute can be set to `false` to prevent this behavior, and enfor
   Internally, this relies on two extensible mechanisms:
 
   - SILE "raw" handlers, which may be declared by additional packages.
-  - Renderers for text formats that can be converted to an image, as supported by the **embedders.sile** module (which is a dependency of this package and is automatically loaded).
+  - Renderers for text formats that can be converted to an image, as supported by the *embedders.sile* module (which is a dependency of this package and is automatically loaded).
 
   The former allows this converter to support rendering of any text format exposed by other SILE packages (or classes).
   The latter allows to render any format that can be converted to an image, provided the necessary software is installed on your host system. (See §[](#recommended-additional-software) for more details.)
 
   : Graphviz DOT graphs
 
-    If you properly installed the **embedders.sile** collection and its software dependencies, then code blocks marked as being in the Graphviz DOT language (again, either with the `dot` format string or the `.dot` class specifier) are rendered as images. When the attribute syntax is used, options are passed to the underlying processor.
+    If you properly installed the *embedders.sile* collection and its software dependencies, then code blocks marked as being in the Graphviz DOT language (again, either with the `dot` format string or the `.dot` class specifier) are rendered as images. When the attribute syntax is used, options are passed to the underlying processor.
     For instance, the image below is produced with `{.dot width="3.5cm" layout=twopi}`.
 
     :::
@@ -819,7 +967,7 @@ The `render` attribute can be set to `false` to prevent this behavior, and enfor
 
   : Pie charts
 
-    Likewise, if you installed the optional **piecharts.sile** collection, then code blocks marked as "piechart" are automatically rendered, with all other attributes are passed to the underlying processor.
+    Likewise, if you installed the optional *piecharts.sile* collection, then code blocks marked as "piechart" are automatically rendered, with all other attributes are passed to the underlying processor.
 
     Consider the following code block, consisting in a CSV table:
     ...
@@ -935,7 +1083,7 @@ Language changes within the text are supported, on either blocks or inline
 elements.
 It relies on the `lang` key-value attribute, where the value is a BC47 language code.
 It is not much visible below, obviously, but the language setting affects the hyphenation and other properties.
-In the case of French, for instance, you can see the special thin space before the exclamation point, or the internal spacing around quoted text:
+In the case of French, for instance, you can see the special thin space before the exclamation point, the use of appropriate quotation marks, and the internal spacing around quoted text:
 
 {lang=fr}
 > Cette citation est en français!
@@ -950,8 +1098,8 @@ This was obtained with:
 ::: {lang=fr}
 > Cette citation est en français!
 :::
-
-Or inline in text: [«Encore du français!»]{lang=fr}
+ 
+Or inline in text: ["Encore du français!"]{lang=fr}
 ```
 :::
 
@@ -967,10 +1115,10 @@ In some languages, they are used the other way round, but obviously the user's i
 ### Custom styles
 
 The converter also supports the `{custom-style="..."}` attribute.
-It is inspired by the syntax proposed by Pandoc for Markdown, in its **docx** writer, to specify a specific, possibly user-defined, custom style name (in that case, a Word style, obviously).
+It is inspired by the syntax proposed by Pandoc for Markdown, in its *docx* writer, to specify a specific, possibly user-defined, custom style name (in that case, a Word style, obviously).
 
 Here, if such a named style exists, it is applied. Erm. What does it mean?
-Well, in the default implementation, if used within in a **resilient** class and there is a corresponding style, the converter uses it.
+Well, in the default implementation, if used within in a *resilient* class and there is a corresponding style, the converter uses it.
 Otherwise, if there is a corresponding SILE command by that name, the converter invokes it.
 Otherwise, it just ignores the style and processes the content as-is.
 Even if you do not use a resilient-compatible class, it thus allows you to use some interesting SILE features.