Inform 7 documentation and resources

Authoring Inform 7
1

How to Not Lose This Post

Note: References and Useful threads/posts below provide a lot of info not in the docs

Inform 7 10.1 (current release)

I7 10.1.2 and IDEs for Mac, Windows, and Linux. The 10.1 release notes detail changes and bugfixes.

10.1 made some info below out of date. The next release will be 11.0. No schedule has been announced.

9.3/6M62 (previous, released 2015-12-24)

Tutorials: start here!

Installation

@Juhana’s Borogove lets you edit and run I7 (10.1, 9.3/6M62, or 8.5/6G60) online: experiment without installing anything. Borogove snippets allows sharing code examples.

For official packages mentioned below: I7 Downloads.

MacOS

Use I7 site’s package, not the App Store’s.

Known issues:

An unofficial MacOS IDE release addresses these (but testing examples in Extension Projects doesn’t work)

Windows

Use the package on the I7 site (said to work with any version of Windows from XP SP 3 on). There’s a current 64-bit-only beta release of a new Windows version that allows compiling for any of 6L02, 6L38, 6M62 that has been tested only on Windows 10, but may work with older versions. Be warned that there have been multiple reports of security/antivirus programs causing problems with it: Avast, AVG, Windows Defender.

Linux

The 6M62 IDE uses GTK2, not modern GTK3, making it hard to build in modern Linux.

Unofficial rpm/deb IDE packages

Linux kernels < 4.11 (c. 2017) are incompatible with versions of ni prior to 6M62. To use 6L38 or older try an old Linux in a VM or Windows Inform in WINE. For 6G60, try playfic.com or borogove.app.

The official packages include components with more recent versions, e.g.,

Versions

Most 6L02 or 6L38 info remains relevant in 6M62. 6L02 had many backwards-incompatible changes: code written for 6G60 or earlier likely won’t compile in 6L02 or later. This post usually notes for what version a given thing was current.

Manuals/Books https://www.musicwords.net/if/I7_Handbook_3.pdf

References

@drpeterbatesuk 's Deep Dives:

@otistdog 's Standard Rules Actions reference (6M62) includes tables for:

A draft I7 reference manual (10.1)

Which action rulebook should you put your rule in? (tl;dr: don’t use Instead rules as a catch-all even if the docs’ examples do)

Times, Turns, and Tenses: details on counting occurrences of actions, and using past tense in conditionals

The Looking action’s activities and rules

Line break behavior; see also Nathanael’s Cookbook

Oliver Reiser’s I7 cheatsheet (6G60)

@emshort’s rules flowchart (PDF) (5U92) illustrating the turn sequence

I7 Windows IDE with the NVDA screenreader

Compilation produces a Project Index viewable in the IDE with lots of details about I7, including many things not in the docs: it’s the closest thing to a reference manual. Its Phrasebook Index section (Phrases, Lexicon, Relations, Verbs) is good to check (along with the docs’ General Index) when you half-remember something you’ve heard of and need to find the right term to look up.

The basis for how the I7 compiler parses I7 code is in your installation’s Internal/Languages/English/Syntax.preform. The docs’ Backus-Naur Form syntax is incorrect. See the Syntax.preform documentation PDF (6L02). Syntax.preform shows what irregular verbs and plurals I7 handles (and how), too.

Extensions

Separate from the Authoring > Inform 7 category here, there is a Technical Development > Inform Extensions category chiefly discussing issues with existing published extensions

Glulx/Glk extensions ecosystem

Extension Writing Guides

Standard Rules

I7 includes the Standard Rules in every game. They’re the authority on I7’s World Model and defaults and can be browsed within the IDE: see “Contents” for any compiled game. They used to be called Appendix A of the docs.

Per WI 27.14, some things in the SR may look modifiable but they’re really interdependent with something hard-coded in the compiler. Beware that the past three versions’ Standard Rules (6L02, 6L38, 6M62) are all marked Version 3/120430 but each is different. (Likewise, 6E59 through 6G60’s Standard Rules are each different but all marked Version 2/090402.)

Games/examples with Source Code available

Inform 6

I7 compiles to I6 before that gets compiled to Glulx or z-code. The I6 Standard Library isn’t involved; I7 uses the I6 Template Layer that Inform installations have under Internal/I6T. Once called Appendix B of the docs, the template layer’s comments document some things not documented elsewhere.

