Adopt ".a3log" and ".a3sol" Extensions for Transcripts and Commands Scripts

[Tristano Ajmone]

Feature Request

• In all Alan terps:
  • Use the .a3sol extension for generated commands scripts.
  • Use the .a3log extension for generated transcripts.
• In Arun, allow using both -l and -c switches in the same invocation, to generate both a transcript and a commands script during the same game session (using the above extensions to distinguish them).

By no means these extensions should be enforced on end users, they should be just the default extensions used by Arun and WinArun, with users being free to change them according to their will (just as it's today).

The proposal is more about providing official Alan extensions for transcripts and commands scripts which are more in line with the other native Alan 3 extensions (.a3c amd .a3r), making them uniquely identifiable as Alan related files, and with all the benefits listed below (the most important being the ability to configure editors to handle them as ISO-8859-1 files, and being aware of their context).

Rationale

• Intuitiveness
  • The .a3sol extension for commands script is more intuitive than just .log, for the .sol extension is commonly found in IF commands scripts (more often referred to as solution files).
  • The .txt extension proposed by WinArun is not suggestive of an IF transcript nor commands script (unlike .a3log and .a3sol), it's just the most common text file extension used on Windows.
• Consistency
  • The .a3sol and .a3log extensions are more consistent with the other Alan file extensions (.a3c amd .a3r), and they can be more intuitively associated with Alan in a single glance.
  • Currently Arun and WinArun use different default extensions for generated transcripts and commands scripts (.log the former, .txt the latter). Adopting these new extensions would add more consistency across the various Alan terps.
• Arun Benefits — Because Arun currently uses the .log extension for generating both transcripts and commands scripts, it can't create both in a single session via the -l -c switches (only one of them will be honored), forcing the player to first create a commands script, and then generate a transcript using the former.
• Editors Encoding — Because Alan requires ISO-8859-1 compliant files, using univoque extensions is far better than using common extensions like .txt or .log, which are often associated to UTF-8 encoding on most editors.
• Improved IDE Experience — Using different extensions for transcripts and commands scripts allows a better workflow with editors. As an example, see how the Sublime Alan package (created by me) can handle the .a3sol and .a3log extensions smartly, both in terms of custom color schemes, syntax highlighting, auto-completions and snippets, as well as encoding settings (ISO-8859-1).
• Git Repos — The .log extension generated by Arun is not ideal for Git repository contents, which often add the *.log pattern to .gitignore, or may have other auto-generated logs with the same extension (and often different EOL normalization settings).

[Thomas Nilefalk]

In the latest dev-build (back to incrementing numbers: 2108, but still only available directly from CI) the interpreter allows creating transcript and solution files from the same run.

Files are named .a3s for solution, and .a3t for transcript.

[Tristano Ajmone]

the interpreter allows creating transcript and solution files from the same run.

this is a wonderful feature!

Files are named .a3s for solution, and .a3t for transcript.

Thanks a lot for this! Having some unique extensions is going to help a lot.

I'll update all the various projects accordingly (it's going to take some time), and the Sublime ALAN syntax too.

[Tristano Ajmone]

the interpreter allows creating transcript and solution files from the same run.

So this could then be achieved without using redirections, but via a new dedicated command line switch?

Could you give me an example of how the new command is used? (I'll have to update all the build scripts to exploit this new feature, when the next Beta is out, and maybe start using it already in the dev branches when it's available in the Alpha SDK)

[Thomas Nilefalk]

So this could then be achieved without using redirections, but via a new dedicated command line switch?

Aah, you did not know/remember/realise that the options already existed? Yes, using the command options to arun will create the transcript and command logs without the need for redirections.

arun -l -c <game>

The same switches are used now, but the difference is that they now don't interfere with each other. Previously which one took precedence was "random". And of course that they have dedicated extensions.

The switches are documented in the alpha manual.

But maybe that should also say something about how the files are created. Something like

The logging options, -l and -c, will create a new file with a name that is the combination of the game name, a time stamp and the appropriate extension in the current directory and write the log in it. The options can be used simultaneously and will then create two files with differing extensions for the two types of logs.

