A-code documentation

After many years I have finally sort-of finished the massive task of documenting the current version of Dave Platt’s A-code (developed for writing his Adventure 3, a.k.a. Adv550), as enhanced by myself for Adventure4+ (a.k.a. Adv660) and then for Adv770.

I know that I am far too close to the subject matter to make a proper assessment, so I would be very grateful to anybody willing to cast an eye on the result of my efforts and tell me whether it actually makes sense. All constructive comments are welcome (including typo reports, of course!), though if anybody feels that the lot needs re-casting, all I can say – if you are prepared to help, than maybe. :slight_smile:

I realise that few people have ever heard of A-code, but Adv550, at least has some historic significance (as does Mike Goetz’s Adv580), and I have a distinct impression that it had a strong influence on Malmberg’s Adv1000.

You can find the current version of the documentation at A-code documentation

There are still some bits that need adding. The debugging section still needs to be written and the styles document finished off. Ideally, I should also add lots more code snippets and maybe even a simple tutorial. But the bulk is done and I would very much welcome an outside view.

Thanks in advance to anybody willing to offer a view.

Mike

10 Likes

I have not yet taken a look, but thanks for doing all this!

1 Like

Are there any ACODE example/tutorial games?

2 Likes

I agree with the need for tutorial games. Writing games with machine language is a rather difficult task. Also, a single file PDF format, if available, would be nice.

1 Like

There is a heavily commented A-code implementation of Roger Firth’s “Cloak of Darkness” nano-adventure. You can find it on the Adventure downloads page at mipmip.org and it is, of course, also on Roger Firth’s Cloak of Darkness page (now gone from the net, but I retrieved a copy from the Way Back Machine – see Interactive Fiction Rescue.

1 Like

A-code is not any sort of machine language. It is a language developed originally by Dave Platt specifically for writing Adventure-style games. Far more readable than a lot of other authoring systems (IMHO, of course – I am biased! :-)).

As for a single PDF… I’d say it is far too complex for that.

2 Likes

Oh, I thought it would be as easy as doing pandoc html to pdf conversion. Any multiple pdfs can be merged with pdfmerge utility. I guess not everyone is on Linux. Never mind, then.

You are right and I was half-wrong – cibersheep has already kindly constructed rough-and-ready versions of both PDF and an ePub derived from my HTML. I am about to add them to the website. But what I really meant was that the documentation is a tree of documents and some serious thought would be required to serialise it into a single document with some logical flow to it. 'Fraid this is not something anywhere near my current priority list, but if you feel it would help – please feel free to have a go.

BTW, I am on Linux (Mandrake → Mandriva → Manjaro). Haven’t used anything else for decades (except some VM-based testing of my software on Windows and Macs). But document handling has never been something I needed to look into.

4 Likes

A new version of documentation, correcting a few glaring errors, is now at A-code documentation, including updated pdf and epub versions , thanks to @cibersheep. The pdf and epub files now feature their publication date in their names. Both are linked from the index page. Any further updates will be published in a similar manner.

Hope this helps.

3 Likes

I have created a git repo with a basic script to get a basic chain to create the epub and pdf.
It needs a way of fixing the TOC (I remake it in Sigil). While I find a way of automate that, I will keep updating them by hand :slight_smile:

I’m sure the code has bugs and maybe @ramstrong has an alternative to Calibre to build the docs with pandoc. Feel free to send your changes and fixes:

3 Likes

An updated version of the A-code documentation (March 12) is now available from the A-code tools and documentation page A-code documentation

It adds the section on debugging, corrects the name and use of the minor directive for dumping game data (formerly DUMP, corrected to DUMPDATA) and fixes a few typos.

Comments welcome!

3 Likes

New version of A-code documentation is now in place: A-code documentation

It removes the redundant “Rule 5” in the upward compatibility section, replacing it with a brief explanation of the use of the PROMPTED flag in the section describing the CONTEXT mechanism.

It also adds rounds off notes on historical development in the styles section and fixes some more typos.

As far as I am concerned, that completes A-code documentation, as it currently stands. I confess that I had no idea what a massive task it was going to turn out when I started on it a few years ago. Any comments (including typo reports and other criticisms :slight_smile: ) are welcome.

3 Likes

Is there a IFGE options? Seems to be missing from here:
https://mipmip.org/acode/doc/acode-language.html

Also, there is a large chunk right at the end of obsolete and deprecated commands all of which is a link to debugging and probably should not.

As a general point, it would benefit from more examples illustrating how the features are used, and what the point of them is.

1 Like

Please pardon my ignorance… IFGE options?

Thanks for pointing out the runaway link. Have fixed and uploaded the corrected version.

Agree about examples, assuming there is any interest in the documentation, other than as a historical document and an aid for anybody looking at sources of existing A-code games. One of my reasons for posting here was to find out whether it was worth the additional effort. So far, the lack of feedback is not encouraging. :slight_smile:

If I were to add examples of use of individual directives, how to you think it should be slotted it? I think it could be a mistake to overload the language section. Possible options might be a separate document (with links into it from the language document), or pop-ups resulting from clicking on a directive’s name or… Any suggestions? And would you be willing to look at work in progress to offer constructive criticisms?

1 Like

IFGE = if greater than or equal to.
It has IFGT, IFLT, IFLE, but no IFGE listed; I guess that is an error?

Not sure about suggestions, but I would be happy to look at work in progress.

1 Like

ROTFL! My apologies, I missed the obvious due to interpreting IFGE as “Interactive Fiction [something] [something]” – as in e.g. Gender Equality. :slight_smile: Yes, you are quite right, the IFGE directive does exist but I somehow managed to drop it from the list of minor directives. Have fixed – thanks!

Re options. I am not after technical advice, but after a reader’s point of view. And also, whether it is actually worth doing at all.

Thanks for willingness to check anything that might or might not come to being. As programmers tend to do, I am not good at documenting systems and writing that documentation took way more effort than I’d bargained for. If there is an interest, that would be a spur, but otherwise, nothing will happen in a hurry, if ever.

1 Like