
				   ZapBASIC
				   ========

Contents
========

1.0 : Features.
2.0 : Installation.
3.0 : Function.
4.0 : BASIC colour details.
5.0 : BASIC menu options.
6.0 : BASIC buttons.
7.0 : History
8.0 : Authors
9.0 : Contact


1.0 Features
~~~~~~~~~~~~

Recent features include:
 * Improved syntax colouring and tokenisation.
 * BASIC assembler code is now being coloured and syntax-checked properly.
 * Simple bracket matching has been implemented.
 * The mode now also offers support for ZapButtons.


2.0 Installation
~~~~~~~~~~~~~~~~

Copy the application "!ZapBASIC" into an the !Zap.Modules directory and
reboot Zap.


3.0 Function
~~~~~~~~~~~~

  3.10 Editing BASIC
  3.20 Taskwindows

3.10 Editing BASIC
~~~~~~~~~~~~~~~~~~

  3.11 Changing editors/options
  3.12 Using BASIC in ARMBE mode
  3.13 Testing BASIC programs
  3.14 Troubleshooting
  3.15 Technical detail

3.11 Changing editors/options
-----------------------------

There are essentially 3 ways to edit BASIC programs in Zap. Do not be put off
if you dislike the default configuration. You may change most things to your
preference.

In the default configuration, BASIC programs are edited in the Zap extension
mode called BASIC. This is designed to be a desktop version of Acorn's ARMBE.
Those people used to ARMBE should find this mode very easy to use. The
program is edited while tokenised and line numbers are shown in the margin
and updated when new lines are inserted.

Return and delete act differently from ARMBE, acting as they do for the
standard text mode (this is called stream editing). If you wish them to act
precisely as in ARMBE then switch on the 'lineedit' and 'nonstandard'
options. They will then act in a 'line editor' fashion with Return inserting
a new line rather than splitting the current one. The functions Split and
Join (sF1 and cF1) can then be used to split/join lines.

For those people who wish to edit BASIC in tokenised form, and thus with line
numbers accessible, but don't want to see them in the margin, they can be
switched off. Perform the option changes indicated by the clicks:

	options.mode.BASIC		 ; configure BASIC mode
	options.display.linenumbers.none ; turn off line numbers
	options.mode.TEXT		 ; return config mode to text
	options.save options		 ; save your Config file
	
For those who prefer to edit BASIC in detokenised form, there is a separate
mode named BASTXT which accomplishes this. To load a single file in using
this mode it is easiest to set the options menu mode to BASTXT and hold down
CTRL key while loading the file. To change to the BASTXT mode permanently,
change the line of the 'Keys' file which reads:

	BASIC		&1FFB	BASIC
	
to read:

	BASIC		&1FFB	BASTXT
	
In this mode, whenever a file is loaded it is converted into text with line
numbers striped. Saving is the converse. Please note that if the program
contained line number references, then Zap will beep before forcing the BASIC
mode described in 3.12.

3.12 Using BASIC in ARMBE mode
------------------------------

In it's default setup the BASIC mode is designed to emulate ARMBE. Thus line
numbers are displayed in the left margin, and automatic renumbering takes
place as lines are added to the file.  All GOTO and GOSUB line number
references are automatically updated.

In line editor mode, the RETURN key inserts a new logical line. To split the
line in two at the current cursor position press SHIFT-F1 and to join two
lines press CTRL-F1. When two lines are joined, a ':' is inserted between the
statements.  If you do not like this, it can be switched off by turning off
the line-edit and non-standard flags on the edit menu.  See above.

Text is typed as usual with the proviso that tokens are automatically
expanded. For example 'P.' will be expanded to 'PRINT' when the fill-stop is
typed. Also note that in non-standard editing mode excess spaces are
automatically removed from the end of a line (except when this would prevent
the line wrapping onto the next).  'Unix' tab mode just advances the cursor
to the next tab stop as in ARMBE.  The other tab modes, unix and Column work
as in the text mode.

Copying bits out of the middle of lines is performed using the COPY key.
Groups of lines are selected, cut and moved/copied as usual for any text
region.  The regions are automatically renumbered internally. For those (like
me) used to the ARMBE way of moving regions, there is a natural replacement.
For example suppose you wish to move lines 10-50, to before line 100. In the
ARMBE you would do:

  Move to line 10, cM cM, move to line 50, cM cM, move to line 100, cB, f12
  
