
                              ZapInform

    Providing syntax colouring and quick code composition for Inform,
            the adventure-game compiler and design system

                         -------- o --------

  This Acorn RISC OS module provides a new "mode" for Dominic Symes's
definitive Acorn text editor, "Zap".  It was written by Graham Nelson,
who retains the copyright but allows it to be distributed freely on a
non-profit-making basis.  This software is provided with no warranty and
the author accepts no liability for what it may do.  The author would
like to acknowledge Matthew Hambley's "HTML" mode, on which a part of
the redrawing code in this module borrows, Tim Tyler, for a helpful email
conversation, and inevitably Dominic Symes, whose editor as seen from the
inside has a kind of hypnotic power.  It draws you in, it does.

                         -------- o --------

                       Part One: Installation

  If you haven't got Zap installed, you can get hold of it from its web site
at:
	http://zap.tartarus.org/
	
and you will need to follow the instructions given there to get Zap working.
Note that the also-supplied Zap Manual contains details on how to configure
Zap to behave superficially like Acorn's dismal editor "Edit", if (like me)
you were brought up on its keyboard mappings and have no intention of
learning a new batch now.

  Next copy the !ZapInform application into the !Zap.Modules directory, and
restart Zap.

  Inform mode is now available.  Some paths are also set up to detect Inform
files and use Inform mode appropriately.


                         -------- o --------

                       Part Two: A quick tour

  The Inform mode is partly intended to make composing the bare bones of
a game a quicker process, by typing as much of the routine material as
possible for you.  As a demonstration, you might like to follow these
instructions, which make up the source for a simple game in very quick
order.

  Click on !Zap's icon to produce an empty (Text mode) window, and select
"Inform" from the Mode submenu of Zap's main menu.  You now have an equally
empty file running in Inform mode, which looks equally white and bare, but
has the word "Inform" written across the window's title bar.  Go to Inform,
from the Mode submenu, again and this time enter its own submenu, which
should look something like this:

                Inform
          -------------------
          List Objects
          List Classes
          List functions
          More lists...     >
          -------------------
          Room              >
          Object ->         >
          Attribute         >
          Room property     >
          Obj property      >
          More templates... >
          -------------------
          Save and compile

Go to "More templates..." and follow into its submenu.  The idea of these
template options is that clicking on them automatically types in a
template of Inform code for such an item or idea: for instance, clicking
on "Room" puts down the code for a simple room, which you can edit to
your requirements.  The template option to pick is the one called
"Shell game", which puts together the shell for the simplest possible
adventure game Inform can compile.  The only thing you can specify about
this shell of a game is the name of its one and only location: if you
just clicked on the "Shell game" option you'd find that the location was
called "Blank Room", but instead follow the arrow to the right where you
can type in a brief name: type, let's say, "Old Stone Farmhouse".  The
file of text will suddenly fill up with:

    Constant Story "SHELL";
    Constant Headline "^An Interactive Skeleton^";
    
    Constant DEBUG;
    
    Include "Parser";
    Include "VerbLib";
    
    Object Old_Stone_Farmhouse "Old Stone Farmhouse"
      with description
              "The Old Stone Farmhouse.",
      has  light;
    
    [ Initialise;
      location = Old_Stone_Farmhouse;
    
     "^^^^^Welcome to the...^";
    ];
    
    Include "Grammar";

It will look rather garishly coloured: the logic of the colouring scheme
is less apparent when only the bare bones of a game are visible, so bear
with it for now.

  This could now be compiled into a working game, if a highly tedious one.
Instead, add a second room by putting the cursor in the blank line after
the farmhouse's definition and then selecting the menu option

          Room              >

from the Inform menu.  It'll create a room just called "Place" unless you
follow the arrow to the right, as before, and type a better name:
Farmyard seems appropriate.  This should add the following text to the
file:

    Object Farmyard "Farmyard"
      with description
              "The Farmyard.",
      has  light;

(Notice that the cursor is now in the blank line underneath the Farmyard
definition.)  To connect this to the first room, follow the menu option

          Room property     >

which offers a list of the properties which are useful for rooms: click
on the direction property "w_to", say.  The Farmyard will now look like
so...

    Object Farmyard "Farmyard"
      with description
              "The Farmyard.",
           w_to R,
      has  light;

That capital R is a reminder that you need to type a room name here: the
cursor is automatically left immediately after it (i.e. on top of the
comma) so that a single press of Delete removes the R and allows you to
type "Old_Stone_Farmhouse".  Similarly, click the cursor back into the
definition of the farmhouse and choose the menu option for "e_to", then
type "Farmyard".  The result should be this:

    Object Old_Stone_Farmhouse "Old Stone Farmhouse"
      with description "The Old Stone Farmhouse.",
           e_to Farmyard,
      has  light;

    Object Farmyard "Farmyard"
      with description
              "The Farmyard.",
           w_to Old_Stone_Farmhouse,
      has  light;

