StdLib Manual: Unified Examples

[tajmone]

What I would ultimately like to achieve with the StdLib 2.2 Manual is to take the various examples found across the document and turn them into one or more real sample adventures.

We're already using real adventures for the examples, i.e. source adventures that are for internal use, which get actually compiled and run with solution files in order to ensure:

1. That the examples still work with current StdLib code and ALAN compiler.
2. That the Manual always shows up-to-date code and transcripts.
3. That we can tweak the examples sources in real adventures, and the documentation with self-update without any copy-&-paste required.

Because sometimes the manual offers alternative examples, there are variations of the same example sources (otherwise we couldn't have same rooms/entities with different definitions).

Currently, only the short examples are actually deployed to the extras/manual/ folder, for end-users consumption. Most of the examples are taken from adventures for internal use only (i.e. their name starts with an _, so they won't be deployed).

I think it would be more beneficial to tweak all examples so that we can build a real sample adventure (and its variation(s), for the alternative approaches) that can be shipped to end user, so they can actually play with it and edit it to experiment what they've learned.

Many examples refer to a kitchen, a lab, or some other type of room. So we could create an adventure containing all these rooms, in a connected way. Some tweaks might be required to make the examples more consistent, but the good thing is that Asciidoctor allows us to selective hide some source details, as required.

E.g., in the real source file the actual definition of a room might contain extra details that are not relevant to the example:

THE livingroom ISA ROOM
  EXIT north TO garden.
  HAS floor_desc "There is an exquisite white carpet on the floor.".
  HAS walls_desc "The wallpaper has a nice flower pattern.".
  HAS ceiling_desc "A huge chandelier is hanging from the ceiling.".
END THE livingroom.

in the above source, the EXIT north TO garden. line is not relevant for an example focusing on custom descriptions of room objects. The way we're currently handling this in the manual is by selectively skipping the irrelevant lines when including the source snippet via tags:

-- tag::livingroom[]
THE livingroom ISA ROOM
-- end::livingroom[]
  EXIT north TO garden. -- Exit omitted in example!
-- tag::livingroom[]
  HAS floor_desc "There is an exquisite white carpet on the floor.".
  HAS walls_desc "The wallpaper has a nice flower pattern.".
  HAS ceiling_desc "A huge chandelier is hanging from the ceiling.".
END THE livingroom.
-- end::livingroom[]

We then include the example in the manual via the livingroom tag:

[source,alan]
--------------------------------------------------------------------------------
include::{utf8dir}/_variations1.alan[tag=livingroom]
--------------------------------------------------------------------------------

and the final code result in the book will be:

THE livingroom ISA ROOM
  HAS floor_desc "There is an exquisite white carpet on the floor.".
  HAS walls_desc "The wallpaper has a nice flower pattern.".
  HAS ceiling_desc "A huge chandelier is hanging from the ceiling.".
END THE livingroom.

... with the EXIT line omitted!

This is a very convenient approach that allows us to manipulate source files to suit examples needs, and reuse the same source code multiple times.

If we can make sure that all the examples of the book could fit into a single sample adventure (and its variations) it would be much better for us as maintainers of the docs, as well as for end-users — who will have access to the actual examples to play with.

Of course, all those tag-comments are stripped out from the sample adventures deployed in extras/manual/.

So @AnssiR66, if you don't mind me tweaking the examples a little bit (e.g. move an example to another pre-existing room, were it would fit better our needs and goals), I'd like to create a unified experience of the various sparse examples.

[AnssiR66]

Yes, sounds good again! Please go ahead..

[tajmone]

One-Adventure per Room

Right now, I think I'll start by creating a single adventure per room, except for examples that contain multiple rooms connected via exits and/or doors.

So, e.g., we'll have a livingroom.alan file for the Living Room examples; and likewise garden.alan, meadow.alan, and so on.

And then for the syntax variation examples, we can have garden_b.alan file, etc.

Right now, this is the quickest approach in development terms. Once all the examples have been externalized to real ALAN adventures, we'll be able to see if these can joined into a single adventure, or whether it might be more convenient to keep them as separate examples instead.

Maybe for the reader being able to focus at one example at the time is better.

Anyhow, let's proceed this way and see where it leads ...

[AnssiR66]

A good idea. Yes, let's go ahead! As always, let me know if there is something I can help with.

[tajmone]

As always, let me know if there is something I can help with.

I might have to ask you for the green light to do some radical changes, both in the examples and some chapters contents, if we want to make it before Christmas holidays — and polishing the English too, while I'm a it.

As I'm stating to externalize the code examples to real adventures, I'm discovering that many of them are broken and won't work (or even compile) with the current StdLib or ALAN — most of these problem aren't related to the latest changes (post 2.1) but must be due to them being very old and out-of-sync with the library.

The whole section on clothing needs to rewritten, due to the new changes in the clothing system, and the Clothing Table should either be removed entirely, or become merely an example of how authors could plan specific clothing implementations for their adventure — I was wondering if my "Clothing Tutorial" could be reused in that section, since it's already there, code an all.

Chapter "10. The my_game instance and its attributes" is a real nightmare — both in terms of formatting (ultra-long nested lists which are really hard to track in terms of what is under what) as well as for these verbs-attributes requiring to be double-checked, for most likely many of them no longer apply to the current verbs (that's what I found when translating the library).

For Ch.10, I'll do my best to exploit Asciidoctor's region-tags and include those attributes directly from lib_messages.i, so at least we're sure that the code in the Manual matches that in the library. Since I noticed that the verbs they relate to are already mentioned in the source comments, keeping that list of associations also in the Manual text is only double maintenance work — we should keep just one of them, either in the code comments or in the Manual.

Also, the way lib_messages.i is organized and commented, it should self-explanatory, so I'm not really convinced about the benefits of keeping such a long chapter in the Manual, instead of referring the reader to the source file (after all, 90% of Ch.10 contents are code excerpts from lib_messages.i).

Last but not least, the "Verbs Table", which I'm sure needs to be double-checked again (even though many entires were fixed here on GitHub).

I believe that contents that have aged to the point of being more confusing than useful should be simply eradicated, and then replaced in due time at some point the future, starting from scratch and a fresh view. IMO, it's more important to offer a Manual that contain working code, at the cost of shrinking it in size. And I also believe that re-writing from scratch some problematic chapters would ultimately lead to better versions thereof, and take less time than trying to fix them.

If you can find the time, please try to read the whole manual over again, and actually try out the code snippets and examples it provides, to get a general feeling of how it might feel on a newbie to ALAN and the StdLib — remembering that every time the newbie tries out an example and gets a compilation error he/she might get frustrated at ALAN and give up. Jot down a list of the sections which you think might need to fixed or improved.

Since many years have past since you wrote the manual, you should be able to look at it with fresh eyes, and with the hindsight of all the experience cumulated in those years since.

Mid November might seem far away right now, but it's quite a short time to revamp a whole book for a library that was itself revamped (many times over). I just think that if we miss the Christmas opportunity we might miss a good chance for our community to dive into creating ALAN adventures, until the summer holidays.