The Inform 7 Documentation Must Die
Arrrghhhhhhhhhhh. That is a scream/growl/sigh of frustration, not a pirate battle cry. I am frustrated to despair by these twisty little passages of words, all different, and all unhelpful.
Here are two case studies in frustration.
First, I tried to find where exactly you can conditionally set the description of the room. This is NEVER mentioned directly, and looking for describe turns up nothing. Yes, eventually by chance I noticed that you can set conditions in the description of the room itself, but that was in a completely unrelated section, and it just so happened to catch my eye. After successive sessions, I did finally manage to figure out how to do something.
Second, I tried to discover how to vary the truth value of a variable. What’s really sad about this is that the docs tell you how to set up a truth value, how it can be tested, but never how to set it. What is the freakin’ point to having SOMETHING THAT CHANGES if you can’t ever change it?
Both of these things are VITAL to game creation, and they are nowhere to be found. Most documentation is incomplete, but it tries; or if it is bare-bones, it is systematic and throughly so; but the I7 docs purposefully frustrate the reader by obscuring and omitting the very information that readers seek. Worse than merely bad, the I7 documentation is perverse, cruel, and head-pattingly, cloyingly, vindictive. It might be going too far to call this documentation evil, but one thing is sure — it must die.
Me, I’m going to keep trying for a little while longer, but the end is in sight. If I can’t find an easier way to do basic things, I’m going to have to port the game. I’m learning ALAN at the moment, so I’ll probably go that route.
The Sins of Inform 7, Part II
Further into the heart of darkness I go, wondering if I can finish New Cat before my code becomes this. (I see the abyss from far off and hope that I never reach it. Abandoning or porting the game at 90% complete would be a similar horror.) En route, I have discovered more horrors that outside beta-testing/usability testing would never have let out of the gate.
1. The tab issue. Inform 7 won’t compile if you indent things improperly. Yet, indention was introduced as a way for programmers to more easily read their code, not as some requirement by programming languages. Generally, programming languages either treat tabs as invalid characters or ignore them as whitespace, but oh no, not Inform 7. Now you can have illegal tabs as well as legal tabs. Hey newbies, guess what? Tabs count only in certain situations, and this is just one more thing that you have to remember. This conditionality is so annoying and regressive as to be positively Microsoftian.
2. The begin brittleness. This is another system-wide problem that reflects an annoying and unnecessary brittleness. To use a multiline if statement, you must use a begin, however, the begin cannot be on the same line. Why? I’m not sure, but I suspect that the parser requires a carriage return before seeing the begin. A decent parser looks for keywords, not formatting. But I suppose once you’re looking for tabs, you might as well look for carriage returns, too.
3. Unhelpful error messages. This is another blindingly obvious problem. When the error message states that the parser was expecting ((condition), but found (condition), that means that the error message itself is wrong. Oy vey. I’ve seen this more than once and figured that hey, it really can’t be asking me to input some crazy construct like that, and forbore. Finally, I was so frustrated that I put in the extra parentheses with no closing match, and guess what? The next error message finds the parser looking for (((condition)) but found ((condition). Sigh.
And that’s not the only example of how regular English is sometimes not the greatest tool to tell people that code is wrong. Have you seen the half-page of ornate English spat out when you were missing a few characters here and there? It’s difficult enough programming, but then to smacked by a wall of cloying prose whenever you fatfinger something is not helpful. Furthermore, the use of first-person is REALLY grating. It’s almost as if the Old Ones tried to come up with something guaranteed to be unhelpful, annoying, grandiose, insulting, and verbose all in one. I think that they succeeded beyond their wildest dreams. If you want to help people program, treating everyone like a two-year old and patting them on the head doesn’t work.
Sadly, that imperious attitude is not new. The superiority complex and treating people outside the dark network as children and idiots is part and parcel of the I7 documentation, and it’s been present for quite some time (making its way through games, personal interactions, and public interactions). For reference, check out how they treated folks who wanted to learn Glulxe, help fix the I6 web site, and on and on. It shouldn’t surprise anyone that the pat-on-the-head-you-idiot mentality has grown up into the sickening weed-garden that it has today. Perhaps it’s their latest revenge upon all of us little stupids. I don’t know. It seems so small and so silly; why not just write error messages that don’t demean people? Are you that in need of proving your intellectual superiority? Does it even make sense to punish people who want to use your tools?
I’m beginning to wonder if I7 was designed on purpose as a nearly closed-loop system, useful primarily (if not exclusively) to a small group of people; on the outside, it could be marketed shallowly (and cynically) as the latest in natural language programming, while effectively raising the bar to make it all but impossible to create games unless you were patient beyond imagination or you were an insider yourself.
Welcome, Visitors (A Public Service Announcement)
It’s really too bad that I even have to post something like this, but explicit disclosure is better than assuming people will get it, because some people don’t.
First, this blog is MY HOUSE. As such it is subject to MY RULES. All visitors are welcome. If you insist on insulting the owner, picking fights with the owner, using vile language, or mixing it up with other visitors, though, your comments will be removed. You get ONE individual warning. (Addendum: one person I have told repeatedly not to contact me; his comments will also be deleted immediately.)
Comments are provided as a privilege. Why is that? This is my personal outlet. It is not intended to kick-start conversations or debate. It is not designed to persuade anyone, as I have not those powers. It is not a watering hole. It is not a free-fire zone. It is strictly personal.
If you haven’t noticed, check out the sidebar. It links to precisely ZERO IF blogs. I don’t comment on other IF blogs (anymore). I don’t advertise, outside of my sig line. So if you are here, you are here because you made an effort to be here. You can’t blame me because you sought out a cottage in the woods.
Second, if you really hate what I have to say, do not come here. For your own inner peace, I advise you to go somewhere else, as I will not change to justify you, nor will I justify myself to you. Furthermore, even your vainglorious fusillades will come to nothing, because I will delete them upon sight. Hopes of shutting me up or slowing me down are equally futile; at the best, you’ll just get comments closed down which will dry up your platform for hate. If you’re motivated enough to try to get past the policies here, make your own blog instead.
The Sins of Inform 7
Inform 7, while powerful, has some serious flaws that a round or two of proper beta-testing from anyone outside the I7 sanitarium would have discovered. But as Inform has always been an incestuous affair governed by the Old Ones, it’s no surprise that horrific wonders would be birthed. Behold, the sins of Inform 7.
1. Tables. In Inform 7, tables are a powerful construct, allowing more than one interesting use (such as responses given a proper topic). However, when tables fall apart, it’s not pretty and it’s downright counter-intuitive and painful. Where would that be? Where the comparison between a table in a book is at its weakest, because a table is wrenched into a programming context, but retains all the restrictions of being a table in a book. Yes. You too can try to fit paragraphs of text into narrow columns!
In other words, this makes sense:
Table of Outer Planets planet semimajor axis Jupiter 5 AU Saturn 10 AU Uranus 19 AU Neptune 30 AU Pluto 40 AU
THIS does not:
Table of Instruction Options
title subtable description toggle
“About Interactive Fiction” a table-name “The game you are playing is a work of Interactive Fiction. In interactive fiction you play the main character of a story. You type commands which determine the actions of the character and the flow of the plot. Some IF games include graphics, but most do not: the imagery is provided courtesy of your imagination. On the other hand, there’s a wide range of action available: whereas in other games you may be restricted to shooting, movement, or searching items you can click on with a mouse, IF allows you a wide range of verbs.” a rule
It’s ugly, hard to follow, and loses all of the power of the metaphor. It really forces people into defining the table rows later where text can flow freely, which says “chuck it” to the whole table layout.
2. Documentation. I don’t often toot my own horn, but I write documentation FOR A LIVING. I get paid to understand how to fit docs to audience and I understand genetically the need for testing. If the Inform 7 cabal could have been bothered to ask for public feedback (something like “Hey, we’d like input on the docs. Can anyone help?”), I could have spared them tons of harsh feedback, and a general decline in their estimation in the whole IF community.
The documentation for Inform 7, is in two words, an obtuse horror. It begins with a trivial example, but never builds on the trivial example to a robust one. Instead it leapfrogs from application to application of the general concept. It’s much like starting off in a field behind your house, and within ten minutes of walking, you’re on the moon. Newbies it doesn’t help; old hands it frustrates. The docs are simply masterful at giving no-one what they really want.
For instance, say that you want to set the describe properties of a thing. Specifically, you want what displays when the object is in a room to vary. Good luck on finding that. The docs never mention it. Sometimes the only reference to how to do something is buried within the documentation of particular extensions. Yeah, I kid you not.
Mostly, the docs describe how to do little things that don’t add up to much; even the extended examples aren’t thorough. I’m sure I’ll find out just how threadbare they are as I go searching through the entire freaking book just trying to find a clue. It’s documentation by piece, but not by whole; I don’t think anyone reviewed the finished project as a whole.
The docs read like some barely-connected daydream instead of an actual description of how to do things or even, how things work. It’s almost like the authors weren’t well-versed on the necessities of typical IF games and the needs of their authors; that sounds bizarre, but how else can you explain the patchwork effect here? I suppose substance abuse is always a possibility, as is the authors being so far out-of-touch with other human beings, that they really believed that everybody knows everything they do and so “Inform for Me” was all that was necessary. What we really need is an “Inform 7 Beginner’s Guide” to parallel the magnificent “Inform Beginner’s Guide” put out by Roger Firth and Sonya a while back. That book’s approach covered all the bases and had a handy set of appendices that listed common commands, properties, and so on.
3. The language itself. I7 is in many ways, a real step backwards for people who actually want to make games, instead of people who want to throw together a few cute objects that don’t do much. Take for instance the age-old problem of objects that are both containers and supporters, like oh, say, a toilet bowl. Is I7 any improvement over I6? No. You’re still stuck trapping verbs that go to one object and shunting them over to another. You’re still stuck modeling two different objects and trying to obscure their differences to the player.
The fundamental problem is that the language just isn’t thing-oriented. It doesn’t help you make things and govern their interactions well. It’s too high-level to deal with the messy reality of a world of objects, and it makes the low-level stuff even more difficult by forcing you to write near-English sentences about stuff instead of
breaker.oos = true;
The latter is more compact and really, semantically more sensible, as you don’t talk your programs into existence; no, you program them, and a programming languages are created for the purposes of achieving what is cumbersome in English. C, PERL, JAVA, all use these “linguistic shortcuts” or more properly said, have their own language constructs to achieve things simply and quickly. I shudder to think of trying to do pointer arithmetic in I7.
But really, the source code of Weishaupt Scholars says it all. I remember beginning to program in I6. I checked out the source code to Christminster. If you were trying to learn a new language and you came across these two examples, which do you suppose would be easier to learn?
No matter how much I7 repents, it can’t be saved.
