feat: Add a captioned listing environment

classes/resilient/book.lua

@@ -418,6 +418,37 @@ function class:registerStyles ()
     numbering = { before = { text = "table " } }
   })
 
+  self:registerStyle("listing", {}, {
+    paragraph = { before = { skip = "smallskip", indent = false },
+                  after = { vbreak = false } },
+  })
+  self:registerStyle("listing-caption", {}, {
+    font = { size = "0.95em" },
+    paragraph = { before = { skip = "smallskip", indent = false, vbreak = false },
+                  align = "center",
+                  after = { skip = "medskip" } },
+    sectioning = {  counter = { id = "listings", level = 1 },
+                    settings = {
+                      toclevel = 7,
+                      bookmark = false,
+                      goodbreak = false
+                    },
+                    numberstyle= {
+                      main ="listing-caption-main-number",
+                      reference ="listing-caption-ref-number"
+                    } },
+  })
+  self:registerStyle("listing-caption-base-number", {}, {})
+  self:registerStyle("listing-caption-main-number", { inherit = "listing-caption-base-number" }, {
+    numbering = { before = { text = "Listing " },
+                  after = { text = ".", kern = "iwsp" } },
+    font = { features = "+smcp" },
+  })
+  self:registerStyle("listing-caption-ref-number", { inherit = "listing-caption-base-number" }, {
+    numbering = { before = { text = "listing " } }
+  })
+
+
   -- code
   -- Default is similar to the original plain \code command, and quite as bad, but at
   -- least uses a font-relative size.
@@ -671,6 +702,21 @@ function class:registerCommands ()
     end
   end, "Insert a captioned table.")
 
+  self:registerCommand("captioned-listing", function (options, content)
+    if type(content) ~= "table" then SU.error("Expected a table content in listing environment") end
+    local caption = extractFromTree(content, "caption")
+
+    options.style = "listing-caption"
+    SILE.call("style:apply:paragraph", { name = "listing" }, content)
+    if caption then
+      SILE.call("sectioning", options, caption)
+    else
+      -- It's bad to use the table environment without caption, it's here for that.
+      -- So I am not even going to use styles here.
+      SILE.call("smallskip")
+    end
+  end, "Insert a captioned table.")
+
   self:registerCommand("table", function (options, content)
     SILE.call("captioned-table", options, content)
   end, "Alias to captioned-table.")
@@ -679,6 +725,10 @@ function class:registerCommands ()
     SILE.call("captioned-figure", options, content)
   end, "Alias to captioned-figure.")
 
+  self:registerCommand("listing", function (options, content)
+    SILE.call("captioned-listing", options, content)
+  end, "Alias to captioned-listing.")
+
   self:registerCommand("listoffigures", function (_, _)
     local figSty = self.styles:resolveStyle("figure-caption")
     local start = figSty.sectioning
@@ -697,6 +747,15 @@ function class:registerCommands ()
     SILE.call("tableofcontents", { start = start, depth = 0 })
   end, "Output the list of tables.")
 
+  self:registerCommand("listoflistings", function (_, _)
+    local lstSty = self.styles:resolveStyle("listing-caption")
+    local start = lstSty.sectioning
+      and lstSty.sectioning.settings and lstSty.sectioning.settings.toclevel
+      or SU.error("Listing style does not specify a TOC level sectioning")
+
+    SILE.call("tableofcontents", { start = start, depth = 0 })
+  end, "Output the list of listings.")
+
   -- Special dropcaps (provided as convenience)
   -- Also useful as pseudo custom style in Markdown or Djot.
 

examples/manual-classes/classes.sil

@@ -116,13 +116,13 @@ above sectioning styles.
 \caption{Predefined command hooks used by sectioning commands.}
 \end{table}
 
-\section{Captioned figures and tables}
+\section{Captioned environments}
 
-The class provides two additional environnments, \autodoc:environment{figure}
-and \autodoc:environment{table}. Both can contain arbitrary contents and a
-\autodoc:command[check=false]{\caption{<text>}} element. The latter is
-extracted and displayed below the contents.
-By default, these environments show their contents centered, with a numbered caption.
+The class provides three environnments, \autodoc:environment{figure}, \autodoc:environment{table}, and \autodoc:environment{listing}, for captioned figures, tables, and listings, respectively.
+They can contain arbitrary contents and a \autodoc:command[check=false]{\caption{<text>}} element.
+The latter, when present, is extracted and displayed below the contents.
+By default, the figure and table environments show their contents centered, with a numbered caption.
+The listing environment does not center its content, but otherwise behaves the same.
 Each of them has its own distinct counter.
 The figure environment is (normally) intended to be used around an illustration.
 
