feat: Add class option for controlling what goes in running headers

classes/resilient/book.lua

@@ -13,6 +13,13 @@ local createCommand, subContent, extractFromTree
 
 local layoutParser = require("resilient.layoutparser")
 
+SILE.scratch.book = SILE.scratch.book or {}
+SILE.scratch.book.headers = {
+  novel = true,
+  technical = true,
+  none = true
+}
+
 -- CLASS DEFINITION
 
 function class:_init (options)
@@ -103,16 +110,28 @@ function class:declareOptions ()
     end
     return self.offset
   end)
+
+  self:declareOption("headers", function(_, value)
+    if value then
+      if not SILE.scratch.book.headers[value] then
+        SU.warn("Unknown headers type '".. value .. "', switching to 'technical'")
+        value = "technical"
+      end
+      self.headers = value
+    end
+    return self.headers
+  end)
 end
 
 function class:setOptions (options)
   options = options or {}
   options.layout = options.layout or "division"
+  options.headers = options.headers or "technical"
   base.setOptions(self, options) -- so that papersize etc. get processed...
 
   local layout = layoutParser:match(options.layout)
   if not layout then
-    SU.warn("Unknown page layout '".. options.layout .. "', switching to division")
+    SU.warn("Unknown page layout '".. options.layout .. "', switching to 'division'")
     layout = layoutParser:match("division")
   end
 
@@ -379,8 +398,11 @@ function class:endPage ()
   if SILE.scratch.info.thispage.headerEven then
     SILE.scratch.headers.even = SILE.scratch.info.thispage.headerEven[#SILE.scratch.info.thispage.headerEven]
   end
-  self.packages["resilient.headers"]:outputHeader(
-      self:oddPage() and SILE.scratch.headers.odd or SILE.scratch.headers.even)
+  if self:oddPage() then
+    self.packages["resilient.headers"]:outputHeader(SILE.scratch.headers.odd)
+  else
+    self.packages["resilient.headers"]:outputHeader(SILE.scratch.headers.even)
+  end
   return base.endPage(self)
 end
 
@@ -400,6 +422,12 @@ function class:registerCommands ()
 
   -- Running headers
 
+  self:registerCommand("book-title", function (_, content)
+    if self.headers == "novel" then
+      SILE.call("even-running-header", {}, content)
+    end
+  end, "Book title low-level command (for running headers depending on headers type)")
+
   self:registerCommand("even-tracked-header", function (_, content)
     local headerContent = function ()
       SILE.call("style:apply:paragraph", { name = "header-even" }, {
@@ -469,16 +497,20 @@ function class:registerCommands ()
       SILE.call("folios")
       SILE.call("set-counter", { id = "footnote", value = 1 })
     else
-      -- Chapters, here, go in the even header.
-      SILE.call("even-tracked-header", {}, content)
+      if self.headers == "novel" then
+        SILE.call("odd-tracked-header", {}, content)
+      elseif self.headers == "technical" then
+        SILE.call("even-tracked-header", {}, content)
+      end
     end
   end, "Apply chapter hooks (counter resets, footers and headers, etc.)")
 
   self:registerCommand("sectioning:section:hook", function (options, content)
     local before = SU.boolean(options.before, false)
     if not before then
-      -- Sections, here, go in the odd header.
-      SILE.call("odd-tracked-header", {}, content)
+      if self.headers == "technical" then
+        SILE.call("odd-tracked-header", {}, content)
+      end
     end
   end, "Applies section hooks (footers and headers, etc.)")
 

examples/manual-classes/classes.sil

@@ -6,6 +6,36 @@ default book class from SILE to this author’s needs and taste. It eventually
 evolved into a full redesign on different grounds. This very document uses it,
 so you can see it in real action.
 
+\section{Class options}
+
+In addition to the class options provided by SILE, the class also supports the following options:
+
+\begin{defn}
+\term{layout}
+\desc{Specifies the default (global) page layout. See part \ref[marker=page-layout].}
+\end{defn}
+
+\begin{defn}
+\term{offset}
+\desc{Specifies the binding offset. See part \ref[marker=page-layout].}
+\end{defn}
+
+\begin{defn}
+\term{headers}
+\desc{Specifies how running headers are used:
+\begin{itemize}
+\item{\code{none}: No running headers.}
+\item{\code{technical} (default): Chapter and section titles go in the even and odd running headers, respectively.}
+\item{\code{novel}: Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers.\footnote{The low-level command to set the book title is \autodoc:command{\book-title{<text>}.}}}
+\end{itemize}}
+\end{defn}
+
+\begin{defn}
+\term{resolution}
+\desc{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.}
+\end{defn}
+
 \section{Standard sectioning commands}
 
 The class supports the following sectioning commands, from the highest
@@ -54,8 +84,9 @@ Chapters have page numbering enabled on their first page and make sure
 no header shown is shown on that page. Both start on an odd page\footnote{Again,
 as almost everything depending on styles, this can be customized.}, and the previous
 even page, if inserted blank, is shown without page number and header. Parts and chapters
-reset the footnote counter. Chapter and section titles go in odd and even running
-headers respectively, unless customized otherwise.
+reset the footnote counter.
+Depending on the `headers` class option (see above), chapter and section titles go in running
+headers, unless customized otherwise.
 
 Notably, the class also defines a few commands currenty used as hooks in some of the
 above sectioning styles.

examples/manual-masterdoc/masterdoc.dj

@@ -32,7 +32,6 @@ metadata:
   keywords:
     - Mythology
     - Fantasy
-    - Feigned history
   authors: Emma Lenski
   translators: Sylvain Forestier
   publisher: Omikhleia
@@ -50,6 +49,7 @@ sile:
     # class: resilient.book # (default choice if not set)
     papersize: 6in x 9in
     layout: ateliers demiluxe
+    headers: novel
     resolution: 300
   settings:
     textsubsuper.fake: false
@@ -58,10 +58,8 @@ sile:
     - 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]
@@ -76,7 +74,7 @@ The `metadata` object contains several general document properties.
 
  - 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).
+ - The `title` may be used in running headers (possibly, depending on the document class and its options).
 
 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).
