Suggestion: a "demo" class and associated document

[dontlaugh]

Creating a class can be challenging. I think the manual is pretty good at explaining the low-level mechanisms. And the built in "book" and "letter" classes are instructive.

Perhaps there is room for a "kitchen sink" kind of class, and an associated example document, that marches through some features that SILE is good at.

Some features to demonstrate in a kitchen sink class.

• Section numbering
• Folio/page number manipulation
• Running header manipulation
• Font changes
• Different kinds of line breaks and page breaks
• Widening/narrowing margins (e.g. for leading article abstract)

I'll add to this list if more comes to mind

---

Demonstrating these features in a "single page, single column" report style layout would be my vote. It should yield simpler Lua, if I understand correctly.

[dontlaugh]

Relates to #455

[baubleb]

A mininum working example boilerplate class would be nice to have so we can just build on that.

I tried to take an existing class, strip it down to bare basics (or so I thought) and it still won't work.

[Omikhleia]

The default book class is instructive, and a pretty short read (about 250 LoC). I recommend starting with it -- It's what I did back in sept. 2021 when I started writing my own classes, and though I eventually departed a lot from it (abstracting my headers, styles, sectioning logic etc. in separate packages, so kind of an overhaul in the end), it was a neat example to get the work started. Of course, it's not perfect and has its subtleties, but nothing blocking. Still, it could be interesting to see where others get stuck.

[alerque]

A minimum working class is a bit different than a kitchen sink demo class, and not very informative either:

local plain = require("classes.plain")

local myclass = pl.class(plain)
myclass._name = "myclass"

return myclass

That's it. You have a working bare bones class. The next step is to start adding or overriding class functions to do what you want. The mostly likely bit you'll want to start with is an _init() function that doesn't just run itself, it runs the init from the parent class. That bit is non obvious but found in every existing class we have:

function myclass:_init (options)
  -- your stuff here (if you want it before the parent init)
  plain._init(self, options)
  -- your stuff here (if you want it after the parent init)
  return self
end

From there look at existing classes to find how they do stuff like add class options or setup frames or whatever.

This is spelled out in the manual by the way including code bits to setup a whole class that does ... something just for kicks. I'm not sure what else we should provide honestly.

[dontlaugh]

The default book class is instructive, and a pretty short read (about 250 LoC). I recommend starting with it

This is the direction I'm heading in.

[Omikhleia]

Re-reading that manual section and @alerque 's note above, it would be doable, I think, to slightly refactor it and review the progression order. Maybe I can it a try at some point?

My mind is not set on this, but I could also propose to change some examples (e.g. the Bringhurst layout is not the simplest to start with, with all these "unexplained" percentages - maybe some explanations on general page layout and a Honnecourt and/or geometric division layout would allow a more thorough learning curve? Illustrating the layout could also help (... and it could be fun to extract it from the frame set rather than include an image...)

Also, we have that chapter on class design, with some details on packages on the way - maybe we could refactor that a bit too, with an explicit section on packages - esp. since 0.13, there's a bit more to say than before.

[Omikhleia]

I proposed some changes in #1778 -- based in part on @alerque 's comment above, and on my own experience too.

@dontlaugh @baubleb since you commented on the topic, it could be interesting to have your opinion on the matter!

On the other hand, it tries at properly documenting the "bare bones" approach to packages and classes, but the general issue is (IMHO) hard to tackle with.

Section numbering, running header manipulations: That's what the book class implement. That's not the only way to do it, though. If we compare, say, SILE core mechanisms and (plain)TeX, all other things being equal, it's a bit as if one wanted to have a full but short explanation of the LaTeX book class internal implementation. I am not sure it's doable, and even desirable.
"Creating a class can be challenging", indeed -- AFAIC, it took me more than 1 year to implement a class system I am satisfied with, and it's not even complete. The SILE standard "book" class is a toy - a neat one to get started with, and I am not sure it has to be made more complex either, but anyhow, anyone really designing class would probably depart a lot too from it.

Folio/page number manipulation is another hard topic.

Font changes, I don't know, it seems to me the manual already covers it decently? (§4.1 - but it doesn't really has anything to do with class/package design, does it?)¹

Different kinds of line breaks and page breaks: What do we need beyond §4.5 (on the SIL side) and §9.2 (on the Lua side)?

Widening/narrowing margins (e.g. for leading article abstract): Is the blockquote example proposed as an addition to chapter 10 in my PR addressing this concern? (Besides, §7.1 already documented something similar)

Footnotes

1. If the question at stakes was actually, e.g. how to customize the default book class, say the font and size of a chapter heading... Well, one mechanism we currently may lack in SILE is a way for classes to provide their own documentation, as we do for packages. That could be an answer -- Other class implementation could do it very differently -- e.g. in my own resilient.sile, I use a very different styling paradigm -- and a solution for the main explanations in the manual to stick with the inner workings of SILE itself. Maybe that's what we need here? ↩

[dontlaugh]

I think my motivation here was actually closer to the spirit of #455

I don't know the state of that issue, but I think giving people a head start on a mildly sophisticated and hackable report/article/memo class is a great invitation to a pretty underserved market.

If we consider the requirements of a report, it has a few solid elements of the "kitchen sink":

Writing a report I want to

• ingest structured data (csv, xml, json, etc.)
• title
• list of authors
• render tables
• render figures
• section headers (numbering optional)
• biliography

