> !ZapConfig
> Allow configuration of Zap (by Dominic Symes)
>  Copyright James Aylett 1996
> Version 1.20

Copyright
---------

ZapConfig is copyright (c) James Aylett. It may not be distributed without
the express and written permission of the author, except that it may be
distributed along with Zap under the distribution conditions as laid down by
Dominic in the standard (public release) Zap distribution. Zap is copyright
(c) Dominic Symes. Any such distribution must contain the entire contents of
the !ZapConfig directory, unaltered in any way.
ZapSetup is copyright (c) Matthew Wilcox.

ZapConfig version 1.20 is intended for use with Zap version 1.30. It is
likely that it will work with subsequent versions of Zap, providing there
isn't a major change in the !Config file format. It requires RiscOS 3.10 or
later to run.

ZapConfig was written using DeskLib, the FreeWare C library for RiscOS.

###  READ THE DISCLAIMER (NEAR THE BOTTOM) BEFORE IT'S TOO LATE  ###
### I cannot be held responsible for any loss of your nice setup ###
###     It's also a good idea to read the known bugs section     ###

Introduction
------------

Zap is very flexible. In many ways too flexible. Too big, too far, too deep,
and much too flexible. More than seventeen innocent users have been put off
by the automatic comment from experienced Zappers, 'Oh, just reconfigure it
if you don't like that'. The next question in the conversation is always
'How?'. Up till now everyone has had to either hack their way through Zap's
Keys file, and use the Options menu, or swap to an alternative base set by
using ZapSetup. This is still far too complex, and so ZapConfig was finally
started properly.

 This may be wrong.

Use
---

Note that I've assumed throughout here that you are familiar with RiscOS and
the way RiscOS programs work. I mean, you're trying to configure _Zap_,
aren't you? :-)

One thing before you start: Zap can cope with no !Config file in its main
directory, but ZapConfig can't currently, so before you run ZapConfig (which
will give an error but _not_ leave gracefully - and it will be left
containing whatever data was in memory, so saving could result in very nasty
things happening), save Zap's !Config file by clicking Menu on Zap's iconbar
icon, moving right from Options and selecting Save options (at the top). This
will keep ZapConfig happy. Note that you must not distribute Zap in this
state; when you distribute Zap you must do it with no !Config file in Zap's
main directory, and with the Standard options set selected.

Loading ZapConfig in the usual way, you click on the iconbar icon to get the
main configuration window. This actually contains very little by way of
configuration, but presents a pair of sections. The top bit contains ten
icons, and allows you access to the actual configuration. Go ahead, click on
them. Just don't say 'Yes' if ZapConfig asks if you want to save anything.
Not just yet.

When one of these opens, the main window closes. Clicking on the iconbar will
only bring the window you're currently using to the front, rather than
opening the main window again. This is to avoid confusion, both on your part,
and in the program itself :-)

The bottom part of the window allows you to specify which configuration set
and which template set Zap uses. The configuration set shown is also the one
you're currently editing using ZapConfig. This uses the configuration sets as
supplied with Zap 1.30 or later, in the style of ZapSetup. Click on the menu
icon (at the far right) to get a list; Standard refers to the standard set
inside the main directory; these are the ones that _must_not_be_altered_ in
copies of Zap you pass on to other people. Down from that will be a list
containing, most likely: Default, MJEbourne, MRWilcox and Salt. The last
three are written by 3rd party authors (Martin Ebourne has written various
add-on modes to Zap, Matthew Wilcox wrote ZapSetup, and Darren Salt wrote a
module adding various commands to Zap). The Default one is not to be confused
with Standard; Default is the best one to edit for your own use.

It is also possible to create new sets, using the item at the bottom of the
menu and typing in the name you want.

Note: if a particular file (Keys, !Config, whatever) doesn't already exist
inside the option set you select then the file loaded for editing will be
from the Standard set supplied inside Zap. However when you save your
changes, these will be saved as part of the option set.

You can change between template sets in the same way, except that you can't
create new ones. ZapConfig will list all template sets available (in
<Zap$Dir>.Templates), up to a maximum of 12. Currently nine template sets are
distributed with Zap (but you probably want to get rid of mine because it's
horrible :-).

To save the configuration and template sets shown - so that Zap will use them
next time it starts up - click on the Save button at the bottom right of the
window.

