Dialog version naming

There will be different release tempos for these things. (Even if that is not true currently, it will eventually be.) A bug-fix library update should have a new version number – and that’s not an “at my own risk” situation, it’s a “you want these bug fixes” situation.

Or that!

The same may well wind up being true of the documentation. If there’s a typo in the docs, somebody will fix the docs. That shouldn’t require a whole new release of the compiler or the library!

That doesn’t necessarily mean the documentation needs a version numbering system. It may be sufficient to say “Docs for library 22, last updated Feb 7th”. But you have to think about them being updated separately, maybe even by different people.

4 Likes

This!

As a side note, the reason why the compiler version is written as 1a/01 is because there’s a small amount of space in the Z-machine header that’s never used by the interpreter, and it’s conventional to store a bit of metadata there (for later cataloguing and reverse-engineering purposes).

But there’s not a lot of room: one block of two bytes, generally used to store the release number (as a 16-bit number); one block of six bytes, generally used to store the compilation date (in ASCII, in YYMMDD format, conventionally called the “serial number”); and one block of eight bytes, generally used to store information about the language (in ASCII, first four bytes) and compiler (in ASCII, next four bytes).

This four-and-four arrangement started with Inform, which writes Info6.32 or the like into those eight bytes, but Dialog sticks with it, putting Dia in the first four and 1a01 in the next four. (The slash is inserted at runtime, not stored in the header itself.)

Having only four bytes of ASCII to work with makes it hard to do major.minor.patch versioning, since it means two of those fields get only a single digit each. Linus’s solution was to write the minor version as a letter instead, allowing 10 major versions, 26 minor versions, and 100 patch versions, before we run out of space.

(If we do eventually run out of space, we can either use letters for the major version too, or extend into the unused byte after Dia, or both. But given that the major version has never even been incremented once yet, that’s not really a problem for the present.)

2 Likes

This is also, by the way, why Dialog requires the game release number to be an integer, when you can put arbitrary text in all the other fields. Those other fields aren’t stored in the header, so they can hold whatever you want; but the release number needs to fit into a 16-bit word.