Improve Actors SCRIPTs

[Tristano Ajmone]

In the Manual, SCRIPTs need to be better explained.

For a start, the sections dealing with SCRIPT/STEP and Actor Statements (USE/STOP) are quite far apart to make it comfortable for the read to study the subject.

NOTE — In commit c2bd0b8 I've added some cross-refernce links on some keyowrds in those sections, to make it at least easy to quickly jump back-&-forth between the two sections.

Add Section on Actor Scripts in 6. Hints and Tips

Probably, a section should be dedicated to actor scripts in Ch. 6 Hints and Tips with more explanations and examples.

The topic is rather important one, and currently the Manual doesn't really get deep into it.

NOTE — I also suggest that the Hints and Tips chapter be renamed Tips and Tricks, which is more commonly used in these contexts.

Improve STEPs

The section on STEPs is not very clear. Mainly, both the BNF rules and the description of the valid expressions is too vague:

step = 'STEP' {statement}
     | 'STEP' 'AFTER' expression {statement}
     | 'STEP' 'WAIT' 'UNTIL' expression {statement}

The text says:

A step can be defined to be executed immediately, at the next move, to wait a number of moves before it’s executed or even to wait for a special situation (condition) to arise.

But it doesn't quite clearly associate these possibilities which the rule variants. Spelling it out in a list might be better:

A step can be defined to be executed:

• immediately (STEP {statement}),
• at the next move (STEP 'AFTER 1),
• to wait a number of moves before it’s executed (e.g. STEP 'AFTER 3)
• or even to wait for a special situation (condition) to arise.

The last point is the less clear, for when I tried complex expressions like checking that an attribute was equal to a certain value I'd get compiler errors stating that the expression in this context must be boolean. All expression should ultimately result in a false/true statement, so lacking examples I'm not sure how the last point might be fully used.

As for the code example:

Step After ticksLeft Of train
  "The train driver enters the train, and after a brief
   moment the train starts to move."

I find it ambiguos, for I'd intuitively think that ticksLeft would be of integer type. Maybe using more explicit attribute names and adding comments to the examples would help the newbie reader.

But I think that overall this section could do with a couple of more examples and explanatory text (even in view of creating a dedicated section for scripted actors in Hints and Tips).