Thank you!

[davidchisnall]

I've wanted an excuse to use SILE for a real project since I saw Simon's talk and had breakfast with him the following day at FOSDEM 2015 (wow, ten years ago!). I hadn't written a book since then, so I hadn't had a good opportunity, but we recently got a grant for me to finish the first edition of the CHERIoT Programmers' Handbook and get it published, so finally an excuse!

I wrote my last few books using semantic markup that happened to be valid TeX and had a separate flow for generating ePub. This came with some annoyances: LaTeX syntax is not very consistent and some things needed to be replicated in very different ways. For example, code listings in the ePub were parsed with libclang and got full semantic highlighting, code listings in the LaTeX used the listings package and got simpler syntactic highlighting.

For the new one, I wanted to be able to produce four different outputs:

• HTML for the web.
• XHTML for ePub eBooks.
• Colour PDFs including the cover, with hyperlinks, for PDF eBooks.
• Mono PDFs for printing.

I wrote a tool that parsed some cleaner markup and ran a set of (Lua) passes over it to produce SIL or XML-like output (HTML is not quite XML, but close enough that a common back end can write both). It turned out that XML was easier to feed to SILE than SIL, so I ended up using the {X,HT}ML back end for everything. This let me write semantic markup and mostly forward it to HTML as div and span classes that I can convert to presentation markup with CSS, and lower progressively to SILE's input, using existing packages where they exist and just generating syntactic markup where not. For example, a keyword in code listing is <span class="code code-Keyword"> in HTML, but just font or color elements in SILE.

My experience with SILE has been great. I've used the packages from @Omikhleia's resilient for a bunch of things and the output looks very nice. Beyond that though, there are two things I really appreciate:

First, I've filed a bunch of bugs and they've been fixed very quickly. Most of them were easy to work around.

Second, the structure of SILE makes it a real Free Software system. As an end user, it's been trivial to extend, either by copying things from PRs into my document or by monkey patching bits of the typesetter. Thank you!

There are really only three limitations that I've encountered:

• LaTeX and HTML have itemized (unordered), enumerated (ordered), and description lists. SILE has only two of these. Not sure why description lists were omitted. I don't need to nest them, so I've worked around that so far by just lowering them to bold then indented text.
• Lack of floats. This makes the typesetting really bad in about 10% of pages for me, with images / listings / tables overflowing the bottom of the page and overlapping the footer. I've implemented a simple version, which works for me. I'd like to help refactor the typesetter / page builder to make this kind of thing a bit easier to support generally, with the page builder informing the type setter that it has no good solutions with the current set of vboxes in the queue and the type setter exposing hooks to try to rearrange things in the queue. There are a bunch of corner cases here that I'm not handling (for example, my floating things cannot contain footnotes - I'm mildly amused by the fact that I'm reimplementing LaTeX bugs from the 1980s and I haven't provided a barrier so that they don't move past chapter titles and so on), but I think it's a starting point for a general approach.
• Lack of the ability to switch to two-column mode and back. Currently, the index is rendered like a table of contents, with a single column, whereas most books use a two-column layout. There are open issues about this. I'm not sure if there's a simple way to do it for this specific use case. From having poked the typesetter a bit, I suspect the root problem is that hboxes are assembled into vboxes too early (and, more specifically, with no easy way of reversing the assembly). This also makes supporting non-rectangular pages hard (if I understand it correctly, the parshape example appears to be constructing vboxes of fixed width).

[Omikhleia]

... Not sure why description lists were omitted. I don't need to nest them, so I've worked around that so far by just lowering them to bold then indented text.

Description lists are different from itemized/enumerated items, semantically and syntactically.

For what is worth, resilient has a package resilient.defn for them (e.g., used for supporting Markdown/Djot description lists). You might give it a try.

Lack of the ability to switch to two-column mode and back.

Let's even go further: N-column modes, N ≥ 2
(AFAIC, whether I'll resume my 2023 attempt at these in 2025... is uncertain, but we'll see)

Or the ultimate dream, modular grid layout (second point there, and subsequent comment)...

[davidchisnall]

For what is worth, resilient has a package resilient.defn for them (e.g., used for supporting Markdown/Djot description lists). You might give it a try.

Thanks, I'm trying that now. It appears that the trim calls are not matching tabs as whitespace, so I need to add a cleanup before I pass this to SILE. It's probably a bit surprising to users: The error is simply '! Definition structure error'. I had to read the code to determine that this was a problem with text around the nodes (items are indented with one tab when I write them and I normally just pass whitespace through to SILE).

The output looks almost identical to my hack, so switching is easy.

Unfortunately it also includes the same bug: Ideally it would have a big page-breaking penalty between the item and description, without it the page builder is quite happy to insert a break there.

[Omikhleia]

By the way, since you mentioned your SILE-made PDF version of a book, I think we'll appreciate to have a reference in our Wiki when ready ;)

[davidchisnall]

Sure. The drafts are here:

https://cheriot.org/book/cheriot-programmers-guide.pdf

The print version uses slightly different input (for example, typesetting code highlighting as bold or italic rather than colours and adding footnotes for URLs rather than making them clickable links) but I think the colour PDF shows of SILE a bit better.

After the first edition is published, that location will continue to have the work-in-progress text towards the second edition, so feel free to link to it.