But to be extra explicit, it is only output. You have to use command redirect to get arun to read from the command file. Unless the first command is

> @input

But you would still have to get that into the interpreter, so there's a Catch 22 there ;-)

(And before you ask, yes, it would be possible to add an interpreter option to start reading from a command file without player intervention ;-), and I'm gonna add it to the backlog, as I can see some merit in having it. Not high prio though.)

[Tristano Ajmone]

Aah, you did not know/remember/realise that the options already existed?

Not really, my memory is vague on this. For some reason, I've been using output redirection in all the various toolchain scripts. I don't remember why, but I think it was to avoid the timestamp in the generated transcript, since I track them in the repositories to either catch diffs or because some AsciiDoc documents need to selective include tagged regions of the transcript (dynamic code in documentation).

arun -l -c <game>

If I remember correctly, the -c option is to capture the player input (commands) into a separate file which can then later be used as a solution file; whereas -l simply dumps to a transcript the whole text going through the interpreter (player input and adventure text alike).

The switches are documented in the alpha manual.

maybe some extra text clarifying what the switches do exactly, along with some practical examples, would be nice.

Also, the Alpha Manual states:

• -c log player command input to a file ('.a3i')

Shouldn't that be .a3s (instead of .a3i), as mentioned above? — please tell me it's just a typo! 😢 because I've already updated the whole Sublime Alan package to enforce the new .a3s extension!!! And it wasn't a minor change either, since it affects all semantic scope names for solution files and their snippets, themes, auto-completions, etc.

But to be extra explicit, it is only output. You have to use command redirect to get arun to read from the command file.

OK. I though that there was a new option to specify both the solution (input) and transcript (output) in a single command. But then, if the timestamp can be avoided (e.g. by specifying an explicit transcript filename, or via an addition switch) it doesn't change much in respect to automation of the documentation projects.

It's also worth considering that now that we have formal file extensions for transcripts (.a3t) and solutions (.a3s) it becomes simpler for ARun command line options to infer if a specified filename refers to one or the other — e.g. the hypothetical command:

arun -l -c ending1.a3t walkthrough1.a3s

could be correctly interpreted as if it had been typed:

arun -l walkthrough1.a3s -c ending1.a3t

i.e. even if filenames are not in the correct position relatively to the switches their context is clear thanks to their extensions. I'm not sure if this has any potential benefits, but it might in the future.

[Thomas Nilefalk]

Aah, you did not know/remember/realise that the options already existed?

Not really, my memory is vague on this. For some reason, I've been using output redirection in all the various toolchain scripts. I don't remember why, but I think it was to avoid the timestamp in the generated transcript, since I track them in the repositories to either catch diffs or because some AsciiDoc documents need to selective include tagged regions of the transcript (dynamic code in documentation).

NP. You can't keep track of everything. As I use a lot of automation to there has been a -r ("regression testing") option to arun for decades to ensure that any output does not include dates, version or other strings that would lead to unnecessary differences. It also removes the timestamps in the log file names...

arun -h

arun -l -c <game>

If I remember correctly, the -c option is to capture the player input (commands) into a separate file which can then later be used as a solution file; whereas -l simply dumps to a transcript the whole text going through the interpreter (player input and adventure text alike).

Exactly. And again, that already worked, what's new now is that you can get both with a single run. As requested in #2.

The switches are documented in the alpha manual.

maybe some extra text clarifying what the switches do exactly, along with some practical examples, would be nice.

Also, the Alpha Manual states:

• -c log player command input to a file ('.a3i')

Shouldn't that be .a3s (instead of .a3i), as mentioned above? — please tell me it's just a typo! 😢 because I've already updated the whole Sublime Alan package to enforce the new .a3s extension!!! And it wasn't a minor change either, since it affects all semantic scope names for solution files and their snippets, themes, auto-completions, etc.

Sorry about that, yes, it was a typo but I had also forgotten to publish the last version where it was fix but was in the repo. I've done that now and also added some more elaborate descriptions.

