Man: Part "Introduction" Pending Updates

[tajmone]

The initial Introduction Part needs to be re-organized better, and it needs some fresh contents.

• [ ] Chapter 1. Who Needs a Library? has been revised up to where there's the horizontal ruler; the text after the ruler is the original text, which is somehow redundant since there's Ch. 2. Importing the Library on that topic:
  • [ ] Remove all text after the ruler.
  • [ ] Sec. §1.1. Additional Resources lists the various additional assets that are distributed with the StdLib package. Currently the unported assets have temporarily commented out and excluded from the final document (until ported to AsciiDoc and updated to the current Lib status):
    • [ ] The testgame.alan asset, showcasing the features of the library, might need to be updated to:
      1. Ensure that it works with latest StdLib.
    • [x] The mygame_import.i file is out of synch with the latest library, so it might need to updated accordingly. drop it:
      • [ ] Remove references to mygame_import.i from the Manual.
        2. Provide usage examples of the latest features.
    • [ ] The Quick Start Guide and Quick Reference documents still need to be ported to AsciiDoc
  • [ ] Sec. §1.2. Where to Start:
    • [ ] It should really be split into an independent chapter of its own.
    • [ ] It also needs some polishing and additional text, although cross reference links to address the reader to specific sections won't be available until some of the present contents are re-organized in their final form, and assigned proper anchor IDs. Still, having now dropped from this section some of its original sub-sections (i.e. those on previous versions of the library), the present contents look rather slim, and might benefit from some revision.
  • [ ] Sec. §1.3. Typographic Conventions — @tajmone will handle this section:
    • [ ] It should really become and independent chapter of its own.
    • [ ] Its contents need to be revised, but we need to wait that the new ALAN syntax is ready, which will also color the StdLib predefined items, at that point we can illustrate the new coding conventions (see #86).

[tajmone]

@AnssiR66, would you take care of

• Updating the testgame.alan adventure?
• Sec. §1.2. Where to Start?

mygame_import.i

As for the mygame_import.i file, is it worth keeping it at all? Having to manually update it every time the library changes is a bit of a burden, unless we find an automated way of extracting the required attributes definitions from the latest library sources.

I've never used this file, so I'm not sure how it works. But if we don't find an automated solution to its maintenance it's going to become a liability on the long term. If it's purpose is just to offer a selection of the LISTING_BLOCK attributes for message responses, then we could easily use some comments tags to mark contents that need to be exported to this file, and use a templating system of some type (Mustache?).

Regarding this, I was thinking in the past couple of days that, since we're adding all those AsciiDoc region tags comments to the StdLib sources, and we might even add further comment markers for automatic generation of mygame_import.i, we could keep the development sources of the StdLib separate from their final distribution files, and generate a "filtered" version for the final package, where all these markers comments are stripped off (just like we're doing with the .alan examples that we're distributing in extras/). If we do this, we don't have to worry about the StdLib sources starting to look ugly due to all those marker comments that are creeping in, for end users won't see them in the final distribution.

[AnssiR66]

Mygame_import is not that necessary and might just make things more complicated. I think we can very well let go of it, and keep the library more simple (even if mygame_import.i is not a part of the library anyway, just an auxiliary file). But it is true, keeping it always up to date with the library would be unnecessary extra work.

[tajmone]

OK, then. If I can come up with an easy way to autogenerate we can always put it back. But, on the other, with the library messages now being in an isolated module, it should also be easier for author to just copy the file and edit it, or copy and paste the desired attributes.