lib_verbs.i — Group Verbs in 3 Categories

[tajmone]

@AnssiR66, I propose to carry out the following code clean-ups in lib_verbs.i to make the module both easier to edit and study:

• [x] Group Verbs into 3 Macro-Categories (alphabetically sorted in each group):
  • Gameplay Meta Verbs — extradiegetic commands relating to the game session, rather than the adventure quest itself (i.e. META VERBS).
  • Player Commands/Game Verbs — commands directed to the main character (Hero) to interact with the adventure.
  • Question Verbs — commands that don't follow the usual form where the player imparts an order to the Hero (e.g. "take apple"), but instead are in the form of assertions or questions directed to the Hero himself (e.g. "Who am I?", "Yes", "Where is the treasure?").
• [x] Remove the Verbs Table from lib_verbs.i source into an AsciiDoc standalone document, which we'll provide as an HTML (PDF, etc.) document to which the player can refer to.
  • [ ] Create "Verbs Table" as a standalone HTML document in extras/.

---

Regarding regrouping the verbs in the 3 macro-categories, I've done that with the Italian Library and found that it greatly simplifies working on the sources, especially for META-VERBS, since you end having related verbs closer to each other (e.g. when working on restore and save). IMO, the "Question Verbs" (less than 10 in number) form a category of its own, and should be kept in a separate group; again, this makes sifting through them easier, since they'll be presented in the same place.

Usually, when one is editing or studying a meta verb (or a question verb), chances are that he/she'll need quick access to similar and related verb definitions, which is why splitting them into these three categories simplifies the task, by avoid long jumps up and down the source file.

As for the "Verbs Table," its maintenance inside the lib_verbs.i source is a burden, and a duplicate effort, since the table also appears in the StdLib Manual. We've already have ported the current table to a DSV file, for inclusion into the Manual:

• extras_src/manual/StdLibMan-inc_table_verbs.dsv

We can reuse the same file to create a stand-alone HTMl document for the "Verbs Table", and distribute it in extras/. In the lib_verbs.i source, we can refer the reader to that file instead of including that huge comments table, thus reducing considerably the size of lib_verbs.i.

This way, we'll have a single source file (the table in DSV format) to maintain, avoiding duplicate efforts and out-of-synch tables. The obvious benefits are that an AsciiDoc table provides rich formatting, and even dynamic links, whereas editing a table in ALAN comment lines is a horrendous editing task (with all the manual alignment to be done by adding spaces, etc.).

Whether we should keep the verbs in the "Verbs Table" all packed together, or also split them up in the same three macro-categories proposed for the source file re-organization, is entirely up to us, and we could evaluate the pros and cons of this — the only cons I can think of pertain looking up a verb; but I'd say that since these categories are fairly intuitive, users should actually benefit from this and be able to look a verb up in its table of belonging without too much thinking, really.

[AnssiR66]

Anoher good idea Tristano! Yes, we can think about the arrangement of the Verbs Table separately later on. We could use the Macro-Categories listing even there very well, instead of the alphabetical listing.

[tajmone]

OK, I've done the part concerning the reorganization of verbs in three groups — it actually took quite a long time, since I had to write some introductory text, and I also took the chance to handle some minor improvements (see commit message).

I'm pretty sure that I didn't leave out any META VERBS from the dedicated group, but let's keep an eye open, just in case (brief and verbose have been dropped, so they're no longer among them).

Help Needed With Intro for yes and no Verbs

@AnssiR66, I've marked in lib_verbs.i (line 8981) a "@TODO" comment for the yes and no verbs, where some introductory text is needed to present these two special verbs, and how they should be used.

Could you write the presentation text for these verbs? I haven't really had a chance to ever use them, so I'm not sure how to present them nor to come up with a usage example.

[AnssiR66]

Yes, I can do that. Basically, these verbs can be used in asking the player a yes/no question and disabling all other verbs, for example: "Do you want to restore a saved game (yes/no)?" When all other verbs are disabled, you can only type "yes" or "no", and the disabled_message can be set to "Please answer either 'yes' or 'no'."

Do you want to restore a saved game (yes/no?

look Please answer 'yes' or 'no'. take book Please answer 'yes' or 'no'. yes

etc. I will write a passage about this and send to you.