-.. raw:: latex
-
- \newpage
-
====================
Tools of the trade
====================
.. epigraph::
- | *C was a captain, all covered with lace;*
- | *D was a drunkard, and had a red face.*
+ | |CENTER| *C was a captain, all covered with lace;*
+ | |CENTER| *D was a drunkard, and had a red face.*
.. only:: html
.. image:: /images/picC.png
:align: left
-.. raw:: latex
-
- \dropcap{c}
-
-onventional -- static -- fiction can be written using nothing more than
+|C|\onventional -- static -- fiction can be written using nothing more than
pencil and paper, or typewriter, or word-processor; however, the
requirements for producing IF are a little more extensive, and the creative
process slightly more complex.
* For IF, you still have to write all of the text, but you also have to
establish what text gets displayed when. Once you have written the
- necessary Inform instructions, you use a **compiler** program to convert
- them into a playable format. The resulting information is played by an
- **interpreter** program, which permits you to interact with your
- developing world.
+ necessary Inform instructions, you use a :term:`compiler` program to
+ convert them into a playable format. The resulting information is played
+ by an :term:`interpreter` program, which permits you to interact with
+ your developing world.
With static fiction What You Write Is What You Read, but with IF the format
in which you initially write the game doesn't bear much resemblance to the
text which the interpreter ultimately displays. For example, the "William
Tell" game, in the form that we wrote it, starts like this:
-.. code-block:: inform6
+.. code-block:: inform
!============================================================================
Constant Story "William Tell";
Class Room
has light;
- ! ...
+ ...
You will never need to look at it in the form produced by the compiler::
0000000000000000000000000000168F000000000000010200000000362E3231
...
-but, as you'll notice from the full transcript in "William Tell" story on
-page 219, the player will see the following::
+but, as you'll notice from the full transcript in :doc:`/appendices/c`, the
+player will see the following::
The place: Altdorf, in the Swiss canton of Uri. The year is 1307, at
which time Switzerland is under rule by the Emperor Albert of
Clearly, there's more to writing IF than just laying down the words in the
right order. Fortunately, we can make one immediate simplification: the
translated form produced by the Inform compiler -- those cryptic numbers
-and letters held in what's known as the **story file** -- is designed to be
-read by the interpreter program. The story file is an example of a
+and letters held in what's known as the :term:`story file` -- is designed
+to be read by the interpreter program. The story file is an example of a
"binary" file, containing data intended for use only by a computer program.
Forget all that unreadable gibberish.
So that leaves just the first form -- the one starting "``Constant Story``"
--- which represents the tale written as a piece of IF. That's the **source
-file** (so called because it contains the game in its original, source,
-form) which you create on your computer. The source file is a "text" (or
-"ASCII") file containing words and phrases which can be read -- admittedly
-after a little tuition, which is what this guide is all about -- by humans.
+-- which represents the tale written as a piece of IF. That's the
+:term:`source file` (so called because it contains the game in its
+original, source, form) which you create on your computer. The source file
+is a "text" (or "ASCII") file containing words and phrases which can be
+read -- admittedly after a little tuition, which is what this guide is all
+about -- by humans.
+
+.. Generated by autoindex
+.. index::
+ single: IBM PC
+ pair: NotePad; text editor
+ pair: SimpleText; text editor
+ pair: TextEdit; text editor
+ pair: Windows; operating system
How do you create that source file? Using a third software program: an
-**editor**. However, unlike the compiler and interpreter, this program
+:term:`editor`. However, unlike the compiler and interpreter, this program
isn't dedicated to the Inform system -- or even to IF. An editor is an
entirely general tool for creating and modifying text files; you've
probably already got a basic one on your computer (an IBM PC running
embedded graphics; it simply enables you to type lines of text, which is
exactly what's needed to create an IF game.
-If you look at the game source on the previous page, or in the "William
-Tell" story on page 219, you'll notice ``Include "Parser";`` and ``Include
-"VerbLib";`` a few lines down from the top of the file. These are
-instructions to the Inform compiler to "include" -- that is, to merge in
-the contents -- of files called ``Parser.h`` and ``VerbLib.h``. These are
-not files which you have to create; they're standard **library files**,
-part of the Inform system. All that you have to do is remember to Include
-them in every game that you write. Until you've a fair understanding of
-how Inform works, you've no need to worry about what they contain (though
-you can look if you want to: they're readable text files, just like the
-ones this guide will teach you to write).
+If you look at the game source above, or in :doc:`/appendices/c`, you'll
+notice ``Include "Parser";`` and ``Include "VerbLib";`` a few lines down
+from the top of the file. These are instructions to the Inform compiler to
+"include" -- that is, to merge in the contents -- of files called
+``Parser.h`` and ``VerbLib.h``. These are not files which you have to
+create; they're standard :term:`library files`, part of the Inform system.
+All that you have to do is remember to Include them in every game that you
+write. Until you've a fair understanding of how Inform works, you've no
+need to worry about what they contain (though you can look if you want to:
+they're readable text files, just like the ones this guide will teach you
+to write).
So, we've now introduced all of the bits and pieces which you need in order to
write an Inform adventure game:
-* a text **editor** program which can create and modify the **source file**
- containing the descriptions and definitions of your game. Although it's
- not recommended, you can even use a word-processing program to do this,
- but you have to remember to save your game in Text File format;
+* a text :term:`editor` program which can create and modify the
+ :term:`source file` containing the descriptions and definitions of your
+ game. Although it's not recommended, you can even use a word-processing
+ program to do this, but you have to remember to save your game in Text
+ File format;
-* some Inform **library files** which you Include in your own game source
- file in order to provide the model world -- a basic game environment and
- lots of useful standard definitions;
+* some Inform :term:`library files` which you Include in your own game
+ source file in order to provide the :term:`model world` -- a basic game
+ environment and lots of useful standard definitions;
-* the Inform **compiler** program, which reads your source file (and the
- library files) and translates your descriptions and definitions into
- another format -- the **story file** -- intended only for...
+* the Inform :term:`compiler` program, which reads your source file (and
+ the library files) and translates your descriptions and definitions into
+ another format -- the :term:`story file` -- intended only for...
-* an Inform **interpreter** program, which is what players of your game
+* an Inform :term:`interpreter` program, which is what players of your game
use. A player doesn't require the source file, library files or compiler
program, just the interpreter and the game in compiled format (which,
because it's a binary file not meaningful to human eyes, neatly
discourages players from cheating).
+.. Generated by autoindex
+.. index::
+ single: IF Archive
+
All of those, apart from the editor, can be downloaded for free from the IF
Archive. One approach is to fetch them individually, following the
guidance on Graham's page: visit http://www.inform-fiction.org/ and look
find it easier to download a complete package containing everything that
you need to get started.
+.. _inform-windows:
+
Inform on an IBM PC (running Microsoft Windows)
===============================================
In order to make the download small and fast, these folders include just
enough to get you started as an Inform designer -- the compiler and
interpreter programs, the library files, the ``Ruins.inf`` example file
- from the *Inform Designer's Manual*, and a template for your own first
- game. A few other folders are included as placeholders where you could
- later download additional components, if you wanted them. As soon as
- possible, you should download the *Inform Designer's Manual* into the
- ``Inform\Doc`` folder -- it's an essential document to have, and has
- been omitted from this download only because of its 3MB size.
+ from the |DM4|, and a template for your own first game. A few other
+ folders are included as placeholders where you could later download
+ additional components, if you wanted them. As soon as possible, you
+ should download the |DM4| into the ``Inform\Doc`` folder -- it's an
+ essential document to have, and has been omitted from this download only
+ because of its 3MB size.
3. To verify that the downloaded files work properly, use Windows Explorer
to display the contents of the ``Inform\Games\MyGame1`` folder: you will
double-click the file, it should open in NotePad so that you can see how
it's written, though it probably won't mean much -- yet.
+.. Generated by autoindex
+.. index::
+ single: batch file
+
4. ``MyGame1.bat`` is an MS-DOS batch file (an old kind of text-only
computer program, from the days before point-and-click interfaces) which
runs the Inform compiler. Double-click it; a DOS window opens as the
9. Using the same techniques, you can compile and play ``Ruins.inf``, which
is held in the ``Inform\Games\Download`` folder. RUINS is the game used
- as an example throughout the *Inform Designer's Manual*.
+ as an example throughout the |DM4|.
.. rubric:: Setting file associations
.. note::
- On the command line, you sometimes also see a compiler **switch**
- such as ``-S``, used for controlling detailed aspects of how the
- compiler operates. Rather than do that here, we find it more
+ On the command line, you sometimes also see a compiler :term:`switch`
+ such as :option:`-S`, used for controlling detailed aspects of how
+ the compiler operates. Rather than do that here, we find it more
convenient to place any necessary switches at the very top of the
source file, as we'll explain in the next chapter.
off the top of the MS-DOS window. Press the space bar to continue the
compilation.
+.. Generated by autoindex
+.. index::
+ pair: Windows; operating system
+
The second line -- ``pause "at end of compilation"`` -- just prevents the
window from closing before you can read its contents, as it otherwise would
on Windows NT, 2000 and XP.
+.. Generated by autoindex
+.. index::
+ single: batch file
+
You'll need to have a new batch file like this to match each new source
file which you create. The only item which will differ in the new file is
the name of the Inform source file -- ``MyGame1`` in this example. You
.. rubric:: Getting a better editor
+.. Generated by autoindex
+.. index::
+ pair: NotePad; text editor
+ pair: TextPad; text editor
+
Although NotePad is adequate when you're getting started, you'll find life
much easier if you obtain a more powerful editor program. We recommend
TextPad, available as shareware from http://www.textpad.com/; in addition,
interpreter with similar ease. The convenience of doing this far outweighs
the small amount of time needed to obtain and configure TextPad.
+.. index::
+ single: Apple Macintosh
+
+.. _inform-apple:
+
Inform on an Apple Macintosh (running OS X)
===========================================
+.. Generated by autoindex
+.. index::
+ pair: Mac OS X; operating system
+
Whereas our instructions for using Inform on a PC apply to just about all
versions of Windows, on the Macintosh we need to be more precise. Our
guidance here is specifically for Mac OS X, rather than for its predecessor
run in the Classic environment of OS X; roughly speaking, Classic is an
emulation of the older Mac systems.
+.. Generated by autoindex
+.. index::
+ pair: Linux; operating system
+
* X11: based on a windowing system designed for the UNIX/Linux world. They
need an X-Windows server to run, and their appearance and functionality
may seem a lot different to what the Aqua user expects.
In order to make the download small and fast, these folders include just
enough to get you started as an Inform designer -- the compiler and
interpreter programs, the library files, the ``Ruins.inf`` example from
- the *Inform Designer's Manual*, and a template for your own first game,
- which you may copy and rename each time you begin a new Inform project.
- A few other folders are included as placeholders where you could later
- download additional components, if you wanted them. As soon as
- possible, you should download the *Inform Designer's Manual* into the
- ``Inform/Doc`` folder -- it's an essential document to have, and has
- been omitted from this download only because of its 3MB size.
+ the |DM4|, and a template for your own first game, which you may copy
+ and rename each time you begin a new Inform project. A few other
+ folders are included as placeholders where you could later download
+ additional components, if you wanted them. As soon as possible, you
+ should download the |DM4| into the ``Inform/Doc`` folder -- it's an
+ essential document to have, and has been omitted from this download only
+ because of its 3MB size.
3. To verify that the downloaded files work properly, use the Finder to
display the contents of the ``Inform/Games/MyGame1`` folder: you will see
* select ``Open with`` and choose ``Other...``
+ .. Generated by autoindex
+ .. index::
+ pair: TextEdit; text editor
+
* in the ``Open with`` dialog, go to the ``Applications`` folder and
select TextEdit.
Now, if you double-click the file, it should open in TextEdit so that
you can see how it's written, though it probably won't mean much -- yet.
- The above process may affect only this specific file. To change the
- program that opens by default all ``.inf`` files, try this:
+ .. note::
- * right-click on the file (or Ctrl-click)
+ The above process may affect only this specific file. To change
+ the program that opens by default *all* ``.inf`` files, try this:
- * select ``Get Info``
+ * right-click on the file (or Ctrl-click)
- * in the ``Open with`` tab, select TextEdit as the application
+ * select ``Get Info``
- * click the ``Change All...`` button, and confirm the change when asked.
+ * in the ``Open with`` tab, select TextEdit as the application
+
+ * click the ``Change All...`` button, and confirm the change when asked.
4. ``MyGame1.command`` is a Terminal Shell Script (a UNIX executable
command-line file, a kind of text-only computer program from the days
.. rubric:: Setting file associations
+.. Generated by autoindex
+.. index::
+ single: Infocom
+
The business of first starting the interpreter, and then locating the story
file that you want to play, is clumsy and inconvenient. Fortunately, when
the system first "sees" the Zoom interpreter (which is a nice Aqua
.. note::
- On the command line, you sometimes also see a compiler switch such as
- ``-S``, used for controlling detailed aspects of how the compiler
- operates. Rather than do that here, we find it more convenient to
- place any necessary switches at the very top of the source file, as
- we'll explain in the next chapter.
+ On the command line, you sometimes also see a compiler :term:`switch`
+ such as :option:`-S`, used for controlling detailed aspects of how
+ the compiler operates. Rather than do that here, we find it more
+ convenient to place any necessary switches at the very top of the
+ source file, as we'll explain in the next chapter.
Once you've finished editing those lines, ``Save`` the file (not
``SaveAs``), overwriting the original, and make sure that your text editor
.. rubric:: More about the editor
+.. Generated by autoindex
+.. index::
+ single: syntax colouring
+
As well as the ones that we recommend, other good text editors are listed
at http://www.firthworks.com/roger/editors/. One feature that's well worth
looking out for is "hotkey compilation" -- being able to run the compiler
The Inform compiler is a powerful but undramatic software tool; it does an
awful lot of work, but it does it all at once, without stopping to ask you
any questions. Its input is a readable text source file; the output is a
-story file, also sometimes known as a **Z-code file** (because it contains
-the game translated into code for the Z-machine, which we describe in the
-next section).
+story file, also sometimes known as a :term:`Z-code file` (because it
+contains the game translated into code for the Z-machine, which we describe
+in the next section).
If you're lucky, the compiler will translate your source file into Z-code;
perhaps surprisingly, it doesn't display any form of "success" message when
learn, but just as easy to break, and all Inform designers inadvertently do
so on a regular basis. There's some additional information about dealing
with these mistakes, and about controlling how the compiler behaves, in
-"Compiling your game" on page 189.
+:doc:`15`.
.. rubric:: More about the interpreter
+.. Generated by autoindex
+.. index::
+ single: Infocom
+
One of the big advantages of the way Inform works is that a compiled game
-- the Z-code story file -- is portable between different computers.
That's not just from one PC to another: exactly the same story file will
run on a PC, a Mac, an Amiga, UNIX workstations, IBM mainframes, PalmOS
hand-helds, and on dozens of other past, present and future computers. The
magic that makes this happen is the interpreter program, a software tool
-which pretends to be a simple computer called a **Z-machine**. The
+which pretends to be a simple computer called a :term:`Z-machine`. The
Z-machine is an imaginary (or "virtual") computer, but its design has been
very carefully specified, so that an expert programmer can quite easily
build one. And that's exactly what has happened: a Macintosh guru has