ZapBasAsm help file       for ZapBasAsm v.2.06
 Carl Hetherington 1997
------------------------

ZapBasAsm is an extension module for the Freeware text editor 'Zap'.  It
is intended for programmers who write assembler code for the built-in BASIC.

Its main feature is that it provides syntax-colouring of assembler within
BASIC programs.  Based on Zap's own BASTXT mode, it detokenises normal BASIC
files on loading and then colours the whole file as if it were assembly. 
Whereas this can give some rather strange colours to any actual BASIC within
these files, it gives all mnemonics, registers, constants etc. different
colours.  This can have a surprisingly beneficial effect on source-code
readability.

In addition to this the module provides a few handy Zap commands which can be
bound to certain keypresses and in certain cases called from Zap menus.  In
the current version these are:

BASM_LABELLIST		gives a list of labels defined within a file
BASM_MULTIPLE		checks for multiple definitions of labels
BASM_NUMBERLABEL	automatically numbers labels consecutively
BASM_INSERTPREFIX	completes label names

More details of these commands are given later in this file.



Installation
------------

To install !ZapBasAsm, you will need to do the following:

1.	Open the !Zap directory by holding down shift and double-clicking on
the !Zap icon in its filer window.

2.	Open the Modules directory within !Zap.

3.	Copy !ZapBasAsm into this directory.

4.	Quit !Zap if its already loaded, and reload it.

Once this is done there is only one further consideration to make.  For the
mode to work properly any BASIC files that you want to edit with BasAsm must
be loaded in by either the BASTXT or BasAsm modes.  You do not need to worry
about this unless you have Zap set up to use the BASIC mode by default for
BASIC files.  If you do have this setup, you will need to do one of the
following:

1.  Set up Zap to load BASTXT or BasAsm for all BASIC files. If you load into
BASTXT you can simply select BasAsm from the Mode menu after the file has
loaded.

2.  Set up Zap to load BasAsm for all your BASIC files that contain assembly. 
This is the best solution but as you can guess, the problem is telling Zap
how to recognise BASIC assembler files.  One way is to put all your assembler
files into a directory called, for example, 's' and then to alter Zap's
configuration to load these particular files into BasAsm.

If you don't get this bit right you will find that when selecting BasAsm the
file will turn into a complete mess!



Syntax colouring
----------------

Once you have installed ZapBasAsm it will colour assembler sections
automatically whenever it is selected.  You may want the BasAsm mode to be
selected by default for some or all BASIC files; this is discussed later. 
Otherwise you will need to load BASIC files into the BASTXT mode and then
select ZapBasAsm from the Mode.Load mode menu.

The colours BasAsm mode uses may be configured. If you are unsure of how to 
do this, read the !Help file that comes with Zap.


Commands provided by ZapBasAsm
------------------------------

As mentioned above, ZapBasAsm provides four new Zap commands.


BASM_LABELLIST

This is the simplest of the three.  When called it simply calls the Zap
search code with a search string that (hopefully) finds just label
definitions.  These are sent to a throwback window for your perusal.
This option can be selected from the Mode->BasAsm menu.


BASM_MULTIPLE

This command is designed to find labels that have been defined more than once
within a particular file.  Multiple definitions can give rise to all manner
of strange errors and its worth calling this function if you have a strange
bug that you can't fix.  If any multiple definitions are found they are
listed in a throwback window; if labels are defined more than twice they
appear more than once in the throwback window.  Note that in this version you
can't click on labels in the throwback window to move to them; you'll have to
use the standard search function once the multiple labels have been found.
This option can also be selected from the Mode->BasAsm menu.
Note that if you have labels longer than 256 characters in length then
strange things may happen.


BASM_NUMBERLABEL

This is a command which may or may not suit your way of working.  Because of
the fact that you can't have duplicate labels in the BASIC assembler, I tend
to give common labels, for example loop and skip, consecutive numbers to
differentiate them.  For example there might be a sequence of code

.routine_loop1
<code>
BNE routine_skip1
<code>
.routine_skip1
BLT routine_loop1
.routine_loop2
...etc

The only problem with this is knowing which numbers have been used and which
have not.  This is where this command comes in.  It is used when you have
typed the start of a new label, e.g.

.routine_loop

If you then call BASM_NUMBERLABEL, Zap will look through the file for any
other labels of the form routine_loopx, where x is a number, and will then
enter the next number up in the sequence.

This sounds rather complicated, but works quite well in practice.  With the
above example of code, I could then type

.routine_skip

and then call BASM_NUMBERLABEL and a 2 would be entered.
Note that using numbers of more than 3 digits with this command may cause
unpredictable behaviour.


BASM_INSERTPREFIX

This is another command that may or may not help you, depending on the style
of source code that you write.  Because of the way I avoid duplicate labels,
the label names can end up being rather long and tedious to type.  The
BASM_INSERTPREFIX command, when bound to a handy key, can help.  Basically it
tries to decide what the current subroutine that you are in is called, and
inserts this name at the cursor.  This can be useful in situations like:

.a_long_routine_name

. [*] a_long_routine_name_loop1
MOV r0,r0
B [*] a_long_routine_name_loop1

Executing BASM_INSERTPREFIX at the places marked by [*] inserts
'a_long_routine_name'.  The best way to understand it is to try it out; if it
doesn't work for you then just forget about it.





Notes
-----

ZapBasAsm is based on Zap's original BASTXT mode so you will need the
ZapBASIC module available for it to work.  This module is supplied with all
recent versions of Zap.

I can accept no liability for any loss of data that this module causes.





Credits and thanks
------------------

This module would not have been possible without the helpful inhabitants of
csa.programmer who responded to all my various requests for help.  In
particular I would like to thank:
	Tim Tyler	for helpful emails
	Guttorm Vik	for some source code and ideas
	Matthew Wilcox	for the source to his BasCat program
	Darren Salt	for good ideas
	Matthew Hambley	for releasing the source code to his ZapHTML
			module for me to, ahem, read ;-)
	Dominic Plunkett  for coding tips
	Chris Claydon	for bug reports
	Neil Walker	for more bug reports
	Dickon Hood	for encouragement, bug reports and suggestions
			
			
I'm sorry if I've forgotten anyone.  Of course we must thank Dominic Symes
and the other Zap developers for writing Zap in the first place!





Copyright
---------

The conditions of copying this program and its accompanying files are the
same as those of the main Zap application.

This software is supplied as is with no warranty express or implied about its
suitability for any particular purpose.

The ZapBasAsm module and all accompanying files are  Carl Hetherington 1997.



Getting in touch
----------------

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

I hope you find ZapBasAsm useful.
Carl Hetherington.
