25. Releasing

Writing with Inform

WI §25.1 The finished product

This chapter and the next are about what to do when we have a complete, finished work on our hands.

For almost all of the time when a new work of IF is being written, it lives inside the familiar two-panel spread of the Inform user interface. But that isn't how eventual players will experience it. They will want to play a "story file" in a standard format, and they will do so with a wide range of different interpreters on many different computers or websites, including some – like mobile phones – on which Inform itself will not run.

So how does a new work of IF reach players? The simple answer, covered in this chapter, is that clicking the Release button instead of Go causes Inform to output a stand-alone story file. But as we will see, Release can do much more than that: it can attach covers, include bibliographic data, make websites and much more. Releasing is the process of making all of the material we want to deliver to our eventual players.

But that is only the first step. What do we do with the material when we have it? Printing out a manuscript of a novel is not the same as publishing it. So the next chapter, on Publishing, completes the story.

WI §25.2 Bibliographic data

Almost all printed books have a title page and a so-called "imprint" page, often its verso, which make up a description of the contents. The title page gives the name of the book and of the author, while an imprint page contains a variety of details about the edition, the printing, and so on. An ISBN number is allocated so that, from the number alone, any book seller or cataloguer can identify exactly this work. Sometimes other cataloguing information is added, such as the Library of Congress classification. This set of information is called "bibliographic data", and without it libraries and booksellers would be at a total loss.

IF has bibliographic data, too. Inform has a number of special named values to hold this – who wrote the work being created, what it is called, what headline it has, what genre it has and what its release number is, and so on.

These can be set as follows:

The story title is "Mansfield Perk".
The story author is "Janet Austen".
The story headline is "An Interactive Romance".
The story genre is "Romance".
The release number is 7.
The story description is "In Miss Austen's new interactive novella, Miss Henrietta Pollifax is adopted by the tempestuous landowner Sir Tankerley Mordant, and must make a new life for herself on the rugged moors."
The story creation year is 2005.

Most of these are self-explanatory. The "story creation year" is provided so that if we need to revise the work to fix some bugs a year later – by no means an uncommon occurrence – then we can make sure it is correctly identified as still being basically a 2005 work. (Just as a book which has had innumerable revised printings may say "First published 1988" on its imprint page.) The "story description" is a piece of text, analogous to the back cover blurb on a book: it might be two or three paragraphs long, so the example above is rather minimal, but it should not be epic in length.

As we have already seen, a convenient abbreviation provides that if the first sentence of the source text consists solely of text in quotation marks, then that is considered the title. Thus if the source begins:

"Mansfield Perk"

then that will be the "story title". Further, we can write

"Mansfield Perk" by Janet Austen

with the obvious effect: quotation marks around the author's name are optional here, for convenience, but note that we'd better have them in cases like:

"Three Men in a Boat" by "Jerome K. Jerome"

as otherwise the full stop after the K will end the sentence prematurely.

The text of these bibliographic descriptions cannot normally include text substitutions, since they are written into external descriptions of the story file as part of its "binding". Two exceptions are allowed, though: "[']" makes a literal apostrophe, and can be used if we need to override Inform's normal conventions to do with converting apostrophes at the ends of words to double-quotes. For instance:

"Summer of [']69" by Buzz Aldrin

The other exception is that the "[unicode …]" text substitution works, so for example:

The story description is "This is a sentence[unicode 8212]with a parenthetical in dashes[unicode 8212]because 8212 is the Unicode number for an em-dash. But for example, 'pawn to [unicode black chess bishop]4' draws in a black chess bishop, so it works with names, too."

If the bibliographic named values are not set by the source text, Inform will still need to say something. Unset text and number variables evaluate to "" and 0 respectively, but this would make for a very unhelpful record. So Inform uses the following table instead of any value which is unset:

Story title: Untitled
Story author: Anonymous
Story headline: An Interactive Fiction
Story genre: Fiction
Release number: 1

WI §25.3 Genres

The "story genre" is not used in the banner at all, and exists purely to help librarians. If it is at all possible to do so, authors are asked to use one of the following standard categories:

Comedy, Erotica, Fairy Tale, Fantasy, Fiction, Historical, Horror, Mystery, Non-Fiction, Other, Romance, Science Fiction, Surreal

These categories are based on those currently used by bookshops, but a few notes may be helpful. "Fiction" is intended for works whose essential purpose is literary, in a way which trumps any subject they happen to have: if Julian Barnes writes a mystery, for instance, a bookshop will shelve it with modern novels rather than in the detective stories section, whereas P. D. James's Adam Dalgliesh mysteries will end up filed with detective fiction even though she has appreciable claims to be an important novelist.

"Comedy" is used rather than "humour" to avoid the clash of spellings with "humor". This genre includes parodies.

"Non-Fiction" would be used for a work of IF which is essentially a presentation, perhaps in a novel interactive format, of true information. A meticulous simulation of the Great Exhibition of 1851, for instance, might qualify.

The distinction between "Surreal" and "Other" is that "Surreal" works contain at least some semblance of narrative, whereas "Other" is intended for works which "abuse" the format to present some entirely different sort of game – Tetris, say, or Minesweeper.

WI §25.4 The Library Card

Bibliographic data is useful for two reasons. Firstly, it enables the equivalent of a title page to be printed – traditionally called the "banner" – at the start of play; secondly, Inform uses it to generate the equivalent of a library card for the work, which can be used by other programs to help organise, sort and classify interactive fiction. If the card is given to any other program on any other machine (or an Internet-based archive) then, in principle, that system can know about our work of fiction without a human librarian having to get hold of a copy, play it and laboriously copy out the details.