In Zap you do:

  Move to line 10, cCOPY, move to line 60, ESCAPE, move to line 100, cV

GOTO's are automatically updated. To observe this copy the lines 10 and 20
below several times in a BASIC program.

	10 PRINT "HELLO"
	20 GOTO 10

Shift-F8 renumbers any program in steps of 10. Please note that line numbers
are not stored in the undo buffer as this would be a waste of space. Thus
after multiple undo's, the line numbers may get out of order. This can be
rectified by renumbering (shift-F8). BASIC programs can be appended by
simply dropping them into the window.

3.13 Testing BASIC programs
---------------------------

Zap provides a number of commands to test out BASIC programs while they are
being edited. The first three start up a new BASIC task and RAM transfers
your program to the new task, loading it a PAGE:

BASIC      (scB) This drops you into BASIC with your program loaded at PAGE.
RUN        (scU) This acts as cB and then RUNs the program.
RUNANDQUIT (scF) This acts as cU but automatically quits BASIC when finished.
 
The other two commands save the program first, and then run them from disc.
These are of course slower:

COMPILE    (scC) As cU but saves the program first and chains it from disc.
SAVEANDRUN (scE) As cF but saves the program first and chains it from disc.
BASIC_TWRUN      This saves the progam and then runs it in a taskwindow.

Most of these commands have their own button, for easy access.

Zap calculates the amount of room needed to run the program as the maximum
of: 1) Next slot size 2) Program size+16k 3) Program size * 1.5.

ZapBASIC has a command designed to help locate simple syntax errors in
BASIC programs.  BASIC_CHECKBUF checks for mismatched quotes, brackets and
similar simple errors, generatung throwback based on the results.  This
is intended mainly to provide a quick way of locating errors without
typing in reported line numbers.  The command is not currently aware of
comments in assembler.

3.14 Troubleshooting
---------------------

There are several errors that can occur when editing BASIC in Zap's
tokenised BASIC mode.

The first of these is the 'BASIC line too long' error.  This is given when a
single line is longer than 255 characters, a limit imposed by Acorn's BASIC
interpreter.  Attempts to insert characters on this line will then produce
this error.  This feature can be turned off by ticking the 'Allow long lines'
option in the BASIC mode menu.  This allows lines to exceed the 255 character
limit (albeit with warnings) by a few characters - which can help with the
editing of very long lines.  Attempts to save the file with long lines still
present will then generate an error.

It is possible, when editing BASIC programs in the tokenised BASIC mode, to
get an error 'cln_backward'. This essentially means that the BASIC program
has become corrupted in some manner and Zap can't redraw the screen -
usually the line numbers have got out of sync.

If you get this error it is not normally a cause for panic. The easiest way
to save your program is to switch immediately to text mode (scF1) before
doing anything else. Save it as a text file (if you wish), move to the top
of the file and then switch back to BASIC mode (via scF6), renumber and then
save the program.

The most common cause of the 'cln_backward' error in previous versions of
ZapBASIC was inserting regions with multiple lines which were not aligned to
complete BASIC lines. This was possible when selecting regions via the mouse
using 'ADJUST'.  Fortunately, this case has been addressed; the error should
now occur much less frequently.  It remains possible to produce the error,
for example when editing corrupt or non-BASIC programs in 'BASIC' mode, or by
deliberately mangling the BASIC line-numbers by editing them in 'Byte' mode.

3.15 Technical detail
---------------------

Note that a slight modification is made to the BASIC program on loading.
The actual file format edited is a number of lines of the form:

 xx yy zz "Tokenised line" &0D

Where xx yy zz is the line number in 3 byte text form as stored after a GOTO
or GOSUB statement.



