feat(classes): Add several predefined TOC-like symbols for Djot docs

classes/resilient/book.lua

@@ -61,7 +61,8 @@ function class:_init (options)
   self:loadPackage("markdown")
   self:loadPackage("djot")
   -- Once Djot is loaded, we can register custom pre-defined symbols
-  self.packages["markdown.commands"]:registerSymbol("_BIBLIOGRAPHY_", true, function (opts)
+  local mdc = self.packages["markdown.commands"]
+  mdc:registerSymbol("_BIBLIOGRAPHY_", true, function (opts)
     if not self.packages.bibtex then
       SU.warn("Bibliography support is not available")
       return {}
@@ -70,6 +71,32 @@ function class:_init (options)
       createCommand("printbibliography", opts)
     }
   end)
+  -- Our Djot/Markdown support already provides a _TOC_ symbol.
+  -- Here we can also provide _LISTOFFIGURES_, _LISTOFTABLES_, _LISTOFLISTINGS_.
+  -- And for the sake of consistency, we can also provide _TABLEOFCONTENTS_.
+  -- It is not exactly the same as _TOC_, which does additional things when used
+  -- outside resilient, with fallback to to SILE's default implementation, but it
+  -- is doesn't hurt to provide it here.
+  local extras = { "listoffigures", "listoftables", "listoflistings", "tableofcontents" }
+  for _, sym in ipairs(extras) do
+    mdc:registerSymbol("_" .. sym:upper() .. "_", true, function (opts)
+      return {
+        createCommand(sym, opts)
+      }
+    end)
+  end
+  -- Our Djot/Markdown support provides an undocumented _FANCYTOC_ symbol.
+  -- The reason why it is undocumented is that module fancytoc.sile is not a
+  -- dependency of markdown.sile.
+  -- On the other hand, resilient.sile has all needed dependencies.
+  -- So eventually we'll remove the _FANCYTOC_ symbol from markdown.sile.
+  -- No issue with re-registering it here, and we'll be ready for that.
+  mdc:registerSymbol("_FANCYTOC_", true, function (opts)
+    return {
+      createCommand("use", { module = "packages.fancytoc" }),
+      createCommand("fancytableofcontents", opts),
+    }
+  end)
 
   -- Override document.parindent default to this author's taste
   SILE.settings:set("document.parindent", "1.25em")

examples/manual-classes/audience.dj

