*************************************************************************
* >Commands	List of valid Zap commands				*
*************************************************************************

This file gives details of all the commands defined in the modules Zap and
ZapBasic. It also gives extra details of the format commands must by typed in
in the keys file and at the command prompt (the Ctrl-Escape prompt). The file
E-Command gives technical details on how to write commands, and add tables of
commands. Also read section C of the file ReadMe. Command names are not case
sensitive when typed into the keys file.

Each command can take a parameter. The four types of parameter will be
indicated after the command in the following way:

	WIBBLE			Command Wibble takes no parameter
	WIBBLE <byte>		Command Wibble takes a single byte
	WIBBLE <word>		Command Wibble takes a word (4 bytes)
	WIBBLE <string>		Command Wibble takes a string argument
	
When you type the command into the keys file, or at the 'Command:' prompt,
you type the command name, followed by a space and its parameter. Byte and
word parameters must be preceded by an '&' if in hex. String parameters must
be in double quotes. Double quotes can be included in strings by doubling
them up. An error is given if the parameter you place after the command does
not match the type of the command. There are several special cases:

 1 If the command takes a string parameter, but you omit the string, then a
   minibuffer will be opened for you to type the string into when the command
   is executed. For example, see the command SEARCHFORWARD (Ctrl-S).
   
 2 If the command takes a byte or word parameter and you specify 'n' as the
   parameter, then the keynumber of the key you bind the command to is
   substituted for the 'n'. For example, see the command CHAR.
   
 3 The '*' command. This is used for duplicating a range keypad entries.
   The format of the command is *n where n is optional. 'n' is the key code
   (or first key code of a list) of the key (or keys) to copy.
   It is of the form &yy0xxx where yy is the keymap number and xxx the key
   number. The default value of n is the current key being bound in keymap
   0 (ie with yy set to 00).
   Eg the line  "&20170-&2017F	*&40"  will cause keys &170-&17F in keymap
   2 to have their definitions copied from keys &40-&4F of keymap 0.
   
 4 If you type a command into a keys file and it doesn't exist, then no error
   will be given. This is so you can put commands in your keys file for
   extension modes that may not always be loaded. However, if a command does
   exist but its parameters are incorrect, then an error will be given.
   
 5 If you define a key twice, then the later one will be used. Ie, the keys
   file is read sequentially and new definitions overwrite the old ones.

Commands can be chained together by use of the separator ':' as in BASIC. You
may NOT chain together commands which use the minibuffer (ie commands which
take a string as parameter but with the string unspecified). The two commands
BASEMAP and KEYMAP provide a means of swapping from one keymap to another and
for providing multiple key press commands as you get in Emacs. See the Emacs
keymap for examples of their use.

Examples:

 (1)	&020-7E		CHAR n
 (2)	&013		SEARCHFORWARD
 (3)	&131		BASEMAP 1
 (4)	&10018		KEYMAP 2
 (5)	&10150-&101FF	*
 (6)    &132		INSERT "Hello" : UP : RIGHT
 (7)	&133		insert " ""hello"" "
 
In (1), key &20 (space) is assigned the command CHAR &20, key &21 (!) is
assigned the command CHAR &21 etc. In (2), no string is given after
SEARCHFORWARD, so you are prompted for it when you press cS. (3) Ensures all
further keypresses are looked up in keymap 1, thus switching to Emacs
emulation mode. (4) Switches to keymap 2 for the next key press only, thus
allowing for two-key commands beginning with ctrl-X. In (5), keys &150-&1FF
in keymap 1 are assigned to the same commands they have in keymap 0. (6)
inserts the string "Hello" into the file and then moves up then right.

Below is a list of all commands provided by the Zap or ZapBasic modules. They
are in alphabetical order.

			****************
			* Command list *
			****************

ADDRESS
Shows line numbers in address format by changing b8-b9 of w_format.

ASSEMBLE <string>
Assembles the instruction given by string, placing it at the cursor position
(and using this position to determine the assembly address for BLs etc). It
does this by spawning a small (self modifying) basic program and using the
operating system variables Zap$Temp and Zap$TempNum to pass arguments.

AUTOINDENT
Toggles auto indent on and off (b16 of w_flags)

BASEMAP <word>
This command switches the key basemap to the given keymap number. All further
keypresses will use this keymap. It acts by writing variables key_basemap and
key_current (see E-Vars).

BASIC
Calls the extension mode entry point e_basic. This is mode dependant and used
by ZapBasic to drop the user into Basic with the program loaded at PAGE.

BEEP
Does a VDU 7.