And it's likely I'm going to want to print this out, single-sided, on my office laser printer, staple it, and hand it to my colleague. In that scenario, consistent/even margins (and headers/footers!) look more appropriate than the alternating, offset style of a bound book. That's my opinion, anyway.

I haven't ready your PR yet. I will check it out soon. Thank you <3

---

On the topic of "coding style" for classes, or teaching people how to write classes, I think there is a type of documentation that is missing from the manual: API reference documentation.

The manual goes into detail about the following:

• Concepts used in the SILE engine. Examples like kerns, boxes, frame, glue. Terms of art.
• Existing packages and their usage. I count ~40 pages of the manual dedicated to this. Necessary, and quite helpful, to jump in and find a snippet that might be relevant to what I'm trying to do
• Tutorials that walk the reader through designing a class.

None of these are precisely the same as a comprehensive, up to date, API reference. Forgive me if this exists somewhere else and I'm just unaware.

Consider this API: SILE.process

If I use Ctrl+F in the current PDF of the Manual, I do see 4-5 examples usages, and also some prose content that indicates what that API is doing, but what's lacking is a big appendix - autogenerated from source code - that lists out every top-level API, what it does, and in which version it was introduced.

I'm sure this isn't always straightforward with Lua, where you can set/modify objects all over the place, but certainly the standalone functions could be documented. Perhaps there's a Lua documentation framework you could adopt.

[Omikhleia]

@dontlaugh Thanks for all the details, it's really interesting, helpful and challenging!

First, regarding your second point, "API reference documentation "already has some tickets about it (e.g. #493, #1337). I recognize the need here, but SILE is still in 0.x and the way forward is not that obvious. I'll be blunt, but documenting what we currently have is an effort, and I am not sure it's worth investing yet up to that point... I might be wrong, though... But it's already hard to improve and maintain the existing manual, there are a lot of things there... and many might still change for the best. Yet, some incremental improvements might be doable indeed. Actually, the "big glossary" you mentioned is also part of the problem with having a good indexer (#1339). So I would say "It's tracked', although an ETA is not obvious to state with limited resources ;-) I wanted to work on the indexer some 6 months ago, but time flees fast...

Regarding your first point, hey, interesting thoughts!

• "ingest structured data (csv, xml, json, etc.)": XML is rather covered already, isn't it? It's hard to say, my in-progress book has 80% of its contents in XML and SILE is doing pretty well there (at least, with less weirdness than XSLT and XSL-FO, my previous attempt at the same content...), but it's hard to judge what people really expect here! -- On CVS, JSON = What kind of "ingestion" are you thinking to? (personally, I've, for instance, experimental code for rendering pie charts and bar graphs from CSV, but I didn't proceed beyond a mere Proof of Concepts, as it is not something I really need... I mean, as a developer, it was fun trying, but I dunno if anyone would be interested, so... it remained a PoC).
  EDIT: As for "ingesting" things, see also embedders.sile and spreadsheet.sile. But again I'm not sure what's the expectation was here.

• "title, list of authors" = AFAIC, I'm postponing the topic here (I need it too for a potential project, but there's more than meets the eye here when looked beyond (La)TeX, and I have not made my mind yet on it).
  EDIT: Any anyway there's also a similar issue there: Title / halftitle pages for book class #1111

• "render tables" -- Have you checked, for instance, ptable.sile?

• "render figures" -- Have you checked, for instance resilient.sile and its captioned tables and figures (and lists of thereof)? Ok, as for tables, I'm mentioning my own things here, so I'm probably biased, but it's not necessarily orthogonal to SILE, at least in my view. It's part of the CTAN SLAN however we call the SILE ecosystem ;) After all, nobody would complain in the (La)TeX world if one says "Use (La)TeX indeed, but use the Koma classes instead of the default classes" ;)

• "section headers (numbering optional)" -- Here I am unsure what you mean. Can you clarify the expectation?

• "biliography": Agreed. This one is real hard, and needs knowledgeable people and developers. I called for help here, as it requires a lot of efforts to be done well (= leveraging SILE's existing bibliography support, but also ensuring it meets the needs of Markdown / Djot / whatever other input format). Still, even if we could get, say, ¢iteproc to work well with SILE, the amount of work needed is a bit frightening (says a noob in that field). Developers are welcome here!

As of #455, frankly... My own view on it is that i'ts a 10mn hack using my resilient stuff (hint = layout set to "none", a few styles customized, and here we are.) Again, I might be wrong, I don't write "articles", except if they eventually make it in some 300+ page "book", so my own use case is probably different ;)

[Omikhleia]

For reference, I added some additional links in my previous answer above (marked as EDIT).

This being said, after having taken the time for reconsidering it, I am afraid this issue has become far too broad.

1. It mentions many points, most of them having existing dedicated issues already.
2. Broad issues that evolve afar from an initial request/question and where more and more items are added without a resolution path are near to impossible to fully address.
3. I think we nevertheless addressed some of this one, on better documenting the class and package design in chapter 10 (and other documentation improvements are on their way).
4. Proper class design from scratch is complex. (Even in LaTeX. I am not convinced by articles such as this one, and I have some past experience dabbling into LaTeX's internals...). It's not something we should expect "regular" users to do.

Hence, I am closing this issue.
Please feel free to comment or re-open, if there is really something we could work out together.