*****************************************************************************
* >!Help file for !Zap version 0.70					    *
* All code is copyright Dominic Symes 1992. Please read 'Copyright' file.   *
* NB This program needs the COLOURS module to run. It is in !System.Modules *
*    on Acorns Application disc 1. If in doubt, double click on !System.    *
*****************************************************************************

This is the first release of the text editor !Zap.

Main features:	* Display may be in text, byte or disassembly format
		* All key short cuts are user redefinable
		* Automatic updating line numbers & file addresses
		* Full (unix style) wildcard search with your own definable
		  macros and search 'throwback' buffers
		* Proper unix tabs and true scrollbar operation
		* Full undo on all operations
		* COPY key causes standard cursor editing
		* All features tested on RISCOS 2 and RISCOS3
		* Fast redraw
		* Full printer driver interface and quick print output
		* Any number of markers on each file, and a facility for
		  following branches in disassembly mode
		* Search as you type
		* Learns keys sequences
		* Emacs style Yank (Cut & Paste) and !Edit style move and
		  copy implemented.
		* C throwback supported
		* Reads disc sectors/tracks

In production:	* Proper BASIC editor 'extension' mode for editing basic
		  programs.
		* Fully documented interface so that YOU can write an
		  extension mode for zap
		* C programmers extension mode with bracket matching.


Keys and commands
-----------------

Each key has an associated command as given in the 'Keys' file. On startup,
Zap reads this file to create the current key bindings. Thus by editing
the keys file you may change the action of any key to your preference.
Keys not mentioned in the 'keys' file are passed on (eg F12).
A summary of the default setup is given below: (s=shift c=ctrl)

Command:	Default key:	Action:

DELETE		Delete		Delete last character
DELETENEXT	sDelete		Delete next character
TOGGLEINSERT	Insert		Toggle insert and overwrite modes
				(shows o in title)
COPY		Copy		Initiates copy mode  la Basic Editor.
				Note that you may copy from one window to
				another by selecting on the other.
SELREGION	cCopy		Starts selection of a region via cursor keys.
				Press Escape to end the selection.
DUMPFILE	scCopy		Produce text image of this file.
ESCAPE		Escape	   	Stops copy modes/selection modes/search
				as you type mode/yank mode
TAB		Tab		Inserts a variety of tabs - see tab menu.
FASTUNDO	<-|		See cH
QUICKPRINT	Print		Send file directly to printer
PRINTFILE	sPrint		Print file through printer driver
OPENPRINTER	cPrint		Open printer: filer window
CLOSEPRINTER	scPrint		Close printer: filer window

Cursor keys:

LEFT		Left	        Moves 1 left / goto last mark in code mode
RIGHT		Right		Moves 1 right / jumps to address in code mode
DOWN		Down		Move 1 line down
UP		Up		Move 1 line up
SLEFT		sLeft  		Move back one word
SRIGHT		sRight		Move forward one word
SDOWN		sDown/PageDown	Move down a page
SUP		sUp/PageUp    	Move up a page
CLEFT		cLeft		Move to start of logical line
CRIGHT		cRight		Move to end of logical line
CDOWN		cDown		Move to end of text (and leave marker)
CUP		cUp		Move to start of text (and leave marker)
SCLEFT		scLeft		Move to the left without moving cursor
SCRIGHT		scRight		Move to the right without moving cursor
SCDOWN		scDown		Move down without moving cursor
SCUP		scUp		Move up without moving cursor

Function keys:

EXECUTE		F1		Execute currently learnt key sequence (see scL)
HEXASCII	F2		Toggles hex entry mode when byte/word editing
				(h in title)
SAVE		F3		Brings up save box. You may change filetype
				etc by moving to the relevant box. Or click
				the menu button to bring up file type menu.
SEARCHCUR	F4		Brings up Search by Goto box. (See later)
GOTO		F5 		Brings up goto line box
TOGGLEMARK	F6 		Inserts marker in text/deletes marker
SEARCHBUF	F7		Brings up Search to buffer box. (See later)
FULLUNDO	F8		Full undo (takes slowest path in undo tree)
REDO		F9		Redo (undo last undo whether full or fast)
DELLINE		F10		Delete current line

SPLITLINE	sF1		Split line (Inserts a return)
REPLACE		sF4		Brings up search and replace window.
WORDWRAP	sF5		Toggle wordwrap mode (w in title)
LASTMARK	sF6		Previous mark (eg after ctrl-down by mistake)
NEXTMATCH	sF7		Next match (after an F4 or F7)
DELTOSTART	sF10		Delete to start of line

JOINLINE	cF1		Join line (delete next return)
SWAPWINDOW	cF2		Swap window (after using new view)
NEWVIEW		cF4		New view (open new window on this file)
HELP		cF5		Brings up help text
NEXTMARK	cF6		Next mark (see sF6)	
LASTMATCH	cF7		Previous match (see sF7)
DELTOEND	cF10		Delete to end of line