@@ -96,7 +94,10 @@ The `sile` object provides intructions for processing the master document with S
 
  - 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.
+
+   - If you don't specify a `class` then *resilient.book* is assumed.
+
+   - Other supported options are `papersize`, and, with the resilient book class, `layout`, `offset`, `headers` and `resolution`.
 
 - The `settings` can be used to globally set some SILE parameters.
 

inputters/silm.lua

@@ -7,12 +7,10 @@ local ast = require("silex.ast")
 local createCommand, createStructuredCommand = ast.createCommand, ast.createStructuredCommand
 
 SILE.registerCommand("has:book-title-support", function (_, content)
-  -- Fairly lame command detection, and it's not even doing the proper
-  -- thing. Should be refactored after having addressed issue
-  -- https://github.com/Omikhleia/resilient.sile/issues/58
-  if SILE.Commands["odd-running-header"] then
+  -- Fairly lame command detection
+  if SILE.Commands["book-title"] then
     -- At least resilient.book will do something
-    SILE.call("odd-running-header", {}, content)
+    SILE.call("book-title", {}, content)
   end
   -- I am not going to care for the core book class...
 end, nil, nil, true) -- HACK (*sigh*)
@@ -186,7 +184,9 @@ local MasterSchema = {
             class = { type = "string" },
             papersize = { type = "string" },
             layout = { type = "string" },
-            resolution = { type = "number" }
+            resolution = { type = "number" },
+            headers = { type = "string" },
+            offset = { type = "string" },
           }
         },
         settings = {
@@ -583,7 +583,9 @@ function inputter:parse (doc)
       class = options.class or "resilient.book", -- Sane default. We Are Resilient.
       papersize = options.papersize,
       layout = options.layout,
-      resolution = options.resolution
+      resolution = options.resolution,
+      headers = options.headers,
+      offset = options.offset,
     } or {}
 
   local tree = {

packages/resilient/styles/init.lua

@@ -332,7 +332,7 @@ function package:registerCommands ()
         end
         if not breakafter then SILE.call("novbreak") end
         SILE.typesetter:leaveHmode()
-        -- Here we must apply the font, then the alignement, so that line heights are
+        -- Here we must apply the font, then the alignment, so that line heights are
         -- correct even on the last paragraph. But the color introduces hboxes so
         -- must be applied last, no to cause havoc with the noindent/indent and
         -- centering etc. environments