4.0 BASIC colour details
~~~~~~~~~~~~~~~~~~~~~~~~

   Comments
     All comments following REMs will be coloured this colour. This also
     applies to text following ";" in assembler up to the next ":".
     Eg: REM > SillyProgram
	 Will colour the > and anything following it

   Strings
     Strings surrounded by "'s will be coloured in this colour
     Eg: a$="hello"
	 Will colour the "hello" string

   Tokenised
     Any BASIC tokens will be coloured in this colour.
     Eg: scan$=FNstring0(ptr)
	 Will colour the token FN

   x in PROCx
     The names of any PROCs and FNs will be coloured in this colour.
     These are coloured both in calls and in any definitions.
     Eg: in PROCquit or DEFPROCquit the 'quit' wil be coloured.

   PROC/FN
     The PROC and FN keywords will be given this colour.  They won't
     be coloured if they are part of a definition, though.
     Eg: PROCpoll(%0)
	 Will colour PROCpoll.

   DEF/END
     The DEFPROC, ENDPROC and DEFFN constructs (and also STOP and END)
     will be given this colour.
     Eg: DEFPROCpoll(mask%)
	 Will colour the DEFPROC.

   FOR/NEXT
     The FOR, NEXT, REPEAT, UNTIL, WHILE and ENDWHILE keywords will be given
     this colour.
     Eg: FOR T%=0TO10:NEXT
	 Will colour the FOR and NEXT keywords.

   IF/THEN
     The IF, THEN, ELSE and ENDIF keywords will be given this colour.
     Eg: IF Q% THEN QUIT ELSE UNTIL FALSE
	 Will colour IF and THEN.

   CASE/WHEN
     The CASE, WHEN, OF, OTHERWISE and ENDCASE keywords will be given this
     colour.
     Eg: CASE A% OF
	 Will colour CASE and OF

   DATA
     Data statement values will be coloured this colour (DATA itself is
     coloured as tokenised).
     Eg: DATA infobox%,">HInfobox",12
	 Will colour inforbox% and 12.  The ","s and the ">HInfobox" are
	 coloured as is normally appropriate.

   HexNumbers
     Any hex number will be given this colour.
     Eg: PRINT &745674
	 Will colour &745674

   Numbers
     Any numbers other than hex numbers will be given this colour (including
     binary sequences).
     Eg: PRINT 456
	 Will colour 456

   ( and )
     These brackets will be given this colour. These are mostly used for sums
     and arguments.
     Eg: Appdir$=FNsystemvar(Appname$+"$Dir$")
	 Will colour ( and )

   { and }
     These brackets will be given this colour. These are mostly used for
     lists of registers in assembler.
     Eg: STMFD	 (sp)!,{r0-r5,link}		; Stack registers
	 Will colour { and }

   [ and ]
     These brackets will be given this colour. These are mostly used for
     arrays and offsets in LDR and STR assembler statements.
     Eg: LDR	 r2,[sp,#4*2]			; re-read register 2
	 Will colour [ and ]

   :;,
     These special symbols will be given this colour. The ; colour is only
     used in PRINT, INPUT and BPUT statements.
     Eg: BPUT#o%,"Program:"+Appname$;
	 Will colour the ;

   +-*/=<>
     These arithmetic and comparison operators will be given this colour.
     = in assignment is also coloured this colour.
     Eg: IF testing%=TRUE THEN*Spool
	 Will colour the =

   !?#^
     The memory operators will be given this colour.  The writeback operator
     in assembler is also affected, as are the number and power operator.
     # is also used in file IO (BGET,BPUT,etc) and in assembler (MOV, LDMxx,
     etc).
     Eg: IF start%?ptr%=ASC(":") THEN
	 Will colour the ?
     Eg: BPUT#o%,"Program:"+Appname$
	 Will colour the #

   *Commands
     Commands prefixed by * will be given this colour. This does not apply to
     * commands executed by using OSCLI which will be coloured using the
     string colour.
     Eg: *Dir Clippings:#.Graphics.JPEGs.pics.1.abm.jpeg
	 Will colour the entire line from * through to to jpeg.

   Labels
     Any assembler labels will be given this colour (just the definition).
     Eg: .pollcode
	 Will colour the dot and the variable
   Assembler
     Any assembler instructions will be given this colour.
     Eg: MOV   r0,#0
	 Will colour the MOV instruction

   Directives
     Any assembler directives will be given this colour.  These include the
     DCx, EQUx and ALIGN instructions.  When used as directives & and =
     are also given this colour, as are the '='s used to return from
     function calls.
     Eg: EQUS  "Hello"
	 Will colour EQUS

   Registers
     Registers will be given this colour. Register names recognised include
     r0-r15, sp and pc.
     Eg: MOV   r1,#5
	 Will colour r1

   Shifts
     Any assembler shifts (eg LSL, ROR, etc) will be given this colour.
     Eg: MOV   r0,r2,LSL #2
	 Will colour LSL

   Branches
     Assembler branches will be given this colour (B, BL).
     Eg: BL    pollcode
	 Will colour BL

   LDM/STM
     Multiple register operations (stack/array) will be given this colour.
     Eg: STMFD	 (sp)!,{r0-r5,link}		; Stack registers
	 Will colour STMFD

   LDR/STR
     Single register memory operations (LDR, STR) will be given this colour.
     Eg: LDR	 r0,[r5,#8]
	 Will colour LDR


5.0 BASIC menu options
~~~~~~~~~~~~~~~~~~~~~~

    Window wrap	   Makes the listing reformat to the current window size.
    Drop into...   Downloads the program into BASIC and leaves you at the
		   prompt
    Run		   Runs the program directly from memory, leaving you at
		   the prompt when it exits
    Run and quit   Runs the program and returns to the desktop on exit
    Save and Run   Saves the program, then runs it, leaving you at the
		   prompt when it exits
    Save, Run...   Does all three - saves, runs it and then returns to
		   the desktop (this is the most common one to use)
    List of DEF's  Lists all the functions, like the button
    Check	   Performs simple syntactic checks, generating throwback.
    Bracket...	   Allows the brackets to be matched as in the old C mode
    Don't... code  Stops assembler being coloured
    Don't... APCS  Stops APCS registers being coloured in assembler code
    Allow long     Allow BASIC lines to exceed the 255 character limit.


6.0 BASIC buttons
~~~~~~~~~~~~~~~~~

    -> 10,20	   Renumbers the current program
    List Defs	   Lists the procedures and functions defined in the program
    Save Run	   Saves the program and runs it
    Run		   Runs the program directly from memory, leaving you at
		   the prompt when it exits
    Run and quit   Runs the program and returns to the desktop on exit
    Drop into...   Downloads the program into BASIC and leaves you at the
		   prompt
    < and >	   Indent and outdent the selected region.
    XREM and REM   Remove a level of comments from the currently selected 
		   region / comment out the section with REMarks,
		   respectively.
    Check	   Performs simple syntactic checks, generating throwback.


7.0 History
~~~~~~~~~~~

v1.39 - (05-Mar-2003)
      * Split TaskWindow mode into its own extension module.
      * BASIC mode now colours the ARMv5E instructions (SMALxy etc)

v1.37 - (14-Aug-2002)
      * Modified BASTxt mode to only (de)tokenise if the filetype is BASIC.
        This makes it suitable for use with Brandy.

v1.36 - (30-Sep-1999)
      * Support for internationalised extension structure.
      * Removed final debugging beeps.

v1.35 -
      * Good question. Changelog got lost ...

v1.34 - (05-Feb-1999)
      * DDEUtils/Taskwindow integration, affecting FINDFILE etc.
        This requires a patched version of DDEUtils; you'll need to run
        DDEU_Patch, which will patch v1.53, 1.54 and the unreleased 1.55.
        v1.56 (for RO4) has the necessary support; blame Stewart Brodie :-)
      * Taskwindow text clip rectangle bug fixed
      * Internationalisation (not in the 'Zap 1.40' build)