BINDTOKEY <string>
This call evaluates <string> to a number and then binds the currently learnt
sequence to that (zap internal) key code. When used via the minibuffer, a key
press causes the code for that key to be inserted into the minibuffer. The
only exception is the escape key which will abort. However, BINDTOKEY "&1B"
will work if you really need to rebind the escape key.

CANCEL
Cancel current Yank/Search as you type operations. In a search as you type
operation the cursor is moved back to its starting point.

CDOWN
Advances cursor offset to end of file, leaving a marker at the previous
position.

CHAR <byte>
Inserts the given byte into the file. It does this by calling the mode entry
point e_char. Multiple presses are buffered (as with all <byte> parameter
commands) and passed to the command as one list.

CLEARSEL
Clears any selected regions by calling Zap_ClearSel.

CLEFT
Moves to start of line using the mode entry point e_cminus.

CLOSEOTHER
Closes the next window in sequence (the window which would be swapped to by
SWAPWINDOW). If only two windows are open then the other window is closed.

CLOSEPRINTER
Closes 'printer:$' filer window via *Filer_CloseDir.

CLOSEWINDOW
Closes the current window. If successful (ie no Save/Discard box), then it
places the cursor in the next window.

COLUMNTAB
Set tab mode to column tab by changing b9-10 of w_flags.

COMMAND <string>
Executes the command (or colon separated list of commands) given in the
string, as if they were typed into the keys file. It uses Zap_ProcessCommand
to do this.

COMPILE
Calls the extension mode entry point e_compile. Basic uses this to save a
program to disc and then chain it. A C-mode should cause it to run the
compiler etc.

COPY
Initiates copy mode/copies characters. Uses the mode entry point e_copy to
copy the data. It switches the cursor to mode 2.

COPYSEL
Copies the selected region to input caret position.

CRIGHT
Moves to end of line using the mode entry point e_cminus.

CUP
Moves to the start of a file, leaving a marker at the old offset.

CUT
Deletes the selected region. This is permanent if the undo buffer is off, or
the data can be pasted/yanked back if it is on using YANK. You may yank
across files, but note that when a file is deleted, all the yank regions
associated with the file are also deleted.

DATE <string>
Here the string is in the format required by OS_ConvertDateAndTime (eg %MI
for minutes etc). The string is converted by the above SWI with the current
time substituted and then inserted into the file.

DEFAULTMAP
Changes the key basemap to the default value (as specified in the 'keys'
file.)

DELETE
Deletes characters backward by calling mode entry point e_delete with R7=0.

DELETENEXT
Deletes characters forward by calling mode entry point e_delete with R7=1.

DELLINE
Deletes line by calling e_lineprev and e_linenext to find the line limits.
The line is added to the yank buffer. Cumulative deletes are concatenated in
the yank buffer.

DELTOEND
Deletes to end of line by calling e_lineend to find the line end. The line is
added to the yank buffer. Cumulative deletes are concatenated in the yank
buffer.

DELTOSTART
Deletes to start of line by calling e_linestart to find the line start.

DOWN
Moves cursor down a line.

DUMPFILE
Creates a text image of the current display for this file.

EDITTAB
Sets !Edit type tab mode by changing b9-10 of w_flags.

EMACS
Switches to Emacs key map (ie does a BASEMAP 1).

ESCAPE
Cancel modes: copy mode/yank mode/select area mode/search as you type. The
text is left in its current state. If you wish to undo the last action then
use CANCEL (ctrl G) to cancel the mode.

EXECUTE
Execute last learnt sequence.

FASTUNDO
Undo the last operation taking the fastest route in the undo tree. For
example if you do a,b,undo,c,fastundo,fastundo then it will delete the 'a' as
opposed to inserting the 'b'.

FINDFILE <string>
Opens a buffer on the indicated file (should be a full path name).

FINDFILEREADONLY <string>
As for FINDFILE but puts in read only mode when file loaded.

FONTOTHERFAST
Switches to anti-aliased font with fast redraw (b17,20,21 of w_flags).

FONTOTHERVDU
Switches to anti-aliased font drawn by Font_Paint (b17,20,21 of w_flags).

FONTSYSTEM1DPP
Switches to system font at 1 dot per pixel (b17,20,21 of w_flags).

FONTSYSTEMSCALED
Switches to system font scaled vertically for double pixel mode  (b17,20,21
of w_flags)

FONTSYSTEMVDU
Switches to system font drawn by VDU queue rather than my code (b17,20,21
of w_flags). Use mode 22 to see the difference.

FORMATTEXT
This will format the text from the given cursor position to the paragraph
end. A paragraph end is taken to be a return character followed by a white
space character (ie return,space or tab).

