adv3Lite observations and some questions

[jford]

After a somewhat intensive emersion into the adv3Lite docs and tutorials, I have some comments about the Lite library and some questions about usage.

Comments first—kudos to Eric on a job well done. I have not been using the old library long enough to have a firmly held opinion about it per se, but I did get far enough into it before deciding to give Lite a try to appreciate both the power and the complexity of the, for lack of a better name, adv3Heavy library.

Now, having read the Lite library and tutorial manuals, and having worked through each of the three tutorial projects, I can see that Lite quite nicely achieves its goal of simplifying without sacrificing developer control. So, again, kudos.

And then the questions:

1. In the Airport tutorial, the display board in the Gate area is defined as Distant. Tutorial text says this is to make all commands other than Examine respond with a “too far away” message. This results in this incongruity…

examine board
The display imparts the following information:
TI 179 to Buenos Aires BOARDING GATE 3
RO 359 to Mexico City DELAYED
PZ 87 to Houston DELAYED
BU 4567 to Bogota DELAYED

…but…

read board
The display board is too far away.

How can I override the Read command so that it would behave the same as Examine? I tried this…

dobjFor(Read) asDobjFor(Examine)

…but it did not work. I tried adding it first to the gateArea room and then to the Distant display board definition, but no luck either time. Can it be done? How? Why did the override not work here?

2. At the beginning of the Airport game, before entering any other command, I enter Hint and the game responds with boilerplate text…

hint
Sorry, no hints are currently available. Please check back later.

If I were perverse enough that I wanted my text in place of “Sorry, no hints…etc.” what object would I change? (I tried to modify the Hint class, but could find no available hook to get to the text stream.)

3. Similarly, my own code for an ATM machine now works in its Lite incarnation but with text I’d like to override.

I first implemented the ATM using the Heavy library (and based on the sample.t code distributed with a basic TADS installation). Without that code, multiple bills from the ATM were listed individually, as “a 20 dollar bill, a 20 dollar bill, a 20 dollar bill, a 20 dollar bill, and a 20 dollar bill.” With the aggregaton code, it became “five 20 dollar bills”.

Lite actually handles the situation nicely without the need for a custom coded aggregator, so score one for simplicity.

However, it’s not perfect…

look in wallet
In the wallet Harry sees five 20’s and a credit card.

It should be 20s, not 20’s (it’s a plural, not a possessive). Can I edit that string? What’s the hook for capturing it in code prior to display?

4. And finally, an RFE.

Eric, does your authoring system for writing docs provide an easy means for generating PDFs?

I find the HTML files a bit difficult to use as learning tools. I guess I’m old school, but I like a hard copy that I can flip through manually. I printed your docs from the HTML and put them in binders, which is better than nothing, but there is no index, no page numbers, no book-search capability. PDFs would solve at least the last two of those things. (Actually, I use them both—PDF and HTML—side by side, for the best of both worlds, but if there can only be one, I’d much rather have the PDF than the HTML.)

Thanks.

Jerry

[Eric_Eve]

@jford

Now, having read the Lite library and tutorial manuals, and having worked through each of the three tutorial projects, I can see that Lite quite nicely achieves its goal of simplifying without sacrificing developer control. So, again, kudos.

Thanks! (Both for giving it a go and for your kind comments). I’m glad it’s working well for you so far.

@"jford

1. In the Airport tutorial, the display board in the Gate area is defined as Distant. Tutorial text says this is to make all commands other than Examine respond with a “too far away” message. This results in this incongruity… How can I override the Read command so that it would behave the same as Examine? I tried this… …but it did not work. I tried adding it first to the gateArea room and then to the Distant display board definition, but no luck either time. Can it be done? How? Why did the override not work here?

The solution is to add the following to the display board object:

    decorationActions = [Examine, GoTo, Read]
    readDesc = desc

You could use:

dobjFor(Read) asDobjFor(Examine)

But

readDesc = desc

Is slightly less typing.

What’s going on here is that the Distant class is a specialization of the Decoration class. A Decoration class handles all actions with dobjFor(Default), except those actions that are specified in its decorationActions list, which by default just contains Examine and GoTo. The reason dobjFor(Read) asDobjFor(Examine) didn’t work is that if Read isn’t one of the decorationActions, the Read action gets handled by dobjFor(Default) before the asDobjFor(Examine) has a chance to take effect.