MODE0		scF1		Text mode  (display in standard text format)
MODE1		scF2		Byte mode  (display in hex bytes)
MODE2		scF3		Word mode  (display in hex words)
MODE3		scF4		Ascii mode (display in characters)
MODE4		scF5		Code mode  (display in disassembled code)
MODE5		scF6		extension mode - 5
MODE6		scF7		extension mode - 6
MODE7		scF8		extension mode - 7
MODE8		scF9		extension mode - 8
MODE9		scF10		extension mode - 9

Ctrl letters:

CLEFT		cA		Start of line   - emacs compatibility
LEFT		cB		Back a char     - emacs compatibility
COPYSEL		cC 		Copy selected region to current position
DELETENEXT	cD		Delete next char- emacs compatibility
CRIGHT		cE		Line end	- emacs compatibility
RIGHT		cF		Forward a char  - emacs compatibility		
CANCEL		cG		Cancel search 'as you type' and return to
				start. Also cancel any yank operations.
FASTUNDO	cH <-|		Fast undo (takes fastest route in tree)
INDIRECT	cI		Indirect (move to the address given by word
				at cursor)
DELTOEND	cK		Kill line	- emacs compatibility
LEARN		cL		Learn key sequence (see later on)
RETURN		cM		Inserts a return character
DOWN		cN		Next line	- emacs compatibility
UP		cP		Previous line	- emacs compatibility
SEARCHBACK	cR		Reverse search 'as you type'
SEARCHFORWARD	cS		Search 'as you type' forwards
SELECTBUFFER	cT		Select entire buffer
MOVESEL		cV		Move selected region to current position
CUT		cX		Cut/Delete selected region
YANK		cY		Paste/Yank selected region
CLEARSEL	cZ		Clear selection

ADDRESSES	scA		Addresses shown at line start
INSERTDATE	scD		Insert current date (format is given in the
				file 'keys')
NEXTTRACK	scI		Move forward one track
LASTSECTOR	scJ		Move back one sector
NEXTSECTOR	scK		Move forward one sector
LOGICAL		scL		Logical line numbers shown at line start
LASTTRACK	scM		Move back one track
NOLINENOS	scN		Removes line numbers/addresses
TOGGLEHEX	scO		Line numbers shown in hex/decimal
PHYSICAL	scP		Physical line numbers shown at line start
SWAPCHARS	scQ		Swap next two characters around
READONLY	scR		Toggle read only state (r in title)
SWAPCASE	scS		Swap case of next character/selected region
INSERTTIME	scT		Insert current time (format is given in the
				file 'keys')

Letters:
--------

In text mode letters are inserted as usual.
In byte mode letters are inserted as usual unless in hex mode (F2) when
 the keys a-f,A-F,0-9 enter hex digits
In word mode + hex mode keys a-f,A-F,0-9 enter hex digits

The window title
----------------

Title heading characters:
 *		File altered since last saved
 R		Read only and fixed as read only
 r		Read only but can be toggled to read/write by cR
 u		Undo supported by this file
 o		Overwrite mode active (toggle via Insert key)
 h		Hex entry mode active for Byte/Word (toggle via F2)
 w		Wordwrap mode active (toggle via sF5)

Loading/saving files:
---------------------

(a) Double click on a text file to load it.
(b) Hold down left shift and double click on any file typed file to load it.
(c) Drag the file onto the zap icon to load it.
(d) Drag file onto a zap window to insert it at cursor.
(e) Hold down shift and drag file onto a zap window to insert its name.
(f) Ram loads/saves are fully supported and you may save files into themselves.

SEARCH AND REPLACE
==================

1) The Search window
--------------------

The search window can be broght up by F4/F7/the 'Zap' menu on a file. 

The first column selects whether you wish to search for a string, instruction
or word (4 bytes). In the first two cases enter the string to match. In the
third case enter an expression evaluating to a number to search for.

The second column selects where the search should start and the direction of
the search. You may start at the start of text or forwards/backwards from the
current cursor position.

The third column selects the output. If you choose cursor output (F4) then
the cursor will be moved to the first match and subsequent matches may be
got by sF7 and scF7 as in the Basic Editor. If you choose 'to buffer'
then all matches are placed in a new (text) file. Double clicking on entries
in this text file cause the cursor to be moved to the corresponding match.

2) Wildcards, macros and case sensitivity
-----------------------------------------

In order that the user may have any search syntax he/she chooses, I have
adopted the following approach:

a) All wildcards/commands begin with a '/' as listed below.
b) The user may define up to 16 macros (aliases) in terms of these
   commands.
c) When the search string is entered, all the users macros are substituted
   before the search takes place.