@@ -0,0 +1,66 @@
+{.unnumbered}
+# 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
+
+The *resilient.book* class provides several predefined Djot symbols for use in your documents.
+Each of these symbols must stand alone in its own paragraph.
+Attributes on the symbol are passed through, e.g. `:_TOC_:{depth=3}`.
+
+{variant=Simple}
+: `:_TOC_:` or `:_TABLEOFCONTENTS_:`
+
+  Insert a table of contents.
+
+  Supported attributes:
+
+   - `depth` (default 3) controls the depth of the content added to the table.
+   - `start` (default 0) controls at which level the table starts.
+   - `linking` (default true) controls whether the table entries are active links to the relevant sections.
+
+  ![](./manicule.svg){height="0.60em"} See section [](#packages-tableofcontents) in part [](#resilient-packages) for advanced information.
+
+: `:_FANCYTOC_:`
+
+  Insert a table of contents with a fancy style.
+
+  Supported attributes:
+
+   - `start` (default 0) controls at which level the table starts.
+
+  ![](./manicule.svg){height="0.60em"} See section [](#packages-fancytoc) in part [](#resilient-packages) for advanced information.
+
+: `:_LISTOFFIGURES_:`
+
+  Insert a list of figures.
+
+: `:_LISTOFTABLES_:`
+
+  Insert a list of tables.
+
+: `:_LISTOFLISTINGS_:`
+
+  Insert a list of listings.
+
+Note that these symbols do not automatically generate a heading or title.
+If a title is needed, you must add it manually using the appropriate heading level or styled element.
+
+### Bibliographies
+
+The *resilient.book* class also provides a predefined Djot symbol for inserting bibliographies (references).
+
+{variant=Simple}
+: `:_BIBLIOGRAPHY_:`
+
+  Insert a bibliography.
+
+  ![](./manicule.svg){height="0.60em"} See chapter [](#using-bibliographies) in part [](#master-document) for more information.

examples/manual-classes/classes.dj → examples/manual-classes/book.dj

@@ -1,4 +1,4 @@
-# The resilient book class
+# Deep dive into the resilient book class
 
 The design of the `resilient.book` class was started as an attempt at gradually tuning the default book class from SILE to this author’s needs and taste.
 It eventually evolved into a full redesign on different grounds.
@@ -8,23 +8,24 @@ This very document uses it, so you can see it in real action.
 
 In addition to the class options provided by SILE, the class also supports the following options:
 
-: layout
+{variant=Simple}
+: `layout`
 
   Specifies the default (global) page layout. See part [](#page-layout).
 
-: offset
+: `offset`
 
   Specifies the binding offset. See part [](#page-layout).
 
-: headers
+: `headers`
 
   Specifies how running headers are used:
 
   - `none`: No running headers.
   - `technical` (default): Chapter and section titles go in the even and odd running headers, respectively.
   - `novel`: Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers.[^book-title]
 
-: resolution
+: `resolution`
 
   Specifies the global resolution in DPI (dots per inch).
   Some add-on packages may use it in order to compute the size of generated images, etc.
@@ -35,7 +36,7 @@ In addition to the class options provided by SILE, the class also supports the f
 
 ## Standard sectioning commands
 
-The class supports the following sectioning commands, from the highest division level to the lowest: `\autodoc:command{\part}`, `\autodoc:command{\chapter}`, `\autodoc:command{\section}`, `\autodoc:command{\subsection}`, `\autodoc:command{\subsubsection}`.
+The class supports the following standard sectioning commands, from the highest division level to the lowest: `\autodoc:command{\part}`{=sile}, `\autodoc:command{\chapter}`{=sile}, `\autodoc:command{\section}`{=sile}, `\autodoc:command{\subsection}`{=sile}, `\autodoc:command{\subsubsection}`{=sile}.
 
 All sectioning commands obey styles (relying on the **resilient.styles** and **resilient.sectioning** packages), which notably imply that they have a lot of customization possibilities.
 In the following pages, the described behaviors apply to the default configuration and styling, out-of-the-box.

examples/manual-intro/howto.dj

@@ -13,7 +13,7 @@ That's a very good start! Let us guide you through the process.
 
 Wait, you have not installed the SILE software or the _re·sil·ient_ modules yet?
 
-![](./manicule.svg){height="0.60em"} See chapter [](#installation) and come back here.
+![](./manicule.svg){height="0.60em"} See chapter [](#installation) and come back here when you are ready.
 
 ## Picking a mark-up language
 
@@ -57,14 +57,14 @@ You may want now to customize the document styles according to your needs.
 
 ## Going further
 
-In composing your book, you may need more lowe-level details regarding some of the cool components provided by the _re·sil·ient_ collection.
-These sections are not for the faint of heart, but they are there for you when you need them.
+In composing your book, you may need more details about the available document classes and their capabilities.
 
-![](./manicule.svg){height="0.60em"} Read part [](#resilient-packages){.section}.
+![](./manicule.svg){height="0.60em"} Read part [](#resilient-classes){.section}.
 
-Likewise, you may need more details about the available document classes and their capabilities.
+Likewise, you may need more low-level details regarding some of the cool components provided by the _re·sil·ient_ collection.
+These sections are not for the faint of heart, but they are there for you when you need them.
 
-![](./manicule.svg){height="0.60em"} Read part [](#resilient-classes){.section}.
+![](./manicule.svg){height="0.60em"} Read part [](#resilient-packages){.section}.
 
 {.pendant}
 ---

examples/manual-masterdoc/bibliographies.dj

@@ -1,3 +1,4 @@
+{#using-bibliographies}
 # Using bibliographies
 
 For scholarly works, you may want to include bibliographic references in your book.

examples/manual-packages/packages.dj

@@ -132,12 +132,14 @@ This package is part of the *labelrefs.sile* collection.
 \package-documentation{labelrefs}
 ```
 
+{#packages-tableofcontents}
 ## Enhanced table of contents
 
 ``` =sile
 \package-documentation{resilient.tableofcontents}
 ```
 
+{#packages-fancytoc}
 ## Fancy alternative table of contents
 
 {custom-style=admon}

examples/sile-resilient-manual.silm

@@ -89,12 +89,13 @@ content:
           - manual-styling/advanced/other.dj
           # Not written yet...
           # - manual-styling/advanced/captioned.dj
+      - file: manual-parts/part-classes.dj
+        content:
+          - manual-classes/audience.dj
+          - manual-classes/book.dj
       - file: manual-parts/part-packages.dj
         content:
           - manual-packages/packages.dj
-      - file: manual-parts/part-classes.dj
-        content:
-          - manual-classes/classes.dj
   backmatter:
     parts:
       - caption: Appendices