FULLUNDO
Undo the last operation taking the slowest route in the undo tree. For
example if you do a,b,undo,c,fastundo,fastundo then it will insert the 'b' as
opposed to deleting the 'a'. Compare this with Fast undo.

GOTO
Bring up the goto dialogue box.

HELP
Import the !Help file.

HEXASCII
Toggle hex/ascii entry mode (b5 of the w_flags). Byte mode uses this for
deciding whether 'F' is the letter F or the hex digit F.

INDENT
Indents the currently selected region by the string given in the menu option
selection.indent. If this evaluates to a number then indents by that number
of spaces.

INDIRECT
Jump to the address contained at the word at the current cursor posn (leaving
a marker behind as with any Jumps).

INSERT <string>
Inserts the string into the file at the given offset. It calls the mode entry
point e_char to do this.

INSERTDATE
Insert the current date using the format in the keys file (var &300).

INSERTGS <string>
Inserts the string into the file as for INSERT. However, the string is
GS-Trans'ed first thus enabling you to include control codes and OS
variables. As with INSERT, the mode entry point e_char is used.

INSERTTIME
Insert the current time using the format in the keys file (var &301).

JOINLINE
Call the extension mode entry point e_joinline to join line following the
current line to the end of the current line.

KEEPREGION
Copies the selected region to the yank buffer (Emacs kill ring) and then
clears the selection. This is the equivalent of Emacs Meta-W.

KEYMAP <word>
Change the keymap number BUT only for the next key press. The keymap
number will then revert to whatever the BASEMAP number has been set to
(unless the next key command is also a KEYMAP!) Using this command you can
cause a string of keys to execute a command.

LASTMARK
Jump to the previous mark in the market buffer.

LASTMATCH
Move to the previous match after using the Search window.

LASTSECTOR
Move to the last sector on an (unaltered) file read from disc.

LASTTRACK
Move to the last track on a file read from disc.

LEARN
Start/stop learn key sequence. Subsequent characters will be learnt producing
a beep each time to remind the user. Execute LEARN again to stop the
sequence. Note that all command passed to Zap_ProcessCommand with R2=0 or
R2=1 will be learnt. If R2>1 then the command will not be learnt.

LEFT
Move cursor left by calling mode entry point e_minus.

LINEEDIT
Toggles line edit mode on and off (b14 of w_flags)

LINEWRAP
Toggles line wrap mode on and off using b26 of w_flags.

LISTFNS
Lists function definitions for the given mode. (via e_listfns).

LOGICAL
Set logical line numbers by changing b8-b9,b11 of w_format.

MAKEDEFAULT
This saves the windows options as the current default options. Hence if you
do a 'save options' after this, then the windows options will become the
configured options.

MINIMISEMEMORY
Contacts heap by as much as possible. I'm afraid it's an Acorn OS_Heap type
heap so this won't usually do much.

MODE <byte>
Change the current display mode to the given number. 

MODE0-MODE15
Set the current mode for the given window. This also restores the line number
status last used by that mode. These commands are needed in addition to the
MODE command as commands assigned to menu entries cannot take parameters.

MOVESEL
Move the selected area to current cursor offset.

MULTICOMMAND <data>
This command cannot be typed into the keys file as it takes a data block as
parameter. It is used internally to execute a list of command (eg a learnt
sequence). The data block is a -1 terminated list of entries of the form
given below. Note that all the data for the commands to be executed is stored
within the data block except for data type 4 (other multicommands).
	#0 Command address
	#4 Data length/number of times (R1 on command entry)
	#8 Command data. Depends on the type of the command (see E-command):
		0 No data
		1 List of #4 bytes then align
		2 List of #4 words
		3 0 terminated string then align
		4 Pointer to the data block 

NEWVIEW
Open a new window on this file (copying the old window mode and format).

NEXTMARK
Jump to next mark in the marker buffer.

NEXTMATCH
Move to the next match after using the Search Box.

NEXTSECTOR
Move to the next sector on a file read from disc.

NEXTTRACK
Move to the next track on a file read from disc.

NOLINENOS
Switch off line numbers by clearing b8 of w_format.

NONSTANDARD
Toggles non standard editing on and off (b15 of w_flags).

NULL
Do nothing, but prevents key from being passed on via Wimp_ProcessKey.

OPENPRINTER
Open a filer window on printer:$ via *Filer_OpenDir.

OUTDENT
Outdents the selected region (by the length of the current indent string).

PASTE
Pastes the last cut region repeatedly. Use YANK to cycle through previously
deleted regions.

PHYSICAL
Switch on physical line numbers by changing b8-b9,b11 of w_format.

PRINTFILE
Open the fancy print window.

QUICKPRINT
Open the quick print window.

