search

AnssiR66 / AlanStdLib

The Standard Library for ALAN Interactive Fiction Language
Other
6 stars 2 forks source link

Additional Library Assets Status #91

Open tajmone opened 4 years ago

tajmone commented 4 years ago

A quick reminder on some of the extra assets that were part of the StdLib distribution and might need to be updated or temporarily omitted from the v2.2.0 release. And some further notes on assets that should be moved around in the distribution package.

mygame_import.i

The mygame_import.i sample file probably needs to be revisited from start to end, to ensure it still matches the current state of the library.

We might have to consider to temporarily remove it from the list of additional assets mentioned in the StdLib Manual, and from the final distribution too, until it's fixed.

QuickRef and QuickStart Guides

The StdLib Manual mentions, in the Additional Resources section, among the assets that ship with the package, the following two documents:

... these would both need to be revised to work with StdLib v2.2.0, and also ported to AsciiDoc for consistency sake. Chances are that this won't be done in time for the mid-November ETA (unless we close the dev work earlier and find time to handle them), so I suggest marking their porting and update to a next release, and temporarily comment them out from the list of assets mentioned in the Manual section on Additional Resources.

Alan Cookbook 2

The Alan Cookbook v2 document was ported to AsciiDoc by @Dyskos and added to the alan-docs repository (see alan-if/alan-docs#138):

Since it also contains examples based on the StdLib, we need to update the examples code and the text accordingly (again, using externalized adventure sources to ensure code correctness).

I'm not sure whether we can do that while hosting the Cookbook on the ALAN Docs repo, or if we'll need to move it here to better integrate it with the StdLib.

Moving Assets Around

Also, it's worth mentioning that the following assets should probably be moved from the StdLib/ folder to extras/, for technically speaking they don't belong to the library sources folder:

AnssiR66 commented 4 years ago

I would agree mygame_import could be left out. We could also think whether it is needed at all? Would it be just as well if the game author uses other means to alter default messages? I added originally for the reason that it would be a quick way of altering multiple default messages at once. - Do you mean that if we remove the newgame.alan and testgame.alan files (and the compiled games) from the std lib distribution, where would this extras folder be situated (downloadable from the ALAN website, or where)? Or would this extras folder still be part of the library distribution package?

tajmone commented 4 years ago

I would agree mygame_import could be left out. We could also think whether it is needed at all?

Maybe we could temporarily remove it from the next release, if we don't manage to update it — although we should be able to update it, after all it more or less boils down to pasting code block from the current Lib sources and restore the original comments.

I've never used the mygame_import.i file, so I don't have a clear idea of its benefits, but during its revision, and reading through the whole Manual again, I should learn more about it.

Would it be just as well if the game author uses other means to alter default messages?

Personally, I think that the new lib_messages_library.i module is fairly easy for end authors to copy and adapt; it's now shorter, less cluttered and more intuitive to edit a copy of it. But maybe we can come up with some shell script that can always auto-generate/updated from the latest lib_messages_library.i, via some commented tags or some other hack, so we don't need to worry about mygame_import.i ever being outdated again.

Do you mean that if we remove the newgame.alan and testgame.alan files (and the compiled games) from the std lib distribution, where would this extras folder be situated (downloadable from the ALAN website, or where)? Or would this extras folder still be part of the library distribution package?

What I meant is to keep in the StdLib/ folder just the library sources and the README.html file (so authors can just copy the whole folder in their bew projects), and move newgame.alan and testgame.alan to the extras/ folder.

Whenever a new release is out on GitHub (or a user click on the download button on the repo), the generated end-user Zip archive will contain two folders inside:

  1. /StdLib/ — Library sources + CHANGELOG + COPYING
  2. /extras/ — additional assets:
    • /manual/ — the StdLib Man and its examples.
    • /tutorials/ — the Clothing Guide, its examples, and other tutorials.
    • mygame_import.i
    • newgame.alan
    • other docs (e.g. QuickRef, QuickStart, etc.)
  3. README.html — brief overview of the package contents, and version info.

So I've only removed the compiled adventures (no reason why end users can't compiled them on their own), and removed from the StdLib/ folder any files which are not strictly part of the library.

I though this reorganization of contents made more sense, including converting to HTML all the short documents, in case end users don't have a Markdown previewer.

AnssiR66 commented 4 years ago

yes, your suggestion of the content reorganization is fine.