docs(manual): Global review, nice illustrations etc.

Omikhleia · Jan 31, 2025 · ac4d1c3 · ac4d1c3
1 parent a73f4da
commit ac4d1c3
Show file tree

Hide file tree

Showing 11 changed files with 174 additions and 9 deletions.
diff --git a/examples/images/dore-perrault.jpg b/examples/images/dore-perrault.jpg
diff --git a/examples/images/layout-fuzzy.svg b/examples/images/layout-fuzzy.svg
diff --git a/examples/manual-classes/audience.dj b/examples/manual-classes/audience.dj
@@ -1,13 +1,12 @@
-{.unnumbered}
-# Audience
+{#resilient-classes-audience}
+# Target audience
 
 If you author your content in Djot or Markdown, most of the information you need to write your book is covered in the _Markdown and Djot to PDF with SILE_ user guide.
 There are just a few additional features specific to Djot, which are detailed below.
 
 On the other hand, if you are using the SIL language, you will need more in-depth information about the commands and constructs available in the _re·sil·ient_ classes.
 In most cases, this is the only scenario where the following chapters will be relevant to you.
 
-{.unnumbered}
 ## Add-ons for Djot authors
 
 ### Tables of Contents

diff --git a/examples/manual-layouts/layouts-general.dj b/examples/manual-layouts/layouts-general.dj
@@ -68,3 +68,11 @@ If you designed your own page templates with SILE’s low-level constructs, you
 
 [^layout-binding]: Some printing services even offer coil binding.
 Those coils are going to eat a whole lot of the inner margin!
+
+{.pagebreak .none}
+---
+
+{custom-style=center}
+:::
+![](images/layout-fuzzy.svg){width="80%"}
+:::
diff --git a/examples/manual-layouts/layouts-predefined.dj b/examples/manual-layouts/layouts-predefined.dj
@@ -121,6 +121,7 @@ It is provided here as `canonical`.
 
 ## Non-standard layouts
 
+{.notoc}
 ### A layout with wide margins
 
 Most of the common layouts presented above do not have both a dense text block and wide enough outer margins for annotations.
@@ -136,6 +137,7 @@ The formula is somewhat empirical, but this author finds it decently looking for
 
 As can be seen, the header frame also goes past the text block, englobing the margin area.
 
+{.notoc}
 ### A poor man’s centered layout
 
 In passing, the `none` layout uses margins of 1/6^th^ of the page dimensions.
@@ -148,6 +150,7 @@ It just exists because it’s the base component for other layouts.
 :::
 ^ This is not really a layout.
 
+{.notoc}
 ### An explicit page layout
 
 Some users may think they know better and want to define their own page layout.

diff --git a/examples/manual-masterdoc/bookdivisions.dj b/examples/manual-masterdoc/bookdivisions.dj
@@ -26,7 +26,7 @@ content:
 That is, your content is assumed to be part of the main matter by default.
 Some books, however, require a more complex structure, dividing content into front matter, main matter, and back matter.
 
-![Internal book divisions](images/book-divisions.svg){width="65%"}
+![Internal book divisions.](images/book-divisions.svg){width="65%"}
 
 In such books, the front matter might include a preface, dedication, and table of contents.
 The back matter is more variable, but for instance, it might include an index, bibliography, or glossary.

diff --git a/examples/manual-masterdoc/bookmatters.dj b/examples/manual-masterdoc/bookmatters.dj
@@ -41,7 +41,7 @@ The aim of the resilient master document is to provide a default set of conventi
 - At the end of the book, some _end-papers_ occur.
   On the recto one may find the title, the publisher, sometimes the ISBN is barcode form, and possibly other important mentions --- In some countries, the legal deposit is required to be printed there, etc. This page is also known as an _impressum,_ and its verso is (generally) left blank.
 
-![A resilient book structure](images/book-anatomy.svg){width="65%"}
+![A resilient book structure.](images/book-anatomy.svg){width="65%"}
 
 {#bookmatters:templates-customization}
 ## Customizing the title and endpaper pages
@@ -110,7 +110,7 @@ Yet, when going to print, you may need to have them removed.
 Once you have declared a back cover image, you will notice it automatically contains the ISBN of your book in an overlay at its bottom-right, if you defined it in your metadata.
 (If you didn't, this space is nevertheless reserved.)
 
-![Structure of the back cover](images/book-backcover.svg){width="65%"}
+![Structure of the back cover.](images/book-backcover.svg){width="65%"}
 
 The back cover can also contain additional content, such as a description of the book.
 Let's therefore go on with our possibilities.
@@ -169,7 +169,7 @@ book:
 In most cases, the text on the front cover of a book is part of the overall cover design, with its own typography and layout incorporated into the image.
 If this applies to you, no further steps are needed beyond the options previously discussed.
 
-![Structure of the front cover](images/book-frontcover.svg){width="65%"}
+![Structure of the front cover.](images/book-frontcover.svg){width="65%"}
 
 However, if you're in a situation where the cover design is not yet finalized or the image lacks text, you can use a templated overlay.
 The text will be automatically typeset in either white or black, based on the background color, to ensure optimal contrast.

diff --git a/examples/manual-masterdoc/masterdoc.dj b/examples/manual-masterdoc/masterdoc.dj
@@ -235,7 +235,7 @@ As far as the resilient collection is concerned, a few notable suggestions are l
 
 Last but not least, after the important but mundane sections, it is time to organize the actual content of your book.
 
-![From files to chapters and parts](images/book-parts-chapters.svg){width="65%"}
+![From files to chapters and parts.](images/book-parts-chapters.svg){width="65%"}
 
 For the sake of simplicity, let's consider you have a bunch of files in Djot or Markdown, each representing a chapter---that, is files all starting with a level 1 heading.
 We'll consider more complex structures later.

diff --git a/examples/manual-packages/audience.dj b/examples/manual-packages/audience.dj
@@ -0,0 +1,13 @@
+{#resilient-packages-audience}
+# Target audience
+
+This part goes even deeper into advanced topics than the previous one.
+The following chapters provide internal documentation for the packages included in the _re·sil·ient_ collection.
+
+Authors working in Djot or Markdown will rarely need this level of detail,  except when the _Markdown and Djot to PDF with SILE_ manual indicates that a construct passes its argument to the underlying implementation.
+In such cases, these chapters may be useful for understanding the capabilities of the underlying packages.
+
+For SIL users, however, this section offers valuable insights into the direct use of these packages.
+The SIL language is the focus here, with an assumption of deeper knowledge of SILE, meaning that casual readers may find this section less accessible than the rest of this manual.
+
+This is also of interest to developers exploring the internals of the _re·sil·ient_ components and seeking to extend or modify their functionality.
diff --git a/examples/manual-parts/part-appendices.dj b/examples/manual-parts/part-appendices.dj
@@ -0,0 +1,6 @@
+# Appendices
+
+![At the end of the book: the journey is yours.[^dore1873]](images/dore-perrault.jpg){ width="99%" }
+
+{mark="†"}
+[^dore1873]: Gustave Doré, _Contes de Perrault,_ 1862.
diff --git a/examples/sile-resilient-manual.silm b/examples/sile-resilient-manual.silm
@@ -95,10 +95,11 @@ content:
           - manual-classes/book.dj
       - file: manual-parts/part-packages.dj
         content:
+          - manual-packages/audience.dj
           - manual-packages/packages.dj
   backmatter:
     parts:
-      - caption: Appendices
+      - file: manual-parts/part-appendices.dj
         appendices:
           - manual-appendices/biblio.dj
           - manual-appendices/resume-class.dj