The macros may be examined and altered by clicking on the 'Show Macros'
button. The default macro definitions are stored in the 'Keys' file and may
be altered there. Whether the search is case sensitive or not can be
controlled by a radio icon in the Macro definitions window.

For example, I have * as a standard macro for \#\*. Thus if I typed in
a*b, the string would be converted to a\#\*b. However a\*b would remain
as a\*b as the * follows a \ and is thus treated as a command.

Full details of the wildcard commands are given below:

x (any char)	Matches 'x' (according to case sensitivity)
\x		Where x is not one of the below matches 'x' case sensitively

\( and \)	Act as brackets for bracketing expressions.
\{ and \}	Act as the normal brackets above, but may be referred
		to in the replace string during a search and replace.

\#	Matches any character. Eg a\#d matches 'and','aad' but not 'ad'.
\*	Matches any number of the previous expression. Eg fo\* matches
	'f','fo','foo' etc. and \(and\)\* matches '','and','andand' etc
\|	Matches one expression OR another. Eg hello\|goodbye\|fred.
	Eg \(a\|b\)\* matches 'abababa','abbba' etc.
\[..]	Introduces a range of characters to match. Eg \[a-zA-Z%] matches
	any letter or a '%'. If a '^' is given after the opening bracket then
	it acts as a NOT. Thus \[^abc] matches any character except a,b,c.

\<	Matches line start (and file start) (useful in code mode)
\>	Matches line end
\C	Turns on case sensitivity for the following string only.
	Eg \CFred\|Bill matches Fred case sensitively but not Bill.
\c	As above but turns off case sensitivity.
\\	Matches a '\'

\xxx	Where x is any decimal digit matches that number
	Eg '\0alf' matches 0,'alf' and \233 matches byte 233
	Please note that \999 matches byte 99 followed by '9' as 999>255.
\&xx	As above but matches the hex byte xx when x are valid hex chars.

In most cases you will wish to macro '|' as being '\|' and '(' as '\(' etc.

Examples (in code mode):
------------------------

SWI	    		will match any SWI
LDR\|STR		will match any load or store instruction
R6			will match any instruction using R6
BL\#\*&0000A95C		will match any call to &0000A95C

3) Interrupting the search
--------------------------

The search will be MUCH faster if you give a definite first character to
start with. Eg 'a\(nd\|pple\)' will be a lot faster than 'and\|apple'.
If the search takes longer than 1/3 second, then an hourglass will come
up displaying the position in the file as a percentage underneath.
You may stop the search by pressing escape, and the partial results will
be displayed if you are using 'Search to buffer'.

I think the above should satisfy most persons needs. Please tell me of any
bugs/improvements.

4) Search and Replace
---------------------

A search and replace is activated by sF4 or the File menu. You may
select the search start and direction as above. You may also select
whether the replace is to be selective or global.

The format of the search string is described above. The replace string
has the following format:

\xxx	replace with the decimal byte xxx as above.
\&xx	replace with the hex byte xx as above.
\x	(for any other character x) replace with a 'x' (eg '\\' -> '\')

&n	(where n is 1-9) means replace with the n'th \{,\} expression in the
	search string.
	Eg If the search string is 'a\{\#\}d'
	 and the replace string is 'b&1e'
	Then 'and' will be replaced by 'bne' and 'aad' by 'bae' etc
&&	replace with an '&'


5) Learning key sequences
-------------------------

To learn a new key sequence press cL and then type the sequence. A beep will
be sounded after each logged character to remind you that these key presses
are being buffered. Press cL again to end the sequence. NB ESCAPE will NOT
end the sequence so that escape can be used as part of the sequence.
Pressing F1 will EXECUTE the given sequence.

Examples:

cL cLeft - > Down cL		; inserts -> at line start when F1 pressed
cL cS C A T ESCAPE S cL		; searches for next occurrence of CAT and
				  adds S on the end to get CATS

6) Search as you type
---------------------

Search as you type is activated by pressing cS or cR. The following characters
typed by you are treated as a search string. The cursor is moved to the end
of the next matching search from where you started. You may use 'delete'
to remove characters from the search string. If there is no match then a
beep will sound. This continues until you press a non character key (eg
Escape or a cursor key) in which case the search will halt at the current
position. Alternatively, pressing cG will cause the search to be cancelled
and the cursor returned to its initial position.

7) Miscellaneous
----------------

If the 'Auto delete' option on the Options menu is set then when the last
window on a file is closed, the file is deleted as in !Edit. If the option
is not set then the file remains in memory and new windows can be opened
on it via Create.New view menu option as in !Impression.

If the 'Undo' option on the Options menu is unset then newly created files
do not have full undo storage, and operations cannot be undone (other than
by yank). This saves a little memory.

=====================================================================

I hope you find Zap a useful program.

Dominic Symes
September 1992
