Mention How the AGAIN Message Is Tied to VISITS

[tajmone]

In App. C: Run-Time Messages, improve documentation of the AGAIN Run-Time MESSAGE. It currently reads:

AGAIN : "(again)"

This message is presented immediately after the location name if the location has been visited before to give the player the information that he has visited this location before (a good thing in some adventures). If you wish to disable this, set this message to an empty string. You can also control how often this message appears using the Visits statement (See Special Statements)

Actually, it's only shown in "brief mode", i.e. when VISITS is set to a non-zero value. This should be clarified. The text does mention that it can be controlled via "he Visits statement", but it's worth saying it explicitly.

Instead of providing an XRef to the Special Statements section, we should reference the VISITS Statement section directly, so that the player doesn't have to scroll all the way down to find it. We could also keep both ( Special Statements » VISITS Statement), but in this context it's only the latter that really matters.

Also, the VISITS Statement section doesn't mention that in brief modality the AGAIN Run-Time MESSAGE is shown after the location name. So we should mention it in this section too — possibly also explaining why the AGAIN MESSAGE is only shown in brief mode and not in verbose mode.

@thoni56, what is the rationale for showing the AGAIN text only in brief mode?

Hopefully, these small improvements shall clarify to the reader the connection between the VISITS statement and the AGAIN message, which are currently rather obscure.

[thoni56]

I think your suggestions are all valid and good. Agree also on pointing directly to the "VISITS Statement" is good.

As to the rational for only showing AGAIN in brief mode, as there is no brief mode built in I presume you mean with a Visits set so full descriptions are not shown every time. Or do you mean "only when the full description is not shown"?

I believe there is/was no precise reasoning for that decsion, perhaps just a feeling that with only the heading the player might need another clue on where they are, or have been before, as when the full description is given it in itself could be enough for the player to recognize it.

But if there are, more valid, reasonings for some particular behaviour, I'm not against considering them.

[tajmone]

As to the rational for only showing AGAIN in brief mode, as there is no brief mode built in I presume you mean with a Visits set so full descriptions are not shown every time. Or do you mean "only when the full description is not shown"?

Well, I think we should introduce in the documentation the terms brief/verbose as a way to describe the effects of Visits on the actual game session, after all these terms describe the actual behaviour in a way that most IF players will understand. Introducing these two terms (quoted or otherwise) would simplify any discussions about the Visits statement and its effects on the AGAIN message (which is only shown in "brief" mode).

I believe there is/was no precise reasoning for that decsion, perhaps just a feeling that with only the heading the player might need another clue on where they are, or have been before, as when the full description is given it in itself could be enough for the player to recognize it.

But if there are, more valid, reasonings for some particular behaviour, I'm not against considering them.

Sounds reasonable to me, after all authors can simply disable the feature by defining AGAIN as a null string if they don't like it. Also, there's room for interactive behaviour there, since MESSAGEs allow conditional code.

I haven't really given this much thought, for it's a feature I haven't used much. The only argument I can envision here is that some users might wish that the AGAIN text is shown every time the player returns to an already visited room, since this can't be currently enforced. But this argument is just as good as the original one in favour of only showing it in brief mode, so it's nothing more than a consideration on my side.

So far, I noticed that all (or most) of the ALAN libraries I've come across define AGAIN as a null string by default. I have no idea if this was done based on the preferences of library authors or because that's what most ALAN authors desired.

Since no one ever complained about the default behaviour, I'm in favour of leaving it as it, unless some authors start to ask for it to be tweaked.

[tajmone]

Fixed

@thoni56, I took the liberty to amend the text in those two sections without going through a PR, since we agreed on them and they involved minor text tweaks.

I hope it's OK with you.