Why learn I6 and the template layer?

  • interacting directly with the I6 layer (as many extensions do) is the best or only way to do some things
  • some I7 behaviors are best understood as artifacts of I6 representations
  • directly reading auto.inf (the I6 code generated by the I7 compiler) can be invaluable for troubleshooting

Useful threads/posts

Licensing

How to Organize/Structure Your Project

There’s no one answer; here are multiple answers. See games with available source code for examples.

Bugs

9.3 is no longer maintained; 10.1 fixes several bugs in 9.3. You can search for known bugs and their status or report bugs on the I7 bug tracker. If you’re not sure whether you’ve found a bug, post code that shows the issue to the I7 category and ask.

6M62 Patches by Friends of I7 provides fixes for some known issues in 9.3/6M62.

The I6 that shipped with 9.3/6M62 was 6.33N. The current version is 6.42. Bugs in (the current) I6 can be reported at the Inform 7 bug tracker

The old I7 suggestion forum is accessible via archive.org.

Infrastructure

I6 compiles to your choice of glulx or Z-code (v8 only – I7 games can’t fit in prior versions)

Glulx

Glulx interpreter apps include one or more of:

Others:

Glulx Inform Technical Reference

Glk

Glulx I/O is via the Glk API; glulx terps must be built with a Glk library (built-in for Emacs-glulx/Zag)

  • cheapglk (no window, no status line, just streams of input and output; of interest largely for testing and development)
  • glkterm (curses library, widely available for anything UNIX-ish)
  • glktermw (“wide char” glkterm for Unicode characters beyond Latin1)
  • GlkOte (Javascript implementation used by Quixe and Lectrote)
  • cheap-glkote, a Glkote variant underlying the ElseIFPlayer
  • remglk (Receives/emits JSON objects on stdin/stdout; can represent multiple windows and most Glk events)
  • CocoaGlk (used by the Mac IDE)
    Per its spec, Glk doesn’t offer the revelant text color control to match the Z-machine, but the non-standard Gargoyle Glk extensions can do so. Implementations including them:
  • garglk (the Gargoyle multi-system interpreter)
  • WindowsGlk (Windows IDE)
  • Async Glk Typescript implementation used by Parchment / iplayif.com
  • Chimara GTK3 widget (Linux IDE)
  • Spatterlight’s Glk from Spatterlight

More Glk implementations in IFArchive

Differences between javascript & C Glk APIs

The results of display the boxed quotation look bad in Glk. Spatterlight, Gargoyle, Lectrote, and Parchment use Glk for their Z-machine I/O as well as Glulx, so with these apps, Z-machine games inherit boxed text quotes looking bad.

Glk via network

Glk References

Z-machine

There are countless Z-machine interpreters, e.g.

Z-machine References

Tools and Projects

@Zarf 's

Others

Legacy

I7 in translation

Hosting

Miscellany

Ryan Veeder

Jeff Nyman

@emshort

Updating 6G60 code

IF Resource Links has much more of interest to IF authors in general, not specific to I7

Language Comparisons

History

Toward I6: New Tricks for an old Z-machine

  1. Digging the Trenches
  2. Hacking Deeper, or Follies of Graham Nelson’s Youth
  3. A Renaissance Is Nigh

Toward I7

Toward I7 v10

How to Not Lose This Post

This post is pinned to its category. By default Discourse unpins a thread when you reach the bottom. This can be deactivated in Interface under Preferences in your Profile. Or you can bookmark it: the bookmark icon is at the bottom of the post (you may have to select a … icon to see it). To see your bookmarks, select your profile icon in the upper right, then select the bookmark icon there. If you do lose the post, search the forum for “documentation and resources” or visit while logged out.

Bookmark interface

428x64

690x385
690x385903Ă—504 53 KB

The documentary and resourceful goodness continues in the I7 Documentation and Resources Annex one post below!

20 Likes
81

I7 Documentation and Resources Annex

Ryan Veeder’s audiobook of Writing with Inform

82

Rockin; thank you :slight_smile:

83

Could this be made sticky?

84

Done

85

Would be nice to have an I6 sticky as well, preferably A B O V E the I7 sticky so that there is no doubt as to which language is the original and which the knockoff.

1 Like
86

I would especially push for the link below (which is actually mostly in Inform 7). It’s Appendix A – i.e. the Standard Rules commented and explained literate programming style. To my mind, it’s a vital part of the I7 documentation.

87

For what it’s worth, I haven’t updated the syntax document for the last build, and don’t expect to do so going forward, because the indexing has improved enough that it should now provide a comprehensive reference for that kind of thing (and it’s automatically cross-linked with the documentation). But if people find the old document useful to browse anyway, that’s fine – just be warned it’s largely been supplanted.

