Revising Manual Ch.5: Player Words & Allowed Chars

[Tristano Ajmone]

@thoni56, I've finished porting and cleaning up 5. Running An Adventure, but it might require some text revision.

I've taken the liberty to polish up some sentences wherever I was certain that it wouldn't affect their meaning, but in some places there seems to be either a problem with terminology choice, or the sentences are a bit entangled are not very clear.

I've annoted all comments and proposals in lines that start with a "// @" (eg: "// @TODO: ", "// @FIMXE: ", "// @NOTE: ", etc.), so sifting through the comments can easily be done via Search functionality.

Some revisions might be worth mentioning them here, while others are either self-explanatory notes or just some reminders for enhancements to the text that could be dealt with at any time in the future (jotting them down in th source code ensures that any contributor will see them).

Player Words and Allowed Chars

In Sec. 5.2. Player Input it's stated:

A restriction placed on the player input by the interpreter is that the words the player is allowed to use can only contain alphanumeric characters, underscores and dash.

This point might be expanded upon, as it's a rather important one. Some problems emerge with the above sentence:

• "alphanumeric characters" is rather vague as it could imply different characters ranges in different contexts (like in RegExs, for example), and often this definition includes the underscore, which would make redundant mentioning it separately. Futhermore, Alan accepts as valid words chars all letters supported in the encoding of the adventure, which would include also letters with accents, diacritics, etc., which usually don't fall under the "alphanumeric" category (even in RegEx engines, the term doesn't always include non-Ascii letters).
  • I'd rather use "letters and numbers" here
  • then mention somwhere that all letters supported in the encoding (ISO-8859-1 or others) are valid.
• The "dash" is rather confusing, as usually it's understood as either the en- or em-dash, which are not valid input in Alan as far as I know. Probably "hyphen" would be clearer. I can't actually recall using a dash or hyphen in player input. Any examples?
• Single quotes are not mentioned, but instances might include them in their name (eg: "rock'n'roll" or "Bob's cat").
• Double quotes and Strings-input is not mentioned either, and it might be worth at least mention it in an admonition note, if not in the paragraph itself. This would be a good place to either entertain a full explanation of how string input is seen by the parser, or to provide a cross-reference link to where the Manual discusses it.
  • Also, if I'm not mistaken, the range of valid characters inside a quoted string input is wider that the one of plain word inputs. Is it so?
• Although this specific paragraph focuses on the words of player input, the general context is that of player input, so it might be worth entering into more details (if not in this paragraph, in a dedicated one) about the use of punctuation and which punctuation chars are valid to the parser.
  • "?" Question marks can't be defined as part of Syntax definitions.
  • How does the parser handle the presence of unsupported chars? For example, if the player types "where am I?" and there is a defined syntax for "where am I" (the StdLib contains it), will that extra ? invalidate the whole input, or will it just be ignored and the input work?

In some of the above considerations I'm trying to imagine the sort of questions which might go through the reader's mind, and can actually recall having asked them myself while starting with Alan. So, I thought that these questions belong to this section, for it's probably the chapter that a reader would consult when studying similar issues.

As for the valid characters ranges, I've actually had to peek at Alan source code to work out the exact ranges.