New Edition of I7 Handbook (beta)

The new edition of my Inform 7 Handbook is now available for public perusal and pummeling from

This is still a beta release (and is not yet shown on the I7 page on my website – the link above is the only way to get it). I’d very much appreciate it if two or three public-spirited citizens could give it a quick read and let me know about any errors or significant omissions. If you don’t have time to read the whole thing (which would certainly be understandable), it’s perfectly okay to pick a chapter or two and let me know about any problems you spot.

All of the code examples have been edited for 6L38 compatibility. Barring a typo or two, they should work. There are new explanations here and there, and I’ve adjusted the text where necessary to address various changes. (There’s no discussion of procedural rules or indexed text, for instance.) It’s not a complete rewrite, but it has been re-edited from start to finish.

PM me or just reply to this thread, your choice. All comments gratefully received.

Hey, you actually did it! Congrats!

Thank you Jim for working on an update. As much as I admire the efforts that went into the stock documentation, your handbook is an essential addition.

Any chance of creating an e-pub or mobi version? I’d love to scale the text up to read on kindle or a tablet reader without panning around the static pdf page.

Thanks, Jim, will read this avidly this evening.

HanonO, I’ve converted it using Calibre to an epub which I can use on my Kobo. I can post the resulting file here if Jim has no problem with me doing that, or you can always download Calibre and convert it yourself, if you prefer.

I just found the odt file by not linking directly, so I can do this. Thanks!

Yes, well, that’s the OLD .odt file. Six years old. Not useful. The new one is only on my local drives.

I’m looking into epub formatting. Another reader has already made a bunch of specific suggestions on the text, so I won’t be ready to roll out a revised version (with .odt) for a few more days.

i don’t want to sound important but … were you thinking of this before I went and printed me that big bunch of textbook or was i a catalyst?
I’m just genuinely curious.

I had started working on it back in February, and then developed a bad attitude and stopped. Your printing it out was absolutely a catalyst to get me to finish it – many thanks.

Thanks for the tip on Calibre. I have now converted the beta version of the Handbook from PDF to epub … but I don’t have an epub reader on my Windows PC, so I have no way to look at the converted file.

The epub readers I’m finding online don’t look promising. User reviews suggest they’re mostly crap, and try to install a bunch of other stuff during installation. (Hijackware, and yeah, I just made up that word.)

Can anyone suggest a good epub reader for Windows? (Preferably free, but I don’t insist.)

I believe Firefox has a good ebook-reading plugin (which of course works across platforms, but I cannot remember the name) but I’m not aware of anything except Calibre itself which opens ebooks on Windows or Linux.

I’ve done the Calibre thing and will sideload onto my Kobo Touch in a moment and report back.

Initial conversion: not good.

The Firefox add-on can open the epub document exported by Calibre based on my PDF, but it’s a godawful mess. I have no idea whether the add-on is at fault, or Calibre, or whether I need to code my .odt file somehow to deal with the issue(s).

And in fact, Calibre’s own display of the epub file is crap. Weird line breaks, a complete loss of formatting in the code examples, page numbers floating in between lines of text – and if you click on any of the internal cross-reference links, you’re popped back up to the first page.

I’m certainly open to the idea of producing an epub-format edition, but since the Handbook is free, I’m not too keen to spend a bunch of money buying a capable epub-capable program. Suggestions welcome!

Turns out, if I convert directly from .odt to epub using Calibre, bypassing the PDF stage, the results are much better. But not perfect. The code examples are in blue (yay!), but all of their tab-based indents are lost (boo, hiss!). Text no longer wraps the graphics, but that’s okay. Loss of indents, not okay.

Would a 6-inch width (a 6x9 PDF) be an acceptable compromise? I can do that pretty easily … no more than an extra hour of work.

The Calibre epub conversion loses the indents on all of the code, which is a total deal-breaker.


Ooh er, sorry about that. Dunno if it helps, but I often use this:

I also use the Firefox epub extension. I find it to be quite marvellous for my quick and dirty needs, which is just to preview files before they go into my iPod (Kobo app).

Neither the online converter nor the OpenOffice Writer plug-in is up to handling the document at all. Looks like it will have to stay a PDF.