But to be extra explicit, it is only output. You have to use command redirect to get arun to read from the command file.

OK. I though that there was a new option to specify both the solution (input) and transcript (output) in a single command. But then, if the timestamp can be avoided (e.g. by specifying an explicit transcript filename, or via an addition switch) it doesn't change much in respect to automation of the documentation projects.

As mentioned above the -r should make a difference. And if you create both the command log and the transcript you can do that in one run. But then again, if it works, and don't take too long, there's no immediate need to change your procedures.

(I've long thought about improving my own regression testing tool, Jregr, with parallel execution of tests, but now that running all 1500 test in the Alan suite only takes a couple of seconds, that is no longer a need. Don't fix what's not broken or can give some other upside. Although it might still be an interesting challenge...)

It's also worth considering that now that we have formal file extensions for transcripts (.a3t) and solutions (.a3s) it becomes simpler for ARun command line options to infer if a specified filename refers to one or the other — e.g. the hypothetical command:

arun -l -c ending1.a3t walkthrough1.a3s

could be correctly interpreted as if it had been typed:

arun -l walkthrough1.a3s -c ending1.a3t

i.e. even if filenames are not in the correct position relatively to the switches their context is clear thanks to their extensions. I'm not sure if this has any potential benefits, but it might in the future.

I'm not sure what you are thinking here. I read the "hypothetical" but don't understand what that means, exactly. To be clear, you cannot decide the names of the output log files on the command line to arun. The name patterns are fixed. You can opt to not have the timestamp in them but the basename will be the name of the game.

[Tristano Ajmone]

As I use a lot of automation to there has been a -r ("regression testing") option to arun for decades to ensure that any output does not include dates, version or other strings that would lead to unnecessary differences. It also removes the timestamps in the log file names...

I've been using this option too, to ensure same-randomness across every test, to avoid diffs in the transcripts. But I didn't know it would also remove the timestamp. Depending on the context, it might make unnecessary redirection to the output transcript, if the expected transcript name matches the adventure — but in the test suites, often the transcript is expected to match the solution file, because there are multiple tests for each single adventure.

Sorry about that, yes, it was a typo but I had also forgotten to publish the last version where it was fix but was in the repo.

OK, that's a huge relief.

I've done that now and also added some more elaborate descriptions.

They are good, they clarify better the purposes and real case uses of these options.

I'm not sure what you are thinking here. I read the "hypothetical" but don't understand what that means, exactly. To be clear, you cannot decide the names of the output log files on the command line to arun. The name patterns are fixed. You can opt to not have the timestamp in them but the basename will be the name of the game.

Hence the "hypothetical". I was just brainstorming on the possibilities these extension might add. E.g.:

arun walkthrough.a3s mygame.a3c

could be safely understood by ARun as meaning: Execute the "mygame.a3c" adventure using the "walkthrough.a3s" solution script as input commands. I.e. the context becomes more obvious, making use of switches needless in some cases. I was just wondering whether this could dispense of the canonical switches/options pattern in some use cases, making ARun's invocation more natural like. (no Nobel-prize intuition here, just sharing some thoughts)

[Thomas Nilefalk]

I'm not sure what you are thinking here. I read the "hypothetical" but don't understand what that means, exactly. To be clear, you cannot decide the names of the output log files on the command line to arun. The name patterns are fixed. You can opt to not have the timestamp in them but the basename will be the name of the game.

Hence the "hypothetical". I was just brainstorming on the possibilities these extension might add. E.g.:

arun walkthrough.a3s mygame.a3c

could be safely understood by ARun as meaning: Execute the "mygame.a3c" adventure using the "walkthrough.a3s" solution script as input commands. I.e. the context becomes more obvious, making use of switches needless in some cases. I was just wondering whether this could dispense of the canonical switches/options pattern in some use cases, making ARun's invocation more natural like. (no Nobel-prize intuition here, just sharing some thoughts)

Ok! Right. Thanks for sharing ideas.