The "library card" is not of course a physical card, but a small "metadata" file which could potentially be transmitted quickly across the Internet. It contains no personal data other than what you choose to put on it, using the sentences documented in this chapter: it does not, for instance, identify your computer or IP address. In any case Inform does not send it anywhere, but merely keeps an up-to-date copy within the project, and includes it when making a release copy of the work. You can always see (a representation of) the current library card for a project in the Contents index.

Authors are asked to play fair, in return, by writing sensible and useful bibliographic information for any work which is likely to circulate to other people; by being honest (writing under a pseudonym is fine, but not impersonating other people); and by conforming to standard practice.

The Settings panel of each project contains a tick-box called "Bind up into a Blorb archive on release", and by default this is ticked. "Blorb" is a nonsense word from a popular early 1980s work of IF called "Enchanter", where it was the name of a magic spell whose purpose was to "safely protect a small object as though in a strong box". In the late 1990s, the name was borrowed for a standard format for what might be called the wrapping and packaging of IF. A typical Blorb archive produced by Inform contains the "story file" – the actual program for the story – together with its library card and cover art.

Modern IF interpreters such as Zoom for Mac OS X and Unix, and Windows Frotz, can play blorb archives directly, and the authors of Inform hope to make this the normal practice in future. Still, some interpreters cannot read blorbs directly and have to be given the actual story file: so by unchecking the above tick-box, we can insist that Inform creates only that. The disadvantage with this, of course, is that the library card (with all its bibliographic data) and any cover art is lost in the process.

WI §25.5 The Treaty of Babel and the IFID

During March and April 2006, an agreement was reached between the IF archive and most of the different systems for creating IF – of which Inform is only one – called the Treaty of Babel. While these different systems create computer programs which are quite different internally, the Treaty provides for works of IF to come with bibliographic data which identifies them in a standard way.

Inform is fully compliant with the Treaty. In particular, each new project created by Inform is allocated a unique identification number called its IFID. The IFID is the equivalent for IF of the ISBN of a printed book. Inform copies it onto the "library card" for the benefit of Internet-based libraries which may eventually accession the work. Of course many projects start but never see the light of day, so many possible IFIDs are "wasted": but that hardly matters, as there are plenty more numbers in the world.

The important thing is that

The IFID number must be unique to this one work out of all the IF ever created

Inform will make sure this is true, unless we do something to break this ourselves. For instance, if we take an existing project, copy it as a file, then work divergently on the original and on the copy so that they become two radically different works, they will still each have the same ID. This is a bad thing: if we want to duplicate a project but then turn it into something new, the best way to do that is to create a new project, and to copy and paste the source from the old to the new.

WI §25.6 The Release button and the Materials folder

Inform's Release button does two things: it makes a stand-alone, public version of the current project – a "story file" – and it gathers up, or creates, whatever material we want to go with it.

