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

Contents
========

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

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.

Command completion has now been implemented. This is activated as normal by
typing in the first part of a command and then pressing the full-stop key
("."). Command completion is not at all case sensitive, and it is
possible that it may operate in some cases where it is not appropriate for
it to do so.

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 !ZapObey application into the !Zap.modules directory, then restart Zap.


3.0 What it does
================

3.1 : What it does and does not do
3.2 : Known issues

3.1 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.

Command completion has been implemented.  Note that the 'full-stop'
abbreviations used by ZapObey may not necessarily correspond exactly
with those used by the operating system's CLI routines. What the CLI takes
as a valid abbreviation depends on which modules are loaded.

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.

3.2 Known issues
----------------
* Command completion is not context-sensitive. It does not know about
  evaluating function commands (e.g. AND) and it may act when it is not
  appropriate for it to do so. There are circumstances where it can act
  inside comments, or quoted phrases. This situation will hopefully
  slowly improve.

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 solution 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
preceding 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 preceding 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.

'' : ASCII 151/&97

Used for the FX command.  This colours the following text as a number,
even if it is not preceded by a space.

'','','','','','' 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.
'' : 151/&97 : ...like FX 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. In general it is better to sned a feature request 
to the Zap developers. See the contact section at the end of this file for details

5.0 : History
=============

v0.47 - (30-Jan-03)
      * Removed the now unnecessary buttons code

v0.45 - (18-Jul-01)
      * Minor fix to redraw code

v0.44 - (06-Jul-01)
      * Bugfix to Scripts loading code.

v0.43 - (27-Sep-99)
      * Updated for Zap v1.45.

v0.42 - (27-Mar-97)
      * Buttons support added.

v0.41 - (25-Feb-97)
      * Cured severe bug introduced in 0.39 which sometimes caused Zap to crash on RPCs
        when editing the first line of the file.
      * Command completion routines made more context sensitive so they should never
        operate inside comments, or quotation marks, or in strings preceded by a full
        stop character.  As not all paths in obey files are quoted, this can still be a
        minor source of irritation, though.
      * Completely changed options configuration code.  This means that any stored
        configuration settings from the mode menu will be lost.

v0.40 - (14-Feb-97)
      * Cured bug when editing in linewrap mode which caused some editing
        sequences at line ends to crash Zap.

v0.39 - (09-Feb-97)
     * Corrected code that coloured commands split over line ends.
     * Added code to colour GSTrans sequences which are split over line
        ends.
      * Added command completion routines.
     * Added gratuitous bracket matching for "< ... >" and "{ ... }".

v0.38 - (30-Jan-97)
     * SAVEANDRUN problems eliminated.
     * Capitalisation of 'RMReInit' and 'ShutDown' altered.  The 'case' of
        If ... Then ... Else remains a matter of controversy.

v0.37 - (07-Jan-97)
     * Another RPC instability problem ironed out.

v0.36 - (06-Jan-97)
     * The Zap command "OLEFILECHANGED" was added in error and then
        quickly stripped out again (apologies).

v0.35 - (11-Dec-96)
      * RPC problem with long first lines of files really fixed.

v0.34 - (09-Dec-96)
      * Code producing logical line numbering problems removed.
      * RPC problem with long first lines of files (hopefully) fixed.
      * Alias command now has more sensible syntax colouring.

v0.33 - (28-Nov-96)
      * After being asked about the existence or otherwise of ZapCSV, it was
        decided to add some support within ZapObey for editing CSV files.
        The only real change has been that now lines starting with "%%" are
        coloured as comments.  This interferes only insignificantly with
        ZapObey's colouring of Obey files, but adds useful functionality
        for other users, without adding an entire new mode.
      * CDir is now recognised as being a valid command.

v0.32 - (19-Nov-96)
      * Fixed minor problems with top-bit-set characters in filenames
        being followed by numbers.

v0.31 - (15-Nov-96)
      * The "unnecessary code" removed in v0.26 has been reinserted; it was
        more important than had been anticipated, and adversely affected
        redraw of long lines.
      * FX commands are treated specially, so that they do not need to be
        followed by spaces for their parameters to be correctly coloured.

v0.30 - (10-Nov-96)
      * v0.29 didn't solve the problem (indeed it would even cause problems
        for non-RPC owners), but v0.30 does.  I have applied the solution to
        all my modes.

v0.29 - (09-Nov-96)
      * Speculative fix for RPC owners who use !Zap with dynamic areas:
        a problem sometimes occurred when shift left-arrow was pressed at the
        very start or end of a file.

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.


6.0 : Contact
=============

If you have any comments or bug reports concerning Obey 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/>.
