  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 <keyname> = <sequence of commands>'  occurances
       to 'def <keyname> = call <procname>'  and then  'defproc <procname>
       <sequence of commands>'.  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 <g>) - 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

