§3.3. Options: Misc. Problems

[tajmone]

@thoni56, there are some problems with §3.3. Options.

First of all, the syntax and the examples are unclear, possibly wrong.

Wong Example

According to the provided example, this should work:

Debug.
Language Swedish.
No Pack.
Width 128.

whereas in real use the compiler will complaint about the missing OPTION token:

101 E : Syntax error. Inserting "option" before this token.

Incomplete EBNF

The provided BNF rule is either incomplete or wrong:

option = id '.'
       | id id '.'
       | id integer '.'

Possibly it should look something like this:

options = 'OPTION' {option}

option = id '.'
       | id id '.'
       | id integer '.'

(I didn't have time to check the actual BNF grammars from the ALAN sources, but for the Manual it's more important that BNF rules are easy to understand, rather than matching the real grammar used by the compiler)

WIDTH Option Unclear

The Manual is currently rather obscure about the WIDTH option and its usage:

Width specifies how long the lines the interpreter outputs should be (formatting is automatic!). The Length option will instruct the interpreter on how many lines to show on the screen without any player interaction (<More>). These values are only used if the interpreter itself cannot get the actual values.

In the table it states that the default widht value is 80; in footnote 2 it further states:

2. Width and Length is overridden by the actual terminal or window size, if available.

Based on the information provided on width, the reader is left with many doubts and unanswered questions:

• Is width a recommended setting or a hard setting?
• How does the terminal size override the width setting in context like a script for writing game transcripts to file? (i.e. a script running in the background)

Real-Case Issues Examples

In more practical terms, I'm experiencing some hardship in the StdLib Manual toolchain, where game transcripts are being auto-generated and injected into the AsciiDoc source.

NOTE — Some documents in this repository also use generated game transcripts in their contents, so this wrapping issue also affects the toolchain of this repository.

Specifically, I'm having trouble to enforce wrapping at column 80 in the generated transcripts.

Generated transcripts are wrapping at 72, although the default WIDTH value is supposedly 80. Also, they often end the line with a space character.

I'm using I/O redirection to create the scripts (arun -r adventure.a3c < script.a3sol > transcript.a3log) maybe I should use the ARun -l option instead? If I remember correctly, I had opted for redirections to have better control on the output file naming.

In other words:

• How can I ensure that the game transcripts generated from the toolchain scripts will honor a specif width value and wrap at that column?
• I can't rely on the terminal window (Bash or CMD) having a specific constant width aspect, and need to ensure that the width value is enforced by a variable or constant under my control.
• Does the -l option differ from file I/O redirection in any respect?

I believe that the Alan Manual should cover similar information, and improving the section on OPTIONs would be a good start.

Adding to the confusion, the alan.exe -help output:

  -height <lines>   -- height of pages in list file (default: 74)
  -width <characters>
                    -- width of pages in list file (default: 112)

I guess these settings refer to the adventure's source code listings, and have nothing to do with game transcripts — but, again, the Manual could clarify this better, either in the sections dealing with the CLI tools, or in a dedicated Appendix on command line usage tips and tricks (which IMO is a needed).

[tajmone]

Possible BUG in ARun

After some fiddling around with the WIDTH option in the source adventures, I realized that the main problem is that the value is not honored correctly in the generated transcript, which tend to wrap before the expected column.

If set it to 80 it seems to fail to wrap at the longest possible line that doesn't go beyond that value. E.g. it would wrap at 72 even though the following word is 4 character only. The same applies to any other value, it tend to wrap earlier than expected.

Here's a real example generated from the StdLib repo, using the default setting of 80 (adding it explicitly yelded the same results):

The air in this gloomy tunnel is filled with foul smelling fumes. Your
eyes are itching and your lungs burning.

The output is being wrapped at 71, but the correct wrapping for the value 80 should have been:

The air in this gloomy tunnel is filled with foul smelling fumes. Your eyes are
itching and your lungs burning.

As you can see, there was space for two more words on the line.

Possibly it's a problem with the algorithm that handles line wrapping in the interpreter.

• Is the width value to be considered as inclusive of the max chars per line? (i.e. 80 = 80 chars, or 79?)

I have the impression that white spaces are being included in the computation, for output lines often have a space as their last character. This might be affecting calculation of the wrapping point, falsifying its value.

[thoni56]

I'm looking into these things, but I'd prefer to have these as 3 separate issues, although they are related. Then it is easier to talk about specifics and referring to issue numbers, and also closing them with commits. One of these issues (the one in the comment) should also be directed to the alan project.

Do you want me to split this up?

[thoni56]

So, I have

• created a new issue in the alan project for the possible wrapping bug (https://github.com/alan-if/alan/issues/19)
• fixed and pushed a documentation fix for the unclear BNF for options on master
• re-based dev-man to include that documentation fix
• fixed and pushed a fix to the compiler to handle "No Pack." which is available in a snapshot build (as I also managed to get the uploads to work again after my ISP changed the features available in the level I'm using)

So no need to split this. If you think all is handled appropriately you might consider closing this.

[tajmone]

Thanks a lot for handling it, and sorry for the late reply.

Yes, it makes more sense to split them. The reason I've packed them in a single initial Issue is just that I wasn't sure that all the point would constitute a valid problem, so I just though to trigger a discussion and then see how it went.

[tajmone]

@thoni56, I noticed that you didn't update the document date on master branch, so I've amended the commit with the date fixed (to distinguish the various editions of the Manual) and forced push to master. I've also rebased and forced dev-man on master (an rebuild the docs at each amend).

Hopefully these force pushes shouldn't affect any local work you're doing — since only the date was changed in the main Manual source file, you should be OK by rebasing and rebuilding the docs.

[thoni56]

Thanks. The dates and the generation of PDF and HTML are next things to tackle when it comes to streamlining the process, I guess.

[tajmone]

I hadn't thought about it, but I guess that it should be fairly easy to do by hard-setting the date attribute via the CLI.

Probably this is easier to do via Bash scripts, rather than Batch scripts. Right now the main obstacle in switching all scripts to .sh is asciidoctor-fopub, which doesn't seem to work using Bash for Windows (see #66).

Once I've solved that issue (I already have a solution in mind) I was planning to update the whole toolchain by reusing the scripts from the StdLib toolchain — where I've created some cool Bash functions to handle various ALAN related common operations (e.g. converting to UTF-8 for ADoc inclusion, and sanitizing the sources) via some "centralized" variables that handle repository paths (some dependencies tools require absolute paths in their invocation options).

As long as we can provide the date in the "written" format (e.g. "October 12, 2020") to the date attribute, it should be easy to enforce the date via the CLI invocation. I would still try to edit the date in the source document, whenever possible, for the benefit of anyone who handles the sources, but I guess that this could also be done mandatorily only when updating master branch, and not be so important in the dev branches.

[thoni56]

I was actually thinking more about not having the PDF/HTML in the repo and generate them in some CI-job, which would also update the date.

I haven't though much about this, I only felt that the manual steps of updating dates, generating the outputs and the merge problems that follow are un-necessary work (although no very hard) and could be removed.

But there are a number of follow-up questions from that which I have no ideas about any solution to. Yet.