HKeysEPM -- A patch for the way EPM handles redefinition of keybindings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ and other stuff for EPM -- Copyright (C) 12/1996 by "Herbert" M. Dietze ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Version 1.0 ~~~~~~~~~~~ Introduction ~~~~~~~~~~~~ OK, that's it, folks! I (like quite a few other people) was looking desperately for a good programmer's editor under OS/2 PM which was desired to be fully configurable with keyboard, compiler messages handling etc. IBM's EPM bears those features but its key bindings aren't very easy to configure - you have to get rather deeply into the macro sources written in E. Another thing was that I liked that handling of Borland IDEs like hungry backspace, an enter holding the indent level and last but not least its WordStar based keymap. At last I saw no alternative to getting into that E programming stuff and the result seems to be OK for my needs though it's surely not always the best way I chose to do this or that. If this is your first experi- ence in programming the EPM I'd suggest to read the "confused now?" sec- tion below now! The basic idea is to put all key definitions into a seperate file and leaving all that 'compile if' etc. stuff in its stdkeys.e file. I therefore had to change my stdkeys.e file replacing all 'def ?key' parts followed by more than one instruction by self explaining command names 'defproc ?name' (except from *enter, this did not seem necessary). Now any action performed by a keystroke has its own name. These names are used to define all keys in seperate keymap files like 'mykeys.e' (EPMs usual way to do things like this) like 'def ?key = ?command'. You'll still have to use E syntax but it looks much nicer - and you can define two key commands (like used in WS or Emacs). I've included a demo file with the key bindings I use (they're a bit like qedit, a bit like WS and the rest is just my invention) - mykeys.e. The EPM will still behave like it used to if you don't compile with a mykeys.e file with definitions overriding those from stdkeys.e. If you don't want any of EPM's standard key definitions on keys you haven't defined explicitely you've got to insert empty def's for all keys you don't need in your mykeys.e file (In fact that's the way I did it in my mykeys.e file). I used the EPM 6.03 beta version but there should be no problem with OS/2 2.*'s 5.51 version or any later 6.x release. I've made some changes to my stdkeys.e and ckeys.e files to make them compile with EPM 5.x. It _seems_ to work - though there might still be some routines called that EPM 5.x can't handle. You'll have to fix that yourself! Of course, macro sources and macro compiler are absolutely necessary. Files in this Package ~~~~~~~~~~~~~~~~~~~~~ stdkeys.e : Patched StdKeys.e - defines commands for each keystroke triggered action. Needs herbert.e. mykeys.e : My key definitions (bit like WS / qedit). mymenu.e : My menu file (with the key binding descriptions defined in mykeys.e in the pulldown menus). herbert.e : Contains helper routines. These are a function for en- hanced handling of the enter key (must be activated via the HOLD_INDENT_IN_STREAM_MODE constant) which is cal- led from my stdkeys.e, an extra routine for special handling of the '}' character under C/C++ and a routine for a smarter backspace (like in Borland ide's) . mystuff.e : Just in case you don't already use one! Contains only one line "tryinclude 'herbert.e'". epmhelp.qhl : Text file with quick key reference for my own keymap mycnf.e : My own mycnf.e - modify it as you like it! stdkeys.org : Original stdkeys.e from my EPM package. You may want to have a look at it to find out the difference from yours readme.txt : This file. COPYING : The GNU public license. license.txt : License for EPM files. Installation of the keymap patches for EPM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Backup your std*.e files. 2. Unzip the hkeysepm.zip archive into an own directory (assuming you've already done this :-) 3. Get my versions of stdkeys.e installed. You could do this either by taking my adds from my files and put them into yours (looks like too much work normally) or by just taking my version of stdkeys.e and trying it. It should not be too difficult to fix problems that might occur (EPM gives you messages like 'unknown procedure ...' in the status line when a routine calls something EPM doesn't know, so all you've got to do is grep for this name through your macro directory and fix it!). What I changed with my stdkeys.e file: - replaced most 'def = ' occurances to 'def = call ' and then 'defproc '. So there still are the default key bin- dings active if you don't override them. - changed the definition of the enter command to use my own routine 'henter_common()' instead of 'enter_common()'. This only applies to stream mode and will behave the default way if you set the constant HOLD_INDENT_IN_STREAM_MODE to 0 in your mycnf.e file. This makes the file herbert.e necessary. If you don't like this just change any occurrence of 'henter_common' to 'enter_common' in stdkeys.e. - added some conditional stuff to make it compile under EPM 5.x. 4. Copy the mykeys.e file into the E sources directory and modify it if you like - maybe better wait until all that stuff works! ;-) 5. Edit your mycnf.e file the way you like it. Be sure that VANILLA is not set to 1. 6. If you've just copied my stdkeys.e file over yours copy herbert.e in- to your sources directory. Then add "tryinclude 'herbert.e'" to your mystuff.e file (create one if necessary!) 7. If you want to use my key definitions you may also want to use my menus and my keyboard summary file: - Copy my epmhelp.qhl into your E source directory (backup your own before, be sure you replace it), it contains a short key bindings summary when you press Alt-F1. - Copy the file mymenu.e into your E source directory and change the value of "STD_MENU_NAME" in mycnf.e to the new menu file name. 8. Now change into your .ex files directory (if different from your E sources directory) and recompile your epm.ex and extra.ex (etpm epm, etpm extra). 9. If it all works now you can redefine your key bindings simply by editing your mykeys.e file and recompiling epm.ex. Confused now? ~~~~~~~~~~~~~ If this is your first experience in configuring EPM you might like to read this - it's meant as a SHORT summary of EPM's concepts for primers. If you take a look into the directory containing EPM's files you'll find a file EPM.EXE and several .ex files. Roughly speaking all that EPM.EXE does is initializing a PM window and then reading the macro files EPM.EX and (if existent) EXTRA.EX. Those files completely define EPM's behavi- our as an editor. They also tell EPM which other .ex files it has to read at startup. The EPM toolkit contains all macro sources and the mac- ro compile ETPM.EXE you need to compile those sources. To install this EPM toolkit you've got to copy all dll's to a directory in your libpath (I'd suggest to backup your old ET*.DLL files and simply replace them). Then put the exe's, ex's and hlp's into their own direc- tory (I'd suggest not to use \os2\apps as there will be quite a large number of files). Add this directory to your path and help statements in your config.sys file. Put the macro sources into the same or a seperate subdirectory (I prefere the latter). Change the epmpath statement in your config.sys file to the dir[s] you now use to store EPM's exe's and sources. If necessary change the settings of your EPM object on your desktop and then - finally - reboot. Try your 'new' EPM. If you've had a non English version before - you might wonder now. Sorry, there is no alternative, you'll either have to learn English or know your EPM by heart :-) Now the main modules EXTRA and EPM consist of the sources EXTRA.E and EPM.E that include several other files by default. If you want to make any changes - like include own routines - you can do this in files star- ting with 'my' like mycnf.e, mystuff.e, mykeys.e. ETPM always _tries_ to include them when compiling - so if there is a file of that name present when compiling it will be read. If you only want to modify EPM's key bindings you'll have to take a clo- ser look at STDKEYS.E. It uses a construction like "def c_u = 'undodlg'" to bind the key Ctrl-U to the (very neat) undo dialog. If - like here - there is a name in quotes ('undodlg') this means we deal with a pseudo command that you can use from EPM's command dialog. This makes the .ex files rather large and should not be used too excessively. The other way is simply calling a procedure like "def enter = call my_enter_proc()". This is the preferred way to handle things you don't need to enter from the command dialog. For performance reasons the folks at IBM did not define a procedure for all complex command sequences performed by key commands but if you want to do serious key remapping there is no alternative to this (and this just what I did for this package!). If you now add a file MYKEYS.E to your sources and compile it it will be automatically included by ETPM. All key definitions in there will simply override those from stdkeys.e - this is no error and just normal. OK, back to recompiling EPM (I know I sometimes talk too much ) - you have changed a little something to EPM's standard behaviour, now you've got to recompile all modules affected by this. In our case this is the file EPM.EX. If you've changed any constants in mycnf.e (You can use a quite large number of constants [with rather self explaining names] to switch on / off features before compiling - play around with them if you like, it's a real powerful means) you should also recompile EXTRA.EX, so let's just get used to always recompile both! To recompile your EPM now first change into the directory containing the .ex files (no matter where the sources are - as long as their directory is in the EPMPATH) and then enter the command "etpm epm". If this was successful put "etpm extra". I'd suggest to first leave out my patches to try if it all works well but include the sample file OS2TOOLS.CFG (rename it to mycnf.e first) even if you haven't the slightest idea what it all means. There's just a couple of definitions that should make sure you get no unnecessary trouble when compiling the package for the first time! As long as you don't modify any modules using their own .ex file you should never need to recompile any other files than EPM and EXTRA. Almost Finally ~~~~~~~~~~~~~~ OK, I hope you were lucky to get all this properly installed. After having been on this for about a week this all seems absolutely natural and easy but I guess it won't be for you :-) However I think it's worth it - my EPM now behaves (almost) absolutely the way I like it to. There are still some features left that I miss - read block from file, write block to file, faster bookmark handling (1..9 like in Borland Ide's). You are free to modify and distribute this freely, if there are any serious enhancements, problems or just good ideas (this is still my first experience with E programming!) that could be made - please let me know. Known problems ~~~~~~~~~~~~~~ There are a few things that just would not work or had to be modified: 1. The enhanced KWHelp.e by Mat Kramer did not work properly ('invalid numeric reference') - some define statement did not work properly, so I had to change all occureces of EPM_CURSOR to TEXT_CURSOR. 2. EPM wouldn't accept any definitons of the c_up and c_down and stick to stack commands instead. This is a problem of EPM's key processing routine that can't handle c_up and c_down. License Stuff ~~~~~~~~~~~~~ This is free software. You can use distribute, and modify it under the terms of the GNU General Public License as published by the Free Softwa- re Foundation - either version 2, or (at your option) any later version. For files from the original EPM package see the EPM and ETK docs. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABI- LITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Li- cense for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. You can reach me via Email: herbert@wiloyee.shnet.org