I think I’m about ready to give up on Inform 7 yet again. I hate to do it, both because the IDE (integrated development environment) is extremely nice, and because it’s such a popular authoring system for interactive fiction.
But It’s driving me bats. For two reasons:
First, the “natural language” programming paradigm, which seems to be immensely attractive to new authors, soon loses its appeal as you begin trying to do complex things, or even simple things that are not entirely standard.
A native speaker of English can typically phrase a given idea in a variety of ways (“Bob is standing on the cat’s tail,” “The cat’s tail is beneath Bob’s shoe,” “Bob is standing. His shoe is on the cat’s tail,” “On the tail of the cat is the shoe of Bob, who is standing,” and so on). Most of the time, Inform can only accept one wording of a given idea. Other wordings that seem both entirely sensible and entirely equivalent to Inform’s desired wording either will not compile, or will compile but won’t produce the desired results.
The I7 home page gives, as one of its key examples of the felicity of natural language programming, this sentence: “The prevailing wind is a direction that varies.” The fact that Graham Nelson (the author of Inform 7) feels this is a good example tells us a great deal, because to a native speaker of English, the sentence is gibberish. First, the wind is not a direction. The wind is a movement of air. Second, directions do not vary! They are fixed. North never becomes west (though it could perhaps do so in interactive fiction, at the cost of badly annoying anyone trying to play the game in question).
This sentence does in fact have a meaning in Inform 7. It means that the phrase “the prevailing wind” is being defined as a variable, and that this variable is to be initialized in such a manner that it can take on only one or another of the values defined within I7 as a direction. That is, the prevailing wind can be assigned the value north, northwest, or west, etc., but it can never be assigned the value 7 or “Tuesday.”
Is that clear to the non-expert who reads the sentence?
Second, the manual is a mess. This is perhaps especially surprising because the manual for Inform 6, which was Graham Nelson’s first authoring system, was a marvel of clarity. (In case you’re new to interactive fiction, I should perhaps explain that Inform 6 and Inform 7 have about as much in common as ice cream and a bicycle.)
What is being called “the manual” distributed with I7 is not in fact a manual at all. It’s a fairly reasonable tutorial; if you work your way through it faithfully, from start to finish, you’ll learn a heck of a lot, and the concepts unfold in a reasonably sensible order. But if you’re trying to look up some specific technique, and would like to read a complete, coherent discussion of that technique within a self-contained section of the “manual,” you’re doomed.
A single example will have to suffice. Chapter 12 is called “Advanced Actions.” This, one would think, would be the place one would go if one wanted to create a new action for one’s game (perhaps spearing a fish with a spear whose tip has to be sharpened first in order for the action to succeed — that seems reasonably advanced, in that it involves two objects, one of which has to be held and also has to pass the test [isSharpened=true]). But after two pages, one of which is devoted to a diagram of the manner in which I7 processes actions (that is, player commands), Chapter 12 goes scampering off after the question of how one writes code that will enable the player to give orders to other characters in the game (“Bob, spear the fish”). This material belongs in an entirely different chapter, one on the handling of non-player characters.
There is, in fact, such a chapter. It’s in a second, parallel document called the Recipe Book, which is also included in the distribution. But as can be deduced from its title, the Recipe Book is mainly a tutorial as well. It mostly eschews formal discussion of the minutiae of proper or functional code in favor of presenting numerous examples (the recipes), one of which may or may not have chunks of code that you can copy and adapt to your own purposes.
To develop a clear, logical understanding of I7 by reading the Recipe Book, one would need an extraordinarily well developed intuition.
As far as I can see, the only way to actually learn I7 is to post questions on the rec.arts.int-fiction newsgroup. As a publicity gimmick, this is a winner: 90% of the posts on r.a.i-f are about I7, which guarantees that it will be highly visible to anyone who is interested in interactive fiction. As a way of documenting the programming language, it’s … rather informal.
Jim Aikin's Oblong Blob 
“Is that clear to the non-expert who reads the sentence?”
If by “non-expert” you mean “non-programmer,” certainly not, but neither would be a line of C++ that performs the same thing in different syntax.
I regularly teach Inform 7 to students who don’t know any other programming languages. One benefit of Inform 7 prose is that non-programmers who read it can figure out most of what the paragraphs are supposed to be accomplishing. But you’re right — it’s confusing when beginning programmers try to use synonyms or syntax that seems equivalent to English speakers, only to find those variations rejected.
Given that the people who worked on Inform 7 are doing it for free, I think it’s a bit silly to reject their design choices a publicity gimmick.
But each to his or her own… I6 is still supported, and is in fact being used under the hood of I7.
Thanks for the comments, Dennis. It often seems that nobody is noticing my poor little blog!
> If by “non-expert” you mean “non-programmer,” certainly
> not, but neither would be a line of C++ that performs
> the same thing in different syntax.
My point was not that the syntax of C++ or TADS is easier to understand (it’s not) but rather that the “natural language” appeal of I7 is a mirage. The sentence about the prevailing wind provides a convenient example of the manner in which it’s a mirage.
> I regularly teach Inform 7 to students who don’t know
> any other programming languages. One benefit of Inform
> 7 prose is that non-programmers who read it can figure
> out most of what the paragraphs are supposed to be
> accomplishing.
Yes, I can see that that would certainly be true. But understanding code when you read it is one thing; writing code that does what you want it to do is a somewhat different thing. I may be at a disadvantage in that I’m trying to get I7 to do things for which no examples are provided in the manual. I’d be curious what happens when your students get to that level.
> But you’re right — it’s confusing when beginning
> programmers try to use synonyms or syntax that seems
> equivalent to English speakers, only to find those
> variations rejected.
>
> Given that the people who worked on Inform 7 are doing
> it for free, I think it’s a bit silly to reject their
> design choices a publicity gimmick.
I guess I’d answer that in two ways. First, I don’t think I said that Graham chose natural language in order to implement a publicity gimmick, though I’m pretty sure he chose it in part because of a feeling that it would have a wide appeal to non-programmers. That comment was specifically about the inadequacies of the manual, which leaves one no recourse but to post messages to r.a.i-f. I wasn’t commenting on the language itself at that point. Second, one of the reasons why people do stuff (especially software) for free is because they’re hoping to be noticed and appreciated, so inferring that they would be uninterested in publicity is not quite valid.
I don’t mean to imply, either, that they wrote a poor manual for that purpose (though they may indeed have skimped on the immense labor involved because they knew people could post messages on r.a.i-f). I was only observing that the number of messages posted both has the effect of creating a buzz about I7 and serves as an indication that the manual could be improved.
One of the reasons I started looking at I7 again was because I had (and still have) a vague feeling that it would be fun to teach IF to a bunch of kids at the local library. They bring their laptops, I hand out CDs, and boom, we’re off and running! But in order to do that, I would need to master the intricacies of I7 programming. And I keep hitting these bizarre roadblocks.
If I have so much trouble with it (and I’ve written and released several large games), will it really be easy for kids to master it? Or are we looking at yet another fast-food, instant-gratification activity that they’ll try for a few weeks and then lose interest in? Is it, in other words, another Air Guitar video game, or will they be able to play real music with it? I confess that I have a strong bias in favor of artistic mastery.
Thanks for giving me an excuse to dilate on these points!
Part of Graham’s motivation in designing this manual was to address some of the common complaints leveled against the DM4: that it was too hard to get into, too technical at the outset, too full of minutiae. That lack, for Inform 6, was partially resolved when the Inform Beginner’s Manual arrived on the scene; but that sequence of events made him think (as I understand it) that a new language, especially one aimed at new users who were not programmers, should unfold itself as more of a gradual introduction and less of a weighty textbook.
The process of listening to feedback on this matter for a couple of years has convinced me that there are at least three kinds of manual desired by the various factions:
1) something like what exists now, namely, a gradual introduction to all the major language concepts, though improved with better indexing and cross-referencing.
2) a “real” tutorial, by which those asking usually seem to mean a text that, instead of teaching language concepts in an order dictated by the complexity of those concepts, goes through the process of building a game and introduces each new idea as it comes along. Some people refer to this as a “single game” tutorial, “something like Ruins”, etc. The Recipe Book tries to partly address these people, though it falls short of being the kind of tutorial that most of them are seeking.
3) a reference manual, which presumes that the reader already knows something about IF and probably something about programming, and rigorously sets out methods, offers tips about good coding style, and offers information on subtle reasons for choosing one implementation approach over another (e.g., concerns about performance, memory use, maintainability, and so on which mostly at this point get addressed in RAIF threads).
I may be missing something, but those seem to be the three main categories of suggestion.
As far as I can tell, any kind of manual but the one most suited to one’s own pedagogical style seems incomprehensible and broken. That’s frustrating, and it’s also not really easy to deal with, especially given that we have an evolving language on our hands: there are still some significant features that remain to be introduced, and it’s sufficient work as it is just keeping one and a half manuals up to date. (I maintain the Recipe Book text, Graham the main manual — but that’s still a fair chunk of work.)
Another subtler point is that I doubt either of us would have been competent to do a good job of writing a reference manual at the beginning. Certainly it would have been conceivable to document syntax; but there is quite a lot of advice I might now offer about implementation style, best coding practices, etc., that I learned only by writing a lot of code and offering advice to a lot of other people writing theirs.
It’s easy to remember the DM4 fondly (and I do), but it’s also worth bearing in mind that that was the *fourth* edition, a response to many years of progress and feedback after Inform 6 had already more or less stabilized — and for that matter I6 was a more predictable, because more traditional, sort of creature.
Anyway, this is meant as an explanation, not an attempt to persuade you to continue using a language you find frustrating; most of your comments on RAIF have suggested to me that you would indeed be happiest as a TADS 3 user. The attempt to make one language be all things to all people is doomed, which is why I’m glad there are a bunch of different options in the IF ecosystem.
Thanks for the comments, Emily. I first downloaded the Inform 6 Designer’s Manual in 1999, or perhaps in 1998. Its clarity and literary grace were what persuaded me I would be comfortable learning I6, and I was right. I’m pretty sure that was before the 4th edition.
Frustrating, yes, but I haven’t given up on I7 — not yet. If I should happen to give way to my impulse to try teaching IF as a volunteer at the local library, I7 would clearly be the best choice! But as I said to Dennis, I would need to understand it much better before I attempt to teach it.