search

AnssiR66 / AlanStdLib

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

2.2 Dev: Library Code Discussion #68

Open tajmone opened 5 years ago

tajmone commented 5 years ago

This Issue is a thread for discussing and planning all the changes that should be done to the Library code before the v2.2 release. These include bug fixes, enhancements, optimizations, etc.

For each coding tasks an issue will be created under the 2.2 Dev: Library Code milestone (or, in case of complex changes involving multiple steps, a dedicated milestone might be created), and as part of the StdLib 2.2 Dev project. This should make it easier to track the progress by topics.

tajmone commented 4 years ago

Pending Decisions & Postponing to 2nd-Next Release

@AnssiR66,

in order to proceed toward a StdLib v2.2 release we need to decide what is going to be fixed in this release and what is going to be postponed.

I think that if a bug or feature improvement is reasonably easy to deal with, we should try and fix it now. However, if we decide to postpone it, we should at least document them in a "Known Bugs" section in the main document that ships with the library (its README, or whatever the doc will be), and mark them for the second-next release (via a new label or milestone).

Here are some links to labels grouping the various issues that need to be dealt with or postponed (some labels overlap same Issues):

If you could start by further commenting on these pending issues, we could then have a clear picture of what's left to be done.

AnssiR66 commented 4 years ago

Besides erasing the brief/verbose verbs, I think we could let the other bugs/misfeatures be for now. That way we can offer the latest version of the library as quickly to the userbase as possible...