88

Excellent!

89

Also, this link to Appendix B, the underlying I6 template layer–just as vital in my opinion as the documentation of the Standard Rules.

inform7.com/sources/src/i6templa … index.html

–Erik

90

Thanks for the comments folks, I’ve updated the OP.

91

I third this suggestion. I also recommend that, if the author will be updating the first post, the title be updated, too, so we also know when this was last updated.

92

Good suggestion, done.

93

Yay, glad I could contribute in some small way!

I know that one thing I’m only just discovering is how to use the skein and transcripts from it. Is there any website that guides us through that?

I also had no idea how to use the IDE’s features for looking through all standard actions. I’d think if someone could make a youtube video or selection of screenshots to guide a person through, that’d be hugely helpful. I suspect once people know this sort of thing is there, that’s a lot less work.

Finally, one of the big roadblocks I’ve had is knowing which extensions to use. So many times, I’ve been wondering if I should bother programming X and not knowing whether there was an extension Y that would take care of it. I think any one person’s documentation generally catches some good ones, but is there something more general? I know I’d find it useful to be able to see programming examples or evaluations. Beyond the extension authors’ own, which I don’t want to belittle. But it’s more the “wow, other people can use this”

Is anyone aware of these? Does anyone want to create such a page? Are these questions out of the scope of the topic? I hope I haven’t hijacked the thread, but really, I’m glad someone took the time to tie this up, and I thought I’d ask a few more questions while I was at it.

One final thing–let us know whether it might be better to PM/email you with small changes, or if we should just post here.

94

Posting in the thread works for me. At some point it’ll make more sense to put this somewhere that’s generally editable, like ifwiki, and I’ll probably just post a redirect link in the OP.

Your questions about extensions definitely are relevant, and in fact Aaron Reed proposed something very similar, see this topic Extension Census 2010 - #7 by George. I don’t know if he’s gone further than that.

95

This is a very low-tech way to address this, but I usually go to the Extensions page, click “All Extensions by Category” (or any of the other aggregate links), and do a quick in-page search for keywords related to the problem I want to solve, like “liquid” or “inventory” or whatever.

Regarding better extensions visibility: I think everyone agrees it would be great to have this integrated into the IFDB, or give more sharing and community features to the official site, but it’s as usual a question of volunteer-hours available. We’ve tried to kick-start this a couple times but it involves major work and coordination of effort between several people, and it just hasn’t come together yet.

In the meantime, it would be awesome if someone started a third party site promoting extensions somehow-- I’m afraid it’s not going to be able to be me at the moment, although I’d certainly be open to contributing if a group effort arises.

96

This has worked well for me. I think it is good and will work for others, too. However, it’s those moments where someone points something out and I say “of course the extension was there, and of course it did this” that work really well.

Sounds like a good idea for a spinoff topic. I would like to be part of this effort, because I think my biggest growths as a coder have occurred when I realized that, yes, you could do this-or-that easily.

Though obviously this’d require a lot of white paper, I have some ideas. However, I also have no idea how to go about building a website, or how to possibly integrate a website into something bigger. Simply giving statistics on how many games use which extensions, and maybe a blurb on how they use it, could be effective. Granted, the quality of the games may not reflect the quality of the extensions, but there’s a lot of “how’d they do this” that gets dispelled pretty in a game, regardless of quality, that you don’t see in an example.

I also have no clue how much/little extension authors tolerate/appreciate having an extra example made that uses their extensions. But in my experience, I generally have to use an extension in a dumb game before I’m brave enough to use it in something real.

97

Two more I7 reference documents (slightly oldish):
Emily Short’s 2007 draft of an I7 syntax reference at http://www.inform-fiction.org/I7Downloads/Documents/I7_syntax.txt.
And a document giving the grammar for I7 in Backus-Naur notation at http://www.inform-fiction.org/I7Downloads/Documents/I7-Grammar.pdf. (Not sure about its up-to-datedness.)

98

I’d love to read some of Emily Short’s code after seeing in another post that it’s “spectacularly clean.” Organization is an area in which I’m really interested in developing a good practice.

Where’s the source code at this link? For example, here’s the entry for Bronze:

ifdb.tads.org/viewgame?id=9p8kh3im2j9h2881

I’m sure it’s just me, but I can’t find a link on this page for the source code.

Thanks!

99

All of Emily’s released source is linked from here. (It would be sensible if the IFDB pages also had links to it, though.)