docs: Re-order all chapters in the manual

README.md

@@ -126,31 +126,31 @@ Needed fonts are Libertinus Serif, Symbola and Zallman Caps.
 
 This is but an overview. For more details, please refer to the provided example Markdown document, which also serves as documentation, showcase and reference guide.
 
-- Standard Markdown and Djot typesetting (italic, bold, code, etc.)
+- Standard Markdown and Djot typesetting (emphases, strong emphasis, code, etc.)
 - Smart typography (quotes, apostrophes, ellipsis, dashes, etc.) with Markdown extensions (prime marks)
-- Headers and header attributes
-- Horizontal dividers (a.k.a. horizontal rules, with provision for asterisms, dinkuses, pendants...)
-- Images (and image attributes, e.g. dimensions)
-- TeX-like math
-- Strikeout (a.k.a. deletions), etc.
-- Subscript and superscript
-- Footnotes (both regular and inline syntax support)
-- Fenced code blocks (with attributes)
-- Bracketed spans and fenced divs (with provisions for language change, custom styles, etc.)
-- Underlines
+- Hard line breaks and non-breaking spaces
+- Underline, strikethrough, highlight, deletion, insertion (with provisions for custom styling)
 - Small caps
+- Spans (with provisions for language change, custom styles, etc.)
+- Subscript and superscript
+- Images (and image attributes, e.g. dimensions)
 - Links (with special provisions for advanced cross-references)
+- Footnotes
+- TeX-like math
+- Headers and header attributes
+- Divs (with provisions for language change, custom styles, etc.)
 - Lists
   - Standard ordered lists and bulleted lists
   - Fancy lists
   - Task lists (GFM-like syntax)
   - Definition lists
-- Pipe tables (and table captions)
+- Horizontal dividers / thematic breaks (with provision for asterisms, dinkuses, pendants...)
+- Tables (and table captions)
+- Code blocks (with attributes)
 - Line blocks (with enhanced provision for poetry)
-- Hard line breaks
-- Raw attributes (escaping to inline SILE or Lua scripting)
+- Raw inlines and raw blocks (escaping to SILE, in SIL language or Lua scripting)
 - Raw inline HTML convenience subset in Markdown
-- Advanced use of symbols in Djot (variable substitution and templating)
+- Advanced use of symbols in Djot (variable substitution ,and templating)
 - Advanced configuration (e.g. Markdown variants, headings shifting, etc.)
 
 ## Use with the resilient collection

examples/extra-styles.dj

@@ -4,7 +4,7 @@
 %
 \define[command=customframe]{\center{\roughbox[bordercolor=#59b24c,
   fillcolor=220,padding=15pt, enlarge=true]{\parbox[width=90%lw, minimize=true]{\process}}}}
