fixup! docs: WIP: Djot manual overhaul

examples/sile-and-djot.dj

@@ -404,6 +404,7 @@ Surrounding a word with `:` signs creates a “symbol.”
 The Djot specification leaves the interpretation of such symbols to the rendering engine.
 This converter uses them in specific ways, as detailed in §[](#djot-advanced-topics).
 
+{#djot-raw-inlines}
 ### Raw inlines
 
 Raw inline content in any format may be included using a verbatim span followed by `{=format}`.
@@ -495,13 +496,109 @@ Inline language changes are supported (see §[](#djot-language-changes)), as wel
 
 ## Block elements
 
-### Paragraph
+### Paragraphs
 
-### Heading
+A paragraph is a sequence of non-blank lines that does not meet the condition for being one of the other block-level elements.
 
+A paragraph ends with a blank line or the end of the document.
+The textual content is parsed as a sequence of inline elements.
+A single newline is treated as a space.
+
+### Headings
+
+A heading starts with a sequence of one or more `#` characters, followed by whitespace.
+
+The number of # characters defines the heading level.
+The heading text following that sequence is parsed as inline content.
+
+For example, this very section is a level three heading.
+It was therefore obtained with:
+
+{custom-style=CodeBlock}
+:::
+```
+### Headings
+```
+:::
+
+The heading text may spill over onto following lines, which may also be preceded by the same number of `#` characters (but these can also be left off).
+
+The heading ends when a blank line (or the end of the document or enclosing container) is encountered.
+
+This converter accepts the following pseudo-classes on heading attributes:
+
+ - `.unnumbered` suppresses numbering of the heading.
+ - `.notoc` suppresses the heading from appearing in the table of contents.
+
+The heading attributes, obviously, also accept an identifier, for referencing purposes.
+Here is an example illustrating the use of these attributes:
+
+{custom-style=CodeBlock}
+:::
+```
+{#djot-unnumbered-heading .unnumbered .notoc}
+### Unnumbered heading
+```
+:::
+
+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.
 
 ### Block quote
 
+A block quote is a sequence of lines, each of which begins with `>`, followed either by a space or by the end of the line.
+The contents of the block quote are parsed as block-level content.
+
+#### Regular quotes
+
+{custom-style=CodeBlock}
+:::
+```
+> This is block quote.
+>
+> > They can be nested.
+```
+:::
+
+> This is block quote.
+>
+> > They 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.
+
+#### Attributed quotes (epigraphs)
+
+{ rule="0.4pt" }
+> The Library is a sphere whose exact centre is any one of its
+> hexagons and whose circumference is inaccessible.
+^ 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).
+The caption is introduced with a `^` character, and can contain inline elements.
+For instance, the above quote was obtained with:
+
+{custom-style=CodeBlock}
+:::
+```
+{ rule="0.4pt" }
+> The Library is a sphere whose exact centre is any one of its
+> hexagons and whose circumference is inaccessible.
+^ Jorge Luis [Borges]{.smallcaps}, "The Library of Babel"
+```
+:::
+
+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.
+
+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
@@ -546,13 +643,7 @@ Djot attributes are passed to the underlying definition environment.[^djot-resil
 
 [^djot-resilient-defn]: With the *resilient.defn* environment, the `variant` option may thus be used to switch to an alternate style.
 
-### Block quotes
 
-Block quotes work.
-
-> This is block quote.
->
-> > They can be nested.
 
 {#djot-footnotes}
 ### Footnotes
@@ -761,6 +852,7 @@ The `render` attribute can be set to `false` to prevent this behavior, and enfor
     :::
     ^ An example of a rendered pie chart.
 
+{#djot-raw-blocks}
 ### Raw blocks
 
 ```=sile
@@ -841,22 +933,67 @@ pseudo-class.
 
 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:
 
 {lang=fr}
 > Cette citation est en français!
 
 Or inline in text: ["Encore du français!"]{lang=fr}
 
+This was obtained with:
+
+{custom-style=CodeBlock}
+:::
+```
+::: {lang=fr}
+> Cette citation est en français!
+:::
+
+Or inline in text: [«Encore du français!»]{lang=fr}
+```
+:::
+
 As can be seen, the current language is taken into account when converting
-straight double and single quotation marks to the appropriate typographic variant.
+paired straight double and single quotation marks to the appropriate typographic variant:
+["English"]{lang=en} / ["Deutsch"]{lang=de} / ["français"]{lang=fr} / ["dansk"]{lang=da} / ["русский"]{lang=ru};
+['English']{lang=en} / ['Deutsch']{lang=de} / ['français']{lang=fr} / ['dansk']{lang=da} / ['русский']{lang=ru}.[^djot-smart-quotes]
+
+[^djot-smart-quotes]: For most languages, `"` and `'` correspond to the primary and secondary quotations marks, respectively.
+In some languages, they are used the other way round, but obviously the user's input is respected in those cases (e.g. respectively ["Ghàidhlig"]{lang=cy} and ['Ghàidhlig']{lang=cy}).
 
 {#djot-custom-styles}
 ### 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).
+
+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.
+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.
+For instance, here is some block of text marked as "center", with some inline text marked as "strong".
+
+{#djot-centered custom-style="center"}
+This is SILE and Djot at their best{custom-style="strong"}!
 
+This was obtained with:
+
+{custom-style="CodeBlock"}
+:::
+```
 {#djot-centered custom-style="center"}
-This is SILE and Djot at their best{custom-style="strong"}, really!
+This is SILE and Djot at their best{custom-style="strong"}!
+```
+:::
+
+That's a fairly contrived way to obtain a bold text, but you get the underlying general idea.
+This is one of the ways to use SILE commands in Djot.
+While you could invoke _any_ SILE command with this feature, we recommend, though, to restrict it to styling.
+Another more powerful way to leverage Djot with SILE’s full processing capabilities, and benefit from the best of both worlds, is to use the annotations 
+described in §[](#djot-raw-inlines) and §[](#djot-raw-blocks).
 
 ### Templates and variable substitution
 
@@ -921,29 +1058,6 @@ Again, the variable substitution mechanism also has precedence over these symbol
 
 ## Syntax extensions
 
-### Attributed quotes (epigraphs)
-
-{ rule="0.4pt" }
-> The Library is a sphere whose exact centre is any one of its
-> hexagons and whose circumference is inaccessible.
-^ 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).
-For instance, the above quote was obtained with:
-
-```
-{ rule="0.4pt" }
-> The Library is a sphere whose exact centre is any one of its
-> hexagons and whose circumference is inaccessible.
-^ Jorge Luis [Borges]{.smallcaps}, "The Library of Babel"
-```
-
-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 `\autodoc:package{resilient.epigraph}`{=sile} package may thus be used.
-
-Be aware that this behavior is currently an extension.
-Other Djot converters will therefore likely skip the caption.
 
 {#djot-conditional-attributes}
 ### Conditionals