 ____________________				       ____________________
  ##| ##|  ######|  ##|	#####| 
		      ##| ##|  ##|	##|	##|##|
		      ##| ##|  ##|	##|	##| ##|
		      ######|  #####|	##|	#####|
		      ##|##|  ##|	##|	##|
		      ##| ##|  ##|	##|	##|
 ____________________ ##| ##|  ######|  #####|  ##| _______________________
       		  
 
   ZapSAsm				       Version 1.04 (21 May 1995)
 
       This application is  1995 James Freeman. All Rights Reserved.

		  It is FREEWARE. Use is at your own risk.
	     Please read the conditions at the end of this file.

 
  G E N E R A L	  I N F O R M A T I O N
 
	     Sattingers Law: It works better if you plug it in.
  Arthur Bloch

 Program:  ZapSAsm

 Purpose:  Extension mode and utilities for Zap.

 Requires: Tested on RISC OS 3.1x and later.
	    (Read: it may work on RISC OS 2, but then again...)
	   Zap 1.23 or later.
	    (ZapSAsm will function with Zap 1.20 but, because of a little
	    bug in Zap, two of the colours will be incorrectly rendered.)

 Features:  Module takes up only 4980 bytes.
	    Hand-written in ARM code.
	    Text-based colour extension mode for SAsm source files.
	    Several mode-independent Zap commands.
	    Links Zap with WordWorks (not included :-).


 
  W H O ?   W H A T ?	W H E N ?   H O W ?
 
	   It aint what a man dont know that makes him a fool,
		    but what he does know that aint so.
  Josh Billings

 This program was written in ARM using Zap 125 and SAsm 160. My thanks
 to Dominic Symes (now, remind me, whos that bloke again and whats he
 written that everyones fussing over?) and David Radford for putting
 these programs into the public domain.  SAsm is shareware and written
 by David Holden.

 I give no guarantee that this program will work correctly on all machines
 and all configurations - but it works for me.  Take it or leave it.


 
  S U M M A R Y
 
		  Nothing is so useless as a general maxim.
  Thomas Macaulay

 This directory contains:

 !Help.*			       Help text and reader.
 DemoText			       Demonstration text.
 Impulse			       Impulse methods (text).
 ZapSAsm			       Extension module.

 So, youve seen a colour Acorn C mode on Zap.
 Oh, and a colour BASIC mode.
 And youve seen a colour Acorn Assembler mode.
 But have you seen a colour SAsm mode?  No?  Guess what this is.

 If youve got David Holdens excellent SAsm assembler, then this modes
 for you.  If you havent, then hold your horses - there are a few commands
 you might find useful instead, as well as support for CCs WordWorks.

 For installation instructions, go down right to the end of this section.


 THE EXTENSION MODE
 ==================

 The SAsm mode provides the following additional colours:

   Labels
    Definitions (ie. .labelname) - not references from (eg.) branches.

   Macros
    Both expanded macro and macro function calls are recognised.

   Immediates
    Only if preceded by hash (#).  This means that the enhanced second
    operand feature of SAsm (for CMP, MOV, TST and TEQ) is not
    recognised.  (The reason it isnt currently implemented is because it
    only applies to those four mnemonics; Ive already written the code for
    it, but it operates on all the second operands...)  In addition, the
    equates EQUB, EQUW, EQUD, EQUS, DCB, DCW, DCD, DB,
    DW, and DB are recognised as being followed by an immediate
    constant.

   Strings
    Anything within double quotation marks which isnt a comment.

   Comments
    Both ; (with checks, to allow #PRINT"blah";) and \ are supported.
    I do not recognise REM.  (You honestly dont use this for assembler
    do you?  Oh dearie me...  If anyone requests, Ill probably add it.)

   Directives
    And lines passed to BASIC (ie. lines which begin with a hash).

   Operands1
    Anything after the mnemonic which isnt an immediate, string, comment
    or displayed in the Operands2 colour.

   Operands2
    The following characters within the operand are displayed in this
    colour: [, ], {, }, (, ), !, ^, - and ,.

   Shifts
    Now, and as if you couldnt guess, the shifts (thats LSL, LSR,
    ASL, ASR, ROR and RRX in case you didnt realise) are displayed
    in this colour.

 Remember though: just because youve got so many *logical* colours doesnt
 mean they all have to be different *physical* colours.  Of course, if you
 like your source code looking like a rainbow, thats your decision :-)

 And another thing: SAsm should produce proper colours for SAsm source
 textfiles.  If you load non-SAsm sources, etc, you are likely to find that
 the colouring goes a bit awry.  Remember, it is expecting text in the
 correct syntax for SAsm.  (Oh really?)


 STILL TO BE IMPLEMENTED
 =======================

   Enhanced second operand detection for CMP/MOV/TEQ/TST.

   REM recognition.

   SWI name processing (#swion).

   Non-local labels allowed after colons.

   Multi-line features (very difficult!): {} comments, #end, #area.


 PROBLEMS / FUTURE PLANS
 =======================

   With lines longer than the width of the window, the part(s) which wrap
    round are not coloured correctly.

   Theres also a problem if the text goes right up to the right hand side
    of the window.


 OTHER FEATURES OF THE SASM MODE
 ===============================

 The following are entry points for the SAsm mode:

   The COMPILE and SAVEANDRUN entry points save the source file youre
    editing and run the file !!Make in the same directory as the source.
    (Hint: I use a TaskObey (&FD7) file which *REMOVEs any error files etc,
    then runs SAsm giving it the filename of the !Make file in the same
    directory - this second file is a textfile consisting of various
    directives (eg. #VERBOSE, #ERRFILE) and then a list of #INCLUDEs for
    my source files, constants files and function definition files.)

   The RUN and RUNANDQUIT entry points run the !!Make file without
    first saving the source.  (Provided for completeness because it was
    very easy to do .. I dont know what youd need it for though.)

BTW - the mode sets SAsm$Dir to the directory containing !!Make.

   The LISTFNS entry point searches for all uncommented expanded macros
    and macro function definitions.  It simply begins a search for the
    string \<\(\I\|\&20\)\*\(\&23\( \)\*\-sm\|\+DEF\( \)\*\+FN\).

 Given the way SAsm handles wildcarded source filenames, you will probably
 find the DECANDSAVE command (below) useful.  (I use it all the time.)


 COMMUNICATING WITH WORDWORKS
 ============================

 While Computer Concepts Impulse module is installed, the following
 features are available from ZapSAsm:

   The command WORDWORKS sends the Impulse method NewRegion together
    with the current selection (in Zap) to all Impulse tasks.  If you have
    Computer Concepts WordWorks application loaded, this message is
    recognised by it, and it will try to find the word/phrase in the
    dictionary/thesaurus.  If there is no selection in Zap, this command
    will have no effect.

   ZapSAsm supports the Impulse method Enter (sent by WordWorks), which
    enters the supplied text into the current window.  If there is a
    selection in Zap in the same *file* as the current window (but not
    necessarily the same window), the text replaces the selected text.

 Note that ZapSAsm is not intelligent, in the sense that it will not
 check your grammar!  That is to say - if you send enters to WordWorks,
 it will bring up a display on enter; if you then choose the alternative
 word insert from the thesaurus and replace it in your Zap document, it
 puts insert there - and not inserts.


 OTHER COMMANDS
 ==============

 The following are commands available from any mode:

   The INCVERSION command increments the version number of the current
    file.  In other words, if the leafname is Source5 then its changed
    to Source6.  This wraps round, so File9 becomes File0 (rather
    than File10).

   The INCANDSAVE command increments the version number of the current
    file and then saves it under the new filename.

   The DECVERSION command decrements the version number of the current
    file.  In other words, if the leafname is Source35 then its changed
    to Source34.  This wraps round, so File000 becomes File999.

   The DECANDSAVE command decrements the version number of the current
    file and then saves it under the new filename.

   The LOSECARET command removes the caret from Zap.

   The LISTLABELS command searches for uncommented labels in the current
    file.  It simply begins a search for the string \<\( \|\I\)\*.\.\.\*.

   The WOSCLI command sends its string parameter to OS_CLI (via
    Wimp_StartTask).  (Note that Zaps OSCLI command works differently;
    it sends the *commands output to a scrapfile, then opens a window on
    that file.  WOSCLI on the other hand just shows any vdu output in
    a regular non-multi-tasking Wimp command window.)



 INSTALLATION
 ============

 Copy the !ZapSAsm application into the !Zap.Modules directory, then
 restart Zap.

 
  P R O G R A M	  H I S T O R Y
 
	     The World Record holder for blowing a bugle whilst
	      riding a bike uphill dragging four hundredweight
	     of pig iron and holding his breath is buried at...
  Spike Milligan

 1.00 First version for Zap 120.
 1.01 A few bug fixes later.  It might just work :-)
 1.02 No, it most definitely wont :-(  And Im just doing a couple of bug
      fixes when I notice my text-wrapping problem (see above).  Aaargh!
      OK, its way from perfect, but itll have to suffice for a while.
 1.03 But it only sufficed for a very little while.  Fingers crossed...
 1.04 Another bug fixed after testing with Zap 1.27...
      FIRST RELEASE VERSION, emailed to Dom.


 
  L A S T   W O R D S
 
	   Die, my dear doctor? Thats the last thing I shall do.
  Lord Palmerston (Attrib)

   IMPORTANT legal notes: please read.  If you cannot comply with the
    following, please delete this software package immediately.
    
    (1) Definitions:
    'Package' means the 'ZapSAsm' module and all the files connected with
    this module.
    'The Author' means Mr James P Freeman.
    'Freeware' means freely distributable in the sense that no profit is
    made from the distribution of the package, and that the contents of the
    package remain the copyright of the relevant author(s).  The extent to
    which the contents are copyright The Author is given in section (2).
    
    (2) Extent:
    All files within this package are  copyright The Author.
    The exception(s) above is/are subject to the same distribution
    conditions unless stated otherwise here or elsewhere: in other words,
    it/they should be distributed alongside the The Author's files.
    
    (3) Distribution conditions:
    This package is Freeware.  You may give a copy to anyone but there must
    be no charge.  For so-called 'Public Domain' and 'Shareware' libraries,
    a small fee for the cost of discs, postage and administration is
    allowed, provided that the cost of the disc upon which this package is
    included is NOT MORE THAN UK175 for an 800K disc, or 250 for a
    1600K disc.  This package must be distributed in a COMPLETE and
    UNALTERED state.  Distribution on a magazine disc or other than as
    described here may only be undertaken with The Author's express advance
    written permission.
    
    (3a) Special distribution conditions:
    Although this package may be copied alone subject to the above terms,
    it is specifically designed to be internal to Dominic Symes' Zap
    editor.  Where it is supplied with Zap, that application's distribution
    conditions apply and section (3) should be construed so as to accord
    with those conditions.  If any part of section (3) is inconsistent with
    those conditions, the latter prevail.
    
    (4) Other conditions:
    THIS PACKAGE IS SUPPLIED 'AS IS'.  USE IS ENTIRELY AT THE USER'S OWN
    RISK.  It carries no warranty, express or implied.  No guarantee is
    given of even the implied terms of satisfactory quality or suitability
    for purpose.  The Author accepts no responsibility whatsoever for this
    package and under no circumstances will be liable, in negligence or
    otherwise, for any damage (whether physical or economic), including but
    not restricted to direct, incidental and consequential loss, arising
    through, or in any way connected with, the use or misuse of this
    package or any files or routines contained therein - even if The Author
    has been advised of the possibility of such loss.  The Author reserves
    the right to amend this notice and/or alter the distribution conditions
    of this software package at any time.
    

   PLEASE NOTE THAT THIS PROGRAM IS NOT PUBLIC DOMAIN.

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


 
  E R R A T U M
 
		  This slip has been inserted by mistake.
  Alisdair Gray