The release version of the project can be played by anyone with an "interpreter" – they do not need the Inform application installed on their computers, and they will not be able to see the source text. Released versions differ slightly from the versions playable in the Story panel of Inform, because debugging commands such as ACTIONS are not included with them. (As we've seen, also excluded is any material in the source text under a heading including the words "not for release".) In some cases, if we release along with an interpreter, we can even make the project playable from a web browser, so that the player doesn't need to install any software at all, not even a browser plugin.

The Release button also creates a ".materials" folder for the project, if one doesn't exist already. (On some platforms, the Inform user interface creates it automatically alongside the project.) Inform adopts the following convention:

The files associated with the project "Whatever.inform" should all be kept in a subfolder called "Whatever.materials" in the same folder that contains the project.

For example, if we have a project filenamed Magician.inform which lives in a folder called "Works in Progress", then files might be arranged like so:

Works in Progress
   Magician.inform
   Magician.materials
      Collegio.pdf
      Mating Wyverns.mp3

Of course "Magician" might not actually be the title of the project – it might be an abbreviation, or a working title. The name of the .materials folder has to match the name of the .inform file, not the title.

Several advanced features of Inform make use of the materials folder, and the "Release" button is one of them. It creates a further subfolder called "Release" within the materials folder. This is where it will always place the story file it creates, together with anything released "along with" the story – Inform will not need to put up a dialogue box asking us where to save the story file, because there is already a natural place. For instance, after a successful click on Release, we might then see:

Works in Progress
   Magician.inform
   Magician.materials
      Collegio.pdf
      Mating Wyverns.mp3
      Release
         Collegio.pdf
         Magician.zblorb
         Mating Wyverns.mp3

where "Magician.zblorb" is the actual story file produced by Inform. Note that Inform has made copies of the files to be released with it – the idea is that the Release subfolder contains only what Inform makes, and everything in the Release subfolder can be thrown away at any time.

This is especially useful if we're releasing along with a website (see below), as then the Release subfolder will be exactly what needs to be uploaded to a server to be shown to the world. Equally, the Release subfolder is what can be zipped up and uploaded to archives or (if small enough) emailed out.

WI §25.7 The Joy of Feelies

"Feelie" is a slang word, again going back to the early days of IF, for something tactile included with commercially sold copies of IF games. For instance, Infocom's "Wishbringer" was not just a diskette in a pretty box: the box also contained a map, a letter, an envelope, a magic stone (well, a stone) and a booklet. Most of this was purely for fun, and to flesh out background to the story, but there would usually be clues sneaked into the text or artwork as well.

Today's IF is usually not supplied in physical packaging, and not accompanied by physical objects. But authors do sometimes want to include extraneous matter, whether it's a simple read-me file of instructions or a multimedia extravaganza. Inform does not provide facilities to make artwork, movies, soundscapes, booklets, etc.: there are plenty of programs out there to do all of that already.

But Inform does help with the collation and packaging-together. For instance, by placing the following sentence in the source text:

Release along with a file of "Collegio magazine" called "Collegio.pdf" and a file of "The mating call of the green wyvern" called "Mating Wyverns.mp3".

…we tell Inform that we will also be providing two additional files. Note that in each case we supply a brief description and a filename. The filename should always have a standard file extension for a well-known and thoroughly standardised file format – ".pdf" and ".mp3" are pretty safe: so for instance are ".txt", ".png", ".jpg", ".html". The filename should not include punctuation marks other than the full stop dividing name from extension, and should not exceed 30 characters in length.

It is also possible to supply a feelie which is not a single file, but is a mini-website: that is, a collection of interlinked HTML (and perhaps other) files. The convention here would be:

Release along with a file of "Baltrazar's Guide to Magic" called "Guide".

The absence of a file extension on the filename "Guide" tells Inform that the feelie in question is a mini-website: it is expected to sit inside a folder called "Guide", with its home page being "Guide/index.html". However, a mini-website like this must be created by hand: Inform does not copy it into place, it only creates links to the place where it ought to be put.

We have seen that Inform takes the story file, which is analogous to the pages of a book, and places it into a Blorb archive, analogous to the binding. These new additional files are not placed in the Blorb, because that would make the Blorb archive rather large (and would hide them from the player, which defeats the purpose). But references to them do appear in the Blorb, so that any interpreter playing the Blorb would be able to tell that there are supposed to be additional files available. Similarly, references are entered onto the library card.

WI §25.8 Cover art

Accompanying files are not the only things which can be included in a "release along with" sentence: for instance, we could

Release along with cover art ("A stone gargoyle"), a file of "Collegio magazine" called "Collegio.pdf" and a file of "The mating call of the green wyvern" called "Mating Wyverns.mp3".

Cover art can not only be used to advertise a work of IF, it is also displayed to players by certain interpreters, such as Zoom or Spatterlight for OS X, or Windows Frotz for Windows. It is also used on the IFDB (ifdb.org), and by browsing applications. If Zoom is installed, then on Mac OS X Leopard, the Finder shows cover art directly:

Cover art for a work should be prepared in either JPEG (".jpg") or PNG (".png") format, and we recommend that it should be square, like a music album cover. Programs which notice the cover art for a work of IF are likely to scale this up or down as convenient for their own display purposes, but it would be helpful to provide the original art at 960 by 960 resolution. The cover art must not be smaller than 120 pixels in either dimension.

To provide cover art, we should create an image file called Cover.jpg, or else Cover.png, and place it in the project's .materials folder. For instance, we might have:

Works in Progress
   Magician.inform
   Magician.materials
      Collegio.pdf
      Cover.jpg
      Mating Wyverns.mp3

(supposing that, as in the previous examples, "Collegio.pdf" and "Mating Wyverns.mp3" are the filenames of two feelies that accompany the release).

The text in brackets after the release instruction…

Release along with cover art ("A cathedral at sunset.").

…is provided for the benefit of blind or partially sighted users, and should be brief.

WI §25.9 An introductory booklet and postcard

When IF is aimed particularly at people who have never played IF before, there are certain conventions which it's a good idea to explain, or players will simply not know what to do. It can become a chore writing a clear set of instructions, and then there is the further nuisance of explaining about the need for an interpreter program to play the IF story file.

To alleviate this, Inform can "Release along with an introductory booklet", as for instance in this example:

Release along with cover art, the introductory booklet, a file of "Collegio magazine" called "Collegio.pdf" and a file of "The mating call of the green wyvern" called "Mating Wyverns.mp3".

The introductory booklet is a standard 8-page PDF file, written and designed by Emily Short, which contains all the basic information needed for a player to get started. It has been written to be as general-purpose as possible, in the hope of being useful for a range of widely different works of IF. There will certainly be works to which it would not be an appropriate supplement, and some authors will certainly prefer to write their own notes for players, but of course it is not compulsory. By making it available as a convenience, the authors of Inform do not intend to say that these are the "official" instructions or that others are not. It is simply intended as a time-saver.

As an alternative, or a supplement, it's also possible to:

Release along with an introductory postcard.

which supplies a standard postcard about IF (everything new players need to know, at one glance) written and designed by Andrew Plotkin and Lea Albaugh.

WI §25.10 A website

Much of the published IF of the last twenty years came with a brief text file describing what it was – a release note. Today it makes more sense to write this as a small web page, which can either be placed online, or simply distributed as part of the release.

Inform is able to manufacture such a website automatically. We request this by writing, for instance,

Release along with cover art, a website, a file of "Collegio magazine" called "Collegio.pdf" and a file of "The mating call of the green wyvern" called "Mating Wyverns.mp3".

where the list of ingredients now includes "a website". In fact, Inform makes only a single web page, called "index.html", which it places in the materials folder (as set up in the previous section): this then contains suitable links to all the other material, such as the cover art images, if they are also provided. For instance:

After a successful release now, then, we should see:

Works in Progress
   Magician.inform
   Magician.materials
      Collegio.pdf
      Cover.jpg
      Mating Wyverns.mp3
      Release
         Collegio.pdf
         Cover.jpg
         index.html
         Magician.zblorb
         Mating Wyverns.mp3
         Small Cover.jpg

("Release/Small Cover.jpg" is a form of the cover image intended for display at a smaller size. In earlier versions of Inform, the author had to provide this: there is now no need.)

WI §25.11 A playable web page

Modern web browsers are now so powerful as computing environments that they almost amount to general-purpose computers in their own right. The websites made in the previous section were passive, and simply displayed information about a story file. But it's also possible to make a more active page – one which can play the story file, right inside the browser, for anybody who visits.

To make such a page, we must:

Release along with an interpreter.

This automatically releases along with a website as well, since we need the website in order to house the new page, which will be called "play.html". This page will be bundled up with a customised copy of a story file interpreter coded in Javascript – in effect, a program for a web browser to follow – and a suitably encoded version of the story file. The practical effect should be that anyone visiting the page with any modern browser can just play.

Inform ships with the "Parchment" and "Quixe" interpreters built in. By default Inform will use Parchment if the format (on the project's Settings panel) is set to Z-code, and Quixe if the format is Glulx. In fact, though, Parchment works with either format, and some users prefer using it. If we want to have Parchment even for a Glulx project, we can write:

Release along with the "Parchment" interpreter.

…and that's just what will happen. In fact, Inform also supports the use of any other interpreter the author wants to try. If we have access to an exotic Javascript-based interpreter called, let's say, "Urbzig", then we can install it by putting it into the "Templates" subfolder of the ".materials" folder for the project:

Release along with the "Urbzig" interpreter.

WI §25.12 Using Inform with Vorple

"Vorple" is an innovative system by Juhana Leinonen for allowing web-based Inform stories to make use of web controls and other gadgets. Using Vorple, a story can in principle have an entirely different user interface, and can make much better use of CSS styling, interface to Javascript libraries, and so on.

Vorple has seen rapid development. In its early days it was included as part of the Inform app, but it has now evolved into a dynamic project which is better served by its own website than from here:

WI §25.13 Website templates

Web pages are very idiosyncratic things and Inform will almost certainly not produce exactly what we want. What it actually does is to take an existing "template" web page, and paste in the relevant information to make the final product. So by starting with a different template, we can end up with an entirely different-looking web page: like this one, for instance -

The template ordinarily used by Inform is called "Standard" and comes built in. (A second built-in template, "Classic", imitates the look used in 2005-08. The word "classic" here is to be understood in the sense of Classic Mac OS, the classic Doctor Who adventure "Time and the Rani", classic Mayan civilisation, and so forth – really pretty awful.)

Any other templates we must make ourselves, giving each one a different name, by convention a single word. In this section, we'll make a new one called "Platinum".

Suppose we write:

Release along with cover art, a "Platinum" website, a file of "Collegio magazine" called "Collegio.pdf" and a file of "The mating call of the green wyvern" called "Mating Wyverns.mp3".

This is identical to the previous version except for the "Platinum": note the quotation marks. When it needs to find a template, Inform searches the following places in sequence:

(a) the "Templates" subfolder of the project's own .materials folder, if this subfolder should exist;
(b) the "Templates" folder in the user's own library - on Mac OS X, this is:
   ~/Library/Inform/Templates
or on Windows:
   My Documents\Inform\Templates
or on Linux:
   /Inform/Templates
(c) the built-in stock of templates, currently only "Standard" and "Classic".

What Inform looks for is a folder name matching that of the template – so in our case we need to provide a folder called "Platinum", and put it in either location (a) or (b).

The template folder is expected to contain some combination of the following files:

Platinum
   index.html
   source.html
   style.css
   (extras).txt

There are two HTML pages here, one for the main front page, the other for pages of displayed source text (if we release along with the source text – see later in the chapter). The CSS file defines styles of text – sizes, fonts, colours, and so on – and positions material on the page. The "(extras).txt" – which is optional, of course – allows additional HTML pages, images, movies and so on to be added.

If any of these is missing, Inform uses the one in "Standard" instead. In practice, this means the easiest way to create a new template is to supply just a new CSS file, which can change the colour, font, type size, and position of more or less everything in the site:

Platinum
   style.css

We probably want to start from the "Standard" version of "style.css" and edit in a few changes; the easiest way to get a clean copy of "Standard"'s CSS file to work on is to release the project with a "Standard" template, which causes this default "style.css" to appear in the "Release" subfolder of the project's .materials folder. (But it's wise to move the file out of "Release" before starting to edit it – files in "Release" are overwritten by Inform whenever a release is made.)

This is not the place to describe how CSS works. CSS is a more or less universal format today for describing how web pages should look – their style rather than their content. A dazzling variety of possibilities can be seen at the excellent:

but of course there are many, many other textbooks and websites which describe CSS.

WI §25.14 Advanced website templates

The following describes how Inform uses the extras file and the two HTML pages in a template, and will only be needed if a new template has to make changes so radical that altering the CSS alone won't be enough.

The optional "(extras).txt" file – note brackets – is a text file which contains a list of named extras to throw in. For instance:

easter.html
egg.png

These named files need to be present in the template folder. Files with the extension ".html" go through the placeholder expansion process just like the index and source pages; all other files are copied verbatim.

HTML templates like "index.html" and "source.html" are fully valid HTML pages in their own right, though they have placeholder text where Inform will substitute the project's bibliographic data (see below). The "<head>" element should include a reference to "style.css", which of course will mean the CSS file given in the template (or the one from "Standard" if no CSS file is given) – for instance,

<link rel="stylesheet" href="style.css" type="text/css" media="all" />

When it turns the template into the final web page, what Inform does is to replace certain capitalised words in square brackets with the appropriate text:

[TITLE] becomes the story title
[AUTHOR] becomes the author's name
[YEAR] becomes the story creation year
[BLURB] becomes the story description
[RELEASE] becomes the release number
[COVER] becomes an image of the cover art (the small 120x120 cover image)
[DOWNLOAD] becomes the download link
[AUXILIARY] becomes the list of feelie-like files, if any
[IFID] becomes the IFID
[STORYFILE] becomes the "leafname" of the story file, e.g., "Bronze.gblorb"
[TEMPLATE] becomes the name of the template used to make the page
[SMALLCOVER] becomes the filename of the cover when used at a smaller size
[BIGCOVER] becomes the filename of the cover when used at full size
[TIMESTAMP] and [DATESTAMP] become the time and date of releasing

Everything else is left alone. In source pages, five further placeholders are available:

[SOURCE] becomes the portion of the source text on this page
[SOURCELINKS] becomes the navigational links
[SOURCENOTES] becomes the footnote matter at the bottom of the source
[PAGENUMBER] and [PAGEEXTENT] are such that the text "page [PAGENUMBER] of [PAGEEXTENT]" produces, e.g., "page 2 of 7"

Both [SOURCE] and [SOURCENOTES] must exist on the page, and [SOURCENOTES] must appear after [SOURCE] does in the file. (Of course the CSS in "style.css" might move the copy around on screen, but that's another matter.)

WI §25.15 Republishing existing works of IF

Some long-time users of Inform will have projects which were originally made using the very different Inform 6 language. Story files produced with Inform 6 do not have any of the extra touches in this chapter: in particular, they have no cover art and no bibliographic data, which makes them rather plain and anonymous to newer Treaty of Babel-equipped programs like Zoom, Spatterlight or Windows Frotz.

To help with this, today's Inform can republish an Inform 6 project by combining an Inform 7 source text which contains only release instructions and bibliographic data with an already-compiled Inform 6 story file. We do this by writing a short source text which contains:

Release along with an existing story file.

We then place the story file in the ".materials" folder. By default this will be called "Story.z8", but we can alternatively name it:

Release along with an existing story file called "Zork1_sg.z5".

The Settings panel must be switched to the Z-machine for this to work, since only Z-machine story files are supported this way, not Glulx. And we can now use the Release button to obtain the goods.

An existing story file can take advantage of all of the extra features – cover art, titling, website, feelies and so forth – earlier in this chapter, but not those – walkthrough, source text, map – which are still to come.

The following is a typical example of a source text used solely to bind up an old Inform 6-compiled story file:

"Curses" by Graham Nelson
The story genre is "Fantasy".
The story headline is "An Interactive Diversion".
The story creation year is 1993.
The release number is 16.
The story description is "It's become a matter of pride now not to give up. That tourist map of Paris must be up here somewhere in all this clutter, even if it has been five years since your last trip. And it's your own fault. It looks as if your great-grandfather was the last person to tidy up these lofts..."
Release along with cover art and an existing story file.

WI §25.16 Walkthrough solutions

Since the earliest days of IF, players have distributed solutions to well-known stories, to help out other players at their wits' ends. The commonest format for these is a list of commands to type, sometimes with notes in the margin, and such a solution is called a "walkthrough", since it walks a player through the story.

Few authors publish solutions of their own works, but many supply their testers with solutions, especially towards the end of testing, or submit a solution as part of a competition entry. To help with this, Inform can generate such a walkthrough solution automatically:

Release along with a solution.

Inform will then place a file called "solution.txt" inside the "Release" folder. The solution might look like so (although probably much longer):

Solution to "Memoirs of India" by Graham Nelson
Choice:
INVENTORY -> go to branch (1)
EAST -> go to branch (2)
Branch (1)
DROP MANUSCRIPT
SOUTH
Branch (2)
INVENTORY ... Always a good idea
GIVE MANUSCRIPT TO THOMAS

Inform does not, of course, know how to solve IF all by itself, but derives the solution from the project's Skein. Since the Skein will have been used in testing the story, it will very likely contain a perfect solution – or several different ones, taking the story to a variety of possible endings. In the example above, there are two possible winning lines, which diverge right from the first move. (There can be further divergences: for instance, if branch (2) splits, it will split into branches called (2.1), (2.2), (2.3) and so on.)

But the Skein will also contain plenty of unwanted diversions, so Inform does not rewrite the entire Skein as a solution. Instead, it looks for knots in the Skein which have been annotated. Any knot whose annotation begins "***" (three asterisks) is considered to be a final, winning move. (It is probably a good idea to lock such a knot once it has been annotated thus, too.) We can mark any number of knots "***" since, after all, we can declare any number of lines of play as possible solutions. Inform then constructs the solution out of all lines of play in the Skein which lead to "***" endings, and ignores other threads.

Annotations other than "***" in the Skein are turned automatically into comments in the solution text. For instance, the knot for the INVENTORY command in the second branch above was annotated "Always a good idea", and this was transcribed into the solution. (If an ending knot is annotated with, say, "*** Happy ending!" then the "***" marks it as an ending, and "Happy ending!" is added as an annotation to that ending.)

By default, the solution text is not linked from our webpage, on the assumption that we may want to generate a walkthrough but not immediately advertise it to players. If we wish to change this, we may write instead

Release along with a public solution.

The terms public and private may also be applied to other elements we are having Inform generate to include on our webpage: see also the notes on private source text, below.

WI §25.17 Releasing the source text

Most authors will not want to publish the source text alongside the work itself, because this gives away all of its secrets. Inform provides the option mainly for the sake of the examples published on its own website, where making the source available is the whole point. But anyone is welcome to use the option, of course:

Release along with the source text.

If Inform is not also generating a website, this produces a plain text file called "source.txt" in the "Release" folder, and there is nothing more to be said.

However, if a website is also being released, the source is also converted to a suite of web pages which are linked to and from the home page. (Each heading with substantive content is placed on its own web page, with the opening page containing a contents list.)

Comments in the source are rendered in grey. As a special feature, any comment which begins with an asterisk is considered a footnote and is printed below the source text, with a link. Thus comments thus:

Hercules is a demigod.[* We're using Greek spellings so he ought to be Heracles, but players are so much more familiar with Hercules.]

will be printed more like so:

Hercules is a demigod.[1]
...
Note
[1]. We're using Greek spellings so he ought to be Heracles, but players are so much more familiar with Hercules.

Footnotes are automatically numbered from 1 on each source page.

By default, the source text is linked from our generated webpage, if we are releasing with a webpage. If we wish to change this, we may write instead

Release along with the private source text.

This will create a text file containing the source for our story, and place this file in our release folder, but not create a link so that the player can find it.

Finally, we can:

Release along with the library card.

which releases a stand-alone XML file in 'iFiction' format for the bibliographic data on the story file; this is the same data embedded in the blorb file itself, but having an external copy makes it easier to see what Inform has done, and some external programs can read iFiction data like this.

WI §25.18 Improving the index map

As we have seen, "Release along with…" allows us to package up a work of IF with all manner of extra materials. But what are these to be? One popular option is to produce a map – sometimes partial, sometimes obfuscated – and supply that with the story: besides, there are some IF competitions where the rules require that the referee is supplied with a map even if the players are not, and failing that, it is sometimes nice to be able to print out a map of a work in progress.

The World map in the Index tab is heavily stylised and cartoonish, intended to be clicked on or moused over, and viewed in a browser: although it is, in fact, possible to print it, the results are not very good. Fortunately, the same underlying map mechanism can be used to output something more useful and very much more customisable, as we shall see.

The map-maker is one of the most complex parts of Inform, even though it actually contributes nothing to the final story file: the problem of how to draw up a "correct" map from the source text is by no means easy to solve. Inform tries, but it often gets things wrong. Its general practice is to place rooms on a square grid (actually a cubic lattice, as it works in three dimensions), but not all conceptual maps fit well onto this, and Inform often annoyingly puts a particular room in the "wrong" place. For instance, suppose Inform puts "Didcot" east of "Abingdon" and this makes the geometry look different to what we had in mind. We can correct with:

Index map with Didcot mapped southeast of Abingdon.

Note that this says nothing about exits from any room to any other room, and changes the final work of IF not at all: it simply helps Inform to draw the map index. (Instructions like this one are treated as being almost certainly true, but Inform does not quite always obey: it will never allow two rooms to be superimposed at the same grid position, no matter what we have asked in "Index map with…" instructions.) The same trick is useful if we have a situation like so:

Inside of Sweeping Sands is Beach Hut Interior.

"Beach Hut Interior" is a single room which does not connect to the rest of the map by any of the ten spatial directions, so Inform does not place it on the main map but instead moves it off out of the way in a map of its own. Given that it's just a single room, however, we might prefer to put into a convenient otherwise empty grid position like so:

Index map with Beach Hut Interior mapped west of Sweeping Sands.

Finally, note that this trick also ensures that the two locations are mapped on the same level vertically, and can be useful in cases where room A is both north of and above room B: Inform will want A to be higher up than B, but we can insist otherwise.

WI §25.19 Producing an EPS format map

The "Index map with…" instruction is a much more varied thing than hinted at in the previous section, and its general form is

Index map with [instruction] and [instruction] and ... and [instruction].

where the instructions can be of four different forms, as follows:

[room A] mapped [direction] of [room B]
EPS file
rubric [text] ... and some optional details ...
[setting] of [whatever] set to [value]

We have already seen the first of these instructions. The second is short and has a fixed wording:

EPS file

so can be invoked by typing "Index map with EPS file.", for instance. EPS stands for Encapsulated PostScript, which is a standard file format for line art. EPS files can be edited with sophisticated graphics programs such as Adobe Illustrator, and can be used as illustrations in many word-processors and page layout programs. They can also be converted to PDF by Mac OS X Preview, or used in Linux or Windows with the open-source Evince viewer. We need a line-art format because the map produced will never be exactly what we want: we are probably going to end up hacking it to change the fonts, add some drawings, tidy up the spacing and so on. A really large map will end up using quite a large "canvas", in EPS terms; it may be necessary to shrink it down in order to get it onto an A4 page, or to adjust whatever editing software is used to "custom paper size".

When the map-maker has been given the "EPS file" instruction, it writes an attempt to draw the current project's map in EPS format as a file in the project's ".materials" folder, with the filename "Inform Map.eps".

Note that Inform will over-write any existing file of this name: but that is intentional, because one usually ends up tweaking and rebuilding the project over and over to get the map just so, and it would be tiresome for Inform to produce endless copies "Inform Map 19.eps", etc.

(The reason the EPS file is not placed in the Release subfolder is that it is not going to releasable to the public as it stands: for one thing it will be too raw, and for another, EPS is not a format everyone can read. It is provided as raw materials.)

WI §25.20 Settings in the map-maker

The map-maker has altogether 35 named settings, and tweaking these can affect the result in ways which vary from the subtle to the grotesque. An important point is that the map-maker deals separately with the three levels in its working: the big picture of the whole map; each of the vertical slices which contain sub-maps; and finally all of the individual rooms. For instance, we might have 67 rooms, arranged on 3 vertical levels, all shown on one big map: Inform will try to show these stacked above each other, with the highest level at the top of the map, then the middle level, then the bottom level.

Moreover, not only does the whole map have its 35 settings, but each level has its own independent collection of those 35 settings, and so does each individual room. So the actual number of variables in our example is 1+3+67 = 71 times 35, which is a lot. The convention is that setting the value of S (some setting, let's say) for something affects not only that thing, but also everything inside it, unless they have their own individual settings for S.

For example: one of the settings is called "room-size", and is the size of the little square boxes representing a room, measured in points. (One point is 1/72 of an inch, so 72 points equals 1 inch: it's a traditional printer's measure.) Suppose we write:

Index map with room-size set to 36
   and room-size of level 2 set to 28
   and room-size of the Hall of Kings set to 52.

The first instruction sets the value of "room-size" for the whole map (note the lack of an "of…"); the second for level 2 of the map, and the last for a single room only. The result is that the Hall of Kings is drawn as 52x52 point box, all rooms on level 2 are 28x28 (except the Hall of Kings, if it's on level 2), and all others are 36x36, half an inch square.

The setting instruction also allows three other useful forms. A setting "of the first room" applies to the room in which the story begins: we might for instance write

Index map with room-outline-thickness of the first room set to 2.

which gives this special room a bolder edge to it, since the default value is 1.

We can also apply settings not just to single rooms but to all rooms of a given kind:

A rivery room is a kind of room. Index map with room-colour of rivery rooms set to "Navy" and room-name-colour of rivery rooms set to "White".

Lastly, we can apply settings to all rooms in a given region:

Northern Oxfordshire is a region. Hampton Poyle and Steeple Barton are in Northern Oxfordshire. Index map with room-name-font of Northern Oxfordshire set to "Helvetica-Oblique".

(Note that rooms and regions don't have their own individual sets of the 35 settings: what happens is just that instructions like the last one change more than one room at once.)

WI §25.21 Table of map-maker settings

Note that all map-maker settings have single word names, though many are hyphenated, and that "colour" is always given the English and Canadian spelling, not the American form "color".

fontfont (named in double-quotes)
minimum-map-widthinteger (measured in points: 72 = 1 inch)
titletext (in double-quotes)
title-sizeinteger (measured in points)
title-fontfont (named in double-quotes)
title-colourcolour (named in double-quotes)
map-outlineon/off
border-sizeinteger (measured in points)
vertical-spacinginteger (measured in points)
monochromeon/off
annotation-sizeinteger (measured in points)
annotation-lengthinteger (length to abbreviate down to)
annotation-fontfont (named in double-quotes)
subtitletext (in double-quotes)
subtitle-sizeinteger (measured in points)
subtitle-fontfont (named in double-quotes)
subtitle-colourcolour (named in double-quotes)
grid-sizeinteger (measured in points)
route-stiffnessinteger (Bezier spline curve scale factor)
route-thicknessinteger (measured in points)
route-colourcolour (named in double-quotes)
room-offsetoffset (in percentages of grid-size)
room-sizeinteger (measured in points)
room-colourcolour (named in double-quotes)
room-nametext (in double-quotes)
room-name-sizeinteger (measured in points)
room-name-fontfont (named in double-quotes)
room-name-colourcolour (named in double-quotes)
room-name-lengthinteger (length to abbreviate down to)
room-name-offsetoffset (in percentages of grid-size)
room-outlineon/off
room-outline-colourcolour (named in double-quotes)
room-outline-thicknessinteger (measured in points)
room-shapeshape (named in double-quotes)

WI §25.22 Kinds of value accepted by the map-maker

Integer values are typed in the usual way: 3, -72, etc.

Text is in double-quotes: "Map of Lower Delta", etc.

Font names are in double-quotes: "Helvetica", etc. Note that Inform makes no effort to look for such fonts: if we give the name of a font we haven't got, the result will probably be that the map's EPS file will be displayed in various applications with Courier (which looks like bad typewriting) substituted. All fonts are by default equal to the global "font" setting (by default equal to "Helvetica"), so changing "font" for the whole map affects everything not explicitly specified as having a different font.

Shape names are in double-quotes with lower case. At present, the only legal shapes are "circle", "square" and "rectangle".

On/off values are written just thus: on, off. No quotation marks.

Offset values are actually pairs, and are written as two numbers (possibly negative numbers) joined by an ampersand, as in the example: "Index map with room-offset of Botley set to 10&-30." Note lack of spaces around the ampersand. This means that Botley's room is displaced from its correct grid position on the EPS map by 10% of the grid size eastwards, and 30% southwards. (The grid size is the distance between one grid position and the next: displacing Botley by -200&0 would move it two whole grid positions westwards.)

The route-stiffness setting is used when drawing routes between two rooms. These are drawn as Bezier curves, a standard way to make a smooth curve not only travel from A to B but also from pointing in a given direction at A to ending up pointing in a given direction at B. Thus a Bezier curve may turn a route round so that it leaves A pointing west, but curves around to enter B from the south. (Most routes involve leaving in one direction and arriving in the opposite direction, of course, and in those cases a Bezier curve is just a straight line.)

The stiffness factor for a given room measures how much the curves are allowed to warp around in order to force them to arrive at that room from exactly the right compass bearing. The default is 100. Raising to, say, 250 can force curved paths into freakish zig-zags: whereas lowering to 1, the minimum, may make the route arrive at completely the wrong bearing. (Formally speaking: at each end of the route, a "control point" for the Bezier curve is made by taking the centre point of the room, then adding the relevant compass bearing's vector, scaled up by the route-stiffness as a percentage of the grid size.)

Colour values are named and in double-quotes. These names are the same as those for the traditional set of web-page-safe colour chips, as follows:

"Alice Blue"
"Antique White"
"Aqua"
"Aquamarine"
"Azure"
"Beige"
"Bisque"
"Black"
"Blanched Almond"
"Blue"
"Blue Violet"
"Brown"
"Burly Wood"
"Cadet Blue"
"Chartreuse"
"Chocolate"
"Coral"
"Cornflower Blue"
"Cornsilk"
"Crimson"
"Cyan"
"Dark Blue"
"Dark Cyan"
"Dark Golden Rod"
"Dark Gray"
"Dark Green"
"Dark Khaki"
"Dark Magenta"
"Dark Olive Green"
"Dark Orange"
"Dark Orchid"
"Dark Red"
"Dark Salmon"
"Dark Sea Green"
"Dark Slate Blue"
"Dark Slate Gray"
"Dark Turquoise"
"Dark Violet"
"Deep Pink"
"Deep Sky Blue"
"Dim Gray"
"Dodger Blue"
"Feldspar"
"Fire Brick"
"Floral White"
"Forest Green"
"Fuchsia"
"Gainsboro"
"Ghost White"
"Gold"
"Golden Rod"
"Gray"
"Green"
"Green Yellow"
"Honey Dew"
"Hot Pink"
"Indian Red"
"Indigo"
"Ivory"
"Khaki"
"Lavender"
"Lavender Blush"
"Lawn Green"
"Lemon Chiffon"
"Light Blue"
"Light Coral"
"Light Cyan"
"Light Golden Rod Yellow"
"Light Grey"
"Light Green"
"Light Pink"
"Light Salmon"
"Light Sea Green"
"Light Sky Blue"
"Light Slate Blue"
"Light Slate Gray"
"Light Steel Blue"
"Light Yellow"
"Lime"
"Lime Green"
"Linen"
"Magenta"
"Maroon"
"Medium Aquamarine"
"Medium Blue"
"Medium Orchid"
"Medium Purple"
"Medium Sea Green"
"Medium Slate Blue"
"Medium Spring Green"
"Medium Turquoise"
"Medium Violet Red"
"Midnight Blue"
"Mint Cream"
"Misty Rose"
"Moccasin"
"Navajo White"
"Navy"
"Old Lace"
"Olive"
"Olive Drab"
"Orange"
"Orange Red"
"Orchid"
"Pale Golden Rod"
"Pale Green"
"Pale Turquoise"
"Pale Violet Red"
"Papaya Whip"
"Peach Puff"
"Peru"
"Pink"
"Plum"
"Powder Blue"
"Purple"
"Red"
"Rosy Brown"
"Royal Blue"
"Saddle Brown"
"Salmon"
"Sandy Brown"
"Sea Green"
"Sea Shell"
"Sienna"
"Silver"
"Sky Blue"
"Slate Blue"
"Slate Gray"
"Snow"
"Spring Green"
"Steel Blue"
"Tan"
"Teal"
"Thistle"
"Tomato"
"Turquoise"
"Violet"
"Violet Red"
"Wheat"
"White"
"White Smoke"
"Yellow"
"Yellow Green"

WI §25.23 Titling and abbreviation

The main title of the map is the value of "title" for the whole map, so for instance we might write:

Index map with title set to "Oxford and its Environs".

The subtitle settings apply to the subtitles used for each of the levels, so for instance

Index map with subtitle of level -1 set to "Tunnels and Sewers".

Names of individual rooms can be controlled with:

Index map with name of Radcliffe Camera set to "Library".

(By default, the name of a room is its name in the main IF project, of course.) The smallest writing on the map is normally that used to label unorthodox or unclear exits (in particular, those going from one layer to another): this is what the "annotation" size, font and colour are used for.

For most ways to set up the map, it's a practical necessity to abbreviate names of rooms, or they will spill out all over each other. Inform does this using the "room-name-length" setting. (The "annotation-name-length" is analogous.) For instance, if this setting is 5, then Inform will reduce the text of a name to at most 5 characters. It does this by successively throwing out spaces, lower case vowels, then other lower case letters, punctuation marks and finally upper case letters, always starting at the back of the name and working inwards: the process stops as soon as the name is short enough. For instance, "Reading" is abbreviated to "Redng", "Shangri-La" to "Shn-La" and "Cloud-Cuckoo-Land" to "C-C-L". The result can be a little comical, but is surprisingly unambiguous in practice. Abbreviation can effectively be abolished by raising the "room-name-length" to 128 (the highest permitted level), and note that the setting can be changed for individual rooms, so it is possible to have some room names abbreviated and others not, or in different degrees.

Examples

445.
Creating a floorplan of the cathedral using the locations from previous examples.
446.
Port Royal scenario given instructions for an EPS map.
Creating a map of Greece using the locations from previous examples.

WI §25.24 Rubrics

Lastly, we can add our own arbitrary text to the map: perhaps to annotate points, perhaps just to add more heading matter (such as the author's name, or the date). Each individual line added – and only single lines can be added, not typeset paragraphs – is called a "rubric". (There can be up to 100 of these.) We can create a rubric like so:

Index map with rubric "Here Be Wyverns" size 16 font "Helvetica-Oblique" colour "Thistle" at 150&0 from Cloud-Cuckoo-Land.

This gives rather more detailed information than is needed: "size 16" could have been omitted, giving us 12-point type by default, and similarly there is no need to specify a font unless it differs from the main "font" setting for the whole map; and the colour will be black if unspecified. The "at" position does need to be given, though. Note that it is relative to a given room on the map, and that the position specified is that of the centre-point of the text. (If we had written just "at 100&100", say, that would specify a position relative to the bottom left hand corner of the map.) So, for instance:

Index map with rubric "trapped door" size 8 at -60&-60 from Longwall.

would add a little 8-point-type safety tip for naive map-followers.

Inevitably, the settings in the map-maker will fail to get exactly the effect desired (though they will offer an excellent opportunity to waste entire days). But that is the whole point of producing output in EPS format: Inform aims not to produce final print-ready professional art, but to produce the raw material for making that final work of art. And if all that's required is a sketch-map, then Inform's output should be good enough quickly and without too much fuss.