QUICKSAVE
Save the file directly to disc with no prompt.

QUIT
Kill Zap.

QUOTE
Causes the next key which is typed to be sent to the CHAR command. Hence the
next key is inserted into the file, instead of having the command associated
to that key executed.

READONLY
Toggle the read only state of a file (b8 of f_flags).

REDO
Redo the last undone operation whether full or fast.

RENUMBER
This calls e_renumber and is thus mode independent. ZapBasic uses it to
renumber a file.

REPLACE
Open the Search & Replace window.

RETURN
Cancel split cursor copying and then call e_return to perform the return
action for the current mode.

RETURNNOINDENT
This acts as the return function except that it clears the auto indent flag
across the call to e_return thus giving a single return without auto indent.

RIGHT
Move cursor right using mode entry point e_plus.

RUN
Call e_run mode entry point. ZapBasic uses this to Run a file at PAGE.

RUNANDQUIT
Call e_runandquit mode entry point. ZapBasic runs the file at PAGE and then
quits.

SAVE
Open save box.

SAVESEL
Open save selection box.

SAVEANDRUN
Call e_saveandrun mode entry point. ZapBasic save the file, chains it from
disc and then quits.

SAVEFILE <string>
Save the buffer with filename <string>. This differs from WRITEFILE in that
if <string> is omitted, then the file will be saved with its current name, if
this is a full path name, and the minibuffer will not be opened.

SCDOWN
Move down display one line (without moving cursor).

SCLEFT
Move to left of display one character (without moving cursor).

SCRIGHT
Move to right of display one character (without moving cursor).

SCUP
Move up display one line (without moving cursor).

SDOWN
Move down a page.

SEARCHBACK <string>
Searches backwards for string and then places the cursor at then end of the
match (if found).

SEARCHBUF
Open Search window with output to buffer option set.

SEARCHCUR
Open Search window with output to cursor option set.

SEARCHFORWARD <string>
Searches forwards for string and then places the cursor at then end of the
match (if found).

SELECTBUFFER
Select entire buffer.

SELREGION
Start selection of region by cursor movement. This sets the cursor mode to 4.

SETWIDTH <string>
This evaluates <string> to a number and then sets the width of the mode to
this number by calling the mode entry point e_setwidth.

SLEFT
Move cursor back a word by calling e_sminus.

SPLITLINE
Split line at current cursor posn by calling e_splitline.

SRIGHT
Move cursor forward a word by calling e_splus.

SUP
Move up a page.

SUSPEND
Brings up the command line (same as F12).

SWAPCASE
Swap case of next character/selected region if there is one.

SWAPCHARS
Swap characters either side of cursor.

SWAPWINDOW
Swap window. If possible it swaps to the last used window on the current
file using the marker buffer to determine this. Otherwise it swaps to the
next file in the order files are stored within zap.

SWITCHTAB
This toggles the TAB mode for a file (w_flags b9-b10) between UNIX and
TRUETAB modes.

TAB
Calls e_tab so that the mode can enter the tab as it wishes.

TABDISPLAYARROW
Displays tabs as an arrow followed by spaces (b12-13 of w_format).

TABDISPLAYDASHES
Displays tabs as dashes leading to an arrow (b12-13 of w_format).

TABDISPLAYNONE
Displays tabs as the character 9, (b12-13 of w_format).

TABDISPLAYSPACES
Displays tabs as spaces (b12-13 of w_format).

TABSASSPACES
Toggles b11 of w_flags which governs whether spaces or tab characters are
used for edit/column tabs.

TOBACK
Moves the window to the back of the window stack via Zap_OpenWindow 4.

TOFRONT
Moves the window to the front of the window stack via Zap_OpenWindow 3.

TOGGLEHEX
Toggle hex/decimal display of line numbers (b10 of w_format).

TOGGLEINSERT
Toggle insert/overwrite modes (b1 w_flags).

TOGGLEMARK
Insert/delete mark from marker buffer at current marker offset.

TOGGLEWIND
Toggles the window size. The not-fully-open size is stored in the variables
w_togminx to w_togmaxy.

UNIVERSALARG <string>
This command evaluates the string to a number and then calls the next
executed command (executed via Zap_ProcessCommand) that number of times.

UNIXTAB
Switches to unix tab mode by clearing b9-10 of w_flags.

UP
Move cursor up a line.

WORDWRAP
Toggle wordwrap mode on/off (toggles b13 w_flags)

WRITEFILE <string>
Saves the buffer with filename <string>. Also see SAVEFILE.

YANK
Paste last cut region from undo buffer to current cursor position. On
repeated action it pastes previously cut regions in a cyclic manor.
