Inform 7 Programmer's Manual updated -- get the PDF now

Authoring Inform 7
1

Currently it’s only available as a PDF here, as I wanted feedback on it before going through the trouble of creating the other formats. I did some significant rewriting on it. Here’s what changed.

The introductory In A Nutshell chapter has actual paragraphs now, instead of naked bullet lists. And it breaks down a rule at the end for flavor.

The second chapter is brand new. Titled The Firehose, it’s a broad overview of the whole language. “Subclass like this, enums like this,” that sort of thing. I still spend quite a few pixels explaining the grammar of rules in it, since that’s likely to be new to just about any programmer.

The new chapter Types of Types was added.

The activities chapter is now actually useful, and includes a callgraph/outline/diagram of the five activities used in LOOK.

New chapters on headings, and on Inform 6, were added.

The chapter “Times, Turns, and Tenses” received an extensive rewrite. More information, less theory.

A few chapters were folded into others: Indistinguishable Instances --> Class & Prejudice; No Lights --> Events are Actions; Grammar Gotchas had its size reduced by the new builds so that its remaining parts were distributed piecemeal elsewhere.

Equations were added to the Units chapter.

Many if not most examples of syntax now make use of bold and italic. Bold is used to show the parts of a phrase that aren’t its parameters. Within the flow of narration, code samples are in italics, for the same reason that an oddball French word in an English article would be italicized.

I started favoring the Python syntax because it’s less wordy.

The chapters on relations and rulebooks both received a healthy dose of rewrite, due all the new features of recent builds. Though I don’t think a single chapter escaped unscathed.

I still don’t cover multimedia.

Comments, bug reports, etc. etc., all welcome.

2

Hi Ron,

Just downloaded your PDF and had a quick scan through it. Very useful. Thanks for taking the time to produce it.

I’ll report any specific feedback as I work through it.

Thanks,

Gary

3

I’ll try to give this a look next week. Feel free to bug me if I don’t!

4

Thanks for this, Ron. I’m not at all the intended audience for this, but I did find the first edition useful, and I hope to look at this one soon enough to provide you with some feedback.

For now, I do have a comment about the formatting: It’s kind of a wall of words, with small type, tight leading (space between lines), and a high per-line character count. I have perfect vision, but my eyes huff and puff just contemplating all that left-to-right scanning. Would you consider narrowing the text columns for the final version? (FYI, depending on the leading, type designers generally recommend 60-70 characters per line as optimal. It might also be helpful to use a smaller page size, e.g. 7x10 or 6x9.)

(I spent a number of years in the publishing industry. Please accept that as my excuse for being finicky!)

–Erik

5

I’d second this. It is quite a mass of text. Though for now I have a happy workaround for me, having converted it to my Kindle where I can read it much more comfortably.

6

Thanks everyone.

Erik: I know nothing of that stuff. I had used 10.5 font with some slightly relaxed margins to cram a lot onto a page cause, I dunno, it makes things easier to find when you’re flipping through looking for something. I was using Inform’s Appendix A & B as a reference for font selection and such, but I only eyeballed it. Since it’s a PDF, most every PDF reader I know allows zooming in/out on the text, so the font can be as big as you’d like. Hence I was fine with a smaller font – I’d just zoom in until the line fills the screen, and arrow down to read.

But since you bring it up, I suppose at first blush it is a thick wodge, especially those early pages. Granted, once you start getting into the nitty-gritty, the examples break up the paragraphs…

I’m open to suggestions here. I’ll have another look at the Appendices.

7

I’m enjoying this so far. I agree it’s a bit wall-of-text, but I also don’t think it’s worth worrying about aesthetics on the first pass through.

It also seems like it might have been intimidating for me a month or so ago when I was starting, but now I enjoy the in-depth examples. I’ve seen a few things already that I can incorporate that I didn’t know about before. I think it covers ground that other sources don’t, or at least prioritizes what to learn differently.

The only definite thing to fix I’ve seen is “It is easier to show all parts of a full rule preamble then explain…” then->than.

I’m generally pretty good at finding typos/grammar stuff and in fact it gives me confidence and makes me feel smart when I’m reading something challenging, but I don’t know if it’s better to dump things in this topic, or how interested you are in stylistic stuff–which can be extremely objective. Obviously, I’ll lump things together a bit better when I can sit down and look at this more. But so far, lots of good stuff.

8

Just to clarify, I don’t see the small type as an issue per se–it’s the wide lines that result from using small type on large paper that make a text difficult to read. Here’s a quote from a type manual, for no good reason really except that I have it on hand:

Anyway, you said you’re planning to offer this in multiple formats, so if someone doesn’t like the PDF formatting, they can use say HTML instead.

–Erik

9

Thank you. That was pretty much my intent. (Well, not to intimidate.) I try to prioritize what translates from other languages pretty directly and get the potential coder doing hands-on stuff with what compiles. Of course, I can’t get around rules for very long at all, and that takes some 'splainin.

Then/than noted. Thx.

I’m very interested in stylistic stuff. I hope to write my own i-f one of these days, and some skills transfer between technical writing & creative writing. So yeah, ramble on if you wouldn’t mind, I’d be grateful.

Erik: some from RAIF have or will print it, like, on real live dead trees, so I shall take your advice. I just think it makes the examples ugly to have them wrap around. (I really, really like one-liner examples when I can get away with it, as you can probably tell.)

10

Have you ever read “The Sparrow” by Mary Doria Russell? An amazing first novel by a technical writer.

11

I don’t remember if you discussed “what makes Inform cool” in the first few pages of the previous version, but I thought the discussion was effective, particularly the unpacking of a short bit of Inform source code into a long list of assertions and inferences. (Reminded a little of William Gass’s essay on Gertrude Stein’s use of “and”–he shows how she uses “and” with something like 30 different meanings in one of those chapter-length sentences of hers.)

A minor correction on page 6:

I think this used to be true, but usually now works in the same way for globals as for properties, e.g. this is perfectly valid:

X is a number variable. X is usually 2. X is 3.

–Erik

12

OH, so that was finally supported. Very nice. Thanks Erik