To try out just one more of the standard templates, put the cursor into
the blank line following the Farmyard and this time go to the menu option

          Object ->         >

Follow the arrow to the right and type, say, "Somerset cooking apples".

    Object -> Somerset_cooking_apples "Somerset cooking apples"
      with name "somerset" "cooking" "apples";

should result.  However, even cooking apples can be eaten, and it's also
a good idea to tell Inform that the object has a name in the plural
(so that the resulting game will talk about "some Somerset cooking apples"
and not "a Somerset cooking apples").  Simply follow the menu option

          Attribute         >

and follow the arrow to a submenu listing the most useful attributes which
objects can be given.  Click first on "edible", and the text will become

    Object -> Somerset_cooking_apples "Somerset cooking apples"
      with name "somerset" "cooking" "apples",
      has  edible;

(note that the "has" clause has been entered automatically).  Now go back
and click on "pluralname":

    Object -> Somerset_cooking_apples "Somerset cooking apples"
      with name "somerset" "cooking" "apples",
      has  edible pluralname;

As usual with RISC OS programs, you can click several menu options in
one go by clicking with the Adjust mouse button instead of Select: this
is a quick way to fire off a string of attributes, so that

      has  container openable lockable locked;

can be done in just four mouse-clicks.

  Other templates provided include a container, a door, a vehicle, a
machine which can be switched on or off and male and female characters.
  
  Time to try out what's probably the most useful feature of Inform mode:
the object lister.  Click on the menu option

          List Objects

and a "Throwback" window should be created, each line of which specifies
one of the objects defined in your source file:

    Object definitions in: Text5

      ofclass       definition
                    Old_Stone_Farmhouse "Old Stone Farmhouse"
                    Farmyard "Farmyard"
                    -> Somerset_cooking_apples "Somerset cooking apples"

