A critical assessment of SILE book class in 2025

[Omikhleia]

SILE's "book" document class, mentioned in The SILE Book, is probably what most newcomers will try first when typesetting a book with SILE.

It's likely their first encounter with SILE, and they'll probably assume its capabilities are representative of the system.
But in reality, it is very limited in features and usability...

TL;DR: You may want to just jump to the conclusion at the end.

Designing a generic-purpose book class is not trivial.
It took me quite an effort to achieve a somewhat satisfactory level in my own re·sil·ient book class, and I wouldn't say it's totally done yet.

To better assess the challenges, you'll find below a 2025 assessment of the core book class, compared to the re·sil·ient book class, with comments on some of the problems.

Book structure assessment

From a high-level perspective, let's first consider features related to the overall structure of a book.

Feature	Core Book Class	Resilient Book Class
Covers / Titles	✗ Not available (1)	✓ Front cover, back cover (configurable, templated)
Book Matters	✗ Not available (2)	✓ Half-title page, title page, end-paper page (configurable, templated)
Divisions	✗ Not available	✓ Front matter, main matter, back matter
Subdivisions	✗ Not available	✓ Appendix
Sectioning	△ Three levels (chapter, section, subsection) (3)	✓ Five levels (part, chapter, section, subsection, subsubsection) + specifics for captioned block
Captioned blocks	✗ Not available	✓ Three types so far (captioned figure, table, and listing)

Notes:

