***************************************************************************** * >!Help file for Zap version 1.39b * * Copyright Dominic Symes 1992-1997. See the '!Zap.Docs.Copyright' file. * ***************************************************************************** ZAP is a text editor Main features: * Display may be in many different editing modes. Eg: Text, byte, disassembly, coloured C, assembler, BASIC. * All key short cuts and menus are user redefinable. * 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. * Standard 'copy' cursor editing available. * Fast redraw in bitmap or anti-aliased outline fonts. * Lots of different bitmap fonts supplied. * Syntax colouring and configurable font sub-styles. * Any number of markers on each file. * A facility for following branches in disassembly mode. * Full ARMBE style BASIC Editor. * Search as you type with minibuffer. * Can record and play back sequences of operations. * Emacs style Yank (Cut & Paste) and !Edit style move and copy implemented. * C throwback/info supported. * Reads disc sectors/tracks and memory of other tasks. * Selection of regions via keyboard and mouse. * Taskwindow supports control characters / line-editor. * Emacs compatible keymaps. * Auto indent and bracket matching. * Can edit assembler instructions when in Code mode. * Compatible with Risc OS 2 & 3 & Risc PC. * Automatic detection of DOS text files and Spool files. * Full documentation and source code available. * Third-party interface allows extension modes to be written. * Uses dynamic areas on the Risc PC. ************************************************************************* * Important: * ************************************************************************* (1) This file does NOT contain help on the menu items and dialogue boxes. See the Docs.HelpData file or run the !Help application (in Resources:Apps) to find out about these. (2) The extension modes each have their own help file in the 'Modules' directory. (3) If you are changing versions of Zap then please read the 'Docs.Changes' file first! ************************************************************************* * Contents: * ************************************************************************* Section A Keys and options. A.1 Summary of default key & mouse actions. A.2 How to (re)define more keys. A.3 How to change Zap's default options. A.4 Differences RISCOS 2 / 3 / 3.5 / 3.6 / 3.7. A.5 Multiple keymaps / the Emacs keymap. A.6 Colour and changing the default colours. Section B Loading/saving/printing/editing files B.1 Loading files/creating files. B.2 Saving files and ~ backups. B.3 Dumping/printing files. B.4 Selecting regions. B.5 Copying/cutting/pasting/yanking. B.6 Inserting text/control codes Section C Individual mode help. C.0 Text mode C.1 Byte mode ... etc ... Section D Search and Replace. D.1 The Search window. D.2 The Replace window. D.3 Keyboard (incremental) search. Section E Other features. E.1 Learning key sequences - very useful. E.2 Tabs and indenting. E.3 Fonts and font sizes. E.4 Universal arguments. E.5 The minibuffer E.6 Explanation of some menu entries Section F How to find out more. F.1 Other help files - MENU help. F.2 Obtaining future versions of Zap. F.3 Contacting the authors with suggestions/bugs. ************************************************************************* * Section A: Keys and options. * ************************************************************************* A.1 Default key actions ----------------------- When Zap is loaded, it reads in the 'Keys' file, and uses this to create the current key bindings. The 'Menus', 'Settings' and 'Types' files are also loaded and processed when Zap first loads. More details are in section A.3. Each key mentioned in the 'Keys' file has a command name following it. By editing the file and moving the command names about, you can change the action of any key. See section A.2 for more details (the format of a 'Keys' file entry and how to define multiple keymaps). Please note that the key short cuts given in the menus are automatically updated to reflect your new choice of keys (for whatever you have set as the default keymap). A summary of the default key bindings is given below. (s=Shift c=Ctrl sc=Shift+Ctrl). Key: Command: Action: Return RETURN Splits line / inserts new line in line edit mode. Also indents in auto-indent mode. Edits an instruction in code mode. sReturn RETURN As above. cReturn RETURNNOINDENT As RETURN except doesn't auto-indent. Delete DELETE Delete last character. sDelete DELETENEXT Delete next character. cDelete DELLINE Delete current line. scDelete DELTOEND Delete to end of line. Tab TAB Inserts a variety of tabs - see tab menu. sTab SWITCHTAB Switches between Unix and !Edit tab modes. cTab - Reserved (for users of !Larger/!Menon etc). Escape ESCAPE Stops copy modes/selection modes/search as you type mode/yank mode. sEscape CANCEL Cancel operation and return to start posn. cEscape COMMAND Brings up a minibuffer in which you can type any Zap command. Equivalent of Emacs M-X. <-| DELETE Delete last character. s<-| DELETE Delete last character. c<-| FASTUNDO Undo last operation. sc<-| LASTMARK Jump to last marker Copy DELETENEXT Delete next character. If in 'copy' mode then copies the character. sCopy COPY Initiates split cursor copying. Move cursor with cursor keys and use COPY key to copy. Note that you may copy from one window to another by pressing SELECT on the other. cCopy SELREGION Starts selection of a region via cursor keys. Press Escape/cCopy to end the selection. scCopy DUMPFILE Produce text version of the display. Insert TOGGLEINSERT Toggle insert and overwrite modes. Print QUICKPRINT Send file directly to printer. sPrint PRINTFILE Print file through printer driver. cPrint OPENPRINTER Open 'printer:$' filer window. scPrint CLOSEPRINTER Close 'printer:$' filer window. Space bar CHAR &20 Inserts a space. sSpace CHAR &20 As above. cSpace SELREGION Emacs compatible. scSpace UNSPACE Remove excess spacing around the cursor. Cursor keys: Left LEFT Moves 1 left / goto last mark in code mode. Right RIGHT Moves 1 right / goto 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/PageDown SDOWN Move down a page. sUp/PageUp SUP 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: F1 EXECUTE Execute learnt key sequence (see F.1). F2 FINDFILE Load a named file (Emacs C-X C-F). F3 SAVE Brings up save box. See save box help. F4 SEARCHCUR Brings up Search to cursor box. (See E.1). F5 GOTO Brings up Goto line/address box. F6 DROPMARK Inserts marker in text. F7 SEARCHBUF Brings up Search to buffer box. (See E.1) F8 FASTUNDO Fast undo (takes shortest path in undo tree). F9 REDO Redo (undo last undo whether full or fast). F10 DELLINE Delete current line. F11 - Reserved. sF1 SPLITLINE Split line (useful in Basic mode). sF2 SWAPWINDOW:TOFRONT Swap window (to next window/last used). sF3 SAVESEL Open the 'save selection' window. sF4 REPLACE Brings up search and replace box. (See E.2). sF5 FULLUNDO Full undo (takes longest path in undo tree). sF6 LASTMARK Last mark (eg after ctrl-down by mistake). sF7 NEXTMATCH Next match (after an F4 or F7 search). sF8 RENUMBER Renumbers a BASIC file. sF9 NEXTMARK Jump to the next set marker. sF10 DELTOSTART Delete to start of line. sF11 TOGGLEMARK Inserts a marker (or deletes an existing one). cF1 JOINLINE Join line (useful in Basic mode). cF2 CLOSEWINDOW Close current window (and jump to next). cF3 QUICKSAVE Save the file with no prompt. cF4 NEWVIEW New view (open new window on this file). cF5 WORDWRAP Toggle wordwrap mode (w in title). cF6 FORMATTEXT Format text to start of next paragraph. cF7 LASTMATCH Previous match (see sF7). cF8 BINDTOKEY Bind the learnt sequence (see cL) to a key. cF9 HEXASCII Toggles hex entry mode when byte/word modes. cF10 DELTOEND Delete to end of line (emacs style ctrl K). cF11 LASTMARK Jump to the last set marker. scF1 MODEN "Text" Text mode (display in text format) scF2 MODEN "Byte" Byte mode (display in hex bytes) scF3 MODEN "Word" Word mode (display in hex words) scF4 MODEN "ASCII" Ascii mode (display in characters) scF5 MODEN "Code" Code mode (display in disassembled code) scF6 MODEN "BASIC" BASIC mode (display tokenised Basic) scF7 MODEN "BASTXT" BASTXT mode (display detokenised Basic) scF8 MODEN "Email" Email mode scF9 MODEN "C" Colour C mode. scF10 MODEN "Assembler" Colour Acorn assembler mode. Ctrl letters: cA SPELL Bring up spelling window. cB TOBACK Moves the window to the back of the stack. cC COPYSEL Copy selected region to current position. cD DELLINE:PASTE:UP:PASTE Dupe line. cE KEEPREGION Add the selected region to the yank buffer. cF TOFRONT Moves the window to the front of the stack. cG CANCEL Cancel search 'as you type' and return to start. Also cancel any yank operations. Escape from minibuffer. (emacs compatible) cH HELPCONTEXT Get context sensitive help using !StrongHlp. cI INDIRECT Indirect (move to the address given by word at cursor - useful in Code mode). cJ INDENT Indent selection by string (see selection menu). cK DELTOEND Kill line (emacs compatible). cL LEARN Learn key sequence (see F.1). cM RETURN Performs return action for current mode. cN NEXTMATCH Next match in search. cO OSCLI Presents the user with a * prompt. cP LASTMATCH Previous match in search. cQ QUOTE Insert next character into text (even if it is a ctrl character. eg cQ,cA inserts #1). cR SEARCHBACK Reverse search 'as you type'. cS SEARCHFORWARD Search 'as you type' forwards. cT SELECTBUFFER Select entire buffer. cU UNIVERSALARG Perform next instruction 'n' times. Eg cU 4 RETURN A inserts 4 A's. cV MOVESEL Move selected region to current position. cW SETWIDTH Set the window width. cX CUT Delete/Cut selected region. cY PASTE Paste/Yank once selected region. cZ CLEARSEL Clear selection. scA ESCAPE:COPY:UP:COPY:ESCAPE Copy a single character from above. scB BASIC Drop into BASIC with program downloaded. scC COMPILE Saves then chains/compiles a program. scD INSERTDATE Insert current date (format in 'keys' file). scE SAVEANDRUN Saves then runs a program then exits. scF RUNANDQUIT Runs a program and then exits. scG TOGGLEWIND Toggle window size. scH LISTFNS List function definitions. scI NEXTTRACK Move forward one track. scJ LASTSECTOR Move back one sector. scK NEXTSECTOR Move forward one sector. scL LOWERCASE Force lower case of next character/selection. scM LASTTRACK Move back one track. scN LINENOS 0 Removes line numbers/addresses. scO TOGGLEHEX Line numbers shown in hex/decimal. scP LINENOS 2 Physical line numbers shown at line start. scQ SWAPCHARS Swap next two characters around. scR WINDOWWRAP Toggles the window wrap state (W in title). scS SWAPCASE Swap case of next character/selected region. scT INSERTTIME Insert current time (format in 'Keys' file). scU UPPERCASE Force upper case of next character/selection. scV - Reserved. scW SOFTWRAP Toggles window's soft wrap state (s in title). scX CLOSEOTHER Close other open window. scY YANK Yank cyclically through deleted regions. scZ KEYMAP 1 Emacs prefix key (eg scZ ESC X). Misc: c- SPELL_REPLACE Replace current word with a correct spelling c[ LINENOS 1 Logical line numbers c] LINENOS 3 Addresses shown at line start. sc- (c_) FULLUNDO Undo (emacs compatible) scH HELP Get help on Zap, a key, Zap command or mode sk* DELWORDSTART Deletes the previous word. sk# DELWORDEND Deletes the next word. There are a number of other key bindings, but it is probably not appropriate to go into them all here. Exact details may be found by consulting the 'Keys' file, or by using Zap's 'HELP' command. Standard mouse actions: Click SELECT: Place cursor at the clicked position. Click MENU : Bring up the window menu. Click ADJUST: 1. If the window contains a selection then it is resized. 2. If the window contains a cursor then a selection is formed between the cursor and the click position. 3. The cursor is moved to the last used position (the hollow square if neither of the above apply). Drag SELECT: Selects a new region. Drag ADJUST: Resizes the current region. (in either case holding down CTRL leaves the cursor unmoved). Double click SELECT: Select a word. Treble click SELECT: Select a line. Quadruple SELECT: Select a paragraph. Quintuple SELECT: Select the whole text. A.2 How to redefine more keys ----------------------------- At the start of the 'Keys' file, the keys for keymap 0 (the default key map) are defined. Each line is of the form "comment &xxx command" where 'comment' is any text without a '&' describing the key, 'xxx' is the number of the key in hexadecimal (Zap key number - see below), ' ' is any number of spaces and tabs, and 'command' is the command (or list of commands) to be attached to that key. You may edit the file to add/remove keys as you please. If a key is not mentioned in the keys file then it is passed on to the next task. Thus DO NOT put F12 in the 'keys' file (or if you do then bind it to the command SUSPEND :-). A list of the valid commands you can use and their actions is given in the file 'HelpData' within the 'Docs' directory. See also the file 'Commands' for the syntax to use. To summarise these details, string parameters must be in double quotes (or omitted if you wish the minibuffer to be opened), and commands can be strung together with the ':' separator (as in BASIC). The Zap key numbers lie in the range &000-&1FF and are based on those returned by Wimp_Poll. Thus, the function keys return &180-&1FF, as documented in the PRMs. Just look at the 'keys' file if you don't have a copy of the PRMs. Standard characters return their ascii value &20-&FF as usual. &7F stands for unshifted DELETE. Internally Zap uses some extra codes in the range &00-&1F and &100-&17F which differ from the WIMP's. These are documented in the file E-Keycodes in the 'Docs' directory. Example: Suppose you wished ctrl-] to enter the code &1D into the file. Then you would enter the line: "c] &12D CHAR &1D". The keys c1-c9 and sc1-sc9 have been left intentionally blank. It is recommended that these are used for user commands/macros or binding the learnt sequence to via cF8. See the section A.5 on how to define multiple keymaps and switch between them. A.3 Changing the default options -------------------------------- The Zap menu you get when you click the MENU button on a window contains the status for that window only. Any options changed on this menu will be lost immediately the window is closed. To change any option permanently, use the 'options' menu obtained by clicking on the Zap icon on the iconbar. After you have changed the option on this menu click the 'Save options' entry. Alternatively, (and usually preferably) set up a window the way you like it and then use the 'Copy ops' menu option on the misc menu to make these options default. Then save them, using the 'Save options' entry as before. Please note that some options are stored MODE dependantly. To change these options from the icon bar menu it is first necessary to SWITCH TO THE MODE WHOSE OPTIONS YOU WANT TO CHANGE ON THE OPTIONS.MODE MENU. The options you need to do this for include: 1) Display width. 2) Line number status. 3) Auto indent status. 4) Line edit/Non standard edit status. 5) Hex entry and Overwrite status. 6) Tab display status. 7) Colours. 8) Automatic space stripping on saving. 9) Tab insert status. 10) Auto-width status. When you change mode, the other options menus will be updated to give the status of the flags for this mode. Example: To turn the line numbers off in BASIC editing mode use the sequence of clicks: zap.options.mode.basic zap.options.display.linenumbers.none zap.options.mode.text The mode set on the 'Options.Mode' menu will also be the mode used for loading files whose type is not recognised, or when you hold down the CTRL key. In general you should always put this mode back to TEXT after changing options of other modes. Other options that are saved by clicking Save Settings include: 1) Whether searches are case sensitive or not. (and other options in the Search box) 2) Whether quick print adds a title header or not. To change the size of an opened window for mode n, create a template in the current template file (see the !Run file to see which one is loaded) called mode_n. The size and position of this template determines the opening size and position (modulo stacking) of your window. The other template flags are not looked at. Some other options are stored in the 'Keys', 'Types' and 'Settings' files. The entries are in the form: " &xxx ... " where 'xxx' is a number which will be referred to henceforth as the key variable number. The variable numbers in the above files are documented below: &000-&1FF The default keymap. arg1=the command attached to that key code. &200-&20F These give the 16 search macros. arg1=the macro string (up to 7 chars - NO spaces) arg2=the replacement string (up to 23 chars). &300 The date format to use for scD. arg1=format string as used by the SWI OS_ConvertDateAndTime &301 The time format to use for scT. arg1=format string as used by the SWI OS_ConvertDateAndTime &302 The default font name to use in font display modes. &303 The number of blank lines to leave at the end of a window. &304 The default font size in points. &305 The number of pixels to shave off the top of a font char. &306 The number of pixels to shave off the bottom of a font char. &307 The codes to send to the printer at the end of a line for 'quick print'. arg1=string to be 'GSTrans'ed. &308 Number of characters to keep cursor from the left margin. &309 Number of characters to keep cursor from the right margin. &30A Number of characters to keep cursor from the top. &30B Number of characters to keep cursor from the bottom. &30D Right hand margin in pixels. &30E Filetype of file to be created when SELECT clicked on the iconbar. &30F Filetype of file to be created when ADJUST clicked on the iconbar. &310 The number of pixels to shave off the left of a font char. &311 The number of pixels to shave off the right of a font char. &314 The minibuffer size in characters. &315 The default indent string. &316 Flashing cursor on period in centiseconds. &317 Flashing cursor off period in centiseconds. &318 Minimum auto-width width &319 Maximum auto-width width. &31A Name of the Zap font to use in low-res modes. &31B Name of the Zap font to use in hi-res modes. &31C Default attributes to use for newly created files. &400 The number of the default key map (usually 0). &4xx (xx<>0) Range of keymap xx (see A.5) arg1=smallest Zap keynumber to be supported arg2=largest Zap keynumber to be supported (inclusive) &5xx These say which mode to load a file on dependent on the path. arg1=filetype to match (-1 for match any) arg2=filename to match - the string can contain any of the wildcards documented under searching. arg3=[+] as for arg1 in the 1xxx's below. NB The order in which the names appear is important - the first match will be taken. &1xxx These specify which of the Zap modes a file of filetype xxx should be loaded in as (when CTRL not pressed). arg1=[+] If the optional '+' is present then the file will be loaded even if SHIFT is not held when you double click. The mode name is CASE SENSITIVE. Place the &1xxx variable before the &5xx ones if you want the filetype to be checked before the pathname. &2000 As for &1xxx, but the mode to use for UNTYPED files. &10000+ These specify alternate keymaps (see A.5). &y0xxx arg1=the command to be mapped to key with code &xxx in keymap number &y. A.4 Differences with RISCOS 2 / 3 / 3.5 / 3.6 / 3.7 --------------------------------------------------- DYNAMIC AREAS: Zap uses dynamic area storage for files and fonts on RO3.5. It uses the WimpSlot in earlier versions of the OS. FONTS: If using fonts on RO2, then Zap will need the outline font manager version 2.42. TASKWINDOWS: If using task windows, on RO2 then Zap will expect to find the module 'Task' in the System:Modules directory. This should be the Task module supplied with DDE. Of course ^F12 will not bring up the taskwindow on Risc OS 2. I'm sorry about this, but it's a lot of hassle to find a Risc OS 2 machine to work on. You can always map ^F12 to the command TASKWINDOW. LOADING FILES: Only left shift double click will load a non text file in RO2. Right shift is deliberately not tested for as some people use it for other things. We have no control over this on Risc OS 3. HELP: There is no interactive menu help in RO2. You will have to read the HelpData file directly. TEMPLATES: Zap uses appropriate Template files depending on the version of Risc OS available. A.5 Multiple keymaps / the Emacs keymap. ---------------------------------------- Zap can support several keymaps at once. Each keymap is numbered 0-255. In the default 'keys' file, keymap 0 is the standard Zap keymap and keymap 1 an Emacs emulation keymap. Keymaps 2-4 form part of the Emacs keymap as I will describe below. To switch to keymap n, use the command "BASEMAP n" (by pressing Ctrl-Escape or binding the command to a key). The commands DEFAULTMAP and EMACS act as BASEMAP 0 and BASEMAP 1 respectively. The default keymap to use when Zap starts up is given by variable number &400 in the keys file. Set this to 1 if you wish to use the Emacs keymap all the time. To define a new keymap, keymap number &yy say, you need to do two things. First you must enter a line in the 'keys' file reserving space for the keys. This takes the form: &4yy &aa &bb where &aa is the smallest keynumber you wish to use and &bb the largest (inclusive). See entry &401 for an example. Next you must define the keys. To define key number &xxx you must enter a line in the 'keys' file of the form: &yy0xxx where is the name of the command to be attached to the key. The format of the field is described in A.1 and the 'Commands' file. By using multiple keymaps you can provide for a sequence of keys to execute a command. To do this you need the 'KEYMAP' command. The command 'KEYMAP n' switches the current keymap to 'n'. However, after the next key has been read, the current keymap is restored to whatever basemap you have set with the basemap command. Thus in effect, the keymap only changes for the next keypress (unless that too involves a KEYMAP command). For example, in Emacs "Ctrl-X 4 F" loads a file. This is accomplished by setting: Ctrl-X in keymap 1 is bound to KEYMAP 2 4 in keymap 2 is bound to KEYMAP 4 F in keymap 4 is bound to FINDFILE After the command FINDFILE has been executed, the keymap will be restored to 1 for the next key press. A.6 Colour ---------- Colour is changed using the 'Colour' menu off the 'Display' menu, both on the main Zap window menu. The first 9 colours you can change are the same for all modes, being: Colour Action 0 Background1 The colour used for squares containing no text. 1 Background2 The colour used for squares containing text. 2 Foreground The standard foreground colour. 3 Selection-B Selection background colour. 4 Selection-F Selection foreground colour. 5 Cursor-Bac Cursor background colour (ie the cursor colour). 6 Cursor-For Cursor foreground colour. 7 Line nums Colour used for line numbers (eg in Basic mode). 8 Ctrl chars Colour used for control characters (0-31). Colours 9+ are mode dependant and lie below a dotted line. If the 'all modes' flag at the top of the menu is set then when you change one of the colours 0-8 (as above) then it is changed for all modes, not just that one mode. Colours 9+ only set the colour for that mode regardless of the status of this flag. You will need to change modes to set up the colours for different modes differently. Of course, if you change colours from the window menu, then the colours are only changed for that window and are lost when the window is closed. To change them permanently, use the Display menu off the options menu and then click on 'save options' (or use the Copy Ops menu option). Font sub-styles are set up from the colours dialogue. These are usually greyed out or not visible for colours where fonts are inappropriate, for example when editing the colour of the selected region, for which there is no corresponding font. ************************************************************************* * Section B: Loading, Saving, Printing, Editing files * ************************************************************************* B.1 Loading/creating files -------------------------- These are the ways to load a file into Zap: (a) If the file is a text file then double click on it. (or more generally if there is a '+' for this type in the keys file). (b) If the file is typed then hold down left shift and double click on it. (c) If the file is untyped then drag it onto the Zap icon on the iconbar. (d) Press F2 then type the name of the file and RETURN (TAB completes the filename). When you load a file into Zap, it works out the best mode to load it into. At the moment there are two mechanisms for doing this, both specified in the 'Types' file. These are: (see A.3 for more details). (i) By filename: The keys variables &5xx are followed by a filetype then a filename and then a mode to use. If the (wildcarded) filename matches and the filetype matches then that mode is used. (ii) By filetype: The keys variable &1xxx is followed by the mode name to use for type &xxx. If the name is preceded by a '+' then the file is loaded even if shift is not held. If the file satisfies more than one of the above criterion, then the first one mentioned in the keys file will be used. Sometimes you may wish to load a file in a mode other than its default one. To do this, set the required mode on the 'Options.Mode' menu, and then hold down the CTRL key while loading the file. (Eg Shift-Ctrl double click on the file). It will then be loaded in the selected mode (usually text). Dragging a file into an open window inserts the data at the current cursor position. RAM loads/saves are fully supported and you may even save a file into itself. If you are short of memory then it is recommended that you switch the undo buffer off before performing such drags (by using the 'File' menu). In any mode the window title is of the form: " [*] ([mode name] [options]) [view number/number of views]". The title is centered unless the window is small when it is right aligned so you can see the leaf name and options of the file. A '*' indicates that the file has been altered since last saved. The options characters are described below. The view number is only shown if you have more than one view on a file. R Read only and fixed as read only. r Read only but can be toggled to read/write by scR. D This is a DOS text file (LF->CRLF on saving). S This is a Spool text file (LF->LFCR on saving). A File has non standard attributes (update using OS_GBPB). u Undo supported by this file (so cX acts as cut, not delete). 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 cF5). L Line wrap mode. l Line edit mode active (return inserts new line). n Non standard mode active (used by ARMBE emulation mode). a Auto indent mode active (see the Edit submenu). W Window-wrap is turned on. s Soft-wrap is turned on. You may also create files of a given type using the 'Create.Type' menu, or grab modules using the 'Create.Getmodule' menu. Zap can also read disc sectors and other applications memory. Click SELECT on the Zap icon to create a new text file and ADJUST on the Zap icon to create a new BASIC file. You can change the type of file created by SELECT/ADJUST click in the 'keys' file. Zap will warn you before overwriting a file of the same name if it is altered. If it is unaltered then the newly loaded file will replace the one currently loaded as in, for example, in !Edit. When a file is loaded, OS_FSControl, Canonicalise_Path will be called to convert any path references into full path names (unless you have RISC OS 2). The filename will also be converted to the correct case as reported by the filing system. B.2 Saving files and ~ backups ------------------------------ Press F3 (or click on the menu option 'File') to open the save box. You may change the file type either by clicking the MENU button, or by moving to the type name window, typing the new type name and pressing RETURN. Zap will warn you if you are about to overwrite a more recent file (if you have the check-dates option on - see the options.misc menu), or if the file contains no path. If you ignore the warning then it will save the file to the currently selected directory. Ctrl-F3 (or clicking on 'File.Save') does a direct save. Ctrl-F2 deletes the current file and Shift-Ctrl-X deletes the other file being viewed. Please note that when the SAVE,DISCARD,CANCEL box pops up you may simply press 'S','D',or 'C' instead of using the mouse. The same holds for other dialogue boxes (ctrl S,D,C are also valid). If the directory in which the file is saved contains a directory called ~ or ~ where is any number then instead of the file simply being overwritten, the old version is moved into the ~ directory. If you have multiple ~ directories - eg ~1,~2,~3 ... ~n then the last n versions of the file are kept. If you are using one of the basic modes then please note that you must save from a window in the correct mode. If you switch to text mode and then save, your file will be saved as a text file and not as a BASIC program. B.3 Dumping, printing files --------------------------- First note that any window display may be turned into a text file simply by pressing SHIFT-CTRL-COPY. Once you have done this you could print a file simply by saving it to a printer driver, or by opening the 'printer:$' filing system (press ctrl-print) and saving the file into it. Zap also provides two other printout commands. The first, 'quick print' can be got by pressing the 'Print' key. When you press Return, or click 'PRINT', it will send the display to the printer directly. It sends a LF and a CR to the printer at the end of each line. You may configure the codes sent by altering the 'keys' file variable &307. The second, 'fancy print' can be got by pressing 'Shift-Print'. You must have a printer driver loaded. The file will then be output via the printer driver in the current outline font selected via the 'Display.Font.Othername' menu. The display quality of this option is not yet perfect. There may be problems when using it with Computer Concepts Turbo drivers. 'Fancy printing' has options to preserve syntax colouring. If the option to print in colour is not selected, Zap will still print using font substyles. Note that the default setting for the option controlling printing in colour is taken directly from the options of the currently installed printer driver. B.4 Selecting regions --------------------- There are several ways to mark regions in Zap. The most obvious is to use the mouse. If there is no region selected then DRAG SELECT will mark a new region, and ADJUST CLICK/DRAG will select between the clicked point and the cursor. If there is already a region selected then DRAG SELECT will start selecting a new region, ADJUST CLICK/DRAG will alter the old region. In either case, hold down the CTRL key to leave the cursor unaffected by the selection. The second method is to use the keyboard. This method can be faster when you have got used to it. First move to the start of the region you wish to mark, then press CTRL-COPY and move (via the cursor keys) to the end of the region. Next press ESCAPE (or CTRL-COPY). Alternatively selections may be created by pressing ESCAPE and, while holding it down, moving the cursor to the desired position using the cursor keys. The third method is to use multiple clicks. Double click marks a word, triple click a line, quadruple click a paragraph and quintuple click the whole file. If you do a drag selection after the second/third click, then the text will be selected in words/lines. Note that the BASIC mode usually limits selected regions across lines to full BASIC lines (like the ARMBE). B.5 Copying/pasting/cutting/yanking ----------------------------------- Zap implements both the !Edit style copy/move and the Emacs style paste/yank. The !Edit method: To move a region to the cursor position press ctrl-V. To copy a region press ctrl-C. The Emacs method: To move a region cut it with ctrl-X and then paste it with ctrl-Y (the undo buffer must be on to do this). To copy a region, grab it with shift-ctrl-W (Emacs meta-W) and paste it with ctrl-Y. Press shift-ctrl-Y (Emacs meta-Y) to cycle through the previously deleted regions. Also note that multiple presses of ctrl-K or F10 produce data which can be yanked by ctrl-Y. Another way to copy text is via the COPY key. This is faster for copying small sections of other lines. First press the COPY key to split the cursor into two. One cursor can be moved about by the cursor keys. Move this to the area you wish to copy from and press the COPY key once for each character. Press ESCAPE or RETURN to cancel the copy mode. Please note that you can also use this method across windows and even across modes! B.6 Inserting text/control codes -------------------------------- In text mode there are two features to help you format text as you type it. The first is called 'word wrap' and is toggled on and off via cF5. The second is called 'line wrap' and can be toggled on and off via the 'Edit' menu (or you can bind the LINEWRAP command to a key if you wish). Whilst either of these modes are active, text typed beyond the 'wrap width' margin (set via the 'Edit' menu) is automatically split at spaces and placed on the next line. 'Wordwrap' differs from 'linewrap' in that when you delete characters, the paragraph will be formatted in wordwrap mode (thus pulling text back) but not in linewrap mode. There are two main ways to insert control characters: The first is to 'quote' the character. To do this, press ctrl-Q and then type the control character you want to insert. Eg, ctrl-Q ctrl-A will insert the byte 1. The second is to switch to byte mode (scF2), type the digits in hex and then switch back to text mode (scF1). This assumes that 'hex entry mode' is active in byte mode. When creating macros, by binding a list of commands to a key, you may find the commands INSERT and INSERTGS useful. The first inserts a string into the text and the second passes it to the operating system's GSTrans routine first. ************************************************************************* * Section C: Individual mode help * ************************************************************************* Zap can handle up to 256 text processing modes at any one time. Currently there is space allocated for 32. For details on how to write your own mode see the 'Docs' directory. The currently defined modes are described below. Some additional help is given in the 'HelpData' file. C.0 Text Mode ------------- This is a basic text editing mode. Most of the functions associated with this mode are detailed elsewhere. See the 'Helpdata' file for a detailed listing of menu options. To insert control characters in the text it is easiest to switch temporarily to byte mode. The character &09 in a text file is taken to denote a tab to next column of 8. You may change this character and the way it is displayed from the display menu. Tab action may be changed by the 'Misc.Tabs' menu. C.1 Byte Mode ------------- This mode gives displays the file in hex bytes and is used for examining data or inserting control characters. The hex-entry flag (toggled by shift F3) controls this action. If it is off and you type '0B' then the letters '0' and 'B' will be inserted. If hex-entry is on (h in the title) then the byte &0B will be inserted. Use the overwrite mode (toggled via the insert key) to change the data without shifting the file. C.2 Word Mode ------------- This is similar to byte mode except the data is shown in word form. Typing characters with hex-entry mode off has no effect, but typing with it on inserts the given word in hex. C.3 Ascii Mode -------------- This mode displays data in ASCII dump form. Letters typed are inserted as usual. C.4 Code Mode ------------- This mode displays data in disassembled format with 1 instruction per line. Please note that in RISCOS 3, the debugger adds some extra information after some instructions, but some of this only appears if you disassemble sequentially. Eg TEQP R0,#0 followed by MOV R8,#0 gives the warning 'Not r8-r14'. However this may vanish if you are moving backwards up the file instead of forwards. This happens very rarely but it may cause confusion if you don't understand what's happening. The four most useful keys in code mode are cI,Left,Right,Return. For example if you are at the start of a module then pressing cI will cause you to jump to the start offset of the module. If you are on an instruction 'BL &00012345' or 'ADR r0,&01822445' then pressing Right will jump to the indicated address. At any time, Left will move you back to your previous position. This jumping uses the marker buffer and can be done to any depth you require. The RETURN key enables you to edit an instruction (via the ASSEMBLE command). When you press it, the minibuffer will be opened with the current instruction entered as default. You should then edit the instruction and press RETURN again for it to be assembled and written back. The assembling is done by the ZapBASIC module which tokenises the instruction and then uses the BASIC assembler. Hence you may use the basic functions ASC,EQUD,ADR etc. If the file is typed 'Module' then the first few offsets display the module entry point name rather than the instruction. C.5 BASIC Mode -------------- This mode edits BASIC files directly in detokenised form. See !Zap.Modules.!ZapBASIC.!Help for many more important details about how to use this mode. 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. C.6 BASTXT Mode --------------- This edits BASIC files in detokenised form. See !Zap.Modules.!ZapBASIC.!Help for many more important details. C.7 Email mode -------------- This mode is designed for editing Email messages. '!Zap.Modules.!ZapEmail.!Help' contains extensive help text. C.8 C Mode ---------- This provides a coloured C mode. See the directory '!Zap.Modules.!ZapMJE' for more details. C.9 C++ Mode ------------ This provides a coloured C++ mode. See the directory '!Zap.Modules.!ZapMJE' for more details. C.10 Java Mode ---------------- This provides a coloured Java mode. See the directory '!Zap.Modules.!ZapMJE' for more details. C.11 Throwback Mode ------------------- This mode handles the files generated by Zap's search to buffer, C throwback and !Find info output. Double clicking on an item will jump to that item in the source file. Shift double clicking will jump to the item and then kill the throwback buffer. Clicking ADJUST on a line will remove the line from the file. Treble clicking will move to the match and then bring the window to the front of the window stack. Also note that RETURN acts in the same way as double click and DELETE in the same way as adjust if you move into the file. C.12 Taskwindow Mode -------------------- This mode handles task windows. See the !Zap.Modules.!ZapBASIC.!Help file for more details. C.13-C.31 These modes are reserved ---------------------------------- ************************************************************************* * Section D: Search and Replace * ************************************************************************* D.1 The Search window --------------------- Zap has quite a powerful search facility which is based loosely on emacs search, allowing 'OR' constructs and character ranges. The search window can created by pressing F4 or F7 or using the 'file' menu. Pressing F4 will ensure that search matches are jumped to, whereas pressing F7 will cause all matches to be placed in a separate throwback buffer. Double clicking on a match in the buffer then jumps to the match. Throwback is covered in section C.11. The first column of the search window selects various search options. These differ from earlier versions of Zap. 'Raw search' - If this option is ON then the whole file will be treated as a single line of text and searched accordingly. Thus \< will match the start of the file only and \> the end of the file. A search will produce the same result regardless of the mode a file is in. If this option is OFF then the file is searched in lines. This means that \< matches the start of a line and that you cannot match across lines. In Basic mode the lines are detokenised so that you can match PRINT and substrings of it. In Code mode the lines are disassembled so that you can match substrings of instructions. 'Case sensitive' - If this option is ON then strings of letters will only match if their case agrees. If it is OFF then strings will match regardless of case. 'Use macros' - In order that the user may have any search syntax he/she chooses, the following approach has been adopted: 1. All wildcards/commands begin with a '\' as listed below. 2. The user may define up to 16 macros (aliases) in terms of these commands. 3. When the search string is entered, all the user's macros are substituted before the search takes place. Macros may be examined and altered by clicking on the 'Show Macros' button. If this option is switched OFF then the macros are no longer substituted when the search string is entered. The default macro definitions are stored in the 'Keys' file and may be altered there. (For example; * is by default a standard macro for \.\*. Thus if a*b is used, 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.) '"\" commands' - If this option is switched OFF then \ will match the character \ and not introduce a command (like \10). Hence, none of the commands below will work. The second column selects where the search should start and the direction of the search. You may start at the beginning of the text or forwards/backwards from the current cursor position, or search through all files (forwards from the start of the first file in the stack). The third column selects the output. If the 'to Window' option is OFF (F4) then the cursor will be moved to the first match and subsequent matches may be got by sF7 (Next match) and scF7 (Previous match) as in the Basic Editor. A beep will sound if there are no more matches and the cursor will not move. If the option is ON (F7) 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. All these options can be toggled by using ctrl-letter keys where 'letter' is the first capitalised letter of the option or ctrl-\ in the case of \ commands. There are a number of other short cuts in the window, for example, ctrl-P pastes the current selection in Zap into the whichever search/replace window icon has the cursor. Ctrl-K clears the history, Page Up/Down and the cursor keys navigate the history, and ctrl-Tab replaces the entry with the one used in the last search. The table below details all the escape characters and commands. In it 'x' will be used to stand for any ASCII character unless otherwise mentioned. x Matches character 'x' (according to case sensitivity). \x Matches 'x' case sensitively, unless \x mentioned below. `x Matches 'x' only (without any replacement of macros). \( \) Act as brackets for nesting expressions. \{ \} Act as the normal brackets above, but may be referred to in the replace string during a search and replace. See E.2. \# Matches any character. Eg a\#d matches 'and','aad' but not 'ad'. \. Matches any character except the return character. \* Matches any number of the previous expression. Eg fo\* matches 'f','fo','foo' etc. and \(and\)\* matches '','and','andand' etc. \% Matches the most number of repetitions of the previous expression. Thus \[0-9]\% matches '1' in '1pt' and the '395' in 'ab395rty'. \| Matches one expression OR another. Eg hello\|goodbye\|fred. Eg \(a\|b\)\* matches 'abababa','abbba' etc. \[..] Matches a range of characters. 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 null string at line start (and file start). \> Matches null string at line end. \+ Turns on case sensitivity for the following letters ONLY. Its effect stops at the next wildcard/bracket/command. It doesn't affect nested/bracketed statements - this will be improved. Eg \+Fred\|Bill matches Fred case sensitively but not Bill. \- As above, but turns off case sensitivity. \\ Matches a '\'. \ddd Where d is any decimal digit matches that number. Eg '\0alf' matches byte 0,'alf' and \233 matches byte 233. Please note that \999 matches byte 99 followed by '9' as 999>255. \&hh As above but matches the hex byte hh when h are valid hex chars. \A-\Z Match ctrl A to ctrl Z. \a Matches alert (7) \b Matches backspace (8) \f Matches a form feed (12) \hdd... Where d's are hex digits. Match the given word (32 bit number). \n Matches a new line (10) \o Matches any character except a '.' (useful for matching filenames). \r Matches a return (13) \t Matches a tab (9) \v Matches a vertical tab (11) \wdd... Where d's are decimal digits. Match the given word (32 bit number). \xhh Matches hex numbers as above (where 'x' is the letter 'x'). In the examples below, the default macros are assumed. Please note that you may macro the macros! Eg, you could define '(' to be '\(' and '\( to be '(' if you wished. Examples: cat\|mat Matches cat or mat. re*ment Matches any occurrence of 're' then 'ment' on a line. SWI Matches any SWI (in code mode). LDR\|STR Matches any load or store instruction. R6 Matches any instruction using R6. BL*&0000A95C Matches any call to &0000A95C. \&0A Matches the byte &0A. \= 2.67) Up / sUp Recall line Down / sDown Next line cUp First line in recall buffer cDown Last line in recall buffer These keys can be redefined by commands, but should remain as consistent as possible with the above. E.6 Explanation of some menu entries ------------------------------------ Not all menu entries have completely self-explanatory titles, and sometimes the supplied help data may not be sufficient to indicate the proper usage of the supplied options. This section concentrates on menu entries which have been added since version 1.35 of Zap. Zap.Edit menu: Zap.Edit.Tab Mode: This menus has a number of options which affect how tab characters are entered. To affect how tabs are displayed see the Zap.Display.Tabs menu. 'unix tabs' Refers to ordinary 8-column tab stops. 'As above' Is the option referred to as !Edit tabs in previous versions of Zap. When tab is pressed the cursor jumps to what it thinks will be the most useful column, using the previous line as a template. If this line is not long enough, then the nearest line above which is is used. If none of the preceding lines are long enough a 'unix tab' is used. 'Column tabs' These are like unix tabs, but may be set to a user definable width. 'As spaces' If set tabs are inserted as spaces. If clear then tabs are inserted as tab characters (09) where possible. If the proposed tab stop is not aligned to where a physical tab would end, then spaces are inserted until the correct column is reached. Note that there is also an option with the same name at 'Zap.Display.Tabs.As spaces'. This has a different action - distinguishing between the two actions is recommended. Zap.Edit.Type of wrap: This menus' options affect how Zap treats windows which have lines which are longer than the length which will currently fit into the physical window. 'Window wrap' This performs the same action as the option with the same name in !Edit. Lines which are longer than will fit into the window are wrapped onto the next line. This happens dynamically as the window is resized. There are never any parts of the text which are not visible at the sides of the screen. As a consequence, the horizontal scroll bar cannot be dragged, though it still indicates the true maximum window width and can be adjust-dragged. 'Soft wrap' This option controls how words are wrapped at line ends. It defaults to being off. When turned on, the display of paragraphs is reformatted dynamically as you type, in order to avoid words being split across lines. Different modes can choose where to split words, so, for example, HTML modes can choose to split at the ends of tags. Note that no physical line ends are ever inserted unless the use requests it. 'Word wrap' This acts in a very similar manner to soft wrap, except that line breaks are inserted at line ends as you type. The rest of the paragraph is reformatted accordingly, with spaces and line ends swapping position accordingly. In Email mode, quoting is preserved while the reformatting occurs. 'Line wrap' Like the 'Word wrap' option, except the effect is much more local - the rest of the paragraph is /not/ reformatted. 'Infinite wrap' This is best thought of a sub-option of 'Window wrap'. When on, window wrap allows the width of the window to increased indefinitely. This option is rarely very useful in practice. 'Auto-soft wrap' When on, whenever a file is first displayed by a mode a check is made to see whether it has any long lines. If it does, soft-wrap is engaged automatically. 'Strong soft wrap' This option affects how physical line ends are treated when soft wrap is turned on. It affects mainly the jump to start/end of line options (normally bound to cLeft and cRight), delete to line start/line end, and auto-indent. With the option on, the illusion that the different physical lines are separate entities is much stronger. The idea of a logical line, is hidden as much as possible (although logical line numbers are still available). With it off, editing is much more like it usually is with no soft-wrap, and auto-indent behaves in a more useful manner, looking at the start of the previous logical line, rather than the previous physical one. Zap.Edit.Cursors: The options here affect how Zap's cursors operate. 'Line Select' Controls how selections are made and insertions are positioned. With it on, selections which span more than one line are confined so they always select entire lines. Insertions of regions which contain more than one line are always made at the start of the line where the cursor is, and not at the exact cursor position. This is much like the selection model implemented in BASIC mode. Though this description may sound obscure and the option is usually off by default, it is often very useful. In modes, like assembler mode where lines are rarely very long, it cuts out a number of operations - selections can be made lazily, and there's no need to manually align the cursor before each paste - consequently much time is saved. 'Smart' Affects the behaviour of sLeft and sRight, and related functions (e.g. the delete word options). It is turned on by default. When turned off, these operations stop at spaces and not much else. When on the action feels as though it is much more intelligent. 'ConfineH' Affects the behaviour of cursor right. When the option is on the cursor cannot be moved beyond the end of a line by pressing the right arrow - instead it moves to the start of the next line. This keeps the cursor near existing editable text and more accurately reverses the behaviour of cursor left. Many other editors which can't cope with the cursor's position not being uniquely described by its offset in the file do this, so some may find it familiar. It is off by default, allowing the cursor to be easily moved beyond the end of lines (which is often useful when moving the cursor manually around the file). 'ConfineV' Affects the behaviour of cursor up and down (and other operations which move the cursor vertically). When the cursor moves vertically into a line which does not extend horizontally as far as the current cursor position, the cursor is moved to the end of the line. The preferred horizontal position is remembered. It has the virtue of keeping the cursor near editable text, and simulates the behaviour of many primitive editors. 'Free click' If on then cursor clicks are not confined to the end of the line which they are made on. Instead the cursor can be positioned anywhere in the visible region. This option may be of use to those generating ASCII art. It is off by default. Zap.Edit.Misc: The options here ae editing options which don't fit into other categories. 'Hex entry' If on then ASCII entry is disabled, and entry is in hexadecimal, or binary if a binary display is being used. This is also covered in section C.1 (Byte Mode). 'Line edit' If on then line breaks cannot be deleted by the user by using normal delete operations, and inserting a new line by pressing return does so after the end of the current line. JOINLINE and SPLITLINE still perform these functions as normal. 'Non standard' This option is currently only implemented in ZapBASIC where it strips spaces dynamically from the ends of lines as they are entered. In other modes it may in the future perform other functions. 'Spell check' Engages Zap's spell-as-you-type operation, which uses ZapSpell. Zap.Options.Misc On the icon mar menu, this menu controls a number of options: 'Autoload' leads to a menu which controls the loading of a variety of modules by Zap. 'Auto-del files' causes files to be removed from Zap when their windows are closed. 'Auto-clr regions' makes the selected region be cleared whenever an insertion or deletion is performed. 'Undo supported' configures whether all new files have undo buffers. 'Flashing cursor' makes the cursor flash. 'Check datestamp' examines date stamps and reports (and queries) when files which are being saved are older than those that are being overwritten. 'Auto-clr search' this controls whether the search, search and replace and goto boxes are cleared each time they are displayed. 'Confine cursor' stops the cursor ever going outside the visible window. 'Trap MSDOS files' ...and convert their LFCR combination on load/save. 'Be tolerant' process broken and badly-formed WIMP messages. This option has been added mainly because of a bug in most versions of Fresco. This application won't OLE HTML files to Zap unless this option is ticked. ANT have been informed of this problem. 'Silent operation' causes Zap not to beep. 'No anti-aliasing' inhibits the DSA redraw outline font attempt at anti-aliasing (as it is far from perfect). ************************************************************************* * Section F: How to find out more * ************************************************************************* F.1 Other help files -------------------- The 'HelpData' file contains help for all the leaf windows, main windows, and commands. You can view this by using Acorn's !Help application, or just by loading the text file. On RISC OS 2/3.0 you cannot get help on the menu entries, only the windows (but you can just read the file directly). For those interested in writing an extension mode, or adding new commands, or Zap's internal workings, please look in the Docs directory. You should start with the file called !ReadMe. This directory also contains a Zap keystrip in the form of a Draw file. Please see the file 'Changes' for future plans for Zap. F.2 Obtaining future versions of Zap ------------------------------------ Future versions of Zap will be sent to: 1) Hensa: e-mail: archive-server@micros.hensa.ac.uk (send message 'help') ftp : micros.hensa.ac.uk (IP 148.88.8.84) (outside office hours only for those not on Janet) 2) The Archimedes Public Domain Library (run by David Holden): 39 Knighton Park Road Sydenham London SE26 5RN Please look at the 'Changes' file for any anticipated release date. F.3 Contacting us with suggestions/bugs --------------------------------------- Suggestions and bug reports are welcome. See the Copyright file for the relevant addresses (E-Mail preferred). Suggestions are welcome, but please try to bear in mind that there is already a long list. If you find a bug then please try to give as many details as possible as to the circumstances that cause it - try and get it repeatable. If you have a comment on a Zap extension mode then please direct comments to it's author, rather then the Zap developers in general (see Modules.!ReadMe). We hope you find Zap a useful program. Dominic Symes Tim Tyler Darren Salt James Aylett Martin Ebourne