Ch. 10. (my_game instance): Externalize all Library Excerpts

[tajmone]

• In lib_definition.i:
  • Remove the comments indicating which verbs use every response-attributes group.
• In Ch.10. The my_game instance and its attributes:
  • Don't list every response attributes group, but provide just some examples on how to customize them by editing the StdLib sources, if required.
  • Replace the required excerpts from lib_definition.i with include:: directives to import from the real code, and add region tag comments in lib_definition.i.

---

The chapter StdLib Manual §10. The my_game instance and its attributes is a real maintenance nightmare: as it is, we need to manually verify that the responses attributes definitions in the code excerpts from lib_definition.i actually mirror those in the StdLib sources. More over, listing manually all the verbs they apply to is an added layer of maintenance hardship.

The best solution is to adopt the dynamic-code inclusion approach (discusses in #82) and include the actual snippets from lib_definition.i. Also, avoid mentioning in the Manual all the verbs that use each attributes groups, but keep the list in the library source comments (most attributes already have such a list, but the comments need double checking and better formatting).

This would reduce the Manual maintenance work drastically, limiting it to comment the role and usage of some attributes groups in relation to specific verbs.

The above changes will preserve the original structure of Ch.10, but make it easier to maintain, more accurate and easier to read.

Future Benefits Considerations

The above changes will turn out even more practical with future editions of the StdLib. Thomas has already implemented the comments blocks feature which I requested, and it will be available in the next alpha ALAN releases.

Therefore, in future versions of the library we'll be able to exploit block comments to keep some parts of the Manual text in the library sources themselves. I.e., all text describing specific code sections (in the sources comments) would then become "includable" via Asciidoctor, so we will no longer have to worry about their text maintenance in the Manual, because both code excerpts and their description text will be imported from the sources.

Although this only alleviates maintenance of text relating to specific code snippets, in chapter like Ch.10 it would make a huge difference, basically leaving just a small introductory text in the Manual source file itself.

[tajmone]

@AnssiR66, the more I dig into Ch 10, the more I realize it's a real maintainance nightmare — both the Manual chapter and the Library source.

In the source file, the comments next to the message are often wrong, referring to a misnamed verb (e.g. ask_about instead of about), so both the source file and the chapter would need to be entirely revised — which is hardly doable if we want to come out with a new release by November.

Here is what I think ...

Chapter 10 doesn't really need to list of all existing messages, they are too many and it's rather pointless. If the end user wishes to customize the messages, he/she only needs to open lib_definitions.i in the editor and start working on it. Ch. 10 should only offer an introduction on how these messages work, providing a couple of selected examples to help the reader get confident with the system, but without covering every aspect — after all, the comments in the source file are there to make it easy to study.

Also, to preserve the current contents by including code excerpts from the real source would require tons of tag-comments, which would pollute the source file (we're not speaking of the occasional region-tag here, but basically enclosing within tag-comments every pair of response attributes!).

As for the lib_definitions.i, I personally see no reason of trying to keep an update list of all the verbs that use each messages group. What's the point? With any modern editor is only takes a few seconds to carry out a global search for an attribute in the Library sources, and there you have all their occurrences in the various Library sources.

Both of these issues only introduce a huge maintenance burden, at the cost of risking to end up with incorrect information (which is exactly the case, in the current state of affairs). Providing wrong info is worst than providing no info at all, and I think my arguments above are a valid case for dropping the associated verbs lists, and reducing Ch 10 in size and contents, making it an introductory guide on how to customize library messages.

In the future, with more time at hand, and with the possibility to exploit the upcoming new ALAN block comments, we can go back to that chapter and further improve it. But right now, I suggest we focus on the November update, and delivering Library source and a Manual that provide accurate information, getting rid of all the obsolete stuff.

So, if it's OK with you, I'd like to proceed with both tasks, keeping in Ch. 10 only that which is helpful to understand the messages system — a few invalid parameters example, the default messages for various features (restricted actions, the Hero, dark rooms, etc.), and leaving it to the reader to explore the lib_definitions.i source.

[AnssiR66]

Ok. Mind you, the purpose of v 2.0 and forward has been the making of accessing the library files unnecessary as far as possible and defining everything in the author's own game file, much like in Inform 7 where actually accessing the library is made very difficult. However, in StdLib 2 and forward, it has been necessary to edit for example the runtime messages in the library file directly, because I could not find a workaround for them. I also understand that it is not possible to make ALAN games exactly the same way as in I7, I mean, by making the library disappear wholly to the background. Accessing the library files has always been an essential part in designing games in ALAN, even with v2.1. One alternative would be to not offer any instructions for altering the check messages and syntax restriction messages etc. in the manual; these messages would be "hard-wired" (except for different language versions) and the author could only make additional checks of his own, not edit the existing ones. But this would make the language less flexible. So, I would be in favour of your suggestion, it actually sounds good and makes the author's learning curve shorter. We can proceed that way.

[tajmone]

Great!

I'm sure that in the second-next release we'll be able to come up with a better version of Ch. 10, and maybe even find some trick to allow end users to overwrite default messages without touching the sources (I actually already tested this, it's doable at the cost of adding some extra attributes; surely, it bloats the final adventure, but memory is so cheap nowadays that me might not worry about that — and even in a huge adventures, these extra attributes won't eat so much storage as adding an high-res image would).

Also, I was thinking that advances topics like this one could be kept in separate tutorials, in order to keep the Manual simple, for beginners (otherwise it might look scary).