From: Tristano Ajmone notifications@github.com Sent: Monday, August 31, 2020 10:09 PM To: AnssiR66/AlanStdLib AlanStdLib@noreply.github.com Cc: AnssiR66 anssir66@hotmail.com; Mention mention@noreply.github.com Subject: Re: [AnssiR66/AlanStdLib] 2.2 Dev: Library Code Discussion (#68)

Pending Decisions & Postponing to 2nd-Next Release

@AnssiR66https://github.com/AnssiR66,

in order to proceed toward a StdLib v2.2 release we need to decide what is going to be fixed in this release and what is going to be postponed.

I think that if a bug or feature improvement is reasonably easy to deal with, we should try and fix it now. However, if we decide to postpone it, we should at least document them in a "Known Bugs" section in the main document that ships with the library (its README, or whatever the doc will be), and mark them for the second-next release (via a new label or milestone).

Here are some links to labels grouping the various issues that need to be dealt with or postponed (some labels overlap same Issues):

If you could start by further commenting on these pending issues, we could then have a clear picture of what's left to be done.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/AnssiR66/AlanStdLib/issues/68#issuecomment-683974339, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABO2KHUGP37E2HRK6JSYKE3SDPYPJANCNFSM4HF5XD4Q.

tajmone commented 4 years ago

I agree, I was just looking into the other open Bugs Issues now, and #42 is really a harmless bug — it just leads to a different message, which still makes sense, so end users wouldn't even notice it. It's also quite tricky to solve, for various reasons, so we better leave it as it is, since we can't predict the impact of changes in entangled knots like those.

AnssiR66 commented 4 years ago

Wouldn't the bug/issue with floor/ground be handled with declaring "INITIALIZE FOR EACH o ISA OBJECT, IS takeable INCLUDE o IN allowed of floor. END FOR. " (And this initialize statement goes under "floor"?) And the same for ground? Or am I thinking too simplistically? Should I experiment with this, or is it more useful you apply this code in your test suite? If it is fixable so easily, we can by all means have it dealt with and not postpone it until later...

tajmone commented 4 years ago

Wouldn't the bug/issue with floor/ground be handled with declaring

INITIALIZE FOR EACH o ISA OBJECT, IS takeable INCLUDE o IN allowed of floor. END FOR.

(And this initialize statement goes under "floor"?) And the same for ground?

As mentioned in #42, I think this solution might lead to unexpected conflicts with custom user definitions. But while experimenting with the shift to SUPPORTER class, we might as well test this approach too.

By all means, this is going to be a pervasive change, with many side effects, so it ought to be done with due time at hand for ample testing (i.e. skip it to second-next release).

Revisiting the StdLib Core Design

Although today I'm not as fresh on the StdLib code as last year, from what I remember from the Italian porting work, I think there's a need to sit down and take a bird-eye view of the whole library structure again, to get a full view of its design structure, and see if the underlying design might benefit from some retouching.

Some parts of the library were build on the foundations of the older Alan Library (which, in turn, was build on the foundation of the ALAN 2 library), so there might be some old constructs that are not currently benefiting from newly added ALAN features.

Other parts of the library were "stitched-in" as the need arose, either to extend its features or to amend it according to ALAN changes. Some of these patches might benefit from being re-contextualized in the overall design.

One of the most important tasks (IMO) would be to provide a Design Documentation, explaining in a single document the design goals, the core classes and all the other various elements, and how they interact with each other. This would not only simplify future maintenance and development of the StdLib itself, but would also be of great use to end users wishing to extend the library in their games, or to produce customized versions of it.

This would also be a great occasion for us to regain full control over its design, allowing us to work with a clear vision and a good bird eye view.

Take, for example, the verbs tables found in the sources comments. As it turned out from the discussion in #33, its original intention has been long lost, and many of its entries were never updated and didn't match the current state of lots of verbs (I had fixed some of them while recreating the same table in Alan Italian, but I'm quite sure there are still problems there). By undertaking the task of revisiting the whole design of the StdLib, we'll be able to reformulate these tables as required, mirroring the current state of the library, and provide adequate documentation on its usage.

Definitely, the whole library would benefit from some updated comments in its sources — not so much for a full documentation, but for highlighting key points on how specific code parts might affect other parts of the library, and mentioning some non-obvious mechanism of ALAN at play in certain contexts (e.g. the fact that if an "implicit take" fails, the DOES part would never get executed — see #78).

The problem (IMO) is that the StdLib code-base has really grown in time, but due to the lack of a design blueprint documentation, it's currently quite hard to dive into and start tweaking it — during the Italian port work, I basically read all of its code many times over, reaching a point were I just knew what was where and doing what; but still ... I never understood some aspects of how certain elements relate to each other.

We've all learned from experience that if one doesn't actively work on/with the StdLib for a fairly long time (e.g. one year), then getting back to work on it is not as simple as one imagines — many details are simply forgotten, because there's so much at steak. Hence the need of a solid Design Documentation, which should always be up-to-date, and providing direct links to the relevant code sections, and provide up-to-date code samples in the documentation (something which the new AsciiDoc based documentation toolchain is now able to provide, thanks to the interconnections between documents and sources).

I do realize that might seem to be a hugely demanding task, but I truly believe that postponing it would only slow down work. Good documentation is what empowers programmers to take up from where they left (be it a month, a year or a decade ago), and it's what ensures that projects can outlive their creators, because good docs are the strongest incentive for third parties willing to take on projects created by others — and, trust me, the only thing which is worst than lack of documentation is outdated documentation!

What do you think?

AnssiR66 commented 4 years ago

It might be good to review where the library is at this point, of course. But are you referring to a whole new (separate) design documentation, in addition to the library manual? For the end user, I think things should be kept as simple as possible. Could this design documentation be integrated in the manual? And what is its actual contents? Your message made me also think - the core values of Alan are clarity and simplicity of use - things which attracted to me to it initially. Is the standard library in some way too large, or complex? Should something be left out? Or simplified? I mean, before we start tweaking the documentation, should we take a look at the library itself... I think everything works pretty well in principle, and the library does not change very much how a game would be coded compared to without using the library at all - I mean, with the addition of just the short snippet "The my_game isa definition_block. End the my_game." to the game code, you can design a game pretty much with reading Thomas's Alan manual only, and not reading the library manual at all, but having all the ease at your disposal that the library provides. And Thomas's Alan manual does contain Alan's design principles very well. I understand you mean some library-specific things that should be clarified, like the verb list in the library manual you mention. You have some first-hand insight into what things are unclear to you, because you translated the Italian version. If you can just pinpoint these issues concretely, I think I can edit the manual in some way to make things clearer, and if you feel you have something to contribute in the way of design principles, you can go ahead with that... these are just general musings. I am trying to think what would be the good concrete way to start the actual process.

tajmone commented 4 years ago

But are you referring to a whole new (separate) design documentation, in addition to the library manual? For the end user, I think things should be kept as simple as possible.

I meant a document specifically for library developers and maintainers, and of course anyone wishing to extend the core library in custom way — i.e. an advanced document, which I would exclude from the downloadable Zip for normal users.

Is the standard library in some way too large, or complex? Should something be left out? Or simplified?

That's hard to answer. Compared to common standard libraries from other IF Systems, no it's not too large (it doesn't include a dialogs framework, for example). As from the perspective of ALAN's philosophy — i.e. the idea that end users should create their own ad hoc world adventure from scratch — it might look rather big.

The problem with all standard libraries is that it's difficult to draw a line where the average need lies. For some users, TADS-3's library is too big, for others is just right, and the same goes with other systems. Possibly, ALAN users are more likely to be attracted by the "from scratch" perspective, but at the same time also have access so some helpers to begin with (common classes, verbs, etc.).

In an ideal world, ALAN would provide some sort of macro preprocessor which would allow users to choose which features to use and which to leave out from the library — e.g. they could leave out the clothing system, or the actions restrictions, according to need. Unfortunately ALAN doesn't provide preproccesing commands, so conditional inclusion (and manipulation) of the library sources can't be achieved natively — one might use a third party general purpose preprocessor for the task, and create a sort of "StdLib Wizard", which allows users to pick and choose features, and then produce an ad hoc set of library modules for their need. (I've tinkered with this idea, and it's doable, but it would add an extra layer of complexity to the project).

I think that the StdLib is a great starting point for ALAN beginners, which can then later on tweak the library itself (hence the need for a Design Documentation, to find their way into it).

You have some first-hand insight into what things are unclear to you, because you translated the Italian version. If you can just pinpoint these issues concretely, I think I can edit the manual in some way to make things clearer

You'll find my considerations and comments across the various Issues (both open and close ones).

But the Manual and the Design doc are two very different types of documents, in nature. The former is intended for users who want to learn how to use the library to create adventures, the latter is for developers who need to keep track of how the various elements interconnect and overlap, in order to know were to apply code changes and what sort of impact these might have on the general library.

Personally, I'd be very happy to work on this Design Doc, since it would serve both the StdLib and its Italian translation. I also feel a need for it, because it would allow me to quickly regain the greater picture of the library and its modules, whenever I didn't lay hands on it for months in a row.

Most likely, it's not even going to be a huge document at all: it will consist mostly of direct links to source files, some selected snippets followed by comments, and various tables and appendixes for quick consultation. The Verbs Table found in the sources' comments is a good example of something that belongs to the Design Doc (as well as the Manual, of course).

I do believe that there are still some loose ends in the design that need to double checked — e.g. during the Italian translation work I noticed that many verbs lack checks for when their are applied on the Hero itself — also, the Design Docs should set some guidelines and standards regarding the preferred way to handle similar cases: should there be a Hero check in each verb, or should we define verbs overrides on the Hero actor itself?

Advanced authors need to know this type of things if they wish to extend the library (or include more verbs in their adventure), and they should have a reference document to look things up, instead of having to sift through the library sources and try to work out things for themselves.

It is on this last point that the ALAN StdLib differs from the libraries of other IF systems: ALAN authors will always more of an "open design" mentality when it comes to libraries and their games, because of the ALAN philosophy of allowing custom game worlds, so chances are the advanced users will both wish and need to tweak the library themselves — and this should be a smooth experience, thanks to documentation.

I am trying to think what would be the good concrete way to start the actual process.

It would be harder to explain what I have in mind than to actually write the document itself — It's something that I started to draft for the Italian version, and which I was using as my own guideline in devising the various tests (which in turn I needed to check if the StdLib goals were working in practice).

Usually all IF standard libraries come with some sort of Design docs, so we can look at other systems for inspiration.

The Inform Designer's Manual is an excellent example (although it contains other topics too) because it goes into details of the whole logic of implementing pseudo-natural language interfaces for authors and players.

TADS-3's library is mostly documented in the library sources via comments blocks, which are formatted in a way to allow auto-generating the reference documentation in HTML via custom scripts:

The above provide some good examples of what advanced authors are looking for when they need to master a standard library and be able to tweak it, maintain it or further develop it.