Alan Manual Assets

[tajmone]

This issues tracks the status of required/missing assets for the Alan Manual.

Images and Illustrations

• [ ] Add missing images:
  • x (cover/preabmle) — the logo was reconstructed as a vector image to allow lossyless scaling.
  • [ ] Figure 1 (Ch.2, p.20 of PDF) — "The principles for and relations between a game description, a compiler, a game file and the interpreter"
  • x (Ch.2, p.33 of PDF) — "Relationships between the pre-defined classes.". Rebuilt in SVG using Dia Diagram Editor.

Transcripts

Although not strictly necessary, game and debugging transcripts could be maintained by adding a source adventure and a commands script (aka, solution file) in order to automatically generated transcript files — which could then be included into the document via include directives.

This approach might have some added benefits in terms of maintainance, especially for debugging and -h output, as it would allow always showing the output of the latest compiler/interpreter versions.

But the generated transcript will need some styling (bold, italic) before it can be included into the Manual, in order to comply with the styling conventions.

Maybe, the styling problem could actually be worked around by customizing the source adventure to include AsciiDoc formatting markup in name locations (eg, *Kitchen*); but styling the player input in italics would still need to be done via RegExs substitutions on the final transcript (at the most, the prompt could be set to "> _", to initiate italics, but I can't think of any way to add the closing _ at the end of the input line via the adventure itself).

Another solution might be to create an ad hoc syntax definition for Highlight, which would then automatically style transcripts via syntax highlighting (like I've done in Sublime Alan, with the Alan Transcript syntax). This solution wouldn't require usage of any AsciiDoc markup formatting in the transcripts.

[tajmone]

First Auto-Generated Transcript

In order to reconstruct the compiler log shown in Appendix "F.1. Format of messages", I've created a pseudo-adventure and some automated scripts that output the same log as the original show in the PDF (except that compiler messages are now slightly different):

• /manual/src_scripts/:
  • ZILexample.alan — source adventure to recreate original compiler log of F.1.
  • ZILexample.bat — batch to update compiler log.
  • ZILexample.log — Compiler log shown in "F.1. Format of messages".

Also, I've added AsciiDOc callouts to the literal block, which is easier to maintain (otherwise I would had to use a screenshot edited with photoshop to overlay the boxes).

This is the first example of how, in the future, all game transcripts (including debugging) and compiler logs shown in the Manual could be produced via automated scripts, Alan source adventures and commands scripts.

This would have the advantage of allowing to easily update all logs to the more recent compiler messages (like in the example at F.1), and grant access to all required sources in case editors need to tweak the output.

Tweaking The Example?

As for the compiler log currently shown in the Manual, I think that a better example could be provided by generating two errors on the same line — this would better exemplify how message pointers work.

If it's OK with you, I'd tweak the above mentioned Alan source in order to produce a log with 2 errors on the same line.