feat: Add resilient master file document basic support (1.0)

README.md

@@ -16,6 +16,7 @@ This collection offers:
   - Highly configurable table of contents, headers, footers, footnotes and sectioning environments,
   - And other useful features, from cross-references to advanced captioned figure and table environments, and more…
   - A great parity with Markdown, including many Pandoc-like extensions.
+- A “master document” format, for easily assembling your content.
 - A lightweight “résumé” class, for you to produce a colorful and yet professional-looking _curriculum vitæ_.
 
 ## Installation

examples/manual-front.sil

@@ -0,0 +1,77 @@
+\begin{document}
+\footnote:rule
+\define[command=admon]{%
+\smallskip%
+\set[parameter=document.parindent, value=0]{%
+\roughbox[enlarge=true, singlestroke=true, preserve=true,
+padding=2%fw, bordercolor=#59b24c, fillcolor=230, shadowcolor=#96A8C7, shadow=false]{%
+\parbox[width=96%lw]{\set[parameter=document.parindent, value=0]\font[size=9pt]\color[color=100]{\process}\par}%
+}}%
+\medskip}
+%
+% We do not have a true titlepage for now, build it manually.
+\background[color=#66a0b3,allpages=false]
+\noheaderthispage
+\nofoliothispage
+\hbox{}\skip[height=30%fh]
+
+\begin{center}
+\font[size=20pt]{The
+
+\medskip
+\font[size=35pt, style=italic]{\kern[width=-0.1em]re·sil·ient}
+
+collection
+
+of
+
+classes & packages
+
+\smallskip
+for SILE
+
+}
+\end{center}
+
+\vfill
+
+\break
+
+% Now a legal matter page
+\begin{center}
+\font[features=+smcp]{The resilient collection of classes & packages for SILE}
+
+\raise[height=0.5ex]{\hrule[height=0.4pt, width=5em]}
+
+\medskip
+\href[src=https://github.com/Omikhleia/resilient.sile]{\qrcode[code=https://github.com/Omikhleia/resilient.sile]}
+\end{center}
+
+\vfill
+
+\noindent{}© 2021–2023 Didier Willis.
+
+\noindent{}This material may be distributed only subject to the terms and conditions set forth in the
+Creative Commons Attribution, Share-Alike License,
+version 2.0 (http://creativecommons.org/licenses/by-sa/2.0/).
+
+\hbox{}\par\break%
+%
+\noheaderthispage%
+\nofoliothispage%
+%
+% There we go for the content.
+%
+\chapter[numbering=false, toc=false]{Contents}
+\noheaders
+
+\tableofcontents
+
+\section[numbering=false, toc=false]{Figures}
+
+\listoffigures
+
+\section[numbering=false, toc=false]{Tables}
+
+\listoftables
+\end{document}

examples/manual-intro/howto.dj

@@ -2,10 +2,10 @@
 {.none .pagebreak}
 ---
 
-![The resilient ecosystem at a glance (simplified).](./examples/resilient-ecosystem.dot){width="85%fw"}
+![The resilient ecosystem at a glance (simplified).](./examples/resilient-ecosystem.dot){width="99%fw"}
 
 {.unnumbered}
-# How to read this manual
+# How to use this manual
 
 ```=sile
 \begin[rule=0.4pt]{epigraph}
@@ -21,32 +21,59 @@ dreams---and towards that aim, you consider using the present collection
 of classes and packages.
 That's a very good start! Let us guide you through the process.
 
+{.unnumbered}
+## Picking a mark-up language
+
 Obviously, you first need to pick a mark-up language for your content.
-If you are reading this document, you probably already browsed through the SILE Manual
-and consider using its SIL language.
+If you are reading this document, you probably already browsed through the SILE Manual and consider using its SIL language.
 
-You might do so, indeed---but please note
-that Markdown and Djot are acceptable options too.
-If you properly installed the resilient collection, then the 
-*[markdown.sile](https://github.com/Omikhleia/markdown.sile)* collection is installed too.
+You might do so, indeed---but please note that Markdown and Djot are acceptable options too.
+If you properly installed the resilient collection, then the *[markdown.sile](https://github.com/Omikhleia/markdown.sile)* module is installed too.
 When used with this collection, it's leveraged with additional capabilities.
 
-Let's consider you have some input content ready, now. You have chosen a paper size for
-your book, and are going to use one of our classes, say the *resilient.book* class.
+On the other hand, if you are not already experienced with the SIL language and your content is reasonably simple, this author would recommend to seriously consider Markdown or Djot (with even a preference for Djot when possible).
+Not only are they simpler and lightweight, but they are also more portable, with great tools such as Pandoc to convert them to other formats, so you won't be stuck with a custom mark-up.
+
+![](./temp/manicule.svg){height="0.60em"} Check the _Markdown and Djot to PDF with SILE_ user guide.
+
+{.unnumbered}
+## Assembling your content
+
+Now, let's consider you have some input content ready, as an assortment of files, possibly in different mark-up languages:
+For any long work, indeed, you likely split your content into chapters or any other appropriate division scheme; and you may have used Markdown, Djot or even SIL depending on the effects to achieve.
+
+You now need assemble all these files in some wrapper document, to pick a paper size, a page layout and to set some global parameters (such as, minimally, the default font and language).
+You can do that with the SIL language in a variety of ways, having at hands all the required low-level constructs.
+It is perfectly legit, so follow that path if it has your preference.
 
-![](./temp/manicule.svg){height="0.65em"} _Read part [](#resilient-classes){.section}._
+Yet, the task could be made more straightforward, right?
+Truly, the resilient "master document format" aims at simplifying and streamlining that process.
 
+![](./temp/manicule.svg){height="0.60em"} Read part [](#master-document){.section}.
+
+{.unnumbered}
+## Styling your book
+
+You have chosen a paper size for your book, and are using one of our classes, say the *resilient.book* class.
 It's time then to select a page layout.
 
-![](./temp/manicule.svg){height="0.64em"} _Read part [](#page-layout){.section}._
+![](./temp/manicule.svg){height="0.60em"} Read part [](#page-layout){.section}.
+
+You are nearly done.
+You may want now to customize the document styles according your needs.
+
+![](./temp/manicule.svg){height="0.60em"} Read part [](#styling-paradigm){.section}.
+
+{.unnumbered}
+## Going further
 
 In composing your book, you may need some of the cool packages provided here.
 
-![](./temp/manicule.svg){height="0.65em"} _Read part [](#resilient-packages){.section}._
+![](./temp/manicule.svg){height="0.65em"} Read part [](#resilient-packages){.section}.
 
-You are nearly done. You may want now to customize the document styles according your needs.
+Likewise, you may need more details about the available document classes and their capabilities.
 
-![](./temp/manicule.svg){height="0.65em"} _Read part [](#styling-paradigm){.section}._
+![](./temp/manicule.svg){height="0.65em"} Read part [](#resilient-classes){.section}.
 
 {.pendant}
 ---

examples/manual-masterdoc/masterdoc-workflow.dot

@@ -0,0 +1,34 @@
+digraph G {
+  rankdir="LR"
+  edge[arrowhead="vee"];
+
+  subgraph cluster_ms {
+    doc0 [shape=note, label="master.silm"];
+    style=filled;
+    color="#e0e0f0";
+
+    subgraph cluster_in {
+      doc1 [shape=note, label="chapter1.dj"];
+      doc2 [shape=note, label="chapter2.sil"];
+      doc3 [shape=note, label="chapter3.md"];
+      style=filled;
+      color="#e0e0d0";
+    }
+  }
+
+  subgraph cluster_out {
+   pdf [shape=note, label="PDF"];
+   style=filled;
+   color="#e0f0e0";
+   label="output";
+  }
+
+  resilient [shape=doublecircle, color="#e8ccd7 ", style=filled, label="master\ndocument\ninputter"];
+
+  doc0 -> resilient
+  doc0 -> doc1
+  doc0 -> doc2
+  doc0 -> doc3
+
+  resilient -> pdf
+}

examples/manual-masterdoc/masterdoc.dj

@@ -0,0 +1,163 @@
+# Writing a master document
+
+Say you have a collection of individual chapters (or any other appropriate division scheme) in Djot, Markdown or even SIL, and you want to gather these as a single book, with all bells and whistles.
+
+Seasoned users experienced with the SIL language surely know how to write a "wrapper" document in that format, invoking all required commands and including their content files.
+All the low-level constructs are there for them to do so.
+There are some things, however, that they will end up doing all the time, repetitively: at the very least, pick up a font, set a main language, load fairly standard packages, set PDF metadata...
+Moreover, if your content, or most of it, was authored in Djot or Markdown[^md-metadata-blocks], it feels quite cumbersome to have to write such a wrapper in SIL syntax, doesn't it ?
+
+[^md-metadata-blocks]: Several Markdown processors support metadata blocks as a special construct in (extended) Markdown, with a varying syntax and often _ad hoc_ conventions.
+We are trying, here, to be more general and consistent, regardless of the input format.
+
+The resilient collection introduces a "master document" format which aims at simplifying and streamlining the process, abstracting the wearisome tasks and taking care of (most of) the usual needs.
+
+![Using a resilient master document.](manual-masterdoc/masterdoc-workflow.dot){width=7cm}
+
+Master documents usually have the `.silm` extension and can be processed as shown below.
+
+```shell
+sile -u inputters.silm mybook.silm
+```
+
+The format consists in a simple description of the book properties and content, expressed in [YAML](https://en.wikipedia.org/wiki/YAML), a lightweight human-readable data-representation language.
+Here is an example, showing most of the elements.
+
+```yaml
+masterfile: 1.0
+metadata:
+  title: Excerpts from the Chronicles of Alstre
+  subtitle: Annotated tales from the works of the poet Celdre 
+  subject: Translation and commentary
+  keywords:
+    - Mythology
+    - Fantasy
+    - Feigned history
+  authors: Emma Lenski
+  translators: Sylvain Forestier
+  publisher: Omikhleia
+  pubdate: 2023-07-14
+  isbn: 978-1-4028-9462-6
+  url: https://github.com/Omikhleia/resilient.sile
+  copyright: © 2023, Omikhleia.
+  legal: Tous droits réservés.
+font:
+  family: [EB Garamond, Libertinus Serif]
+  size: 12pt
+language: fr
+sile:
+  options:
+    # class: resilient.book # (this is the default choice if not set)
+    papersize: 6in x 9in
+    layout: ateliers demiluxe
+    resolution: 300
+  settings:
+    textsubsuper.fake: false
+    typesetter.italicCorrection: true
+  packages:
+    - dropcaps
+    - couyards
+chapters:
+  - frontmatter.dj
+  - chap1.dj
+  - chap2.dj
+  - backmatter.dj
+```
+
+The `masterfile` entry is a number corresponding to a version, for compatibility purposes.[^masterdoc-compat]
+
+[^masterdoc-compat]: Currently unused, but it may become useful if we introduce breaking changes in the master document format later.
+
+## The metadata section
+
+The `metadata` object contains several general document properties.
+
+ - The `title`, `authors`, `subject` and `keywords` will automatically be used as PDF metadata.
+
+ - As denoted by the plural, `authors`, `translators` and `keywords` may consist in a list of strings, but they also accept a single string.
+
+ - The `title` may be used in running headers (possibly, depending on the document class).
+
+All properties are passed as metadata made available to the content files.
+In the current implementation, this is only effective with Djot documents, wherein the medatada are exposed as Djot symbols (e.g. `:title:`, `:authors:`, and so on).
+For convenience, for authors and translators, the symbols `:author:` and `:translator:`{.nobreak} are also exposed, and contain the first entry.
+
+## The font section
+
+The `font` object defines the _default_ font, as a font `family` and a `size`.
+
+ - The `family` is either a font name (as a string) or an array of font names.
+   In the latter case, the first font is used as default font and the others are declared as "font fallbacks", would some characters be unavailable.
+ - The `size`, as expected, is the default font size, usually expressed in points.
+
+## The SILE configuratin section
+
+The `sile` object provides intructions for processing the master document with SILE.
+
+ - The `options` are to be understood as document class options.
+  (As such, they can notably be overridden from the command line when invoking SILE.)
+  If you don't specify a `class` then *resilient.book* is assumed.
+
+- The `settings` can be used to globally set some SILE parameters.
+
+- The `packages` object lists extra packages that SILE must use.
+  It can be used to load add-on packages needed by your content but not already provided by the document class and its supporting packages.
+
+## Up to the content
+
+Last but not least, the `chapters` array (or `parts`, see further below) lists the files to include in the work.
+In its simplest form, it consists in an ordered list of file names.
+These files may be of any type supported by SILE, the document class or loaded packages.[^masterdoc-nesting]
+
+```yaml
+chapters:
+  - chap1.md
+  - chap2.dj
+```
+
+This is actually a convenience short form for the fuller syntax.
+
+```yaml
+chapters:
+  - file: chap1.md
+  - file: chap2.dj
+```
+
+In this structured form, other fields are accepted, for enforcing the input format (which can be useful if the extension is non-standard) and the options passed to the input handler.
+
+```yaml
+chapters:
+  - file: chap1.txt
+    format: markdown
+    options:
+      smart: false # disable smart typography support in Markdown
+```
+
+There is another structured form which just takes a "caption" string.
+To be honest, it's mostly provided as a quick convenience placeholder.
+
+```yaml
+chapters:
+  - caption: My adventures
+```
+
+It's the perfect time now to introduce you with content nesting and header shifting.
+All structured forms accept a `content` entry, which is again a list of files to include, with the exact same rules.
+With Djot, Markdown on other formats supporting this feature,[^masterdoc-sil-nesting] the headings in these files are then _shifted_.
+
+```yaml
+chapters:
+  - file: chap1.dj # Level 1 headings = chapters, etc.
+    content:
+      - file: sect.dj # Level 1 headings = sections, etc.
+```
+
+We earlier mentioned the `parts` keywords.
+With document classes supporting parts, such as **resilient.book**, it allows using them, starting at that level.[^masterdoc-astute]
+
+[^masterdoc-nesting]: In particular, you may include a master document in another.
+In that case, though, only the declared extra packages and the content files are used.
+
+[^masterdoc-sil-nesting]: Not available for SIL documents.
+
+[^masterdoc-astute]: Astute readers will realize that the `chapters` structure is just a convenience facility.

examples/manual-parts/part-classes.dj

@@ -0,0 +1,8 @@
+{#resilient-classes}
+# Resilient classes
+
+![Composition work in the 19^th^ century.[^sulek1883]](images/composer_1883.png){ width="70%pw" }
+
+{mark="†"}
+[^sulek1883]: Bogoslav Šulek, Mijo Kišpatić _et al.,_
+_Novovjeki izumi u znanosti, obrtu i umjetnosti,_ vol\ 2, _Matica Hrvatska_, Zagreb, 1883, p.\ 157.

examples/manual-parts/part-intro.dj

@@ -0,0 +1,6 @@
+# Introduction to re·sil·ient
+
+![Printers in 1568.[^meggs1998]](images/printer_1568.png){ width="50%pw" }
+
+{mark="†"}
+[^meggs1998]: Meggs, Philip B., _A History of Graphic Design,_ John Wiley & Sons, Inc. 1998, p.\ 64.

examples/manual-parts/part-layouts.dj

@@ -0,0 +1,7 @@
+{#page-layout}
+# The page layout
+
+![Elegant proportions.[^duerer1525]](images/duerer_messung_1525.png){ width="45%pw" }
+
+{mark="†"}
+[^duerer1525]: Albrecht Dürer, [_Underweysung der Messung mit dem Zirckel und Richtscheyt,_]{lang=de} 1525.