(The file you're editing has no name yet: Zap will have called it something
like "Text1", depending on how many other files you've created today.)
Clicking on the line corresponding to an object automatically jumps the
cursor to that object's definition in the source code: "List Objects" is
basically a navigation aid, though it also offers a sort of overview.

  The column headed "ofclass" is blank because the three objects are all
just plain "Object" objects.  Here's a sample from a more complex game
("Balances", one of the standard Inform examples):

      Place         Hut "Ramshackle Hut"
                    -> furniture "wooden furniture"
                    h_box "cedarwood box"
      SpellBook     -> helistars_book "Helistar's grimoire"
      Place         Grasslands "Grasslands, near Hut"
      Place         Valley "Pocket Valley"
                    -> horse "horse"
                    -> oats "pile of oats"
      Scroll        shiny_scroll "shiny scroll"
      Spell         -> bozbar_spell
      Place         Edge "Edge of Chasm"
                    -> snake "hissing snake"
      FeaturelessCube -> snakes_cube "cube"

  The other listing options display similar Throwback windows, or simply
beep if they find nothing to display.

  Finally, save your sample file to the Inform source-files directory
(so that Zap knows a name for it: "Farm", say) and you can now choose:

          Save and compile

This saves the latest version (in this case, an unnecessary step because
we've just done so) and then calls up a Taskwindow in which is an
application running the Inform compiler.  So you should see a window
appear, bannered "Compiling Farm (Taskwindow)", and then text like

    RISC OS Inform 6.14 (8th September 1997)
    ::###################################################################
    ###########

with hashes being printed in a stream as Inform works away.  (When the
row of hashes is finished, the Taskwindow can be closed and disposed of.)
Note that the "compile" part of "Save and compile" really only simulates
pressing CTRL-F12, to call up a Taskwindow, and then typing the command

    inform -Dx farm

so that you'll need to have Inform already set up in the normal way
(in particular, you'll need the current selected directory to be the
one which has the "Inform" and "Games" directories as subdirectories:
the above command translates Inform.farm to Games.farm).  The new game is
now playable.

    Welcome to the...

    SHELL
    An Interactive Skeleton
    Release 1 / Serial number 970924 / Inform v6.14 Library 6/7 D

    Old Stone Farmhouse
    The Old Stone Farmhouse.

    >e
    Farmyard
    The Farmyard.

    You can see some Somerset cooking apples here.

    >get the cooking apples
    Taken.

    >eat them
    You eat the Somerset cooking apples. Not bad.

    >w
    Old Stone Farmhouse

This is not much of a game, but consider that it was programmed and
compiled with only the following use of the keyboard:

    Typing "Old Stone Farmhouse"
    Typing "Farmyard"
    Deleting "R", and typing "Old_Stone_Farmhouse" (of course this
        can be copied over, so you needn't actually type it out)
    Deleting "R", and typing "Farmyard"
    Typing "Somerset cooking apples"

For a total of 81 keystrokes.

                         -------- o --------

                     Part Three: Syntax colouring

  This is an automatic process in which the text being edited or looked at
is coloured in according to what Zap thinks it means: as if someone had
gone through a book colouring all the verbs in red, and all the nouns in
green.  (Thankfully nobody has yet written a Zap mode to do this.)

  ZapInform sees Inform files in 11 different colours, and can be configured
to use any colours of choice to display these.  In the default scheme,
given in the following table, three of them are red: I prefer this, but
you might want to separate these out.

          Background                            white
          Text in quotation marks               grey
          Comments                              emerald green
          Banner comment backgrounds            beige
          Directives                            black
          Property/attribute/class names        red
              cited in object definitions
          Functions                             red
          Statements inside functions           dark blue
              and arguments to directives
          Identifiers (such as variable names)  dark green
          Assembly-language mnemonics           gold
          Escape characters in quoted text      red
              or characters with special
              meanings (such as ^ for newline)

If you find it distracting that functions tend to be a mixture of two
colours (dark blue and dark green) you can of course configure both
categories to be displayed in the same colour.  At the ultimate extreme
choosing white and then 10 lots of black produces an ordinary monochrome
display, with no visible syntax colouring at all.

  "Banner comments" are comment lines which begin on column 1 with
  
    ! -

or

    ! =

These have emphasised backgrounds (beige instead of white) as I habitually
use comments like

    ! ------------------------------------------------------------------

as division lines in my source code, and the background colouring helps
to make a bigger impression.  I expect nobody will like this but me, but
you can always configure the banner background colour to be the same as
the ordinary background colour.

  The idea of syntax-colouring is that it's easier to take in the source
code at a glance, and also easier to spot elementary syntax errors: for
instance

    Object -> Somerset_cooking_apples "Somerset cooking apples"
      with name "somerset" cooking" "apples";

immediately gives itself away, with the text 'cooking' being dark blue
instead of the expected grey, while most of the rest of the file from
there on has turned grey: there's a missing quotation mark.

  No two users of Zap agree on an ideal colour-scheme: you can experiment
with changing the colours by loading up a good and complicated Inform
source file (say, the source code to "Advent") and using the

          Display > Colours

option from the Zap menu.  However, note that this only changes the colour
scheme for the file currently being looked at: it doesn't change the
saved settings.  Changing the saved settings is a slightly laborious job:
you need to select

          Options > Mode > Inform

from the Zap _icon bar_ menu, then go into

          Options > Display > Colours

Make sure that "All modes" (the top entry in this menu) is _not_ ticked,
by clicking on it to remove the tick if necessary.  You can then alter
the colours, one at a time, using the Colour picker windows attached to
the 19 options below.  After all of that, click on:

          Options > Save Options

Your new colour scheme will now be the one used whenever you edit an
Inform file in future.

                         -------- o --------

                       Part Four: Limitations

  ZapInform has to contend with quite a tricky language, lexically
speaking -- for instance, no regular-expression search pattern can
infallibly detect object definitions -- and it quietly makes a number of
compromises for the sake of being as useful as possible.  For instance,
it's possible to slightly confuse the syntax colouring in some
circumstances (by e.g. editing the middles of important keywords like
"with", depending on what follows), which results in short-lived and
usually mild colouring errors: this is a compromise in that ZapInform
prefers speed to absolute accuracy, my original version having been
always right but with a noticeable speed loss during rapid typing.
Since my machine has a StrongARM processor, this speed loss might be
much less tolerable on other Acorn machines: hence the compromise.

  Also, features like "List objects" assume that:

     Directives, object definitions and the [ character introducing
     a function always begin on column 1 of the file; otherwise
     nothing else appears on column 1 except possibly for comment
     characters, !.

This assumption is true for almost everybody's style of writing Inform.
In particular it means that code inside functions should be at least
slightly indented from the margin:

     [ BadStyle;
     print "This is not a good idea.^";
     ];

     [ GoodStyle;
       print "This is a much better idea.^";
     ];

The system for automatically inserting properties and attributes assumes
that with and has clauses are written like so:

       with name "apples"
       has  edible pluralname;
     ^      ^
     ^      Column 8 here
     Column 1 here

Since all of ZapInform's own templates follow this pattern, the property-
and attribute-adding features should always work when initially creating
objects: after that they might go wrong (inserting the text at the wrong
point, perhaps, but never deleting anything) if you've messed about with
the indentation.

  There's nothing to stop you editing files with any layout conventions,
of course, and the syntax colouring is not one of the features requiring
any special layout: you might have to do without the templates and
the List Objects window, but that's all.

                         -------- o --------

                         Part Five: History

  This help file accompanies v1.0beta, the first beta-testing release,
and was written on 24th September 1997.

                         -------- o --------

			  Part Six: Contact
			  
If you have any comments or bug reports concerning Inform mode, we'd love to
hear from you. The best place to send messages to is the zap-users mailing
list at <zap-users@zap.tartarus.org> - you don't have to be subscribed to the
list to post to it. Alternatively, you could contact one of the Zap
developers directly - our addresses are in the Contact section of Zap's
website, which is at <http://zap.tartarus.org/>.

                         -------- o --------