1. Issue "Book class needs some default way to handle titles" (#599) (2019)

2. Issue "Title / halftitle pages for book class": #1111 (2020)

3. Issue "Book class could use a \part command": #601 (2019)

   The issue also briefly mentions other sectioning levels ("subsubsection") and book divisions in the discussions.

   See also Draft PR #597 (2019).

Sectioning levels assessment

Let's look deeper into sectionining levels.

Feature	Core Book Class	Resilient Book Class
Sectioning page breaks and spreads	✗ Hard-coded	✓ Configurable (via styles)
Sectioning vertical skips ang breaks	✗ Hard-coded (1)	✓ Configurable (via styles) + consecutive skip collapsing
Sectioning title styling	△ Programmable (via code hooks)	✓ Configurable (via styles)
First-paragraph indent strategy	✗ Hard-coded (English convention)	✓ Configurable (via styles)
Folio strategy (on chapters, etc.)	✗ Hard-coded	△ Programmable (via code hooks)
Running headers depending on level	✗ Hard-coded, broken (2) (3) (4)	✓ Configurable (3 default strategies, code hooks and styles)

Notes:

1. Without consecutive skip collapsing and page break penalty adjustments.

   This has (bad) implications for successive sectioning levels, for instance a section immediately following a subsection, without any intervening text.
   In the worst scenario, it can lead to excessive vertical space between the two levels, and even a page break between them...

   For reference, see "Note on consecutive skips" in the re·sil·ient user guide.
   The styling paradigm in re·sil·ient implements skip collapsing, but still has some rough edges on penalty adjustments.
   That the topic was never discussed is somewhat surprising, given how common it is in book design, and how well it has been handled in "competitors".
   In its true form, it requires a more sophisticated approach that what re·sil·ient does...

2. Issue "Book class has running headers on wrong page": #1842 (2023)

3. Issue "Section titles in running header are conditioned by folios": #1291 (2021)

4. Issue "Footnotes in section headers": #1287 (2021)

   This is a much more general problem with "fragile" commands (footnotes, cross-reference labels, etc.) in any content (which section titles are a special case of) that may end up in running headers, ToC entries, PDF bookmarks, etc. --- as noted in issue #1369 in 2025.

   In re·sil·ient, the question was only addressed in 2025, "Prevent fragile commands from leaking" (#138), with transitional implementation, out of desperation.
   The fact that the question was never discussed, with a documented core solution (e.g., at command registration), probably hints at a lack of understanding and knowledge in SILE's user community. The TeX-systems have been dealing with \protect-like mechanisms for decades.

Table of contents assessment

However implemented, the table of contents is a key element of book structure...

Feature	Core Book Class	Resilient Book Class
ToC title	≃ Configurable (via i18n localization key)	≃ Not available (by design, see documentation for the rationale)
ToC entry styling	△ Programmable (via code hooks)	✓ Configurable (via styles)
ToC page formatting	△ Part hard-coded, part programmable	✓ Configurable (via styles)
ToC fillers	✗ Hard-coded (1)	✓ Configurable (via styles)

Notes:

1. Draft proposal "Add hfill-command parameter to TOC": #1650 (2022)

Page layout assessment

Above we looked at what goes into a book, but the page layout is also important.

Page layout here refers to the overall layout of the page: margins, positioning of headers and footers, sizing and placement of the text block, etc.
In SILE, these are the "frames" making a "frame set", and at higher level, "page masters."

Feature	Core Book Class	Resilient Book Class
Page layout	✗ Hard-coded default (1)	✓ Several off-the-shelf layouts
Binding gutter offset	✗ Not available	✓ Adjustable class option for existing layouts

Of course, low-level control of frames and page masters is possible, and the SILE user manual has a section on that.
The core mechanism is powerful, but not very user-friendly.
As feedbacks (in discussions etc.) show, it's hard to get right for a non-expert user.
Some modules (for footnotes, folios, etc.) may have assumptions about the page layout, which may complicate things further.

Notes:

1. The default layout in the book class is defined with percentages that are not explained anywhere.
   The weird decimal values correspond to inner margin ~1/12th of the page width, bottom margin ~1/6th of the page height.
   It would hint towards a ratio-based Van de Graaf layout ("division 12 2" in re·sil·ient terminology)...
   But with outer margin ~1/7th of the page width, and top margin = ~1/8.6th of the page height, it is not really that.
   It's a questionable choice for a default layout, and not very instructive on how these are usually designed, with elegant proportions in mind.

Additional remarks:

The SILE user manual devotes a section to explaining how to set up custom page layouts at low level.
However, the provided example (derived from the LaTeX memoir package documentation) refers to "Bringhurst's book" in vague terms.
The values corresponds to the very first layout in table 3.1 from the said memoir documentation (with illustration in table 3.2), attributed to Bringhurst in the accompanying text...
But there's a problem here.

Robert Bringhurst designed a rather elegant layout for his book, based on geometric properties and pentagonal-based constructions (encompassing more things, actually, than just the disposition of the frames on the page). It is illustrated in the frontispiece of the 3rd edition, just before the table of contents.

I do not know where the author of the notes for the memoir package got his values from.
They refer to the 1992 edition of Bringhurst's book, which I do not have access to, and mention an original size of 132 × 227 mm (ratio 1:1.72). In their bibliography, they list only the 2nd edition, but with the wrong year (1999 instead of 1996).
Checking the 3rd edition (2004), the layout does not match, especially the inner and outer margins, which differ significantly.
This edition uses a page size of approx. 134 × 232 mm (ratio 1:1.73, closer to 1:√3 see below).
It's a bit embarrassing that The SILE Book refers to a layout from a secondary source, which might not be accurate, or at best incomplete.

More importantly, this layout is specifically designed for pages in a 1:√3 ratio. It is misleading (at least) that the applicability of a given layout to a specific page ratio is not mentioned in the user manual. It's even more true for Bringhurst's layout, which only works for that specific page ratio, or it looses its geometric qualities.

Users probably use other more common page sizes, in 1:√2 (ISO), 2:3 (US trade), or other ratios.
If SILE wants to help them design great books, it should make them aware of these aspects of book design.
For examples, see part III of the re·sil·ient user guide for more details on page layouts.

Overall assessment

The book class is used in several test cases, as the bare "plain" class is not enough for them.
It makes it quite hard to change its behavior, without breaking the tests in the process.

Overall, the core book class suffers from several issues.

• It is very minimal and limited in features --- it doesn't cover many common book elements and features
• It has not seen much development since its inception --- many issues have been left unaddressed for years
• It has several hard-coded behaviors --- its usability is hampered by lack of configurability, which ill-defined "hooks" cannot easily override
• It has questionable design choices in some aspects --- Default values and behavior are not always sane and sensible

It is more meant as a "teaching example" or a "toy" than a production-ready class.
To that respect, it is not bad for what it is, and looking at its internal code can be instructive. It did learn a few techniques there, that I later reused.

But assuming users will design their own book class for production use is not realistic.
Most users will expect a usable default book class, and will not have the time or expertise to one themselves.

The same remarks would apply to other document classes, e.g., for articles.
To that regard, see open issue "Implement an article class", #455 (2017)...
It never happened, and probably never will.

Rational users will expect such standard classes to be provided out of the box --- and easily tunable to their needs --- or they will simply switch to another typesetting system. It needs dedication and passion to go against that grain.

I am not a rational user, probably. But in my 4-year experience with SILE so far, I haven't seen many users working on their own classes to any extent that would make them general-purpose and re-usable by others, on a scope comparable to what I have tried to achieve with re·sil·ient (documented in a carefully written user guide, and demonstrated in several books).

Conclusion

Its name is misleading, the core book document class is a "minimal toy book" example class, not suitable for real-world book typesetting.

It could be significantly improved, but that would require a lot of work and design effort, duplicating much of what I have struggled with in re·sil·ient.

IMHO, minimally:

• It should be renamed to something like "minimal-toy-book" to avoid any confusion about its current capabilities.
• It should be clearly documented as a minimal example class, not a fully-featured book class.

That would be a first step, allowing to keep it as both a teaching example and a test tool.

What would be the next step?

• It's hard to imagine a volunteer now stepping up to take on the hard task of designing and implementing a full-featured book class, without re-inventing the wheel.
• It's hard to believe one could just monkey-patch the existing class to make it a tad better, and achieve a satisfactory level of features and usability.

So maybe SILE, at least "semi-officially", should consider endorsing the re·sil·ient book class in some way... 😁

But it in any case, letting users think that the core "book" class is "something real" is very likely to cause frustration and disappointment...

Comments, feedbacks and advice are welcome on this topic (which might, or not, become part of a longer essay) 😀

[KMickle]

I don't have much useful feedback, but I have the perspective of a new user coming from a LuaTeX and (earlier) MS Word background.

I have never seen the book class as something that is usable in any way to set real book (or documents whatsoever). I treated it from the very first mention as "look what we can do by using SILE's base function! And look how wonderfully it works!". So, your point about this class being a sample or an educational artifact is exactly how I always felt.

It should be obvious that every author and every book/journal have their own vision of how to do things. So, it is not generally expected of a typesetting system to provide readily-usable document classes. I never had an intention of typesetting something I need as quickly as possible, but if I were to, I would first go to the publishers' to check if they have the class, and if they don't (and they don't 😆) I'd go for macro packages. And that's where I'll probably hit re-SIL-ient first.

Long story short, I disagree with the point that SILE needs additional classes out of the box, as those should be either authored or willfully obtained. At the same time, it would probably very wise for a typesetting system to help and promote macro packages, such as re-SIL-ient, that draw in recognition and quality for the whole system. Don't we hear LaTeX more often than TeX? And LaTeX is not the typesetting system.

.... that reminds me: I found the base class has some dependencies in the plain class, which is totally bad. I need to file that..

[Omikhleia]

N.B. On the Bringhurst layout; just for the proof regarding my criticism of the example in the SILE manual

Left: Pages of the actual book (3rd edition) overlaid onto the frontispiece design schematics = perfect match.
Middle: The bluish text block overlay is from table 3.2 (left) in the memoir specification = incorrect
Right: The bluish text block overlay is the "bringhurst" layout in re·sil·ient 3.2.0 = quite good (for true nigglers, we could advocate that the footer frame is not matching perfectly -- partly by laziness, partly by design... well, mostly by laziness, TBH)

[jodros]

After using SILE for more than two years, and having used resilient for a while, my suggestion is:

• to make SILE simpler: get rid of all these useless packages and classes (there are some which are merely drafts and shouldn't be in the main branch), and then simply focus on improving technical matters like language support (the CJK compatibility, and so on), frames tricks, etc... Leave everything that isn't too technical to extensions. Embracing a kind of minimalist approach to its development.

• dedicate the other half of the time to developing extensions, as you have done (qrcode.sile, barcodes.sile, and others). However, this requires more public promotion of the core software; it's just a matter of more people getting to know it so new packages will emerge naturally.

[Omikhleia]

Hi @jodros

... get rid of all these useless packages and classes...

But how does it relate to the current discussion here on the default book class (and the dozen-or-so related issues mentioned above¹)?
(Surely, one could do a critical assessment of other classes and packages, but that's probably another topic)

... more public promotion of the core software...

That's also a different topic beyond the initial discussion, which could deserve its own separate discussion. (Users are the ones creating hype with show-and-tell success stories...)

Footnotes

1. What should we do with these open issues, if SILE sticks to its limited book class? ↩

[jodros]

But how does it relate to the current discussion here on the default book class

My suggestion would be to not have default classes, but base and plain, and all the other being just examples, so when it comes to the current book, I agree with you

It should be clearly documented as a minimal example class, not a fully-featured book class.

However

Rational users will expect such standard classes to be provided out of the box

Basically I tried to say the same as @KMickle above:

Don't we hear LaTeX more often than TeX? And LaTeX is not the typesetting system.

As an active user of both the core SILE and re·sil·ient, I would approve such decision. The SILE manual could point out re·sil·ient as the simple way of doing the work with practicality, and let the core typesetting system for those who want to extend it by themselves...

[Omikhleia]

... but base and plain...

The "plain" class is just adding a few (EDIT: read "low-level") TeX-like commands, unrelated to any class support....and which could therefore be supplemented via a package (= the path actually taken by re·sil·ient since v3.0.0, with a package resilient.plain... EDIT: So as not to depend any longer on the "plain" class, but introducing its own class hierarchy...)