19-Sep-98
      * Copy cursor wrapped token bug fixed by Darren. (This slightly changes the
        behaviour when copy from end-of-line.)
      * 'Delete word' commands by Paul Moore added (as a temporary measure).
      * A number of miscellaneous bugfixes.
 
26-Sep-97
      * A large number of bugfixes over a period of time :|
      * 'Force renumber rate' option to minimise the renumber start and step
        figures.  This is a bit of a temporary measure, to help with the
        combination of large BASIC programs and multiple libraries.
      * Added the FINDFUNCTION command and the associated 'FIND' button which
        searches for references to function and procedure definitions, and the
        definitions of assembler labels.  This can be a very useful button.
        The FINDFUNCTION command uses a protocol which has been designed to work
        in all modes, but so far BASIC mode is the only client.

15-Aug-97
      * Added the 'Free click in keywords' option for those who don't like the
        default click behaviour being unusual in BASIC mode.  This allows
        ZapBASIC's behaviour when keywords are clicked on to be configured to be
        loke that of most other Zap modes.  The redraw of the cursor with this
        option on is not perfect and it is off by default.
      * Added the 'Allow long lines' option which permits lines to exceed the
        255 character limit imposed by BASIC.  This is to allow very long
        tokenised lines to be more easily edited; where detokenising a single 
        token can exceed the maximum length.  Attempts to save files with long
        lines will fail with error messages, directing the user to the
        problematic line.
      * Reorganised the 'Menus' file slightly to accommodate the options which
        are altered least frequently.

