docs: Add general considerations on markup languages

Opinionated, for sure. Wrong? It's up to you.

examples/introduction.dj

@@ -170,8 +170,7 @@ Some *Djot* content
 ## Credits
 
 We owe a lot to John MacFarlane, for the *djot* and *lunamark* Lua libraries which empower this collection of packages.
-
-Additional thanks to:
+Additional thanks go 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.

examples/lightweight-markup.dj

@@ -0,0 +1,80 @@
+# General considerations
+
+[O]{custom-style=Initial}[ne]{.smallcaps} of the primary motivations behind the development of the components provided in this module was the ability to typeset an entire book "from front cover to back cover," using text files written in a lightweight markup language.
+
+My response to this challenge was the _re·sil·ient_ collection of classes and packages for SILE.
+It includes master documents, book matters, a robust book class, and a neat styling paradigm.
+As mentioned in the introduction, this module doesn't enforce the use of the resilient collection, but it does strongly recommend it for maximizing the package collection's benefits.
+You do not have to believe me on faith, and you can judge for yourself.
+After all, you are currently reading a user guide based on it, with styled headings, colorful dropped capitals, and more...
+
+Resilient meets most of my own requirements, and I hope to improve it further.
+However, there was still one issue that needed to be addressed: the input format.
+
+## On markup languages
+
+While I once enjoyed using LaTeX, I found it impractical due to its complex and non-user-friendly syntax, as well as difficulties in converting to other formats.
+Though Patoline and Pollen appeared promising, their lack of widespread support posed limitations.
+Lout, once hailed as a potential LaTeX replacement, is now defunct.
+I am going full opinionated here: 
+SILE does not fare much better with its SIL custom language, burdened by its own spacing idiosyncrasies.
+HTML with CSS is too technical for most authors, and the WYSIWYG office suites are not appropriate for large projects.
+
+Anyhow, these languages are not "lightweight markup languages," as close to plain text as possible...
+Forget FOP and XML-FO, insane XSLT transformations, DocBook and the like, for the same reasons.
+
+In recent exploration, Typst caught my attention.
+However, in my views, its custom syntax fails to significantly improve upon existing options, blurring the distinction between content and style and lacking a clear separation of concerns.
+Regarding styling, Typst does not revolutionize the field, and does not seem to tackle the challenge.
+I am not saying that mixing scripting, layout decisions, styling, and content is _inherently_ bad.
+I am doing it casually in this document (via raw inline and raw block elements), and it's fine for advanced tasks.
+But for most content, it's not the best approach...
+
+What if I could get rid of SIL, and any similar custom language, and use a lightweight markup language instead?
+Hold on, SILE is actually agnostic to the input format.
+Since every bit of its Lua code is exposed to the user, it's possible to extend it to support other input formats, potentially leading to wider community adoption, and independent tooling.
+Enter Markdown. 
+Actually, enter a serious contender, Djot.
+
+## On Djot over Markdown
+
+Should you pick Djot over Markdown, as hinted by this author in the following chapters?
+Several reasons are purely technical and relate to how the languages are implemented within this module.
+
+: Easier debugging
+
+  The implementation of Djot excels in tracking line numbers and positions, or at least in providing some context when encountering a syntax issue in the input document.
+  Conversely, the Markdown implementation lacks this functionality, making debugging and generating meaningful error messages more challenging.
+  Troubleshooting a minor markup mistake in a lengthy Markdown document can be arduous.
+
+: Better performances
+
+  The Djot syntax demonstrates less ambiguity compared to Markdown, contributing to a more efficient implementation of the language grammar.
+  Markdown, while benefiting from a PEG-based implementation in order to accommodate numerous extensions and syntax subleties, suffers from decreased efficiency.
+  Parsing a comparable document in Djot significantly outperforms Markdown in processing speed.
+
+{.dinkus}
+---
+
+Beyond technical considerations, it's also worth examining the functionality of each language and assessing their ease of use.
+
+: Readability 
+
+  Markdown can be intricate, with subtle nuances where even a single space can trigger unexpected effects.
+  It exhibits non-intuitive behaviors, such as the use of indentation to denote code blocks.
+  There are inconsistent outcomes with lists, emphases, headings...
+  See John MacFarlane's ["Beyond Markdown"](https://johnmacfarlane.net/beyond-markdown.html) essay for some more examples, and the reasons that led him propose Djot.
+
+: Extensibility
+
+  Djot offers greater flexibility and power by supporting attributes on both block and inline elements. These attributes can be leveraged by the converter to produce content with enhanced richness and styling options.
+  Djot's extensibility is also facilitated through the use of symbols.
+  In the upcoming chapter, we will delve into various methods employed by this module to expand Djot's capabilities even further. These include generalized captions, templates, variable substitutions, conditional statements, and more --- all while maintaining fidelity to the original concepts.
+
+: Compatibility
+
+  Markdown enjoys widespread adoption, with native support from numerous tools and platforms.
+  This could be your main reason to stick with Markdown, especially if you already have a large collection of documents written in this format.
+  However, its utility is somewhat diminished by the proliferation of dialects and extensions developed over the years.
+  The Pandoc software adeptly handles a vast array of these variations, making it an excellent tool for converting between different flavors of Markdown.
+  Nevertheless, since version 3.1.12, Pandoc has extended its support to Djot, rendering the distinction between Markdown and Djot less significant.

examples/sile-and-markdown-manual.silm

@@ -12,7 +12,7 @@ metadata:
   publisher: Omikhleia
   pubdate: 2024-03-01
   url: https://github.com/Omikhleia/markdown.sile
-  copyright: © 2021–2024, Didier Willis.
+  copyright: © 2022–2024, Didier Willis.
   legal: |
     This material may be distributed only subject to the terms and conditions
     set forth in the  Creative Commons Attribution, Share-Alike License,
@@ -50,6 +50,7 @@ chapters:
   - toc.dj
   - extra-styles.dj
   - introduction.dj
+  - lightweight-markup.dj
   - sile-and-djot.dj
   - sile-and-markdown.md
   - sile-and-pandoc.dj