Custom section commands (listing)?

[davidchisnall]

The package includes captions for tables and figures. I also need to be able to display code listings. I assumed that the sectioning support would be able to make them. I've created the following package that I thought created the right styles:

local base = require("packages.resilient.base")
local package = pl.class(base)
package._name = "listings"

function package:_init(options)
	base._init(self)

	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 " } },
	})

	self:registerStyle("listing-caption", {}, {
		font = { size = "4em" },
		paragraph = {
			before = { indent = false, vbreak = false },
			align = "center",
			after = { skip = "medskip" },
		},
		sectioning = {
			counter = { id = "listing", level = 2 },
			settings = {
				toclevel = 7,
				bookmark = false,
				goodbreak = false,
			},
			numberstyle = {
				main = "listing-caption-main-number",
				reference = "listing-caption-ref-number",
			},
		},
	})
	self:registerCommand("listingcaption", function(options, content)
		options.style = "listing-caption"
		SILE.call("sectioning", options, content)
	end, "Listings caption")
end

return package

And the following simple test:

\begin[class="resilient.book"]{document}
\use[module=packages.listings]{}
\ref[marker=lst:listing]{}
\ref[marker=lst:listing2]{}
\ref[marker=lst:listing3]{}
\sectioning[marker=lst:listing, style=listing-caption]{Here is a caption}
\sectioning[numbering=true, style=table-caption]{\label[marker=lst:listing2]{}Here is another caption}
\listingcaption[marker=lst:listing3]{Here is a third caption}
\sectioning[marker=fig, style=figure-caption]{Here is a figure third caption}
\end{document}

The figure-caption and table-caption ones are simply to check whether I understand how \sectioning works. It seems to do what I expect. But the captions for the two that use the listing-caption are prefixed with 'Table' (small caps), and not 'Listing'. I'm really confused about where that's coming from. Looking at the resilient.book class, I thought the numbering = { before = { text = " bit was defining this, but modifying my installed copy of sile/classes/resilient/book.lua to put something else in table-caption-main-number style doesn't change it both the listing-caption and table-caption lines are prefixed with Table.

The figure-caption line is correctly prefixed with 'Figure', so obviously the infrastructure is working correctly and I am doing something wrong, but I'm not sure what.

[Omikhleia]

I'm getting this with your code:

Isn't it what you expected?

[Omikhleia]

I don't see anything that uses the numberstyle.reference field. I expected that to provide the style for the number in references, but it doesn't seem to.

Correct. The corresponding feature on the labelrefs.sile package wasn't implemented: Omikhleia/labelrefs.sile#2

While it works "in most scenarios", labelrefs has some deep issues (some of which were discussed here Omikhleia/labelrefs.sile#1) which are still present in "bare" SILE -- The "multiple package instanciation" question is still existing.

I still have it under my radar, in my tracklist for 2025, but I haven't taken any decision yet. There's a possibility I'll deprecate labelrefs.sile entirely, and bring it back entirely into resilient.sile, and then complete the planned styling for it. But there's so much to do in various areas that I won't commit to any deadline.

[davidchisnall]

Thanks. I can work around it quite easily (I already do for HTML output, where the numbers for cross references need to be computed separately anyway), I just didn't want to write code to work around the lack of a feature that actually exists.

[Omikhleia]

@davidchisnall Your listing styles and commands could be part of the next resilient release -- I hadn't such a thing 'cause I didn't need it initially, but there's no reason otherwise. Do you mind me importing the code from this discussion? (also adding a \listofliistings convenience command on the way).

[Omikhleia]

(With due credits of course)

[davidchisnall]

Most of it is copied and pasted from your code with trivial changes, so no objections at all. It would be great to have in the default release.

If you’re interested, the book I’m working on currently is here. This is the tooling that does the conversion from semantic markup to HTML or SILE is here (and is currently totally undocumented and not expected to be usable by anyone except me). The HTML version of the book is here, I still need to make a few cleanups of the SILE version for the PDFs and generate indexes (I’m not happy with how the text in the doc comment blocks is rendered currently, I haven’t figured out how to disable indents for every paragraph in a range and the padding is not right.