
        ZapObey - A syntax colouring mode for Obey files
        ================================================

               !Help file for ZapObey version 0.27

Contents
========

1.0 : Features.
2.0 : Installation.
3.0 : What it does.
4.0 : Customisation.
5.0 : History.

1.0 Features
============

The program recognises a large range of operating system commands, and does
so even if the commands are in mixed case or are in abbreviated form.

It correctly colours GSTrans sequences like <Obey$Dir>, |G and <255>.

Numbers are recognised in decimal, hexadecimal and binary formats.

Redirection of the output of commands to different streams is indicated.

There is Beautify option which forces the displayed case of recognised
commands to follow the standard set out by Acorn, and a BEAUTIFY command,
which processes the file in the same manner.

The Zap SAVEANDRUN and RUN commands now start up a new task and execute the
file.

It is easy to customise the module to add your own *commands if required.

Cursor key enhancements stolen from Martin Ebourne's modes (see later).


2.0 Installation
================

Copy the module "ZapObey" into an appropriately-named subdirectory of the
"3rdParty" directory inside the Zap application.

In the file called "External", in the directory "!Zap.Options.Default" or 
wherever the variable Zap$External points to, add lines as follows:

<Zap$3rdParty>.Tyler.ZapObey *
	Obey
	-
	BEAUTIFY

This tells Zap about the new mode.  The '*' causes the mode to be loaded when
Zap starts and if this is undesireable, can be omitted.  If you want Obey
files loaded by default into this mode then you will need to edit the "Keys"
file.

My keys file has these lines in it:

File types:
...
Obey		&1FEB	Obey
Deskstart	&13F0	Obey
Desktop		&1FEA	Obey

