API documentation

[davidchisnall]

I mentioned this over breakfast after your FOSDEM presentation, but unfortunately I haven't had much time to look at sile since then:

I'm interested in being able to use sile for typesetting inside other programs and some of the recent work on lua bridging to other languages (e.g. sol2) makes this even more attractive. Unfortunately, there seems to be a lack of documentation for the Lua code. Given the goal of allowing arbitrary parts of sile to be replaced, this is unfortunate. For example, for on-screen rendering I would like to be able to provide sile with direct access to in-memory data structures describing markup (rather than having to convert to XML and send that to the lua code) and then retrieve the glyph positions within a set of frames defined in code, but then use my own code for displaying the glyphs. In the absence of documentation, and without the desire to read all of the sile code, it's not clear where to start with such an endeavour.

[simoncozens]

For what it’s worth, I am working on this. I’m run off my feet with day job work and other projects at the moment but I hope to get back to checking in some useful documentation soon.

[alerque]

Cross-linking b9e2ea6 which appears to be related to this.

[davidchisnall]

Great, looking forward to seeing it.

[Omikhleia]

This old issue was very general. As I wrote in discussion #1729:

SILE API is not stable yet, and likely to change until 1.0.
This request from 2017 came to early, and was partially addressed at the time, but I don't think the core team can devote more effort to this.
Having a good User Manual is already an effort (tracked in various other issues).

Yet, there's something doable:

Cross-linking b9e2ea6 which appears to be related to this.

The developers.sil file introduced in that commit (and later slightly trimmed down) never made it to the manual (or to any spin-off guide), and its content is real far from useful...

Looking at what we have in the current manual, there's not much here that is not covered one way or another.

One thing, though, comes to mind, now that we have a better Chap. 10 (Designing Packages & Classes): an additional chapter on inputters and outputters, written in a similar way, would make sense in my opinion: explaining the concepts (likely with a figure too) and the basic class logic.

Let's get the motivation doing it?

[alerque]

I agree. Lets consider the improvements in #1815 as closing this issue.

There is another issue, #1337, for what I plan to do with API documentation in the long run which is posting it online using auto-generated documentation tools (both Lua and Rust). This makes much more sense than the PDF format for documenting API interfaces rather than typesetter usage. Once that starts to take shape we can consider what adjustments to the manual make sense.