Open tajmone opened 4 years ago
AnssiR66
commented
4 years ago ok Tristano, thanks for thinking about doing this. I'll be following how the work is coming along. I will also be writing (some of) the intro part for the manual we were talking about earlier, and letting you know soon.
tajmone
commented
3 years ago @AnssiR66, there are only 30 days left to the mid-November ETA, and I seriously doubt that we could manage to finish the new edition of the StdLib Manual — there's still a ton of work, and roughly a hundred code examples that need to be checked (and externalized) to ensure that they work correctly with the current library.
On the other hand, the library sources have been well polished, and all the major bugs resolved — the few that remain don't have any significant impact on how adventures will behave.
What I propose then is to create a "Release Candidate" of StdLib v2.2.0 (v2.2.0-RC1), which could then be announced on the mailing list by mid-November, with a download link pointing to a Zip file somewhere (e.g. on Google Drive). We could apologize for the lack of an updated Manual, and tell end users that they can refer to the current Live Preview of the WIP draft of the Manual which, although incomplete, it does already cover many of the new/edited features already, so it should be usable in that sense.
I think that we shouldn't miss the Christmas holidays, because they could be a good chance for some authors to find time to work on an ALAN adventure, especially since due the COVID lock-down many people will be spending their holidays at home.
What do you think?
AnssiR66
commented
3 years ago That's possible, then on the other hand, should the updated manual + v2.2.0 be released at the same time, for clarity's sake? I can provide to you various text passages in a rather quick timetable, for inclusion in the manual, if you give me a list (even cursory) of what I can contribute. I know that we talked about me providing something for the beginning (to replace 'what to read if you...' etc., on the other hand, you have been working on that, as well?). What did we agree about the long chapter with the listing of default attributes? To instruct the player to just ready it cursorily? But that it would still be there? As you've been updating the manual, for your part, as well, just let me know a brief update where I can help.. In any case, as you have been working on all of this more intensively as of late, and if you foresee that the manual might not be ready by mid-November in any case, I don't oppose a release candidate along the lines you suggested above.
tajmone
commented
3 years ago @AnssiR66, sorry for the late reply — I did actually write a long reply on the same day, but I must have closed the browser without publishing my reply comment, since it's gone lost. :-(
That's possible, then on the other hand, should the updated manual + v2.2.0 be released at the same time, for clarity's sake?
If we do that, then we should include some WARNING admonitions at the beginning of each chapter, mentioning it's current state in regard to the library. I've already started adding similar admonitions, but more as a reminder for ourselves, about what's pending to be done.
I can provide to you various text passages in a rather quick timetable, for inclusion in the manual, if you give me a list (even cursory) of what I can contribute.
Yes, that's a good idea. The best solution that comes to my mind is the above mentioned admonitions blocks techniques (i.e. adding the TODO notes directly in the generated Manual, so we can both see them), along with using Issues to coordinate work.
The main problem is that I don't have a clue of what really needs to be done. I.e., there's no "grand master plan" at work here, I'm basically dealing with one chapter/section at the time, and trying to work out what needs to be fixed, by looking into the Lib sources, testing via the test suite, and then start working on external examples, including them in the Manual and generate the transcripts.
In short, there's no way to know which original examples from the Manual still work until you try to compile them with latest ALAN and the current library. Maybe we should quickly go through all the examples which have not yet been externalized to real adventures (for internal use or deployed in the final package) and mark out those example that don't compile — some of them might not compile due to minor syntax errors (e.g. a missing .), while others might be totally out of synch with the latest library.
The problem here is that most of the Manual's examples come in the form of incomplete snippets (where the reader is supposed to imagine the missing parts), so in order to test them one needs to re-create the whole example into a full compilable adventure — which is, essentially, the same task as "externalizing" the example to a compilable adventure, and then dynamically include selected source snippets in the manual. This is why I'm trying to do this with all the examples as I start working on a chapter/section.
But if you could start to rebuild the current examples into full ALAN adventures, that would help. I then only need to add the AsciiDoc region comments to include the required snippets in the book, and we have an example that is sure to work. We don't need to distribute every single example adventure to the end user, some of them we can keep them for internal use (just to provide example snippets that are known to compile), in the latter case we only need to prefix the adventure name with an _ (e.g. _meadow.alan) and it won't be deployed to the extras/ folder.
I know that we talked about me providing something for the beginning (to replace 'what to read if you...' etc., on the other hand, you have been working on that, as well?).
The old sections for users of the very old library versions have already been removed. The "ALAN Newbies" section is drafted, but the "Standard Library Newbies" section is on hold because until the book chapters are re-organized it's not possible to provide specific links. But if you can write an updated introductory text for these sections it would be great.
Similarly, I was thinking that with the new book structure, it would be good to have some introductory text for Parts, Chapter, and Level 1 Section (I'm hoping to provide a symmetrically balanced structure to the final book, which is usually the AsciiDoc way of organizing contents).
Some chapters I haven't looked into them, so my guesses are as good as yours, therefore feel free to come up with suggestions.
What did we agree about the long chapter with the listing of default attributes? To instruct the player to just ready it cursorily? But that it would still be there?
Now that the old chapter on the my_game instance has been split into different topics (just like the lib_definition.i module has been split into three files), the library messages are now in a chapter of their own:
This chapter should be drastically trimmed down to a few basic examples to teach the reader on how to find the attribute containing the response for a specific verb, and to how edit it's default message.
I haven't even touched that chapter yet, but it's the one that's going to take the most work. Basically, almost all the current contents should be dropped, except those presenting special cases like Hero messages, score, etc., and we need a new text presenting the logic by which message attributes are named (i.e. the conventional use of _sg/_pl and other suffixes), and the above mentioned "mini tutorial" on how to customize the predifined library responses by overriding the original LISTING_BLOCK attributes directly on the my_game instance.
B.t.w. I've noticed that the Manual doesn't explicitly mention the fact that the my_game instance has the ability to override the the original LISTING_BLOCK definitions because the former is an instance of the latter, which it's a class; it might seem obvious, but for newbies it might not be so, so I think that's something worth mentioning very clearly in the "Getting Started" Part, where I think it's also the right place to briefly introduce the my_game instance, it's importance and usage instructions. That's another Part that needs some text updating, including:
I also think that there's a need for an Appendix dedicated to testing adventures via commands scripts (solution files) while developing a game, to ensure that edge cases are covered and that it doesn't break up during development — something similar to what's found in the i7 Manual, except that it will be all driven by scripts in this case (CDM batches under Windows, Shell scripts under Linux and macOS).
As you've been updating the manual, for your part, as well, just let me know a brief update where I can help.. In any case, as you have been working on all of this more intensively as of late, and if you foresee that the manual might not be ready by mid-November in any case, I don't oppose a release candidate along the lines you suggested above.
I definitely think that there's no way the Manual could ever be ready for mid-Nov! Even by working an average of 2-4 hours per day on the project, there's still too much to do. Also, we should ensure that the final release is really polished, whereas right now I'm typing fast, more draft-like than final version, so we should probably need a good final proofreading, possibly by someone totally fluent in English.
But a release candidate is still worth it, after all, don't forget that the library sources' comments have been update, so end users can always look at the in-sources documentation if they need to check out some details — not to mention that they can ask on the mailing list any questions.
Since the StdLib Manual is an ongoing-work, and we're always publishing an HTML Preview in the repo, probably the best solution is to tell end users to always check the preview link from the dev branch, which is being update almost on a daily bases, whereas if we give them an HTML draft chances are that they won't be looking at the live document, thus missing out any updates.
To conclude, you're right, we should start coordinating hour efforts, so each one can focus on specific aspects of the Manual. Now that the all the major code fixes have been dealt with, and the toolchain has been improved, we should focus on the Manual contents. Probably we should start opening an Issue for every single topic that we need to coordinate efforts on, to prevent long and dispersive threads and keep each contribution work focused. We can carry on discussing here the various areas that needs attention, and once we find a task to handle, we open a separate Issue for it.
Does it sound good to you?
tajmone
commented
3 years ago We already have a dedicated milestone for the v2.2 docs:
So, as we create some topic-specific Issues, we can associate them with that milestone, which makes it easier to filter through the pending tasks (we'll probably end up with many WIP issues before the Manual is finished).
I'll start right away to add some Issues for the various missing contents that come to my mind:
@AnssiR66, I though of creating this long-standing Issue to keep you up to date of what's going on in the development at all times. I'll be updating it from time to time, providing new info and preview links, so you can easily follow up with the ongoing work without having to read every Issue or commit.
Current Objectives
This what I'm focusing on right now:
THINGattributes that are currently in the "Library Classes" Part, so that the latter will focus only on the specialized classes created by the library.Converting all the toolchain batch scripts to Bash scripts, so we have a unified scripting system that will also work on Continuous Integration services (like Travis CI, Circle CI, etc.).Move into a Git submodule all the toolchain assets that can be shared with other ALAN projects, to lessen maintenance efforts (see #103).v2.2.0-RCpre-release, others will have to wait for the official release:wearandremove(#101) to allow custom non-clothing wearables.pourmust check if vessel is closed. (#108)floorandgroundverbs not executing. (#42)