If your version of Zap is earlier than Zap 1.30 then you will need to edit
your !Run file to include a command to load the module.  Then, the next time
Zap is loaded Obey files or desktop boot files (or any other filetypes you
have told Zap about will be loaded into the new mode and come out all
rainbow-hued.

When the module is first installed its logical-colours have all been set to
default to different physical colours.  This has been done to show the
breadth of the syntax colouring involved.  Some of the colours a are a
little contrived, and choosing your own colours is recommended.

It is recommend that if you want to see what the module does, you should
have the colours all set to different vaules at least for an initial period,
until you clearly understand what each colour means.


3.0 What it does and does not do
================================

This program correctly displays most Obey files and desktop-boot files which
are commonly encountered.  When it does not know about a command it assumes
that it has an orthodox syntax and colours it differently from normal
commands to indicate that it has not been recognised.  This method of
gracefully failing enables the module to be used as a spell-checker and, to a
limited extent, a syntax checker.  Missing Then commands, for example may be
spotted more easily.

Leading spaces and '*'s are dealt with correctly by the module.  Leading
'%'s, '@'s and '.'s are also ignored: this is mainly to cooperate with a
number of PD programs which use these characters as special preprocessing
commands when multi-tasking Obey files.  The '%' character is also used to
prevent GSTrans from acting on a line.

The code used to display numbers should deal with most things correctly.
Numbers of the form 2_010101, &A012 are recognised.  Numbers may contain ':'s
(as in Sys$Time) and may end with the letter k (for memory specification). 
Numbers in paths are not coloured.  There are some contrived lines of valid
code in which the numbers are not coloured correctly:
'Save0BadCAB1+C0DCAFE' is one example.  Examples such as this one can
usually be made pretty if desired by placing quotes around filenames and
putting an & or a leading 0 in front of hexadecimal numbers that begin with a
letter.  '&' is not coloured as a hexadecimal prefix when used in the form
&.filename.

The module does not attempt to process the parameters of the Configure
command; they are displayed as plain text.  Recognising them would be easy to
add to the module, but it may not be worth the space, as the Configure
commands are rarely encountered in in Obey files.  There are also problems as
different machines can have different configuration options.

The parameters of 'SetAlias$...' commands are not processed.  Code was
written to do this, but has now been removed from the module as processing
the parameters of these commands no longer seems appropriate.  If you want to
see some of the problems that doing this produces then you can enter a
TaskWindow and type the command 'ShowAlias*'.  Then change to Obey mode and
delete the first column by using search and replace with "Alias$*:" as the
item searched for.  Most of the problems with the 'SetAlias$'s stem from the
commands being passed to OS_GSTrans before they normally would be.  Doing
this will also give you some idea of the commands that your computer uses
that are not currently recognised.  For more comprehensive information on the
same subject stoke your computer up with your favourite command-providing
modules and then try an extensive text-massage session with the output of
*Help Commands.

There is Beautify option which can be ticked just off the mode menu.  Setting
this forces the displayed case of recognised commands to make the file more
legible.  It does not affect the file, just the way it is displayed.  To make
this option more useful when editing files, there is also a BEAUTIFY command,
which processes the file in the same way.  No attempt is made to change the
case of unrecognised commands, paths, or command parameters; only recognised
commands are processed.

The module also contains some enhancements to the cursor keys so that when
they are  used in combination with the shift key they behave in a more
appropriate manner than when is in text mode.  These routines have been
stolen from Martin Ebourne's C mode and are documented by him in his own 
directory.  Basically they make the shift-cursor combinations pause more
frequently and more intelligently step through the code.  As Obey files often
contain paths, this comes in very useful.  Martin has kindly given me his
permission to use his code.  His Assembler mode provided the initial
inspiration for the module, and my appreciation of his C mode has risen
astronomically now I appreciate the problems involved in getting colouring
modes to work properly at low widths.  He also provided me with Dom Symes'
 address when I most needed it (thanks Martin).


4.0 Customisation
=================

4.1 : Why customisation?
4.2 : How to customise.
4.3 : The format of the commands.
4.4 : The common command-terminators.
4.5 : The rare command-terminators.
4.6 : Terminator summary.
4.7 : Final Notes.


4.1 Why customisation?
----------------------

It is not easy to write an Obey file colouring module that will suit all
tastes.  Different users may have different commands which are recognised by
their computer, different files in their library, or pointed to by their
Run$Path variable, different modules which provide their own commands loaded
by default, and so on.  No attempt has been made to write a program that
examines all the files in the Run$Path, examines the currently selected
directory, looks at all the Alias$... variables and talks to all resident
modules to find out which commands they support.  Even if a module did all
this it would still not have enough information to correctly colour Obey
files because it would need to know something about the syntax of the 
commands to do this.

An example of this is the common 'Do' command.  For those to whom it is
unfamiliar, it was written because some commands do not get the operating
system to feed their parameters through the GSTrans-decoding engine.  This
means that Filer_OpenDir <Obey$Dir> (for example) will not work as it does
not even try to decode the <Obey$Dir>.  The 'Do' command solves this by
passing the entire command through the OS_GSTrans SWI before passing it on,
so you can write Do Filer_OpenDir <Obey$Dir> and it should work.

What has this to do with syntax-colouring of Obey files?  Well, for 'Do
Filer_OpenDir <Obey$Dir>' to be coloured correctly, the computer needs to
know that the Do command is unusual in that it takes an operating system
command as its first parameter.  An alternative strategy of colouring all
strings that contain commands has problems and tends to produce code that is
liberally spotted with commands where they shouldn't be and looks as though
it has caught a fever.

My soultion to all this is to provide a module that is customisable for those
users who wish to fine-tune its behaviour for their own system.  Hopefully
this will make the module easier to upgrade, better able to satisfy the needs
of users with unusual requirements, and make it possible to provide support
for non-english speaking computer users.  If someone were to translate this
module into Welsh (for example), then I would be delighted.


4.2 How to customise
--------------------

I have attempted to program this module in a manner which makes it as easy as
possible for users to alter the list of commands which it recognises and
highlights.

The list of recognised commands is stored at the very end of the module. 
There is no user-interface provided for changing this list, but the module is
hacker-friendly and if you are reasonably confident about what you are doing
and find that there are some commands which the module is consistently not
recognising, then it is possible to simply load the module directly into a
text editing mode of Zap, and edit the list of recognised commands directly.


4.3 The format of the commands
------------------------------

If you go to the end of the module you should find something that starts...

   ...Access |AddTinyDir |ADFS |Alpha{Append |Audio |Back |Backdrop |...

Commands are stored in alphabetical order of their first letters. This order
should be maintained when adding to the list; in order to speed  up its
search routines the module uses an alphabetical index which is  recompiled
each time it is run: if the commands are out of order then it may get
confused and fail to recognise your commands.

Commands may be of any length.  Because of the indexing system used, there is
very little time penalty for adding new commands, though they do take up
extra space.  The commands are searched in the order in which they appear,
and it is sometimes important to realise this.

Each command is spelt out in full, usually with a trailing space, and the end
of the command is indicated by a character of ASCII value greater than 124
(the code for 'z').

There should be no other spaces, carriage returns or anything else until the
end-of-table marker which is two asterisks: '**'.  These are important and
should not be deleted under any circumstances.

The case of the commands is not important in command recognition, but it is
used when the Beautify option from off the mode menu is ticked, or when the
BEAUTIFY command is issued.  If you prefer your Error commands or If...Then
structures in upper case then this can be easily changed.


4.4 The common command-terminators
----------------------------------

The terminating character used determines how the module interprets the
preceeding command.

Currently-used terminating characters are as follows:

'|' : ASCII 124/&7C

This is the most common terminator.  Command checking is subsequently turned
off and no further commands are expected, except possibly Else.  If a command
is not recognised then it is treated as though it were terminated in this
manner.

'}' : ASCII 125/&7D

This signifies that the first parameter of the command is to be treated as
another command.

Current examples of this are Do and TaskWindow.

'{' : ASCII 123/&7B

This indicates that the command is a prefix.  Any command that starts with
the specified string is assumed to be a valid command and is coloured
appropriately.  If you use a command like 'I{' in the list then please ensure
that it is at the end of the 'I's in the list.  If it is at the start then it
will match any command starting with the letter 'I'.  This means that If
statements will no longer correctly be recognised, and the module will not
know when to look out for Then or Else commands.  Using this option
frequently means that the utility of the module as a spelling and syntax
checker decreases, as it matters less and less how you spell commands-no
matter what you enter gets recognised as a valid command.

Existing currently in the module are:
Desktop_... Filer_... Zap...  Basic...
FrontEnd_... ShellCli... Memory... Alpha...

'~' : ASCII 126/&7E

This is used for commands where the existing punctuation routine analysers
are inappropriate and are turned consequently to be turned off.  Very little
processing is done to these commands: GSTrans sequences are still expanded
and the Else command is checked for if there is a preceeding If ... Then
construct, but that is about it.

In the module are: Echo Configure Help Key Show

'' : ASCII 156/&9C

This terminator is used when you do not want a command highlighted as such,
but do not want it to be marked as unrecognised either.  The only example in
the module is System: which is not a command at all.  The reason for this is
that during the module's testing there were a number of commands of the form:

  'RMEnsure SomeModule 1.00 System:Modules.SomeModule'

The program would get to the 1.00 and then be expecting an operating system
command, instead of which, it finds a path with no RMLoad, RMRun, Filer_Run,
or even a '/' in sight.  Instead of highlighting 'System' as an unknown
command, providing this terminator seemed to be the simplest solution.  If
required, other common path prefixes may be included: 'ADFS:', 'SCSI:',
'Root:', etc.  Colouring apart, '' acts much like '|', except for the fact
that commands which it terminates are not sent to either of the 'Beautify'
routines when these are activated.


4.5 The rare command-terminators
---------------------------------

The rest of the commands are mainly for internal use.

'' : ASCII 138/&8A

This is only used for the Eval command.  It changes the list of recognised
commands to: Mod, Str, Val, And, Or, Eor, Not, Right, Left and Len.  Then and
Else commands are still recognised if appropriate.  Some people may find the
case of these commands not to their taste when the beautify option is used,
preferring AND, OR, etc.  Once again, it is possible to edit the module
directly, but this time is is important to preserve the length of the list of
commands.

'' : ASCII 139/&8B

Used for the If command.  When used, the Then command becomes active and the
expression evaluation functions are turned on (see notes for Eval, above).

'' : ASCII 137/&89

Used for the Then command.  Only recognised if preceded by a '' (If)
command.  When used, the next string is treated as a command and the ''
(Else) command becomes active....

'' : ASCII 136/&88

Used for the Else command.  The command is only recognised if preceded by a
'' (If) command and a '' (Then) command with no corresponding '' (Else)
command.  When used, the next string is treated as a command.

'' : ASCII 143/&8F

Used as the terminator for RMEnsure.  When used, command checking is turned
off until a number is recognised.  Then the next string after the number is
then treated as a new command.

'' : ASCII 174/&AE

Used for the Error command.  This colours the command differently from usual
and any number immediately following it is coloured as a number.  Subsequent
text is treated as though it followed after a '~' terminator i.e. no
punctuation or numbers are coloured as such.

'','','','','','' and '' : ASCII 249-255/&F9-&FF

These terminators are not currently used in the module at all.  They are,
however necessary if some widespread utilities are used.  They make the Nth
parameter of the command into a new command where ''->N=1, ''->N=2,
etc.  IfFile, IfDir, IfAbsent and IfExists all require these commands if they
are to be implemented.  '' is the same in its action as '}' which is easier
to enter from the keyboard.

There are a number of utilities that cannot easily be dealt with by the above
scheme: AppEnsure, TaskEnsure, IfPodule and IfThereIs are problematical
examples as they use a command as a parameter after a variable number of
switches and paths.  Without wading further into their syntax it is not easy
to tell what is a command and what is not.  If you want to implement these,
it is probably easiest to deal with them in a simple manner and using the '|'
terminator, which means that their parameters will not be parsed.

If a trailing space is placed between the command and its terminator, then a
space will be necessary for the command to be matched. Whether this is
necessary or not depends on the command.  For example 'Pointer1' is a valid
command and 'Pointer1' is not.  In this instance the command should have a
trailing space, i.e. 'Pointer|'.  Trailing spaces do not affect abbreviated
versions of the command so 'Point.1' is still allowed.  'If1Then|Acomment'
is a valid piece of code and if the Then command contained a trailing space
then this would be coloured incorrectly.

The commonly-used terminators can be entered from the keyboard.  For the
others, if you really want to use them, you can enter them by using !Chars or
a program with similar functionality, or by using the Alt+numeric keypad
combinations and entering them by way of their ASCII codes.


4.6 Terminator summary
----------------------

'|' : 124/&7C : Normal and most common terminator.
'}' : 125/&7D : First parameter is new command.
'{' : 123/&7B : Command is a prefix.
'~' : 126/&7E : Punctuation turned off.
'' : 156/&9C : Command not highlighted.
'' : 138/&8A : ...like Eval command.
'' : 139/&8B : ...like If command.
'' : 137/&89 : ...like Then command.
'' : 136/&88 : ...like Else command
'' : 143/&8F : ...like RMEnsure command.
'' : 174/&AE : ...like Error command.
'','','','','','' and '' :  249-255/&F9-&FF :
N=1,2,3,4,5,6 or 7.  Nth parameter is a new command.


4.7 : Final Notes
-----------------

If you decide to edit the module in the manner described above, it is
recommended that you make a backup of it before you do anything.  Modules can
be fragile things and a single space inserted at the start of the file will
render it completely useless.

5.0 : History
-------------

v0.28 (03-Nov-96)
    * Module configuration now no longer strips spaces by default.
    * ASCII 13 characters are now displayed correctly.

v0.27 (28-Oct-96)
    * Module shortened by 300 bytes or so.

v0.26 (14-Oct-96)
    * Bugfix for RISC PC users experiencing occasional problems.
    * Support for common "Repeat" command added.
    * Some unnecessary code removed resulting in minor decrease in size.
    * A few minor changes to the default colours and their documentation.
    * History section added to this file.

v0.20 (20-Oct-95) 
    * First released version.

Enjoy
 _____  __  __  _____               The Mandala Centre,
|_   _||  \/  ||_   _|  11 Alexandra Road, Clifton, Bristol, BS8 2DD.
  | |  | |\/| |  | |              tim@varuna.demon.co.uk
  |_|  |_|  |_|  |_|         http://www.varuna.demon.co.uk/tmc/