@@ -165,12 +165,32 @@ have guessed it.
 \caption{Styles used for tables.}
 \end{table}
 
-The figure and table caption styles are actually sectioning styles, and the captions are
-inserted into the table of contents at level 5 and 6 respectively. It implies that one has
-the possibility to have them shown in the TOC, if passing a sufficient \autodoc:parameter{depth}
-value to the \autodoc:command{\tableofcontents} command. While some authors may appreciate that,
-other, most likely, prefer having them in separate lists. Two convenience commands are
-provided to that effect.
+The listing environment is (normally) intended to be used around blocks of code, or similar.
+Note that the commmand does not switch to verbatim mode, it is up to you to do so if needed.
+
+\begin{table}
+\begin[cols=40%fw 50%fw, header=true]{ptable}
+  \begin[background=#eee]{row}
+    \cell[valign=top]{Style}
+    \cell[valign=top]{Description}
+  \end{row}
+  \begin{row}
+    \cell[valign=top]{\code{listing}}
+    \cell[valign=top]{Style applied to the listing content (not including the caption).}
+  \end{row}
+  \begin{row}
+    \cell[valign=top]{\code{listing-caption}}
+    \cell[valign=top]{(Sectioning) style applied to the listing caption.}
+  \end{row}
+\end{ptable}
+\caption{Styles used for listings.}
+\end{table}
+
+
+The caption styles are actually sectioning styles, and the captions are inserted into the table of contents at level 5, 6 and 7 respectively.
+It implies that one has the possibility to have them shown in the TOC, if passing a sufficient \autodoc:parameter{depth} value to the \autodoc:command{\tableofcontents} command.
+While some authors may appreciate that, other, most likely, prefer having them in separate lists.
+The following convenience commands are provided to that effect.
 
 \begin{table}
 \begin[cols=40%fw 50%fw, header=true]{ptable}
@@ -186,6 +206,10 @@ provided to that effect.
     \cell[valign=top]{\autodoc:command{\listoftables}}
     \cell[valign=top]{Outputs the list of tables.}
   \end{row}
+  \begin{row}
+    \cell[valign=top]{\autodoc:command{\listoflistings}}
+    \cell[valign=top]{Outputs the list of listings.}
+  \end{row}
 \end{ptable}
 \caption{Commands for lists of figures and tables.}
 \end{table}

examples/sile-resilient-manual-styles.yml

@@ -392,6 +392,65 @@ header-odd:
     paragraph:
       align: "right"
 
+listing:
+  origin: "resilient.book"
+  style:
+    paragraph:
+      after:
+        vbreak: false
+      before:
+        indent: false
+
+listing-caption:
+  origin: "resilient.book"
+  style:
+    font:
+      size: "0.95em"
+    paragraph:
+      after:
+        skip: "medskip"
+      align: "center"
+      before:
+        indent: false
+        skip: "smallskip"
+        vbreak: false
+    sectioning:
+      counter:
+        id: "listings"
+        level: 1
+      numberstyle:
+        main: "listing-caption-main-number"
+        reference: "listing-caption-ref-number"
+      settings:
+        bookmark: false
+        goodbreak: false
+        toclevel: 7
+
+listing-caption-base-number:
+  origin: "resilient.book"
+  style:
+
+listing-caption-main-number:
+  inherit: "listing-caption-base-number"
+  origin: "resilient.book"
+  style:
+    font:
+      features: "+smcp"
+    numbering:
+      after:
+        kern: "iwsp"
+        text: "."
+      before:
+        text: "Listing "
+
+listing-caption-ref-number:
+  inherit: "listing-caption-base-number"
+  origin: "resilient.book"
+  style:
+    numbering:
+      before:
+        text: "listing "
+
 lists-enumerate-alternate1:
   inherit: "lists-enumerate-base"
   origin: "resilient.lists"