-\define[command=customblockframe]{\center{\framebox[bordercolor=#7393b3,
+\define[command=customblockframe]{\center{\framebox[bordercolor=#66a0b3,
   shadow=true,
   fillcolor=250,
   padding=4pt,
@@ -44,7 +44,16 @@ class:registerCommand("Ean13", function (_, content)
 end)
 
 class:registerCommand("Initial", function (_, content)
+  if type(content) ~= "table" then SU.error("Expected a table content in dropcap environment") end
+  if #content ~= 1 then SU.error("Expected a single letter in dropcap environment") end
   local letter = content[1]
-  SILE.call("dropcap", { lines = 3, family = "Zallman Caps", join = true }, { letter })
+
+  -- discardable style
+  local dropcapSty = class.styles and class.styles:resolveStyle("CustomDroppedInitial", true) or {}
+  local family = dropcapSty.font and dropcapSty.font.family or "Zallman Caps"
+  local lines = dropcapSty.special and dropcapSty.special.lines or 3
+  local color = dropcapSty.color
+
+  SILE.call("dropcap", { lines = lines, family = family, color = color, join = true }, { letter })
 end)
 ```

examples/introduction.dj

@@ -0,0 +1,188 @@
+# Introduction
+
+[T]{custom-style=Initial}[his]{.smallcaps} collection of modules for the [SILE](https://github.com/sile-typesetter/sile) typesetting system provides a complete redesign of its former native Markdown support.
+Most of the content you are reading right now is written in either Djot or Markdown, and processed using the converters offered by this collection:
+
+ - *markdown* inputter and package: native Markdown support,
+ - *djot* inputter and package: native Djot support,
+ - *pandocast* package: native support of Pandoc JSON AST files.
+
+For casual readers, this collection notably aims at easily converting Markdown or Djot documents to print-quality PDFs.
+
+With Djot and Markdown being made first-class citizens in SILE, you can now write your documents in these lightweight markup languages.
+There is actually more than one solution to achieve great results in that direction:
+
+ 1. Directly using the native converter packages,
+ 1. Using the Pandoc software to generate an output suitable for SILE.
+
+![Supported routes from input to output.](./markdown-sile-overview.dot){width="96%fw"}
+
+The Markdown converter offers a great set of Pandoc-like extensions, and the Djot converter provides additional features as well.
+Whether you favor Djot, a recent but serious contender to Markdown, or the more traditional Markdown, there is no need for you to delve into SILE's default language[^sile-default-language] or Lua programming.
+Yet, these options remain available under the hood for those seeking a blend of possibilities.
+
+[^sile-default-language]: That is, the SIL language, whether in its TeX-like syntax or XML flavor.
+
+
+## Installation
+
+### Standard installation
+
+This module collection requires SILE v0.14 or upper.
+
+Installation relies on the *luarocks* package manager.
+To install the latest version, you may use the provided “rockspec”:
+
+{custom-style=CodeBlock}
+:::
+```bash
+luarocks install markdown.sile
+```
+:::
+
+Refer to the SILE manual for more detailed 3rd-party package installation information.
+
+{#recommended-additional-packages}
+### Recommended additional packages
+
+The following package collections are not strictly required, but they are recommended for a better experience.
+When installed, they provide additional features:
+
+ - The [*couyards.sile*](https://github.com/Omikhleia/couyards.sile) collection provides additional support for fancy thematic breaks.
+ - The [*piecharts.sile*](https://github.com/Omikhleia/piecharts.sile) collection provides support for rendering pie charts from CSV data.
+
+To install them, use the following commands:
+
+{custom-style=CodeBlock}
+:::
+```bash
+luarocks install couyards.sile
+luarocks install piecharts.sile
+```
+:::
+
+Also recommended is the *resilient.sile* collection, which provides a set of classes and packages for a more advanced usage.
+It is described below in §[](#usage-with-the-resilient-collection).
+Note that it takes care of installing the above collections as well, so you don't have to install them separately if you go the "resilient" way.
+
+{#recommended-additional-software}
+### Recommended additional software
+
+This module also installs the [*embedders.sile*](https://github.com/Omikhleia/embedders.sile) collection, a general framework for embedding
+images from textual representations, performing their on-the-fly conversion via shell commands.
+
+These require additional software to be installed on your host system, to invoke the necessary conversion commands.
+Please refer to its documentation for more information.
+Typically, this manual illustrates the use of the Graphviz collection of tools to render graphs in the DOT language.
+
+As with anything that relies on invoking external programs on your host system, please be aware of potential security concerns.
+Be cautious with the source of the elements you include in your documents!
+
+
+## Usage
+
+### Usage from command line
+
+The following chapters describe the packages' features, and how to use them within existing documents (themselves in SIL, Djot or Markdown syntax).
+It's perfectly possible, though, to perform direct conversion from the command line.
+For instance, here is how it may be done for Markdown document...
+
+{custom-style=CodeBlock}
+:::
+```bash
+sile -u inputters.markdown somefile.md
+```
+:::
+
+... Or for a Djot document.
+
+{custom-style=CodeBlock}
+:::
+```bash
+sile -u inputters.djot somefile.dj
+```
+:::
+
+This method directly produces a PDF from the input file, using SILE's standard *book* class.[^intro-book-class]
+
+[^intro-book-class]: Actually, it uses a *markdown* class derived from the standard book class and loading the required modules.
+You don't really have to know that, unless you intend to invoke SILE with the `-c` option to specify another class of your choice; in that case you will need to load additional modules explicitly---unless it is a resilient class, of course.
+
+{#usage-with-the-resilient-collection}
+### Usage with the _re·sil·ient_ collection
+
+To unleash the full potential of this package collection, we recommend that you also install our [*resilient.sile*](https://github.com/Omikhleia/resilient.sile) collection of classes and packages.
+
+{custom-style=CodeBlock}
+:::
+```bash
+luarocks install resilient.sile
+```
+:::
+
+Then, you can automatically benefit from a few advanced features.
+Conversion from command line just requires to load a resilient document class, and optionally the poetry package.
+For instance:
+
+{custom-style=CodeBlock}
+:::
+```bash
+sile -c resilient.book -u inputters.markdown -u packages.resilient.poetry somefile.md
+```
+:::
+
+(And likewise for the Pandoc AST or Djot processing.)
+
+A "resilient style file" is also generated.
+It can be modified to change many styling decisions and adapt the output at convenience.
+
+### Advanced usage from existing documents
+
+While direct conversion from the command line may be adequate for very simple workflows, there are a number of things usually best addressed by using some kind of "wrapper" document.
+
+The resilient collection introduces a "master document" format, streamlining several usual tasks. Give it a chance, and you may even end up producing a book with SILE from front cover to back cover, without a single statement in SIL.
+
+This package collection provides several ways for including Markdown or Djot content in documents written in SIL syntax.
+Once you have loaded the *djot* or *markdown* package, the `\autodoc:command{\include[src=<file>]}`{=sile} command supports reading a Djot or Markdown file.
+Let's illustrate this for Djot, but the same applies to Markdown.
+
+{custom-style=CodeBlock}
+:::
+```
+\use[module=packages.djot]
+\include[src=somefile.dj]
+```
+:::
+
+Embedding raw Djot content from within a SIL document is also possible.
+Again, the same applies to Markdown.
+
+{custom-style=CodeBlock}
+:::
+```
+\begin[type=djot]{raw}
+Some *Djot* content
+\end{raw}
+```
+:::
+
+
+## Credits
+
+We owe a lot to John MacFarlane, for the *djot* and *lunamark* Lua libraries which empower this collection of packages.
+
+Additional thanks to:
+
+- Simon Cozens, _et al._ concerned, for the early attempts at using *lunamark* with SILE.
+- Vít Novotný, for the good work on lunamark, and the impressive [*witiko/markdown*](https://github.com/Witiko/markdown) package for (La)TeX---a great source of inspiration and a goal of excellence.
+- Caleb Maclennan, for his early work on a Pandoc-to-SILE converter which, though on different grounds, indirectly gave me the idea of the Pandoc AST alternative approach proposed here.
+
+{.dinkus}
+---
+
+{custom-style=FramedPara}
+:::
+Thank you for your attention, gentle reader.
+We wish you a very pleasant journey through the rest of this manual.
+Don't hesitate to provide feedback and help pushing this collection forward.
+:::