R⁷RS Large Report: Docbook Edition

[Peter McGoron]

Hello everyone,

I (with some discussion with Wolfgang Corcoran-Mathe and others in
#scheme) have started an experiment to write out the R⁷RS-Large in
Docbook/SXML.

I chose Docbook because it has a kitchen-sink of elements for describing
technical books. It is also in XML, which means that (if we're careful!)
we can write it in SXML, which is more Schemely. Docbook 5 also has a
nice HTML5 renderer and is supported (somewhat) by Pandoc.

The current setup stores the SXML of sections as values exported from
R⁷RS libraries.

The critical reason for using SXML is that we can then compose
fascicles/the report with simple quasiquote/unquote. For instance,
sections of the Macrological Fascicle that would appear unchanged in the
report can be written as a separate SXML fragment and included in a
script that generates the Macrological Fascicle and one that generates
the actual report.

We could do this in the regular XML ecosystem, with XInclude and others,
but processing this would require using something like XSLT. I am not
very experienced with XML.

The current repository uses Docbook 5.0, but we could probably write in
some common subset of Docbook 4.4 and Docbook 5.0. dblatex targets
Docbook 4.4 for example.

The current renderer is a set of XSLT 3.0 scripts that are recommended
for use with Docbook. I don't know XSLT (any version) and I'm not
inclined to learn how to use it, so in the future I/we/someone can write
Scheme scripts to translate the Docbook/SXML into HTML/LaTeX/plain text.

Regarding math, we can use any type of math input, we just need to
modify the generator scripts. For instance, we could use a <latex>
element that the XSLT HTML scripts would translate into KaTeX or another
LaTeX web math renderer. Or we could replace XSLT with something else
and process LaTeX math in a special way.

The SXML->Docbook code are simple and written in portable R⁷RS. They
have been tested to work in Gauche and Chibi.

The repository is here: https://codeberg.org/phm/r7rs-large-docbook
An example rendering of the introduction to the report and a
bibliography is here:
https://florida.moe/r7rs/docbook/procedural-fascicle/unofficial-draft/

I appreciate any comments or contributions.

-- Peter McGoron

[Vincent Manis (he/him)]

I hesitate to raise this, lest I be accused of bikeshedding, but was any
consideration given to using Scribble? -- vincent

[Peter McGoron]

(Forgot to send this reply to the whole list.)

If you're talking about Scribble the @-syntax to build S-expression
documents, I think it would be OK with me, but I'm not very familiar
with it.

If you're talking about Scribble the Racket *tool*, then I'm not so sure
about using it. It's pretty tied-into Racket's language system, so it
would be non-portable and possibly break with updates to Racket. At
least with Docbook there's more of a chance to write separate tooling,
because Docbook has a precise specification.

The standard Scribble macros are very LaTeX-centric, and the program
markup is very Racket centric. It also doesn't solve the hard math
typesetting problems we have, like the formal semantics.

I'm not super attached to Docbook, I just tried the first thing I
understood could do the job and whipped up a proof-of-concept. If enough
people like Scribble I wouldn't mind switching.

-- Peter McGoron

[Wolfgang Corcoran-Mathe]

On 2026-03-21 11:59 -0400, 'Peter McGoron' via scheme-reports-wg2 wrote:
> If you're talking about Scribble the Racket *tool*, then I'm not so
> sure about using it. It's pretty tied-into Racket's language system,
> so it would be non-portable and possibly break with updates to
> Racket. At least with Docbook there's more of a chance to write
> separate tooling, because Docbook has a precise specification.

Exactly. My main concern about Scribble is its Racket dependency.
chibi-scheme has some tools for parsing Scribble, but I believe you're
stuck with Racket for publishing.

--
Wolfgang Corcoran-Mathe <w...@sigwinch.xyz>

[Vincent Manis (he/him)]

Then I guess Docbook it is, given that the source can be written in
SXML. If we restrict the Docbook elements to what Pandoc supports, then
we can still produce a nice-looking typeset document using LaTeX. (I
have no idea what is possible with FOP, but pretty much everything I've
seen done with it looks ugly.) That's an easy toolchain to install,
comprising Chibi or Gauche, pandoc, and a basic TeX setup. I would very
much like it if the final Large Report, in its typeset version, has the
same ALGOL 60 Report flavour as all the previous Scheme reports. This
seems achievable in this approach. -- vincent