09-Aug-97
      * Disabled the changes connected with retokenising lines made on 28-Jul-97
        for users with Zap version 1.35 - as these were causing problems when
        MOVESEL (cV) was used - sorry.
     
08-Aug-97
      * The 'LineNumber' colour has been removed.  Line numbers in GOTO/GOSUB
        statements are now coloured the same colour as any line numbers in the
        left-hand margin.
      * The colour category has been reused to provide a colour for function and
        procedure names.  Colouring these the same as the PROC/DEFPROC that
        preceded it proved not to be universally popular.
     
05-Aug-97
      * The ASSEMBLE instruction now disassembles 'Undefined instruction's
        as DCDs.
     
28-Jul-97
      * Insertions and deletions which take place on a single line have been
        recoded.  These now finish by retokenising the line.  Insertions are made
        as though they are being typed, so that, for example, pasting a REM into
        the start of a line now detokenises the rest of the line before
        commenting it out.  Also, it is no longer possible to exceed the limit
        to the length of BASIC lines by pasting in code.
        There are still some unusual artefacts present: in a top-bit-set
        character is pasted outside a string, then it is taken to be a token, and
        if a tokenised command is pasted into a string or a REMark then the top-
        bit-set character-equivalent is inserted.  The retokenisation of the line
        after a paste can have some unusual effects.  If tokenisation elsewhere
        on the line is affected then undoing the change may position the cursor
        in an counter-intuitive manner.  Also, if the selected area's tokenisation
        changes, the size of the selection is not adjusted accordingly.
     
26-Jul-97
      * '!Edit tab' mode now searches backwards through the file to find a
        line long enough to provide it with a guide if the previous line
        is inadequate for this purpose.  If no such line is found the
        default tab setting of 8 columns is used.
     
23-Jul-97
      * Bugs in colouring of REPEAT command cured.  This can now be followed by
        correctly-coloured *commands.
     
21-Jul-97
      * Minor changes mainly affecting the colouring of crunched BASIC assembler.
        OPTpass and DCDconst are now coloured correctly.
      * REMarks when used in assembler to start comments now no longer adversely
        affect the colouring of preceding instructions.
     
19-Jul-97
      * Added two new buttons and four new commands designed to allow sections of
        BASIC code to be easily commented out with REMarks.
     
