The 2.0 edition of the Inform 7 Handbook is now available for download from musicwords.net/if/i7hb.htm. In fact, there are two files. It was suggested that some folks might want to read it on smaller devices, so the PDF is available in either 6x9 (for that purpose) or 8-1/2x11 (for printing on paper). The two files are substantially identical, other than a carriage return here or there to improve the layout.
Also available is an OpenOffice .odt version, which is useful in at least two ways. First, if you want to copy and paste the code examples, you’ll find that Acrobat Reader won’t copy the Tab indentations, which is fairly annoying. Copying from the .odt will preserve the Tabs. Also, if you’re thinking of translating it to another language (as someone was planning to do five years ago – don’t know how far that project got), having a word processor file as a starting point would probably be helpful.
Although this is an official release, corrections and suggestions are still welcome. I expect I’ll do a minor update in a few weeks – I just wanted to get the project off my desk this week so I can work on something else.
Comments about the first half (I just skimmed in some areas):
Scenery p53 - “To solve the first problem, we’ll add an Understand rule to the trees.” — It might be better to put one set of the amended example text (The tall old trees, etc) here. Because there’s three paragraphs between the previous and next example text, it might be a bit hard to follow. Plus, this is an early part of the manual, and being able to trace these additions slowly, bit by bit rather than combining the plural-name and understand concepts into a single update, would ease understanding.
p56 - "Generally speaking, if an object is mentioned in the room description, it should probably be implemented as a separate scenery object. " — It’s probably worth mentioning the converse as well, to show this is a gameplay/design/writing-to-convey-affordances issue just as much as it is a ticking-all-the-boxes implementation issue. That is, if a thing is not important to the story and the gameplay, it should be omitted from the room description.
p79 - “You can create one region that’s entirely within another region, but Inform won’t let two regions
overlap one another.” — This seems confusing, but maybe I’m alone in the terms overlapping and subset/superset seeming too similar. I would say “partially overlap” instead of “overlap” here, to avoid any ambiguity.
Floorless Rooms p85 - “If you forget to do this, things that are dropped will end up (oddly enough) in the
starting location of the game — the first room defined in your source.” — I think this would be clearer to explain exactly what’s going on, and why, here. “…will end up in the default room — the first room defined in your source.” Especially since the first/default room might not be the starting room, if there is a “The player is in” line defined somewhere else in the source.
Adding Vocabulary Words with “Understand” p97 - “This is a key concept: The author can only refer to an object using
the actual word or words that are used in the sentence that creates the object.” — I think this is important enough to either elaborate further, or set off in some way; at least with bold text. New writers often tend to confuse “understand” texts and the in-code names of objects.
p99 - “But if it’s not initially carried, you have to explicitly say that it’s not fixed in place.” — Or you could just call it “portable”.
p100 - “What you need to know is that before you make something openable or lockable (unless it’s a container or a door), you have to tell Inform that it can be openable or lockable.” — Maybe point out that doors and containers don’t require this because those kinds have already been defined as potentially openable and potentially lockable:
p110 - “The name “under#bed” is not special; it’s just a good idea to use a name that the player is not likely to type.” — Wouldn’t it be safer (and more legible) just to make the thing privately-named?
p117 typo - “It have no solution at all.”
p120 - “Instead of taking something when the noun is hot:” — “Instead of taking something hot” also works.
p130 typo - “students, One of them”
p131 oversight - "from the Public Library [???] " — would be good to indicate the current status and availability of the extension.
On page 116, the sentence starting “If the player is carrying the holdall” seems to want to be placed above the previous example (starting on page 115), as it ends with a colon.
I’m really enjoying reading through this, Jim, so thanks for putting it together.
I’m just getting to the end of the Handbook and hope you don’t mind me adding another couple of suggestions.
In Chapter 9, section Headings, you write “In most programming languages, you can put various parts of the code in separate files on your hard drive. Inform doesn’t allow this…” which is true, but can be got around to a degree. I was reading a discussion on this forum about version control and someone suggested writing the various chunks of your game as different plugins, and then including them into the main game in the usual manner (e.g. “Include Chapter One by Vaughany. Include Chapter Two by Vaughany.” and so on). I’ve not written any game big enough to warrant this sort of separation of content but it might be useful to some.
In Chapter 10, section The Skein, (you may already be aware of this and chose not to include it in the Handbook, but stil…) the ‘blessed’ thread in the skein is used when releasing with a solution (walkthrough).
I hope that’s useful and I haven’t suggested the bleedin’ obvious.
I know it’s possible to put separate files in pseudo-extensions. If you do that, though, you lose the advantage of being able to find sections of the work using Volume, Chapter, Section, etc. Plus, the IDE is not set up for multiple panes of source code; each extension will be in its own floating window during editing sessions, and will have to be opened separately from the File menu at the beginning of each work session. In TADS Workbench, when you open your WIP to start writing, all of the tabs that were open last time are opened again automatically. Plus, your game code will now be stored in two different folders (one in the Extensions folder, the other in something like MyGame.inform), so backing up your work becomes a bit more tedious.
Still, this level of detail won’t matter to most I7 authors.
At this point, I feel the new Handbook is basically complete. It can be downloaded, and if you want to take it to the print shop you can – it even has a spiffy new photo on the front cover. Barring any finding of technical errors, I’m not planning to do any more work on it, at least not for another 5 years…
If you have extensions you only need for one project, you can put them in MyGame.materials/Extensions/Author Name/Extension.i7x and they’ll be accessible only within MyGame.inform. It’s useful if you sometimes need to override the standard version of an extension, and it means it’ll be in the project files for backing up if necessary.