About the examples

Example 1

★

An explanation of the examples in this documentation, and the asterisks attached to them.

This is the first of about 400 numbered examples. In a few cases, such as this one, they provide a little background information, but almost all demonstrate Inform source text. The techniques demonstrated tend to be included either because they are frequently asked for, or because they show how to achieve some interesting effect.

The same examples are included in both of the books of documentation, but in a different order: in Writing with Inform, they appear near the techniques used to make them work; in The Inform Recipe Book, they are grouped by the effects they provide. For instance, an example called "Do Pass Go", about the throwing of a pair of dice, appears in the "Randomness" section of Writing with Inform and also in the "Dice and Playing Cards" section of The Inform Recipe Book. Clicking the italicised WI and RB buttons at the right-hand side of an example's heading switches between its position in each book.

Many computing books quote excerpts from programs, but readers have grown wary of them: they are tiresome to type in, and may only be fragments, or may not ever have been tested. The authors of Inform have tried to avoid this. All but two dozen examples contain entire source texts. A single click on the paste icon (always placed just left of the double-quoted title) will write the complete source text into the Source panel. All that is then required is to click the Go button, and the example should translate into a working game.

In most cases, typing the single command TEST ME will play through a few moves to show off the effect being demonstrated. (You may find it convenient to create a "scratch" project file for temporary trials like this, clearing all its text and starting again with each new test.)

As part of the testing process which verifies a new build of Inform, each example in turn is extracted from this documentation, translated, played through, and the resulting transcript mechanically checked. So the examples may even work as claimed. But the flesh is weak, and there are bound to be glitches. We would welcome reports, so that future editions can be corrected.

Each example is loosely graded by difficulty: if they were exercises in a textbook, the asterisks would indicate how many marks each question scores. As a general rule:

★ - A simple example, fairly easily guessed.
★★ - A complicated or surprising example.
★★★ - An example needing detailed knowledge of many aspects of the system.
★★★★ - A complete scenario, containing material not necessarily relevant to the topic being demonstrated.

In general, the main text of Writing with Inform tries never to assume knowledge of material which has not yet appeared, but the trickier examples almost always need to break this rule.