@jford

2. At the beginning of the Airport game, before entering any other command, I enter Hint and the game responds with boilerplate text… If I were perverse enough that I wanted my text in place of “Sorry, no hints…etc.” what object would I change? (I tried to modify the Hint class, but could find no available hook to get to the text stream.)

The message “Sorry, no hints…etc.” is generated by the showHints() message of the hintManager object in hintsys.t. At first sight it may look a bit awkward to customize one message deep in the code, but the easy way to do it is with a CustomMessage object, like so:

CustomMessages
    messages = [
       Msg(currently no hints, 'You\'re too soon for hints! ')
    ]    
;

(This is explained more fully in the Messages section of the manual).

@jford

It should be 20s, not 20’s (it’s a plural, not a possessive). Can I edit that string? What’s the hook for capturing it in code prior to display?

You’re quite right that the apostrophe is incorrect there. The adv3Lite routine that groups identically-described objects in lists uses the LMentionable.pluralNameFrom() method borrowed from the Mercury library. This in turn calls pluralWordFrom(), and it’s this method that seems to be causing the problem.

The comment in the method about apostrophe-S plurals states:

        /*
         *   Certain plurals are formed with apostrophe-s.  This applies to
         *   single lower-case letters; certain upper-case letters that
         *   would be ambiguous without the apostrophe, because they'd
         *   otherwise look like words or common abbreviations (As, Es, Is,
         *   Ms, Us, Vs); and words made up of initials with periods
         *   between each letter.  
         */

But this doesn’t cover the 20’s case. This is instead coming from a little further on in the method:

     /* for all-capital words (CPA, PC) or numbers, just add -s */
        if (rexMatch(acronymPluralPat, str) != nil)
            return '<<str>><<apost>>s';

Here the comment doesn’t match the code (bear in the mind that I didn’t write this particular part of the library; I simply took it over from the existing Mercury code). My best guess is that this is simply an error in the Mercury code, which I’ll fix in the next release. In the meantime you can patch your version of the library by searching for the above lines in english.t (in LMentionable.pluralWordFrom) and changing:

   return '<<str>><<apost>>s';

to

   return '<<str>>s';

To answer your other question, you can capture output prior to display using gOutStream.captureOutput(func), but it would be awkward to solve the problem that way, so I’d suggest using the solution described above. I’ve already made the change in my copy of the library.

@jford

Eric, does your authoring system for writing docs provide an easy means for generating PDFs?

No, I’m afraid it doesn’t; at least, not one that would really meet your needs. My ‘authoring system’ is simply Notepad++. Any appearance to the contrary is due to the fact that I used some files from the TADS 3 System Manual as templates for my own documentation files, and didn’t bother to delete the comments suggesting they’d been generated from something else. In fact, apart from the bits copied in the header and footer, it’s all hand-coded HTML.

A quick experiment just now showed that I can open the HTML files in MS Word and save them as PDF files, but just doing that doesn’t really provide much of an advance on printing out the HTML files. To produce a decently-usable PDF version of the docs would require a heck of a lot of work, merging all the files into one MS Word doc, editing out the irrelevant header and footer information, tidying up the formatting of the code samples where lines were too long for the page, probably manually applying styles to generate a decent table of contents, and then marking up the entire thing for indexing. This is not something I really want to contemplate doing right now, especially since either it would all have to be done again with each new release, or else I’d have to repeat any edits I made in the HTML version in the MS Word version too, which is the hassle I’ve ended up giving myself with the Tour Guide and Getting Started and which I’m absolutely determined not to give myself with anything else ever again.

(Originally the HTML and RTF versions of the Tour Guide and Getting Started were generated from something called Help and Manual, but what came out was not-quite-right HTML and not-quite-right RTF which then needed a lot of tweaking by hand, so that using Help and Manual to maintain both versions came to seem more trouble than it’s worth).

If adv3Lite reached a point where it was unlikely to change for several years, and if there appeared to be sufficient demand for a PDF version of the docs, then it might be worth considering, but as it is…