Updated I7 Handbook

In another thread we’ve wandered into a discussion of how my I7 Handbook might be updated, or why I haven’t updated it since 2009, or something like that.

Some people find the Handbook useful. (At least one person has recently taken the PDF down to a copy shop and had it printed and spiral-bound. I’m flattered!) Not that the Handbook documents anything that’s not in Writing With Inform (it doesn’t). But it organizes and approaches the material in a different way, which some people may find appealing.

It certainly needs an update, though. It was written for 5Z17.

I started working on an update a few months ago, but got bogged down due to the rather unsettled state of I7 extensions. An extension I had recommended in the Handbook (Consolidated Multiple Actions by John Clemens) is broken – that is, it fails to compile in the current version of I7 – and I was unable to figure out how to fix it.

I’m sure it’s not the only extension that suffers from this problem. Secret Doors by Andrew Owen, for example – useful, and broken. I was able to fix that one myself. Sometimes all you need to do to fix an extension is search for the word “indexed” and delete it. But sometimes the challenge is more complex. And based on my very limited searching, it doesn’t appear that Writing With Inform explains how to update no-longer-functional code.

Ideally, what I’d like to have happen would be for some public-spirited person to write a longish appendix for the new Handbook, an appendix called “How to Fix Stuff That Doesn’t Work Anymore.” This would be useful not only for fixing older extensions when they’re needed but for fixing one’s own old games and example game code that others may have made available for download. My idea is that the results of the new code should be functionally identical to the results of the old code, or possibly better.

Unfortunately, I’m not competent to write such an appendix. But if someone is willing to tackle the job and wrestle it to the ground, I’ll go ahead and finish the updated Handbook. That’s my offer. It’s a big job, but I think it would be worth doing.

Any takers?

As an ESL speaker I doubt I’m competent to write the thing myself. I can really only offer suggestions. But Emily Short’s extension update guide should provide some inspiration. The latest release of I7 also sported a nasty bug when it comes to adding Images, at least last I checked, and since the only solution I’ve seen is rollback to 6L02, I can’t help but wonder if that would be the better choice for the guide.

According to the I7 website, 6L38 fixes about 150 bugs. For that reason, I’m reluctant to revert to 6L02.

Emily’s extension update guide is certainly useful as a starting point. It would need to be fleshed out quite a bit.

The fact that English is not your first language, if that’s your only concern, should not dissuade you. I’m a professional writer and editor. Polishing manuscripts that need a little more work is what I do. (Anyway, from what I’ve seen, you write very well.)

Quite possibly, the Appendix I’m envisioning could be a collaborative effort. Someone could start it, someone else could add to it, and then I could finalize the text and check everything.

Jim,

It was your handbook that got me started using Inform four years ago. I graduated to the Inform manual fairly quickly because I wanted to learn the complex stuff, too. But the handbook was a great, easy-to-follow guide for a beginner like me, with no programming experience.

I’d like to help you with the guide, but it sounds like what you’re looking for would involve more experience than I have, like familiarity with Inform 6 since some extensions rely on it. Still, if you are looking for help from someone who is fairly comfortable with Inform 7 and could update some old code or look at an outdated section of the guide, you can contact me. Of course, I’d be willing to contribute to a community effort to update the guide as well.

Neil

And that appendix would just say, “Read the Results pane when you try to compile and follow its advice”?

With regard to the Consolidated Multiple Actions extension, it did have some outdated I7 grammar issues, so I went through and fixed those, which let me get far enough to see the multiple I6 errors it was throwing, at least.

There have been some renamed constants and functions in the latest I6 update that accompanied I7 6L38, as (partially) documented here, and Consolidated Multiple Actions relies pretty heavily on some I6 includes. I did try renaming the extension’s references to these changed constants and functions, which fixed those errors, but only let me get as far revealing different I6 errors. So my point is that Consolidated Multiple Actions is essentially a lost cause unless the original author, or someone a lot more competent with I6 than I am, wants to update it.

My broader point is that the Handbook’s target audience probably mostly consists of people who don’t want to tinker with I6 code in the first place, and that fixing out-of-date I7 grammar tokens is usually as easy as reading the Results pane, so I just don’t see what the big deal is. My even broader point is that outside of a core few authors, I7’s extension authors have not been doing a great job of maintaining their extensions.