Configuration Part 1 - Key bindings
-----------------------------------

It is advisable to read Sections A.1, A.2 of the Zap help file at this point,
since they explain key bindings. However you may ignore the bits which talk
specifically about the Keys file - just read the bits which explain how the
command format for each key binding works, and what key bindings are in the
first place.

Clicking on the 'Edit key bindings' button will open a dazzling window
representing your keyboard. If you have a RiscPC then this window will be
slightly different to if not, since the RPC uses a standard PC-style keyboard
layout, whereas older machines use a modified keyboard.

The window is split in two; the top displays the current key binding you are
editing, and the bottom displays the keyboard. Clicking on a 'key' on the
keyboard will select that key as the one to edit. This is then displayed in
the far left icon at the top. To the right of this are two option buttons,
showing whether you are editing the shifted and/or control-modified version
of the key (in that order - !FinalLook for RiscOS 3.1 will result in the
shifted icon being somewhat obscure because the available fonts for RiscOS
3.1 don't contain a suitable shift character). At the far right is the actual
action performed by this keypress; the command bound to the keypress.
Clicking on the shifted and control-modified icons will toggle them on and
off, and any alteration in the keypress being editing will be reflected in
the action icon, which is editable to allow you to change it. Choosing
another keypress _temporarily_ saves the key binding you have altered; the
changes aren't saved until you close the window.

ZapConfig now deals with the full *&xxx command used in Zap's standard
keybinding for the keypad numbers (it drops the key bindings through to
keymap 0, with the base of the range starting at &xxx. Omitting the &xxx -
having just the command '*' - drops through to keymap 0 with no renumbering,
as used in the Emacs keymaps, 1).

On closing the window you are asked whether you want to save the changes.
Cancel loses your changes totally (discards them). There's no "don't close
the window" option, because I'm using wimp report boxes to make the code
simpler.

Note that the keys ',' '.' and '/', plus some others, don't actually do
anything in Zap when used with control or shift and control. ZapConfig deals
with this in a slightly upsetting way due to the way it's coded; the control
switch has no effect on these keys, so for instance it treats shift+ctrl+'.'
the same as shift+'.' = '>'.

Configuration Part 2 - Window Display
-------------------------------------

Clicking on the 'Window display' button will open a window allowing you to
set all sorts of groovy things associated with fine-tuning Zap's display. It
is divided into three parts.

In the top left you can configure Zap's treatement of anti-aliased fonts
(character reduction refers to how many pixels it strips off each character
when displaying), and the default font and size to use.

In the bottom left you can configure Zap's default bitmap fonts, both the
low-res and hi-res versions.

On the right you can set all sorts of things associated with Zap's window
spacing. End of file zap is the number of lines Zap adds to the end of a
window so that you're not typing right at the window extent. Cursor indent is
how close you can get to the edge of a window before Zap will start scrolling
it. Left margin doesn't work, but right margin does and is in OS coordinates.
Auto-width gives the upper and lower bounds for the auto-width width (using
the auto-width option :-). Margin is in characters.

Right down the bottom you can set Zap's default redraw style (bitmap, system
or anti-aliased, DSA or VDU).

Closing the window asks if you want to save the changes, as above.

Configuration Part 3 - Miscellaneous options
--------------------------------------------

It is advisable to read Section A.3 of the Zap help file at this point, which
talks about search macros (variables &200-&20F) and the general options
(variables &300-&31B currently). In addition it is useful to understand what
a mode is :-).

Clicking on the 'Miscellaneous' button will open a window which allows you to
set various options associated with Zap.

At the very top is a section allowing you to configure what sort of files are
created when you click with Select or Adjust on Zap's iconbar icon. Type in
the number of the filetype you'd like created; Zap looks these up in its
internal filetype-recognition table (see the next section) to work out which
mode to use.

(Note that to create a text file in 'C' mode, if text files go by default
into 'Text' mode, you should do the following: first, find an unused
filetype. Then edit either Zap's !Boot file or your computer's boot sequence
to perform '*Set File$Type_xxx Text', where xxx is the filetype you've
chosen. Then get Zap to create type &xxx on either Select or Adjust,
depending on preference, and add in the next section a filetype recognition
for type xxx to load into 'C' mode and perform the Zap command 'Newtype &fff'
- ie set the entry to 'C:Newtype &fff'. Then clicking Select or Adjust as
appropriate will open a text file in mode 'C'.)