17-Jul-97
      * Colouring of DEFs and assembler comments had been recently broken.
      * Zap now makes some attempt to load files with appended data and corrupt
        BASIC files.  Because it can't cope well with redrawing arbitrary data
        sequences, any appended DATA is truncated, and corrupt files are loaded
        only up to the point of serious corruption.  There are three new warnings:
      * 'This BASIC file has a missing terminator' - which means that the file
        should be saved from Zap before any attempt is made to run it.
      * 'Appended data truncated - beware of data loss' - given when a BASIC
         program with appended data is loaded into Zap.  Take heed of this
         warning: saving the file will lose the truncated data.
      * 'BASIC file seriously corrupted - truncated on loading' - Zap has
        attempted to load a seriously corrupted BASIC file, but it failed to
        complete the process.  Take heed of this warning: saving the file
        will lose data.
        These changes mean that it is possible to view files like 'DEARCHIVE/BAS'
        in BASIC mode.  They may also help with recovering parts of corrupted
        BASIC files.  However, they can be potentially dangerous - be warned.
        It is still possible to view the entire files by loading them into text
        mode (usually by ctrl-dragging them to the icon-bar) and then switching
        to BASIC mode.
      * New separate colour categories for:
         1: PROC and FN - these now colour the keywords and their names;
         2: DEFPROC, DEFFN and ENDPROC;
         3: FOR, NEXT, REPEAT, UNTIL, WHILE and ENDWHILE;
         4: IF THEN ELSE ENDIF;
         5: CASE WHEN OF OTHERWISE ENDCASE.
        Some of the old categories (e.g. those allowing separate colouring of the
        names of PROCs, FNs, DEFPROCs and DEFFNs) have been scrapped to make some
        room for these.  It is recognised that these colours will be missed by
        some people - sorry.
      * Improved colouring of some sequences in compressed assembler.  Notably,
        the colouring of ORR0,0,#1 is improved, as is that of MOVPC,R14.
      * Improved colouring of the & directive in compressed sequences.
      * Colouring of DEFPROCx*FX15 improved.  It is still coloured incorrectly
        if the procedure has parameters and the BASIC tokeniser isn't aware
        of the * command in this type of sequence (i.e. it'll try to tokenise any
        keywords it finds if you try to edit such a sequence), so it's best to
        avoid using them.
      * Some improvements to allow (hopefully) better detection of sequences
        which look like assembler in ordinary BASIC - e.g. SWI += 1.
     
15-Jul-97
      * Two bugfixes affecting which characters terminate assembler labels.

12-Jul-97
      * Structures such as MOVEQ in assembler (i.e. ones which contain BASIC
        tokens) are now coloured correctly when split across line ends.
      * The historical problem involving inserting code at a point just beyond
        the last line of a BASIC program no longer results in the first three
        letters of the inserted text being 'consumed' by the line number.

10-Jul-97
      * Bugfix for last version - colour wrapping had been quite broken in this.

08-Jul-97
      * Fed lots of files through a BASIC compression program and then viewed
        the results.  As a result of this a number of colouring problems were
        identified.  Some of these have been fixed:
        * The colouring of DEFs (as in DEFPROCs) had a tendency to penetrate
          following BASIC if there were no spaces colons or brackets around.
        * In 'IFA=0THENE=0' the THEN was not considered to terminate the number
          perfectly.  This meant the E was being coloured as a number (it was
          treating it as an exponent which zero was being raised to).
        * Ampersands are now considered to terminate assembler comments.  This
          means '.label&&0' is now being coloured properly.
        * Directives (e.g. OPT and ALIGN) no longer need trailing spaces for them
          to be coloured correctly.  This currently has the side effect that
          BASIC variables with the same names are coloured incorrectly if they
          are followed by an exclamation point (e.g. DCD!0=0).
      * Extended the BASIC_CHECKBUF command.  This now generates throwback and
        has its own button devoted to it.
      * Button bar redesigned so that more options are available from it.

28-Jun-97
      * /Very/ primitive support for ZapSpell added.  Only the contents of
        comments and REM statements are checked.
      * Bracket matching added to Taskwindow mode.
      * Work on the BASIC_CHECKBUF command started.

23-Jun-97
      * Problems with clicking in a BAISC window affecting the selection in
        another window fixed.

16-Jun-97
      * Problems with ALIGN not being coloured properly resolved.

05-Jun-97
      * Problem with the colours in Taskwindow mode not being saved fixed.

01-Jun-97
      * Internal confusion over some of the buttons' flags sorted out.

31-May-97
      * A change to the selection constraints which removes a bug which meant
        that the line number on the first line of the program could be selected
        and copied into the body of the program.

28-May-97
      * Minor tweaks to the colouring of conditional instructions with the 'P'
        extension in assembler, such as TEQP.

20-May-97
      * A severe problem with variables starting with the '`' symbol fixed.

16-May-97
      * '=', when used as a function terminator was sometimes colouring any
        subsequent string as a number.
      * A bug meant that lines like 'equd$ = ""' in BASIC were being coloured as
        assembler directives.

13-May-97
      * Removed hard-wired aliasing of the Taskwindow command within ZapBASIC.
        This was done in part to cooperate with the different alias required by
        Darren Salt's new taskwindow running program.
      * Selection constraints added along similar lines to those originally
        envisaged by Darren Salt.