EDIT: Well, in fairness, as far as out-of-date I7 grammar goes, having a handy in-one-place reference, eg “You used to say [this], now you have to say [that]” would be pretty cool.

FWIW, I’m currently trying to get an updated version of Secret Doors into the public library. It was a partial dependency of one of my own extensions.

There is such a reference in the I7 changelog. It’s getting progressively buried by later releases though, and I’m not sure how many people will think to look there.

Well, no – to give just one example that I encountered yesterday, if the old code uses a procedural rule, the Results pane will NOT tell you how to rewrite your code so as to get the same results without using a procedural rule – and searching for the phrase “procedural rule” in the Search field for the Documentation produces exactly zero results. So in that case (which happens to be the first one that I tried), the Results pane is completely useless. It will tell you what line the error is on, but after that, you’re on your own.

Right. And my point is that it was a dandy, useful extension. For that reason, the changes in I7 have actually made I7 worse in at least one respect (and probably a few more). This bothers me. Perhaps it shouldn’t.

Nor should they have the responsibility for doing so. Inform 7 should have been designed in such a way as to insure backward compatibility.

The Handbook’s target audience, I would say, is people who would like to write good games without making themselves crazy trying to fix a bunch of I6 inclusions. If you have to fix a bunch of obscure stuff in order to write a game that presents text to the player in the way you would like it to, then I7 has failed. The purpose of the Handbook is ultimately to prevent that sort of frustration from happening, or at least to minimize the likelihood.

That would be nice, yes. There may be such a reference doc somewhere online. But at times (as with your experience trying to fix Consolidated Multiple Actions) there’s more to the process than substituting a new way of phrasing something. If I’m going to finish revising the Handbook, I would like it to actually address these issues. I’m not pleased with the idea that I should skirt them on the premise that nobody will really mind.

What is it you’d like out of Consolidated Multiple Actions? Having taken a look at it and gone “Guh,” I’ve thought of trying to rewrite it from scratch–probably basing it on Text Capture rather than Hypothetical Questions. (Is Hypothetical Questions updated for 6L32? That seems like it’d be a bear to update.) That is, my idea is that you run all the actions in sequence the way they would, but if an action is a candidate for consolidation you hold the text that would printed while it runs. Then at the end you have rules for spitting out some of that text as you captured it and consolidating other parts of it. Does this sound like this would reproduce the functionality you want, if I could pull it off? (Note: I would not have time to do this for a while.)

As far as updating I6 inclusions go, from my one successful attempt updating an I6-heavy extension sometimes the I6 inclusions are just a big chunk of the I6 templates with a couple of lines changed. So sometimes you can do this by looking at the old version of the templates that the extension is modifying, seeing how the I6 inclusions modify it, going to the new version of the templates, and trying to put the modifications into the new version. Sometimes this is easier than other times.

Anyway, updating stuff that dives into the I6 is definitely the hard part. As zarf says the parser is difficult to deal with; it definitely requires updating every so often, but the way it is it seems as though updates to the parser are inevitably going to break things. I tend to agree that Inform 7 should have been designed in such a way as to ensure backward compatibility but that would require a time machine. :-/ (And there are some things that probably break compatibility that I’m glad to have lost–the library message system was terrible and I’m glad to have the response system instead.)

A time machine wouldn’t be sufficient, I’m afraid.

And I should say that when I mean “should” I mean “it would be ideal” more than “someone did wrong in making this not happen.”

Here’s the relevant passage from the old edition of the Handbook. This was the page (in the section on “Plurals & Collective Objects”) where I hit the roadblock and stopped revising…

I have no idea whether your idea would duplicate this behavior.

With respect to the time machine – I’m not a software engineer, so I’m sure I’m completely wrong about this, but my thought is, everything that the I7 compiler does starts by compiling down to I6 code, and from there it goes on to produce some sort of virtual machine code. And all of the old compilers still exist. So one way to approach the problem (again, this is probably horribly wrong) would be (a) to include all of the old compilers as idle modules alongside the current compiler, (b) insert a line at the top of any extension saying, “Compile for 5Z17” or whatever, (c) compile that module separately using the old compiler, and then (d) link it with the new game code at either the I6 or the virtual machine code level.

