infocom/compilers/inform5/general-notes.txt

Manuals
=======
For the first time in two years, an attempt has been made to rewrite the
documentation altogether (and "properly this time"), though some passages
from the old manual do remain.  There are now two Inform manuals:

  The Inform Designer's Manual  (106 pages of A4)
  The Inform Technical Manual  (22 pages of A4)

and only the former will be of interest to most users.  The manuals are
given in TeX, a text-markup-language used by mathematicians and scientists
which is just about readable as ASCII (after a fashion); there will shortly
be plain text and postscript editions too.

The Designer's Manual has some 31 exercises with full answers (mainly for
extended examples: how to implement difficult puzzles), proper documentation
of exactly what attributes do, advice on error messages, a long index (about
800 entries), a specification of the language, a lengthy tutorial (the first
half is mainly tutorial in style) and details of all the new features.  In
my view it's hugely better than its predecessor.  The Technical Manual is,
as it claims, technical.

The author's paper,

  The Specification of the Z-Machine  (44 pages of A4)

(which also documents the assembler at the bottom of Inform) has also been
re-posted in TeX form, in an updated edition.  It has been tidied up somewhat
and a few mistakes in the previous edition (none of much consequence) have
been corrected; the very last opcode in Version 6, recently discovered by
Mark Howell, has been added.  Inform 5.3 changed the opcode names slightly
to bring them in line with a standard set of names agreed between Mark and
myself, and this paper uses them.  (Thus Mark's disassembler "txd" now uses
exactly the same names as the Inform assembler.)

Balances
========
The source code to Release 2 of this slight but hopefully amusing game is
now available (it needs I5.4 to compile).  The game itself has been
re-posted also, and has many small bugs (none serious) fixed.  The author is
grateful to the many who have written to make complaints and suggestions.
The "spell-casting" code is, incidentally, easily transplantable.

Toyshop
=======
A number of new toys have arrived on the shop floor: a matchbook of five
matches and a box of eight candles (to demonstrate imitation and real plural
objects, respectively), a blackboard you can write any sentence on and a
pair of gloves which can separate into a left and right glove on request.

Advent
======
Is hardly changed at all, except in being flagged as Release 2 to distinguish
it from the incorrectly-compiled version posted earlier.



Files on Inform
===============

The Inform home directory is  if-archive/infocom/compilers/inform at
the anonymous FTP archive ftp.gmd.de.

The directory "source" contains ANSI C source for the compiler, divided
into a number of files.  Note that the header file no longer contains the
ever-growing modification history, which has been moved to the Technical
Manual, which porters may find useful.  There is also a single tar file
containing all the source files.

The directory "examples" contains Inform source code for Shell, Hello
Cruel World, Toyshop, Advent and Balances.  Each is a single file named
as whatever.inf.

The directory "library" contains the three files which make up the Library,
i.e.,

    parser.h    verblib.h     grammar.h

The directory "executables" is provided for executable copies.  The
Acorn Archimedes version is called

    archimedes_5.4

and I would ask porters to use a similar notation - i.e., to use a file
name to indicate the machine, include the number 5.4 and indicate the
compression format if there is one.  (This one is a single executable file.)

The directory "manuals" contains TeX source of the documents available:

    designers_manual.tex
    technical_manual.tex
    specification.tex

and will hopefully soon contain .ps (PostScript) and .plain_text files.

In addition there are a number of actual games, which have file-names
ending in ",z3" or ".z5".  These must be downloaded in binary mode,
and can only be run with the aid of an interpreter for your machine:
see the directory  if-archive/infocom/interpreters  to find one.


Graham Nelson
Oxford University
October 2nd, 1994