Below this are two sections; on the left you can specify the date and time
format strings Zap uses, while on the right you can see which mode Zap uses
by default (filetypes it doesn't recognise, and any filetype loaded with
Control held down use this mode). The first five modes (Text, Byte, Word,
Ascii, Code) are internal to Zap, and are listed by name. All others are
listed by number, since there is no way of knowing which mode number an
extension mode will actually be allocated.

Below this on the left is a section controlling Zap's print features, and to
the right there is a section for controlling the minibuffer. You can't yet
configure the minibuffer colours (if you need to, use Options->Mini buffer
from Zap's iconbar menu).

Right at the bottom are some file options; check date on saving file,
auto-remove files on closing their last window, and trap MS-DOS (text) files,
which isn't documented, but definitely works.

Closing the window gives you the option of saving the changes you've made.

Configuration Part 4 - Filetype recognition
-------------------------------------------

It is useful to read Section A.3 of the Zap help file at this point, which
talks about the filetype recognition variables (&5xx and &1000 - &2000).

Clicking on the 'Filetype recognition' button will open a window which allows
you to alter how Zap treats various filetypes. The window is split into three
sections.

At the top is the filetype currently being considered; you may move through
them using the bumper icons, or use the menu icon (far right) to bring up a
short menu of common filetypes (currently text, basic, HTML, data and a
writeable item for a hexadecimal number). There is a special instance, which
has apparent filetype -1 (ie it appears before filetype &000), which is for
path checks on _all_ filetypes.

Below this is section which deals with path checking (&5xx variables). You
can only have 256 of these currently, which shouldn't cause huge problems,
but is something to be aware of.

The top line of the section gives a path search string (see Section E of the
Zap help file), allows you to scroll through currently defined path checks
using the bumper icons, and gives you a New button to create a new path
check. To alter a current path check, just edit the contents of the writeable
icon. It is not currently possible to delete path checks once they are
defined by using ZapConfig; if you need to, load the Keys file into Zap
itself, find the appropriate variable, and delete it.

Below this is a line telling Zap what to do with it. The autoload option
means that Zap will load this file even when shift isn't held down, and the
icon at the far right gives the name of the mode to load it into followed by
a colon (':') separated list of commands to execute on loading. At the far
right is a menu icon, which brings up a menu of all available Zap modes (note
that if any more "base" modes are added - ie ones which load with the central
Zap program rather than separately - then these will not be present here).
Selecting one sets it as the mode to use. Normal Zap commands may be
specified after the mode, separated by colons (':').

ZapConfig will temporarily save path checks as with the keymap.

When creating new path checks, ZapConfig will store path checks on filetype
-1 (all filetypes) last, preceded by other filetypes in order. Within each
filetype it will store them in whatever order they are defined (except that
for all filetype checks, they will be stored in reverse order). Note that it
is possible that this is incorrect, in which case you'll have to edit the
Keys file directly - it really is too difficult to come up with a usable way
of doing it in ZapConfig. (If anyone has ideas on this, however, please pass
them on!)

At the bottom is the default action; if Zap can't match the file's path to
any specified in the path checks then it will load it into the mode
specified. If no mode is given then Zap won't load it. The line works in the
same way as the bottom line in the path checking section.

ZapConfig will temporarily save default actions as usual.

Closing the window gives you the option of saving the changes you've made.

Configuration Part 5 - Edit options
-----------------------------------

Clicking on the 'Edit options' button will open a window which allows
you to alter how Zap's edit functions work. These options affect all modes.

The window is split into three. Top left you can configure Zap's line- and
word-wrapping facility. Top right you can set various miscellaenous edit
options: whether undo is supported by default, whether the cursor should be
confined to the window (moving the cursor's position as the window scrolls),
whether selections are cleared automatically (as in Impression, for
instance), and the width for column tabs.

At the bottom you can set various search options: case sensitivity, whether
the search window should be cleared each time, whether you can use search
macros, and the macros themselves; you can move through the list using the
bumper icons. The macro is on the left, the expansion on the right, and both
are editable and are temporarily saved as usual. See Section E in the Zap
help file for more information.

Closing the window gives you the option of saving the changes you've made.

Configuration Part 6 - Display options
--------------------------------------

Clicking on the 'Display options' button will open a window which allows you
to alter various display-related functions. I originally had these in the
same section as Window display, but the box got too big to fit onto a mode 13
screen :-) These options affect all modes.

The window is split into three. At the top you can alter the cursors which
Zap uses, plus whether they flash or not and the flash periods. Below this
you can change the characters Zap treats as end-of-line and tab, plus the
line spacing Zap uses and whether it treats data as big or little endian
(leave it switched off if you don't understand this :-).

At the bottom you can set the start line and address Zap uses when printing
line numbers/addresses. Note that this option may be overridden; for instance
Absolute code will be set to start at address &8000 when loaded in since this
is where it will be executed if run.

Closing the window gives you the option of saving the changes you've made.

Configuration Part 7 - Alternate keymaps
----------------------------------------

It is advisable to read Section A.5 of the Zap help file before fiddling
around with the alternate keymaps.

Clicking on the 'Keymaps' button will open a window which allows you to set
up and edit up to 255 alternate keymaps to the "base keymap" (keymap 0) -
which can be altered using the 'Edit key bindings' button - and also to set
which keymap is the default one for Zap to use. You cannot yet delete
keymaps, but it's fairly trivial to do so directly in the Keys file (just
don't do it while ZapConfig is running, or you might lose you changes).

The window is divided in two; at the top you can choose the default keymap,
using the bumper icons to scroll through the list of defined keymaps.
'Standard' refers to the base map, number 0. All others are referred to by
their "map comment", which is stored at the end of the map declaration in the
Keys file. In the Keys file supplied with Zap these comments are surrounded
by brackets: '(' and ')'.

At the bottom of the window you can similarly scroll through just the
alternate keymaps. The comment can be set here by changing what is in the
writeable icon, and you can add a new keymap by clicking on 'New'. You can
also edit the key bindings for this keymap by clicking on 'Edit key
bindings'. This will close the keymaps window, and open the keyboard window
(as used when editing the base keymap - only with the definitions for this
keymap). Closing this window will ask you if you want to save the changes to
the keymap, and then will return you to the keymaps window.

Closing the keymaps window will give you the option of saving any changes you
have made. Note that this is done automatically whenever you start editing
the key bindings for an alternate keymap, so it only affects changes you have
made since then.

Configuration Part 8 - Mode-specific options
--------------------------------------------

Clicking on the 'Mode options' button opens a window allowing you to set some
of the options specific to individual modes. Note that it is not possible to
edit some options for each mode (for instance the indent and pause for Martin
Ebourne's 'C' mode), because they are handled directly by the mode itself
rather than by Zap; only Zap-handled options are editable here.

The window is split into three; at the top left you can choose the mode whose
options you wish to edit, via a menu. At the bottom left there are a series
of display options, and at the right there are a series of edit options (Line
edit is in preference to Stream edit, Insert as spaces refers to tabs, and
Strip spaces is on saving). The 'Colours' and 'Mode cols' buttons at the
bottom of the display options section are currently greyed out, but will
bring up menus of, respectively, the standard nine colours common to all
modes, and any additional colours which the mode has defined.

If the mode does not currently have an entry in the !Config file for the open
option set, ZapConfig will construct a default entry using a standard set of
colours (which may be subsequently overwritten by the module when it is
loaded; it is advisable to edit options for a mode only once it has an entry
in the !Config file - do this by loading the mode using Options->Mode->Load
mode on Zap's iconbar menu and then Options->Save options), and options
stored in Zap's global options block in the !Config file. (Note that these
options are not currently editable in ZapConfig.) In addition it turns off
auto-indent.

Closing the window saves the changes back to Zap's !Config file. Note that
ZapConfig does not ask for confirmation here.

 this isn't necessarily the right set of standard colours, since I'm not
even bothering to look them up in the Wimp palette at the moment. Once I add
colour editing this will be sorted out.

Configuration Part 9 - menus
----------------------------

Clicking on the 'Menus' button will load the Menus definition file for the
option set open into a text editor (typically Zap). At the top of the file is
a brief explanation of the file format. I'd only advise fiddling with this
file if you know what you're doing :-).

Configuration Part 10 - Upgrading
---------------------------------

IMPORTANT NOTE: the upgrader mentioned in this section has not been
extensively tested (although the installer has). Since you can't use it to
install over versions of Zap prior to 1.30, it's fairly useless at the
moment, so checking it out isn't one of my priorities. However if you do have
cause to use it, do so with caution, and I'd be inclined to ensure you have a
backup of BOTH the new and old copy before doing anything.

Clicking on the 'Upgrading' button will open a window which allows you to
upgrade Zap itself, and also to quickly install and deinstall Zap extension
modules. The window is divided in two; at the top you can scroll through the
currently-installed extension modules, using the Remove button to deinstall
any currently present (note that this merely removes them from the External
file so that Zap no longer knows about them - they will still be present,
typically within the !Zap.3rdParty.<author> directory). The Auto button
dictates whether the module is auto-loaded when Zap starts (" *" in the
External file). To install a new extension module, drag it to the top section
of the window; ZapConfig will first try to find it in the list of
currently-installed modules, upgrading it if it is already present.

While installing (or upgrading - see later), the window will change to give
some information about the current action of the installer (although
generally it will flash past too fast to read). If any errors come up, the
left-most icon, Abort, will become selectable; clicking on it will close the
window and restore your previous installation of Zap. Clicking on the
right-most button, OK, will close the window without restoring Zap (in most
cases the copy of Zap left by the installer will still work, and if not much
has gone wrong you may want to accept the new version and tidy up by hand).
If any warnings come up, or if the installation is successful, you will be
notified and the right-most action button, reading either Continue (meaning
there's more to do) or OK (meaning the installation is complete) will become
selectable. The only exception to this is when you are installing a
directory, or upgrading Zap, in which case under certain circumstances an
error will occur but the left-most button will be Skip, meaning that the
process will skip the section which caused the error and attempt to finish
anyway.

If you attempt to install a module of the same or earlier version as the one
already present, you will be warned, and given the choice of continuing with
the installation, overwriting the current (and hence more recent or
identical) version, or of skipping that module.

If the module isn't already present then ZapConfig will do one of the
following:
  * if the module's help string contains an author name, then the installer
will create a directory within !Zap.3rdParty based on that name, and copy the
module into there. If the directory already exists it, will ask you if you
want to put it there.
  * if there is no author name in the help string, the installer will attempt
to locate the first extension mode defined by the module, and take the author
name from that.
  * otherwise it will create a directory within !Zap.3rdParty based on the
module name (from the module title string) and copy the module into there. If
he directory already exists, it will ask you if you want to put it there.
  * as a special case, if the module appears to have been written by Dominic
Symes, then the installer will place the module in the !Zap.Code directory.

Note that this falls down for Daniel Wagenaar's SoftWrap extension, because
the last name in the author string is Rooy. ZapConfig will therefore copy
SoftWrap into !Zap.3rdParty.Rooy, unless you use the guided installation
procedure via a (Config) file, as described below, or install the entire
Wagenaar directory.

The installer will then create an entry in the appropriate External file, using
the following method:
  * if the module is already listed (identified by its file leafname) then it
will replace that section of the External file. If it has wimp messages, a
boot command, or the autoloading flag present then these will be preserved.
  * otherwise it will be added to the end

The installer will attempt to scan the module for the Zap modes and commands
present; note that it will NOT pick up wimp messages which the module can
handle, since I have no real way of working that out. (I could trace the Zap
"service call" entry point from the command table and check for message
receipt testing, but there are only two modules I know of which respond to
messages - ZapBASIC and ZapOLE - and ZapBASIC doesn't appear to do anything
with its service call entry point). This shouldn't really matter, though,
because most modules don't use this feature.

It finds modes and commands by looking for code fragments identified as Zap
calls (using the standard procedures which come as examples in the Zap
documentation), and finding the calls Zap_AddMode and Zap_AddCommands. It
then backtraces to find the appropriate pointer, and from there can find the
mode and command tables. This method will therefore only work on extension
modules written using this style of code fragments, although in practise most
if not all such modules do so. I allow a small amount of mis-matching,
although if the fragment deviates from the expected code in any way the
installer will warn you.
Both of Daniel Wagenaar's modules (DWExt and SoftWrap) deviate slightly, but
ZapConfig will pick them both up successfully. ZapENH (latex mode extension)
by Elliott Hughes will flag a "suspicious code fragment" warning twice (once
for the mode, once for the command table), but will otherwise pass through
fine.

To do a more complete installation of an extension module, you can drag a
directory to the top section of the window. The installer will then look for
things in the following order:
  * "(Config)" - file format described below. This tells the installer
exactly what to do when installing the module, including which bits to copy
from the directory, where to put them, whether to alter the Keys file to add
extension maps, what to add to the External file, and how to
deinstall/upgrade a current copy of the module. It is strongly advised that
people writing or maintaining extension modules use this method to provide an
installer.

    If this file isn't present, the installer will first copy the directory
into !Zap.3rdParty, querying if it already exists, and then install all
relocatable modules in the directory using the procedure above, with the
addition that if there is no boot file specified for a module in the External
file, the installer will look for files in the same directory to use as a
boot file. It will only consider obey files, named (in this order):
!Boot<module>, !<module> and !Boot. The installer will prompt before adding a
boot file to the External entry.

Note that to re-install a module which is present in
!Zap.3rdParty.<directory> but not referrenced in the External file, you
should either drag the directory or the module from its location within
!Zap.3rdParty to the installer window, which will recognise that it is
already in the right place and not attempt to copy it. It will also search
for an appropriate bootfile as above.

Note that the External file is updated every time you remove or install a
module, but that altering the auto-load status of a module does not cause the
External file to be saved. If you have altered any of these switches since
saving the file when you close the window, ZapConfig will ask you if you want
to save, in the normal way.

The bottom section of the window allows you to install a new version of Zap.
ZapConfig will already know where the old version of Zap is, from <Zap$Dir>,
although you can alter this by dragging a copy of Zap onto the appropriate
path icon. Similarly, ZapConfig expects you to be installing from
adfs::0.$.zap/zip.!Zap (ie a copy of !Zap inside the root of a zip file in
the root of a floppy in drive zero). Again, you can alter this by dragging a
copy of Zap onto the appropriate path icon. Clicking on Install will install
the SECOND (lower) copy of Zap over the FIRST (higher), without destroying
all your configuration. It will do this by copying the core files, font
files, documentation and a few other things, and then installing all the
extension modules, starting with ZapBASIC, in !Zap.Code, and then progressing
through all the directories in !Zap.3rdParty.

The upgrader does not check the version numbers of Zap that you're playing
around with, and so it is possible to completely destroy your copy by
installing an older version which doesn't use some of the new files over a
newer version. The upgrader is only really useful for versions of Zap from
1.30 onwards.

ZapConfig takes a complete copy of your working !Zap before starting any
installation or upgrade, placing it in <Wimp$ScrapDir>.ZapConfig. In the
event of something going wrong in the upgrade, you will be able to restore
your original configuration by selecting the Abort button.

(Config) file format
--------------------

As mentioned above, the "(Config)" file is looked for by ZapConfig when
installing a directory of extension modules. This section describes the file
format, and is intended for extension module authors wishing to use it so
that ZapConfig can reliably install their modules, and is therefore a little
more technical, not to mention more sloppily written (:-), than the rest of
this file.

It is split into command groups of the form:

GROUPNAME <optional parameter>
  Subcommands or options
  ...
/GROUPNAME

and commands of the form:

COMMANDNAME <parameter>

Lines starting with a bar ('|') are comments. All indentations must be a
single tab character (ASCII 9).

The following groups and commands are currently recognised:

Name		Use				Example

TARGET		Specify target directory	TARGET <Zap$3rdParty>.Extension
OMIT		Files to omit when copying	OMIT
						  ReadMe1st
						  Installer
						/OMIT
MODULE		Specify how to install a	MODULE MyMod
		particular module. This is	  ... commands ...
		considerably more complicated	/MODULE
		than the other groups, since it
		may contain several subcommands:

		Use				Example
TARGET		Override target directory	TARGET <Zap$3rdParty>.Special
NAME		Target name			NAME SpecialMod
SUPPORT		Support files to copy to TARGET	SUPPORT
						  !BootSpec
						  SpecOpts
						/SUPPORT
DEINSTALL	Commands to deinstall old	DEINSTALL
		version (sent via oscli)	  Delete <ZC$Dir>.<ZC$File>
		The following variables are	  Delete <ZC$Dir>.!Boot
		defined:			/DEINSTALL
		  ZC$Dir -- directory of old v.
		  ZC$File -- leaf of old v.
		  ZC$Version -- old v. number
		Performing an error will cause
		the installer to stop
		installing this module.
KEYS		Alterations to make to keys	KEYS
		file - will be done on current	  KEY 116 KEYMAP 5
		option set. Possible commands:	  KEYMAP (HTML mode extensions)
		  KEY <line>			    001 NULL
		  REMOVEMAP <keymap number>	    ... etc ...
		  KEYMAP <comment>		  /KEYMAP
		The KEY line should be a hex	/KEYS
		key/variable number, followed
		by the command. If you give no
		then the entry will be removed.
		REMOVEMAP removes a keymap, both
		the definition and the &4xx
		variable.
		KEYMAP will create a new map
		with the lowest number possible.
                The actual variable numbers are
                recalculated from the key numbers
		given. For simplicity, the range
		is stored as 0x000-0x1ff.
		ZapConfig will convert all
		whitespace into the appropriate
		number of tabs and spaces.

		Note that you cannot currently
		edit keymaps directly; use
		KEYMAP, which will replace
		rather than add if appropriate.
		Attempting to directly edit a
		key number higher than &2000
		will most likely cause memory
		leakage in ZapConfig.
EXTERNAL	Alterations to make to External	EXTERNAL
		file. Commands are:		  LOADCOMMAND Run <Zap$3rdParty>.Filters.!Run
		  LOADCOMMAND <comm>		  COMMANDS
		  AUTOLOAD			    FILTERSEL
		  MODES				    ... etc ...
		  COMMANDS			  /COMMANDS
		  MESSAGES			/EXTERNAL
		This will replace any previous
		External entry for this module,
		as identified by leafname.
		These commands must be in the
		order given, but any many
		be omitted.

There isn't an INSTALL command because ZapConfig will automatically copy all
files required, and I can't think of anything else you might need to do on
installation. If anyone can think of anything useful, please get in touch.

Once a file has been specified either as the parameter to a MODULE group, or
in a MODULE group's SUPPORT command, it will not be copied to the normal
TARGET directory. Files listed in the OMIT group will NEVER be copied - they
should typically be installation instructions and scripts which are not
needed by ZapConfig (ie for use if you don't have or use ZapConfig).

You MUST include the following: a TARGET command for the entire file, and a
MODULE group with at the least a blank DEINSTALL group (because the parser
doesn't copy the module files until it finds the DEINSTALL group) for every
module you want installed automatically. It also doesn't really make sense to
define a MODULE group without using at least one of the KEYS and EXTERNAL
groups.

The order of commands and groups is important: you must define the TARGET
directory for the file before any MODULE groups. Similarly if you override
the TARGET or NAME of a module, then you must do so before any other commands
or groups in that module group.

The DEINSTALL group contains commands to be run on an old version before the
new version is installed. You don't actually need to delete the old version,
since the installer will copy the new version over the top anyway (unless
it's locked). Similarly you don't need to delete any SUPPORT files.

I have included sample (Config) files for two of the current extension
distributions for which the automatic directory installer doesn't suffice
(Matthew Hambley's ZapHTML, which needs an additional keymap, and Martin
Ebourne's ZapMJE, for which it adds a couple of key bindings for useful
functions). These are in !ZapConfig.Examples. Hopefully these illustrate
fairly well how to write (Config) files. If any mode authors require more
sophisticated installation procedures, please feel free to get in touch with
me and I'll see what I can do.

The End
-------

And that's it. Read the disclaimer. Share and enjoy. Please get in contact if
you've any suggestions/bug reports/etc.

The latest version of ZapConfig will be held on Crystal
(crystal.clare.cam.ac.uk) in something approximating the
/pub/acorn/zap directory. In addition I will attempt to keep the Hensa
archive site up to date (presumably in the same directory as Zap itself).
Anyone may upload complete copies of ZapConfig to any other site which
doesn't charge for access/downloading; I would like to know of where these
sites are if you so do.

Known bugs
----------

When submitting bug reports, it would be helpful if you could give the
following: version of ZapConfig, version of Zap, machine specs (memory -
especially how much free application space you had at the time - RiscOS
version, chipset) and what you were doing at the time if at all possible.
Repeatable bugs are easier to iron out :-).

Restrictions:

 * Resetting Zap$Dir while ZapConfig is running will confuse it hugely.
 * ZapConfig will only cope with 10 character leafnames and 256 character
   pathnames. If the latter is a problem when installing or upgrading, try
   doing it from as near the root as possible.
 * ZapConfig writes '| Default options' when it means Standard options,
   because this is apparently what ZapSetup expects. However this conflicts
   with the actual options set 'Default', so it's possible that this is
   wrong and hence may not work with ZapSetup.

Bugs:

 * None known, although my Config parsing may still be slightly flawed (less
   my ability to read the specification than my ability to think straight at
   2am, honest).

The future
----------

 * Colours editing.
 * Menus for font selection.
 * You should be able to edit the 'default' mode options somehow. Actually,
   I'm not sure whether Zap actually uses these flags in the !Config file to
   mean anything useful, so it's possible that I'm barking up the wrong tree
   completely here.
 * I'd also like to figure out a way of executing a Zap call from within
   another wimp task, probably by using a support module or something. This
   might allow me to edit options handled by the modes themselves, and
   certainly would rid myself of the difficulty of the above, since I could
   simply ask Zap to load the mode and re-save the !Config file if there was
   no appropriate entry.
 * I should probably use Filer_Action rather than crude *Copy in the
   installer and upgrader. In addition, the upgrader is rather patchy (and
   I'm not entirely certain it works).
 * I should probably use External Edit to send the Menus file to an editor,
   because that would be a lot neater. Currently I'm calling *Filer_Run,
   which again is quite crude.
 * The Config installer should be able to insert a "KEYMAP x" command based
   on the keymap number assigned by a KEYMAP group. It should also be able to
   add new path checks at the earliest number rather than hoping that it's
   not writing over someone else's.

Matthew Wilcox also suggested a scripting mode for Zap, but obviously I'm not
that mad :-).

If you have any other suggestions, please contact me (see below).

Disclaimer
----------

Neither the author nor distributor of ZapConfig can in any way accept
liability for any loss or damage arising from the use or inability to use
either ZapConfig or the information contained within the ZapConfig
documentation, even if they are previously informed of the possibility of
such a loss.

THIS IS PARTICULARLY IMPORTANT with ZapConfig at the moment, since it is by
no means guaranteed to be bug-free, and if it chews up your Config file, Zap
may freeze the machine while trying to load it. If you load Zap in your boot
sequence, like I do, therefore, it can cause major problems if you have to
reset your CMOS and then reconfigure your computer again (it takes a few
minutes even if you have a saved CMOS set). It is HIGHLY ADVISABLE to ensure
that you have a backup set of the Config and Keys files - do this by creating
a brand new set using ZapConfig, going to edit the keyboard layout, and then
saving it (ZapConfig should load the default Keys and Config files, and then
save them back in the correct place for the new set). This guarantees that if
anything goes wrong you are at least able to go back to a working set in the
style that you like. You can copy the External file in the same way by
opening the Upgrading window, toggling an autoload flag on one of the modules
on and off, then closing the window and saving the changes. Alternatively you
could do it all manually, which is probably much easier :-).

Thanks
------

 * Dominic for writing Zap in the first place.
 * Martin Ebourne for C mode, and for pointing me in Dominic's direction.
 * Matthew Wilcox for ZapSetup, and for almost, but not quite, challenging me
   to write ZapConfig.
 * The Egham Hills crew for meandering assistance, company, and sidetracking.
 * Tony Houghton for WinEd.
 * The team behind DeskLib (even if they overly complicated some things :-).
 * M&E, Penny, Katie, Jenni, Adrian, Dan & others for support.

Contacting the author
---------------------

If you wish to contact the author, write to the following address:

James Aylett
Clare College
Cambridge
CB2 1TL

This is available until June 1997. From then God knows, presumably, although
hopefully I'll know in advance also.

Support is available from sja20@hermes.cam.ac.uk, or on Egham Hills or
Monochrome (ne|el|pr.mono.org) - username dj. For email support, please
include ZapConfig in the first sixteen or so characters of the subject line.

Please note, however, that while at Cambridge I don't actually have access to
an Acorn that I can work on, and so it may take a while for me to track down
a solution to any problems you have.