home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / mag_discs / 2 / programs / !Zap / !Help < prev    next >
Text File  |  1992-10-19  |  15KB  |  364 lines
  1. *****************************************************************************
  2. * >!Help file for !Zap version 0.70                        *
  3. * All code is copyright Dominic Symes 1992. Please read 'Copyright' file.   *
  4. * NB This program needs the COLOURS module to run. It is in !System.Modules *
  5. *    on Acorns Application disc 1. If in doubt, double click on !System.    *
  6. *****************************************************************************
  7.  
  8. This is the first release of the text editor !Zap.
  9.  
  10. Main features:    * Display may be in text, byte or disassembly format
  11.         * All key short cuts are user redefinable
  12.         * Automatic updating line numbers & file addresses
  13.         * Full (unix style) wildcard search with your own definable
  14.           macros and search 'throwback' buffers
  15.         * Proper unix tabs and true scrollbar operation
  16.         * Full undo on all operations
  17.         * COPY key causes standard cursor editing
  18.         * All features tested on RISCOS 2 and RISCOS3
  19.         * Fast redraw
  20.         * Full printer driver interface and quick print output
  21.         * Any number of markers on each file, and a facility for
  22.           following branches in disassembly mode
  23.         * Search as you type
  24.         * Learns keys sequences
  25.         * Emacs style Yank (Cut & Paste) and !Edit style move and
  26.           copy implemented.
  27.         * C throwback supported
  28.         * Reads disc sectors/tracks
  29.  
  30. In production:    * Proper BASIC editor 'extension' mode for editing basic
  31.           programs.
  32.         * Fully documented interface so that YOU can write an
  33.           extension mode for zap
  34.         * C programmers extension mode with bracket matching.
  35.  
  36.  
  37. Keys and commands
  38. -----------------
  39.  
  40. Each key has an associated command as given in the 'Keys' file. On startup,
  41. Zap reads this file to create the current key bindings. Thus by editing
  42. the keys file you may change the action of any key to your preference.
  43. Keys not mentioned in the 'keys' file are passed on (eg F12).
  44. A summary of the default setup is given below: (s=shift c=ctrl)
  45.  
  46. Command:    Default key:    Action:
  47.  
  48. DELETE        Delete        Delete last character
  49. DELETENEXT    sDelete        Delete next character
  50. TOGGLEINSERT    Insert        Toggle insert and overwrite modes
  51.                 (shows o in title)
  52. COPY        Copy        Initiates copy mode à la Basic Editor.
  53.                 Note that you may copy from one window to
  54.                 another by selecting on the other.
  55. SELREGION    cCopy        Starts selection of a region via cursor keys.
  56.                 Press Escape to end the selection.
  57. DUMPFILE    scCopy        Produce text image of this file.
  58. ESCAPE        Escape           Stops copy modes/selection modes/search
  59.                 as you type mode/yank mode
  60. TAB        Tab        Inserts a variety of tabs - see tab menu.
  61. FASTUNDO    <-|        See cH
  62. QUICKPRINT    Print        Send file directly to printer
  63. PRINTFILE    sPrint        Print file through printer driver
  64. OPENPRINTER    cPrint        Open printer: filer window
  65. CLOSEPRINTER    scPrint        Close printer: filer window
  66.  
  67. Cursor keys:
  68.  
  69. LEFT        Left            Moves 1 left / goto last mark in code mode
  70. RIGHT        Right        Moves 1 right / jumps to address in code mode
  71. DOWN        Down        Move 1 line down
  72. UP        Up        Move 1 line up
  73. SLEFT        sLeft          Move back one word
  74. SRIGHT        sRight        Move forward one word
  75. SDOWN        sDown/PageDown    Move down a page
  76. SUP        sUp/PageUp        Move up a page
  77. CLEFT        cLeft        Move to start of logical line
  78. CRIGHT        cRight        Move to end of logical line
  79. CDOWN        cDown        Move to end of text (and leave marker)
  80. CUP        cUp        Move to start of text (and leave marker)
  81. SCLEFT        scLeft        Move to the left without moving cursor
  82. SCRIGHT        scRight        Move to the right without moving cursor
  83. SCDOWN        scDown        Move down without moving cursor
  84. SCUP        scUp        Move up without moving cursor
  85.  
  86. Function keys:
  87.  
  88. EXECUTE        F1        Execute currently learnt key sequence (see scL)
  89. HEXASCII    F2        Toggles hex entry mode when byte/word editing
  90.                 (h in title)
  91. SAVE        F3        Brings up save box. You may change filetype
  92.                 etc by moving to the relevant box. Or click
  93.                 the menu button to bring up file type menu.
  94. SEARCHCUR    F4        Brings up Search by Goto box. (See later)
  95. GOTO        F5         Brings up goto line box
  96. TOGGLEMARK    F6         Inserts marker in text/deletes marker
  97. SEARCHBUF    F7        Brings up Search to buffer box. (See later)
  98. FULLUNDO    F8        Full undo (takes slowest path in undo tree)
  99. REDO        F9        Redo (undo last undo whether full or fast)
  100. DELLINE        F10        Delete current line
  101.  
  102. SPLITLINE    sF1        Split line (Inserts a return)
  103. REPLACE        sF4        Brings up search and replace window.
  104. WORDWRAP    sF5        Toggle wordwrap mode (w in title)
  105. LASTMARK    sF6        Previous mark (eg after ctrl-down by mistake)
  106. NEXTMATCH    sF7        Next match (after an F4 or F7)
  107. DELTOSTART    sF10        Delete to start of line
  108.  
  109. JOINLINE    cF1        Join line (delete next return)
  110. SWAPWINDOW    cF2        Swap window (after using new view)
  111. NEWVIEW        cF4        New view (open new window on this file)
  112. HELP        cF5        Brings up help text
  113. NEXTMARK    cF6        Next mark (see sF6)    
  114. LASTMATCH    cF7        Previous match (see sF7)
  115. DELTOEND    cF10        Delete to end of line
  116.  
  117. MODE0        scF1        Text mode  (display in standard text format)
  118. MODE1        scF2        Byte mode  (display in hex bytes)
  119. MODE2        scF3        Word mode  (display in hex words)
  120. MODE3        scF4        Ascii mode (display in characters)
  121. MODE4        scF5        Code mode  (display in disassembled code)
  122. MODE5        scF6        extension mode - 5
  123. MODE6        scF7        extension mode - 6
  124. MODE7        scF8        extension mode - 7
  125. MODE8        scF9        extension mode - 8
  126. MODE9        scF10        extension mode - 9
  127.  
  128. Ctrl letters:
  129.  
  130. CLEFT        cA        Start of line   - emacs compatibility
  131. LEFT        cB        Back a char     - emacs compatibility
  132. COPYSEL        cC         Copy selected region to current position
  133. DELETENEXT    cD        Delete next char- emacs compatibility
  134. CRIGHT        cE        Line end    - emacs compatibility
  135. RIGHT        cF        Forward a char  - emacs compatibility        
  136. CANCEL        cG        Cancel search 'as you type' and return to
  137.                 start. Also cancel any yank operations.
  138. FASTUNDO    cH <-|        Fast undo (takes fastest route in tree)
  139. INDIRECT    cI        Indirect (move to the address given by word
  140.                 at cursor)
  141. DELTOEND    cK        Kill line    - emacs compatibility
  142. LEARN        cL        Learn key sequence (see later on)
  143. RETURN        cM        Inserts a return character
  144. DOWN        cN        Next line    - emacs compatibility
  145. UP        cP        Previous line    - emacs compatibility
  146. SEARCHBACK    cR        Reverse search 'as you type'
  147. SEARCHFORWARD    cS        Search 'as you type' forwards
  148. SELECTBUFFER    cT        Select entire buffer
  149. MOVESEL        cV        Move selected region to current position
  150. CUT        cX        Cut/Delete selected region
  151. YANK        cY        Paste/Yank selected region
  152. CLEARSEL    cZ        Clear selection
  153.  
  154. ADDRESSES    scA        Addresses shown at line start
  155. INSERTDATE    scD        Insert current date (format is given in the
  156.                 file 'keys')
  157. NEXTTRACK    scI        Move forward one track
  158. LASTSECTOR    scJ        Move back one sector
  159. NEXTSECTOR    scK        Move forward one sector
  160. LOGICAL        scL        Logical line numbers shown at line start
  161. LASTTRACK    scM        Move back one track
  162. NOLINENOS    scN        Removes line numbers/addresses
  163. TOGGLEHEX    scO        Line numbers shown in hex/decimal
  164. PHYSICAL    scP        Physical line numbers shown at line start
  165. SWAPCHARS    scQ        Swap next two characters around
  166. READONLY    scR        Toggle read only state (r in title)
  167. SWAPCASE    scS        Swap case of next character/selected region
  168. INSERTTIME    scT        Insert current time (format is given in the
  169.                 file 'keys')
  170.  
  171. Letters:
  172. --------
  173.  
  174. In text mode letters are inserted as usual.
  175. In byte mode letters are inserted as usual unless in hex mode (F2) when
  176.  the keys a-f,A-F,0-9 enter hex digits
  177. In word mode + hex mode keys a-f,A-F,0-9 enter hex digits
  178.  
  179. The window title
  180. ----------------
  181.  
  182. Title heading characters:
  183.  *        File altered since last saved
  184.  R        Read only and fixed as read only
  185.  r        Read only but can be toggled to read/write by cR
  186.  u        Undo supported by this file
  187.  o        Overwrite mode active (toggle via Insert key)
  188.  h        Hex entry mode active for Byte/Word (toggle via F2)
  189.  w        Wordwrap mode active (toggle via sF5)
  190.  
  191. Loading/saving files:
  192. ---------------------
  193.  
  194. (a) Double click on a text file to load it.
  195. (b) Hold down left shift and double click on any file typed file to load it.
  196. (c) Drag the file onto the zap icon to load it.
  197. (d) Drag file onto a zap window to insert it at cursor.
  198. (e) Hold down shift and drag file onto a zap window to insert its name.
  199. (f) Ram loads/saves are fully supported and you may save files into themselves.
  200.  
  201. SEARCH AND REPLACE
  202. ==================
  203.  
  204. 1) The Search window
  205. --------------------
  206.  
  207. The search window can be broght up by F4/F7/the 'Zap' menu on a file. 
  208.  
  209. The first column selects whether you wish to search for a string, instruction
  210. or word (4 bytes). In the first two cases enter the string to match. In the
  211. third case enter an expression evaluating to a number to search for.
  212.  
  213. The second column selects where the search should start and the direction of
  214. the search. You may start at the start of text or forwards/backwards from the
  215. current cursor position.
  216.  
  217. The third column selects the output. If you choose cursor output (F4) then
  218. the cursor will be moved to the first match and subsequent matches may be
  219. got by sF7 and scF7 as in the Basic Editor. If you choose 'to buffer'
  220. then all matches are placed in a new (text) file. Double clicking on entries
  221. in this text file cause the cursor to be moved to the corresponding match.
  222.  
  223. 2) Wildcards, macros and case sensitivity
  224. -----------------------------------------
  225.  
  226. In order that the user may have any search syntax he/she chooses, I have
  227. adopted the following approach:
  228.  
  229. a) All wildcards/commands begin with a '/' as listed below.
  230. b) The user may define up to 16 macros (aliases) in terms of these
  231.    commands.
  232. c) When the search string is entered, all the users macros are substituted
  233.    before the search takes place.
  234.  
  235. The macros may be examined and altered by clicking on the 'Show Macros'
  236. button. The default macro definitions are stored in the 'Keys' file and may
  237. be altered there. Whether the search is case sensitive or not can be
  238. controlled by a radio icon in the Macro definitions window.
  239.  
  240. For example, I have * as a standard macro for \#\*. Thus if I typed in
  241. a*b, the string would be converted to a\#\*b. However a\*b would remain
  242. as a\*b as the * follows a \ and is thus treated as a command.
  243.  
  244. Full details of the wildcard commands are given below:
  245.  
  246. x (any char)    Matches 'x' (according to case sensitivity)
  247. \x        Where x is not one of the below matches 'x' case sensitively
  248.  
  249. \( and \)    Act as brackets for bracketing expressions.
  250. \{ and \}    Act as the normal brackets above, but may be referred
  251.         to in the replace string during a search and replace.
  252.  
  253. \#    Matches any character. Eg a\#d matches 'and','aad' but not 'ad'.
  254. \*    Matches any number of the previous expression. Eg fo\* matches
  255.     'f','fo','foo' etc. and \(and\)\* matches '','and','andand' etc
  256. \|    Matches one expression OR another. Eg hello\|goodbye\|fred.
  257.     Eg \(a\|b\)\* matches 'abababa','abbba' etc.
  258. \[..]    Introduces a range of characters to match. Eg \[a-zA-Z%] matches
  259.     any letter or a '%'. If a '^' is given after the opening bracket then
  260.     it acts as a NOT. Thus \[^abc] matches any character except a,b,c.
  261.  
  262. \<    Matches line start (and file start) (useful in code mode)
  263. \>    Matches line end
  264. \C    Turns on case sensitivity for the following string only.
  265.     Eg \CFred\|Bill matches Fred case sensitively but not Bill.
  266. \c    As above but turns off case sensitivity.
  267. \\    Matches a '\'
  268.  
  269. \xxx    Where x is any decimal digit matches that number
  270.     Eg '\0alf' matches 0,'alf' and \233 matches byte 233
  271.     Please note that \999 matches byte 99 followed by '9' as 999>255.
  272. \&xx    As above but matches the hex byte xx when x are valid hex chars.
  273.  
  274. In most cases you will wish to macro '|' as being '\|' and '(' as '\(' etc.
  275.  
  276. Examples (in code mode):
  277. ------------------------
  278.  
  279. SWI                will match any SWI
  280. LDR\|STR        will match any load or store instruction
  281. R6            will match any instruction using R6
  282. BL\#\*&0000A95C        will match any call to &0000A95C
  283.  
  284. 3) Interrupting the search
  285. --------------------------
  286.  
  287. The search will be MUCH faster if you give a definite first character to
  288. start with. Eg 'a\(nd\|pple\)' will be a lot faster than 'and\|apple'.
  289. If the search takes longer than 1/3 second, then an hourglass will come
  290. up displaying the position in the file as a percentage underneath.
  291. You may stop the search by pressing escape, and the partial results will
  292. be displayed if you are using 'Search to buffer'.
  293.  
  294. I think the above should satisfy most persons needs. Please tell me of any
  295. bugs/improvements.
  296.  
  297. 4) Search and Replace
  298. ---------------------
  299.  
  300. A search and replace is activated by sF4 or the File menu. You may
  301. select the search start and direction as above. You may also select
  302. whether the replace is to be selective or global.
  303.  
  304. The format of the search string is described above. The replace string
  305. has the following format:
  306.  
  307. \xxx    replace with the decimal byte xxx as above.
  308. \&xx    replace with the hex byte xx as above.
  309. \x    (for any other character x) replace with a 'x' (eg '\\' -> '\')
  310.  
  311. &n    (where n is 1-9) means replace with the n'th \{,\} expression in the
  312.     search string.
  313.     Eg If the search string is 'a\{\#\}d'
  314.      and the replace string is 'b&1e'
  315.     Then 'and' will be replaced by 'bne' and 'aad' by 'bae' etc
  316. &&    replace with an '&'
  317.  
  318.  
  319. 5) Learning key sequences
  320. -------------------------
  321.  
  322. To learn a new key sequence press cL and then type the sequence. A beep will
  323. be sounded after each logged character to remind you that these key presses
  324. are being buffered. Press cL again to end the sequence. NB ESCAPE will NOT
  325. end the sequence so that escape can be used as part of the sequence.
  326. Pressing F1 will EXECUTE the given sequence.
  327.  
  328. Examples:
  329.  
  330. cL cLeft - > Down cL        ; inserts -> at line start when F1 pressed
  331. cL cS C A T ESCAPE S cL        ; searches for next occurrence of CAT and
  332.                   adds S on the end to get CATS
  333.  
  334. 6) Search as you type
  335. ---------------------
  336.  
  337. Search as you type is activated by pressing cS or cR. The following characters
  338. typed by you are treated as a search string. The cursor is moved to the end
  339. of the next matching search from where you started. You may use 'delete'
  340. to remove characters from the search string. If there is no match then a
  341. beep will sound. This continues until you press a non character key (eg
  342. Escape or a cursor key) in which case the search will halt at the current
  343. position. Alternatively, pressing cG will cause the search to be cancelled
  344. and the cursor returned to its initial position.
  345.  
  346. 7) Miscellaneous
  347. ----------------
  348.  
  349. If the 'Auto delete' option on the Options menu is set then when the last
  350. window on a file is closed, the file is deleted as in !Edit. If the option
  351. is not set then the file remains in memory and new windows can be opened
  352. on it via Create.New view menu option as in !Impression.
  353.  
  354. If the 'Undo' option on the Options menu is unset then newly created files
  355. do not have full undo storage, and operations cannot be undone (other than
  356. by yank). This saves a little memory.
  357.  
  358. =====================================================================
  359.  
  360. I hope you find Zap a useful program.
  361.  
  362. Dominic Symes
  363. September 1992
  364.