Migrating the Å-machine specification to Antora

Technical Development Specifications
1

The Å-machine specification is currently stored in hand-formatted plaintext, with spacing and newlines arranged to make it look good in an 80-column monospace terminal with 8-space tabs. Unfortunately, this makes it look very bad on anything that’s not an 80-column monospace terminal with 8-space tabs (such as a phone, or my text editor with 4-space tabs).

A while ago we migrated the Dialog manual to Antora, the same tech used for the Z-machine spec (at least the modern, pretty version of it that I use).

I propose we do the same to the Å-machine spec. Cross-references are very nice when data types have to be compared, and if the 32-bit version takes off, it will be nice to have more elaborate formatting to flag which parts are word-size-dependent and which aren’t.

I’ve mocked up a quick conversion to show what it would look like. Ideally we could pull the “opcode semantics” section out into its own page, but this will do for a start.

What do people think? Any strong objections to this course of action?

4 Likes
2

Sounds like a great idea; what’s great is that the A-machine docs can live the A-machine repo, and we can update the manual to read from there as well as dialog (that’s one of the reasons I like Antora so much).

1 Like
3

How would we go about doing that? I know how to make Antora read different versions from different repos or branches, but not different projects entirely.

I agree that would be the best way of hosting this, though, so if you can set that up in the manual repository, I’ll put the spec stuff into aamachine/antora.

4

It’s as simple as adding further sources to the content stanza in the antora-playbook.yml file, and supplying an antora.yml file in the aamachine repo.

5

It’s now officially live! It could definitely use some work (hint, hint, people who are more proficient with Antora than I am), but I think this is already a significant improvement over the plaintext form.

Things that need figuring out:

  • How to make the version display as 1.0 instead of 1
  • How to make the navbar on the left not completely empty
  • How to split the “Opcode Semantics” chapter into its own HTML page (ideally while keeping the source in the same .adoc file)
  • How to tag certain (not all) releases as having new spec versions
  • How to allow linking to the latest version of the Å-machine spec without specifying what version that is

For the moment, I’ll be maintaining the plaintext and asciidoc versions of the spec in parallel. That may change in the future.

1 Like
6

I’ve also got it set up to bundle the generated HTML into each release. It doesn’t have an index.html file, though; you have to search through the directories to find the actual HTML. I don’t know why. It seems like the Antora playbook is exactly the same as the Dialog one?