1.1. Preface

The Inform Recipe Book is one of two interlinked books included with Inform 7: a comprehensive collection of examples, showing the practical use of Inform. The other book is Writing with Inform, a systematic manual for the software. If you are reading this within the Inform application, you will see that the Recipe Book pages are on "yellow paper", while the manual is on "white paper".

The Recipe Book assumes that the reader already knows the basics covered in Chapters 1 and 2 of Writing with Inform: enough to get simple projects working in the Inform application. It's helpful, but not necessary, to have some familiarity with the main ingredients of Inform. For instance, the reader who can play and test the following source text, and who can take a guess at what it ought to do, should be fine:

The Recipe Book is not a tutorial - it offers advice and examples to crib from, not theory or systematic teaching. The examples here are provided with the express intention that authors cut and paste useful passages into their own works, modifying as they go. This is an excellent way to get things working quickly.

In the traditional saying: good programmers write good code, but great programmers steal it. (Appropriately enough, nobody seems to know who said this first.) For the avoidance of any doubt - the example text is here to be taken, and this infringes no copyright, and requires no acknowledgement. So steal at will. The examples are a part of Inform itself, and as such, they are available to anyone who accepts the Inform licence.

Many programming languages for conventional computing, such as C, come with elaborate libraries of ready-written code - so elaborate, in fact, that they often need much larger manuals than the language itself, and can be hard to learn. Even expert programmers typically use only a small part of what is available in such libraries, giving up on the rest as too complex to use, or too difficult to find out about, or not quite what they need.

The designers of Inform chose not to go down this road. Rather than providing a general system for liquids (say), which would have to be a quite complicated and opaque program, Inform provides a choice of examples showing how to get different effects. The writer can read the text which achieves these effects, and can simply cut and paste whatever might be useful, and rewrite whatever is not quite wanted.

The wider community of Inform writers has made a great wealth of material available in the form of Extensions, too, and under a Creative Commons Attribution licence requiring only a namecheck: we don't cover the Extensions in this book, because it would grow far too long and be a constant labour to maintain, but it's well worth seeing what is out there.

See Acknowledgements for a chance to try out the cross-referencing links in the Recipe Book - click on the red asterisk or the name of the destination to go there

ExampleAbout the examples
An explanation of the examples in this documentation, and the asterisks attached to them. Click the heading of the example, or the example number, to reveal the text.

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.

ExampleMidsummer Day
A few sentences laying out a garden together with some things which might be found in it.

Chapter 1: How to Use The Recipe Book	Chapter 8: Vehicles, Animals and Furniture
Chapter 2: Adaptive Prose	Chapter 9: Props: Food, Clothing, Money, Toys, Books, Electronics
Chapter 3: Place	Chapter 10: Physics: Substances, Ropes, Energy and Weight
Chapter 4: Time and Plot	Chapter 11: Out Of World Actions and Effects
Chapter 5: The Viewpoint Character	Chapter 12: Typography, Layout, and Multimedia Effects
Chapter 6: Commands	Chapter 13: Testing and Publishing
Chapter 7: Other Characters

	Start reading here: §1.1. Preface
	Part I. Writing with Inform
	Indexes of the examples and definitions

	Contents of The Inform Recipe Book
	Chapter 2: Adaptive Prose
	Indexes of the examples

	Start of Chapter 1: How to Use The Recipe Book
	Onward to §1.2. Acknowledgements