Interestingly, that’s about as much of a world model as the Scott Adams system had: a big pile of boolean flags and a counter that can go up or down. The one thing it had that Twine didn’t was the concept of “objects” which each have a name and a location (and nothing else). Any state beyond the location of an object had to be a flag or a value of the counter.
1 Like
I played a bit with Inform7 years ago. The only thing I remember experiencing was the disorientation of believing I could type in English (almost any logical sentence) and Inform would parse (the irony is not lost on me) the sentences and construct the logic behind the scenes. Then I became aware of what was really happening and was a little disappointed. 
(Also, I’m not saying the following to be argumentative in any way.)
Regarding self-documentation, watch this short 5 minute video…
(…that channel has a few gems of short videos that I urge all programming minds to watch.)
Regarding reduced cognitive load… having the separation of language between story logic and story narration is a plus for me. Now I’m programming, now I’m authoring a story.
I still think Inform7 is a great tool, and one day I think I’ll dive deep into it. Anyway, just food for thought from an outsider’s perspective.
I have a question about Inform’s documentation…
I’m a self-taught programmer, mostly. I took one Java class in college and that’s it. I later learned Python (and teach it in HS now) and of course Inform 7, and I had a job making gameboy games in C++.
For those languages, I would do random internet searches when I was trying to learn something, but the examples were often either super complex (like including error checking and optimization) or very barebones and not really at the level you’d use in an actual program. So I’d try to find open source code to cobble things together.
Inform’s large list of examples has been very useful to me, and Emily Short’s open source code. While I have bumped into problems with the documentation from time to time, I’ve found it superior to the random internet snippets I got when searching for help with C++ or Python.
But I’ve heard a lot of people say that Inform’s documentation sucks. I definitely found some problems with it while reading the whole thing recently, but like I said, it’s better than what I’ve found.
So my question is, what documentation are you comparing it to? Do you have resources for other programming languages that you find superior to Inform’s documentation?
I’m partly asking rhetorically to prove a point but partly asking as a self-taught programmer and teacher who generally wants to be better and wants to have good resources to share with my students. What languages have good documentation, and what is that documentation?
4 Likes
I think the documentation is very good, but I found I had to read it more than once to get what was going on. It would be better if it started with an overview of what relationships are and how everything connects through them. Then explain how the statements create and alter relationships between elements of the story world. Relationships are fundamental to Inform, but they aren’t really discussed significantly until chapter 13. Way too late.
Also, if you’re coming from a programming background, you find yourself shouting just tell me the keywords and the syntax. All that information is there of course, but it feels buried.
Also, there is sometimes alternate phrasing of statements that do exactly the same thing and that’s confusing too. I know that’s to accommodate the different writing styles of Inform developers, but it does not help with concisely presenting the language. Inform feels so wide sometimes.
5 Likes
Think of the documentation as a study guide that has three hundred carefully and verbosely worked examples from, say, group theory, but never deigns to tell you what exactly a group actually is. It’s a recipe book, and that works great if you want to follow someone else’s recipe with minor modifications. (And as I mentioned above, the creators of I7 have definite ideas on what you should and shouldn’t be doing with the language.) If you want to understand how the thing actually works, or even just quickly look up the magic words I7 decided to make up for all the usual Computer Science 101 data structures and commands, it’s a slog.
Honestly, for comparison, the DM4 for I6 isn’t bad. It certainly has its flaws (and it also relegates a lot of necessary black magic in the language to exercises or appendices, or even never mentions them at all), but I picked up the langauge from it without much difficulty. At the very least, it presented enough of the language that I could extrapolate the bits I didn’t know from what I did know. In I7, there’s an abstraction barrier imposed in both the documentation and the examples, and I don’t even know what to search for half the time. Also, frankly, the I7 documentation is designed for people who aren’t familiar with and even may be scared off from coding. I’m not part of that audience, and as such it doesn’t contain information I do want (e.g., lower-level details) and does contain information I don’t want (e.g., explanations of what numbers are).
3 Likes
That’s pretty much exactly like this famous book, which I definitely wouldn’t recommend as a textbook:
I think I see your point. If you specifically want to know how to make functions, for loops, complicated if statements, etc., it’s not really clear from the documentation how to find that and use that. I do think that’s somewhat intentional (because IMO traditional programming patterns don’t really make the best Inform games), but having obstacles presented to a reasonable method of study would be very frustrating.
2 Likes
My biggest issue is:
This one. Inform does have a complete reference to its syntax, every phrase and its arguments and its return type, every rulebook and rule, everything you’d need to reference…
…in the Index. Which isn’t officially posted anywhere online. It’s only available in the IDE. And you can’t access it until you compile a working program. The other documentation assumes that you’re reading everything with the IDE open and can check the Index freely, but if I’m trying to answer a quick question on my phone, I can’t do that.
If the Index were included as a standard part of the documentation, that were easy for me to reference online, I’d be much happier. (Some people from this forum have put it online, but I’m complaining about the official documentation, not what fans have put together to fill in the gaps.)
7 Likes
Not quite. I don’t really see syntax in there – I see phrases. But that doesn’t tell me, for instance, how I need to phrase a description of values in order to get Inform to actually parse it (the problem in Inform that bugs me the most).
2 Likes
Yeah. Java’s. For instance: https://docs.oracle.com/javase/7/docs/api/java/io/FileInputStream.html
Absolutely fantastic documentation.
4 Likes
Thank you; I’m starting a Java segment with my students on Friday, and I’m sure this will be very useful!
Edit: Oh, I thought it would be more of a beginner’s thing. I don’t think I’ll show this to students! But it will be useful if I get stuck…
5 Likes
Are all his videos C++? I can’t tell or know, because I’ve never touched C++, and also he has no ABOUT information on his channel.
The first minute or so his anti-comment reasoning in this video is sort of obviated by Inform. He starts giving variables names using English phrases so that he doesn’t have to add a comment for his brain to understand what he was doing. That’s part of his summary at the end of the video, too. ‘Make your code more human’ – and one of the ways he does it is by slipping in more English.
There appear to be many good technical reasons in the middle of the video as to why not to use comments in C++ (Again, I say appear because I’ve never written C++ in my life). When he starts lecturing about how comments lie in general, I just will him to die in a sewer. There he can lie with his own crappy comments that lie to him, while me and my awesome comments that tell me the truth for eternity will carry on.
Actually, I expect comments do lie all the time in shared work settings. Consulting my memory, I know they do, because you’ve got a pile of people all doing everything differently in both their brains and life. For my own programs, and when I share my own programs, comments are super-duper.
-Wade
3 Likes
Ha, I actually recommended that book to someone else recently— definitely not as a topology textbook, but as a source of motivating counterexamples for the various separation axioms and other complications that arise in point-set topology. I like that analogy, though I could also argue that I7 is like the opposite of that book: It’s a source for examples for (what the designers consider to be) the most common and idiomatic situations that come up in game design, and you’re on your own if you want to do something more complicated or something they’re not interested in.
I do think that’s somewhat intentional (because IMO traditional programming patterns don’t really make the best Inform games)
I disagree, but more importantly, I want to know exactly how I7 works and how I can use it to make the game I want, not the game the I7 designers think I should want. It’s one thing to relegate more complicated topics to a later section or appendix, but the I7 documentation goes out of its way to make it difficult to find certain information, even if you’re an advanced user looking for something very specific.
4 Likes
The video was merely to suggest the idea that regular programming syntax can be self-documenting. It’s not exclusive to Inform7. I wasn’t trying to suggest anything else.
Sorry about causing any confusion there.
1 Like
Good documentation should let you predict how your program will behave. It would include a reference sufficiently specific and comprehensive that someone else could re-implement the language. We should know not only how things behave when they’re passed appropriate arguments, but what the behavior is with inappropriate arguments: is there an error? If so, what? What else might happen?
If you try looking up Python documentation, you’ll quickly find the Python Tutorial, the Python Language Reference (including the full Python grammar specification) and the docs of the Python Standard Library.
If anyone’s a real glutton for punishment, pretend you’re a newbie who doesn’t know the answer to these and isn’t an expert on what’s where in the docs, so you’re relying on the table of contents, the general index, and searching. And you have access to a Project Index.
- Scope seems pretty important – what exactly is in scope when?
- I entered “north, get all” and it worked! What are all the kinds of ways you can give commands?
- How come my images don’t work when I
release along with an interpreter? - What exactly can you do with glulx that you can’t do with the Z-machine and vice versa?
- Does something hold another thing if the thing is a part of it?
- Is it always true that if X holds Y then X also encloses Y?
- What’s the difference between the
[something]and[thing]grammar tokens? - What’s the difference between a visible thing and a touchable thing in action definitions?
- Would a
before doing something with the keyrule be triggered when unlocking something with the key? - I’m getting an error when I try to refer to
the actorin my activity – what do I do? - For a rule using a named action pattern which of
with <the thing>,in the presence of <the thing>,when <condition>,in <location>andduring <scene>can I use? - When exactly is
in the presence oftrue? -
WI 16.7’s phrase definitions say
(a table entry)… but where do I find out what are all the things that that can be? - What’s
3 * 2 + 1? How about3 times 2 plus 1? - Given
To say t: say "", is the condition"[t]" is emptytrue? - How can I make a literal verb value for “to be”?
verb bedoesn’t work. - How come I can’t make “o” an abbreviation for “open” and why am I getting this weird “Sorry, that can’t be corrected.” message?
- I saw somebody say something about
ambiguously plural– what’s that? - Can I make a multi-word verb like “to look forward to”?
- If you put a room in scope, an action applying to a touchable thing wouldn’t work on it, right?
- Would something be in scope if it were undescribed?
- In to-phrase arguments where you have (v - whatever), what kind of things can you use for “whatever”?
- What happens if I stop the action during a
Carry outrule? - Can a non-person thing be an actor?
- WI 3.20 was really specific that “wearing” and “carrying” were different things. Does someone enclose what they carry?
- Why is my relation of
various texts to one thingnot working when the exact same syntax works withvarious things to one thing?
Spoiler – the result will be one of:
- you won’t find an answer
- you’ll come up with an incomplete answer
- you’ll find contradictory answers
- you’ll get a wrong answer
I’m sure someone could quibble with how relevant some of those are, or how reasonable or not it may be to expect to easily find an answer to it. But some of them are pretty important and for many of them it really should be trivial to get an answer without experimentation.
(And, no, I’m not suggesting that it’s reasonable to expect a single developer to write something with the detail of the Python documentation. I’m separately addressing the question “what does good documentation look like?” and giving examples of some of the I7 docs’ shortcomings.)
[Edited: On reflection, I think one of the original ones is actually determinable, so I replaced it.]
14 Likes
Many of these could be implemented in I7. Not square brackets, but you could for example use => for array access instead.
My Data Structures extension allows for both
set key (key) in/of (map) to (val);
let val be get key (key) in/from/of (map) or (backup);
as well as
(map) => (key) = (val);
let val be (map) => (key) || (backup);
There’s no reason someone couldn’t make an extension giving more conventional programming syntaxes for most of I7’s standard library.
2 Likes
There isn’t even a reason someone hasn’t already done it!
(not intended for production use, unsafe when used as directed, no implied warranty of suitability for any purpose)
3 Likes
Sorry to be so blunt, but … use another language, then? In all(?) other languages, the syntax is simply what it is. Language designer’s prerogative.
Inform is peculiar in that it allows you to amend, and even change, the syntax of the language, but I’m not convinced that doing so would necessarily be a good idea. (You’d be giving up Inform’s arguably biggest advantage: the large number of people on the forum that can help you with questions.)
Many languages have a notion of “good style”, either as a community consensus, or (like Python) prescribed by the language designers. Inform is firmly in the latter camp, and it does not surprise me at all that the manual reflects those ideals.
I’m pretty sure that the Inform documentation’s goal is not to be a dry Javadoc-style API reference manual. (Which does sort of exist for I7 in the form of the Index, as Daniel pointed out.)
1 Like
And I do use other languages, but:
So I don’t have many people to ask questions or bounce ideas off; it’s much harder to find people to collaborate with; there are few extensions available, so I have reinvent the wheel in a lot of cases; I have to find an alternative for the the I7 IDE’s packaging, because I’m only going to get about two dozen players with a completely frictionless setup and only a couple if there’s any sort of installation required; and so on.
I’m talking about the kind of game I can make with I7, not the coding style involved in implementing it.
1 Like
I mean, plenty of people on this forum also have experience with TADS and Dialog and Adventuron and I6/PunyInform and… And all of those can package their games into web pages, which is the ultimate “no installation required”.
There’s nothing wrong with disliking Inform, but it certainly doesn’t mean you’re locked out of the IF community.
4 Likes
Never said I was locked out the IF community, just that it means that I’m in a small part of a community that’s already pretty small.
1 Like