This would require that only one new line be added at the top of an existing extension in order to restore its functionality. The business of linking that compiled code to the game code would of course be highly non-trivial, because for one thing parts of the new game code would be making use of the keywords and rules found in the old extension. Totally impractical, I’m sure – or at the very least, a nightmare. I offer the idea strictly as an example of an approach that would make the author’s life a lot easier.

Yeah, that’s not possible even in theory. It might be a bit more feasible if extensions were compiled as separate modules and linked together with the main code but they aren’t. (And even if they were it would probably still not be possible.)

After some tinkering, I have (what I believe to be) working versions of Consolidated Multiple Actions and its required extension Hypothetical Questions. I haven’t seen John Clemens around much lately, but I wanted to a) check with vaporware whether he would mind my uploading the replacement of Hypothetical Questions and ideally also b) get a couple of volunteers to beta-test those updated extensions to make sure that my fix didn’t miss out something critical. Email me if you’re up for that and I can get in touch.

As for “how do you do this in general?”, it would be pretty hard to describe how to fix I6 inclusions in extensions in a reliable way. To the extent that I7 is able to be backwards compatible (which is “not entirely, but one tries to break as little as possible”), it does this by turning the same I7 syntax into changed I6 syntax under the hood when major functionality is altered. Extensions that pry into the I6 under the hood are thus at much greater inherent risk of breaking, and it may require some understanding of the underlying system to fix them.

However, a pretty common thing is for an extension to be modeled on something from the standard I6 templates, but with tweaks; this was the case with CMA, so the necessary thing was to find the original code from which it was derived, figure out what had changed as a result of Inform version updates and what was CMA code replacement (which was made easier, I have to say, by the fact that John Clemens had neatly commented this up!), and then do a little surgery to make them mesh again.

Repeating from the other thread. Would the Handbook work as a wiki-style document that anyone could update on the fly?

That would help with finding bugs, smoothing out the tone and so on which could shore up the deficiencies of us non-native speakers (though thank you, Jim, for the compliment). A wiki-style page might iterate faster and could be more accessible. Problem is, I’ve yet to see a Wiki page that could be constrained to the layout of a book and still look good. And since Jim just mentioned how someone saw fit to print out the Handbook, and given his own experience with typography, I’m wondering if we really want to make that tradeoff.

Also, regarding collaboration, I’m afraid filial matters will soon take up all my time, which is the real reason I’m hesitant to enter a new project.

Im not sure a wiki is a bad idea just because it is not formatted lije a traditional book. All of the good ones usyalky have a well designed content page from which you can cruise directly into a topic, the key is good linking both forward and backward as well as lateral. I spend more time using the “find” function in a document than I do anything which is exactly how a wiki works. I think it would be great and would not require any one person a large amount of time. If those who wrote the original documents laid out the table of contents with links to a blank page and made the contents uneditable you could simply sit back and proof the code snd lessons being submitted. You could also add a page for a user submitted adendum to table of content entries. Just my two cents. Cheers.

If someone wants to set up a wiki, I guess that would be great. But a wiki relies on the active participation of a community of knowledgeable users – not only to create the content but to weed out inadequate content. Someone started a TADS 3 wiki last year, but my impression is that it didn’t catch on.

Participating in an I7 wiki wouldn’t interest me, not only because I’m not a regular I7 user but also because I like the idea of a downloadable PDF, which can be text-searched to find relevant items or even printed out.

Then a Google Doc makes some sense, as it can be collaboratively edited and exported to Open Office format documents as well as PDF. It keeps all the edits too, in the same way a wiki does.

Google doc is a good idea too, especially if someone wants to maintain it for invited editors and approve/reject changes. GDocs are awesome.

Hmm. Turns out I have a Google Doc account, though it’s been years since I used it. I tried uploading the OpenOffice draft of the Handbook, but the document formatting was rather badly trashed. So I tried saving it locally as a Word 95 .doc, but when Google Doc tried to upload that file it reported an upload error.

At the moment, I feel disinclined to pursue this approach any further. Honestly, if someone wants to help, it’s easy enough for me to send you a .doc, .rtf, or .odt. You can turn on Track Changes and wail away all night long.