12-May-97
      * Cured bug affecting command completion after colons in lines.
      * Cured old selection bug triggered by dragging alternate edges of the
        selection with ADJUST in BASIC mode.

v1.33 - (27-Apr-1997)
      * Support for buttons and window-wrap added.
      * Bracket matching.
      * Extensive colouring added.
      * BASIC assembler colouring.

A 'warts and all' history follows...

			BASIC changes since v1.32
			~~~~~~~~~~~~~~~~~~~~~~~~~
      * BASIC colouring rewritten to colour assembler comments correctly.
	- A comment is taken as anything beginning with a ';' unless there
	  are no colons (outside strings) since the last PRINT, SYS OR VDU
	  statement, or  anything after a '\'.  This is much prettier and
	  offers visual feedback about when comments are (often incorrectly)
	  terminated by ':' characters.
      * The corresponding changes have also been made to the internal
	  tokenisation routines, so the following issue has been resolved:
	  In the line:
	  MOV PC,R14 ; REM return : ] : PRINT "the end" : END
	  (which is now considered to be a comment *only* between the
	  semi-colon and the colon :-), Zap used to tokenise the REM
	  (before the tokenisation routines knew about assembler comments)
	  and thus refused to tokenise the subsequent PRINT.  Now,
	  everything correctly follows the syntax of the BASIC assembler.
      * Added a new BASIC colour for the numbers of GOTO statements.
      * Added two new BASIC colours for the names of functions and
	  procedures.
      * Added colour categories for *commands, DATA statements, two colours
	  for numbers (one for hex) one colour for each type of bracket and
	  four colour categories of punctuation.
      * Added window wrap to the BASIC mode.  There were some complications
	  in that BASIC does not like widths smaller than four, so a new
	  version of ZapButtons was produced.
      * Added routines designed to make window update much smoother when
	  using window wrap with a selected region.
      * Added buttons to the BASIC mode.  This works well...
      * Added a colour to BASIC mode for assembler labels.
      * More changes to the tokenisation in BASIC's assembler comments.
	  In the sequence [ .label ; REM xxx : ] if this had been tokenised
	  by a previous version of Zap then the REM would have been
	  tokenised.  I was trying to preserve the appearance of this in the
	  new version, but this has proved to be an inconsistent strategy.
	  Now, old tokenised statements in assembler comments are reduced to
	  their top-bit-set tokenised equivalents.
      * Still more changes to BASIC tokenisation of assembly comments.
	  Top-bit set characters are now never expanded into BASIC
	  commands in these.
      * Detokenisation has been split into two sections internally: one
	  section is used by the colouring and redraw routines and the
	  other does 'only what is absolutely necessary' to actually
	  detokenise.  This means improved colouring has a minimal impact
	  on the speed of detokenising in general (as used by the search
	  routines for example).
      * The hourglass is now active during the execution of the RENUMBER
	  command from BASIC.
      * Thanks to some bug reports (thanks) 'Drop into BASIC' and 'RUN' have
	  now started working again. Also the colours in BASIC mode can now
	  be successfully saved.  The bits used to store the buttons status
	  no-longer overwrite the bottom 5 bits of the mode's width.
      * Some complicated changes to the BASIC tokenisation.  The old approach
	  had some fundamental flaws, so it all got rewritten (making three
	  times in two weeks so far...) The apparent changes are:
	   - Old tokenised expressions in assembler comments are preserved
	     so their appearance is now preserved :-)
	   - Top-bit set characters inserted into assembler comments are now
	     expanded into tokenised BASIC :-(
	   - Low-level calculations of tokenised line-lengths are now
	     working properly (this was the *big* problem).
      * Assembler colouring added to BASIC mode.  Issues here are:
	  - MOVE, AND, EOR and OR are still being tokenised 'underneath' the
	    new colouring.  This means clicking on the middle of MOVEQ, ORR,
	    AND, and EOR commands behaves in an counter-intuitive manner.
	  - The syntax checking of conditions does not operate if this
	    tokenisation is occurring.
	  - Most structures do not require spaces after them and may run
	    into any following parameters.  Some however need to be
	    separated by a space.  The colouring does not perfectly mirror
	    the syntax of the BASIC assembler in this respect.
	  - No special colour for immediate constants.  This may not happen.
      * Improvements to the BASIC assembly colouring.
	  - Instructions now wrap properly around the window edges.
	  - Tree search algorithm for decoding assembly instructions
	    rewritten, so it is now blindingly fast.  This has allowed
	    the entire co-processor and FP instruction sets to be added with
	    no noticeable speed penalty.
	  - Added full parsing of the IA/IB/DA/DB/FD/FA/ED/EA stack types.
      * Added simple bracket matching to the BASIC mode.  This only deals
	  with code on a single line so [... ...] assembler structures split
	  over a number of lines will not cause the code to fire.  The delay
	  is not configurable at the moment.
      * Included a 'Don't colour code' option in the BASIC menu to turn
	  assembler colouring off if for some reason it is not required.
      * Added lots of code to be more 'fussy' about how the end of
	  instructions should be in BASIC assembler.
      * Added code to deal with a number of cases where assembler-like
	  sequences occur in normal BASIC code.  This section will probably
	  never be perfect, but catching 99% of cases should be practical...
      * Added support of colouring of registers in the BASIC assembler.
	  The APCS register names are supported, as well as the floating
	  point and co-processor register sets.  APCS register name
	  colouring can be turned off if desired.
      * Added support for colouring shifts in the BASIC assembler (LSL etc).
      * A bug in the expansion of tokenised BASIC code has been fixed.  If
	  an abbreviation of a command whose tokenisation was dependant on
	  there being no following alphanumeric character (e.g. QUIT or
	  ENDPROC), and there was such a following alphanumeric present, then
	  the cursor used to be updated as though tokenisation had occurred.
      * Extensive revamp of the floating point/co-processor instructions
	  in the light of lots of helpful information from Darren Salt.
      * Added colours for LDR/STR, LDM/STM and Branches to the BASIC mode.
      * Modified the routine that performs insertions.  These now check to
	  see if a multiple-line insertion ends in the middle of a line, and
	  if so it inserts the section on a separate line and appends a
	  carriage-return to the end of the inserted region.  This sorts out
	  a number of problems, including cases where the insertion would
	  previously have corrupted the BASIC program or lead to the
	  'cln_backwards' error.  The extra carriage-return does however
	  mean that the insertions may behave in a slightly counter-intuitive
	  manner.
      * ZapBASIC now resets the Taskwindow alias when it quits to point to
	  ZapCode:Taskwindow (if <ZapCode$Path> exists) or
	  <Zap$Dir>.Code.Taskwindow if it doesn't (see recent history...).
      * Selection constraints have been applied to the BASIC mode.  These
	  carefully control the areas which are allowed to be selected.
	  The main benefit the user sees is that it is no longer possible to
	  copy line numbers into the body of the text.


			Taskwindow changes since v1.32
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      * Improved keyboard handling when using the QUOTE command (cQ).
	- Routines designed to expand quoted function key presses in
	  taskwindows no longer fire when other unusual control combinations
	  are pressed.  This means (amongst other things) that 'QUOTE'ing c@
	  now correctly produces a character zero, and that 'QUOTE'ing c_,
	  c[, c], c\, and c^ functions as expected.
	- 'QUOTE'ing function keys when not in a taskwindow still produces
	  short encoded strings, though.
      * Primitive taskwindow colouring implemented.  There are currently
	  colours for any lines starting with > or *.  There are a number
	  of cases where taskwindow colouring is inappropriate.  If using
	  unusual languages, prompts or defining text windows then the
	  colours may be better off set to the default foreground colour.
      * Now c@ (sc2) works correctly in taskwindows and passes the correct
	  control code to the LineEditor module.  Binding it to "CHAR 0" in
	  the default keymap would also make good sense.  On RPCs c@ is
	  not the same as sc2 (it's sc') whose Zap keynumber I don't
	  know at the moment...


8.0 Authors
~~~~~~~~~~~

ZapBASIC was written by Dominic Symes. Tim Tyler implemented most of the
above changes to make v1.33. Since then it has been maintained by Darren
Salt.


9.0 Contact
~~~~~~~~~~~

If you have any comments or bug reports concerning BASIC or BASTXT modes,
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/>.
