home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / epmkmap1.zip / README.TXT < prev    next >
Text File  |  1996-12-26  |  14KB  |  244 lines
  1.   HKeysEPM -- A patch for the way EPM handles redefinition of keybindings
  2.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.   and other stuff for EPM -- Copyright (C) 12/1996 by "Herbert" M. Dietze
  4.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.   Version 1.0
  6.   ~~~~~~~~~~~
  7.  
  8.   Introduction
  9.   ~~~~~~~~~~~~
  10.  
  11.   OK, that's it, folks!  I (like quite a few  other  people)  was  looking
  12.   desperately  for  a  good  programmer's  editor  under OS/2 PM which was
  13.   desired  to  be  fully  configurable  with  keyboard,  compiler messages
  14.   handling etc.  IBM's EPM bears  those  features  but  its  key  bindings
  15.   aren't  very  easy to configure - you have to get rather deeply into the
  16.   macro sources written in E. Another thing was that I liked that handling
  17.   of Borland IDEs like hungry backspace, an enter holding the indent level
  18.   and last but not least its WordStar based keymap.
  19.  
  20.   At last I saw no  alternative  to  getting into that E programming stuff
  21.   and the result seems to be OK for my needs though it's surely not always
  22.   the best way I chose to  do this or that.  If this is your first experi-
  23.   ence in programming the EPM I'd suggest to read the "confused now?" sec-
  24.   tion below now!
  25.  
  26.   The  basic  idea  is to put all key definitions into a seperate file and
  27.   leaving all that  'compile  if'  etc.  stuff  in  its stdkeys.e file.  I
  28.   therefore had to change my stdkeys.e file replacing all 'def ?key' parts
  29.   followed  by more than one  instruction by self explaining command names
  30.   'defproc ?name' (except  from *enter, this did not seem necessary).  Now
  31.   any action  performed by a keystroke  has its own  name. These names are
  32.   used to  define all keys in seperate keymap  files like 'mykeys.e' (EPMs
  33.   usual way  to do things  like this) like  'def ?key = ?command'.  You'll
  34.   still have to use E syntax but it looks much  nicer - and you can define
  35.   two key  commands  (like  used in  WS  or Emacs).  I've included a  demo
  36.   file with the  key bindings I use (they're a  bit like qedit, a bit like
  37.   WS and the rest is  just my invention) -  mykeys.e.
  38.  
  39.   The EPM will still  behave like  it used to if  you don't compile with a
  40.   mykeys.e file  with definitions  overriding those from stdkeys.e. If you
  41.   don't  want any of  EPM's standard  key definitions  on keys you haven't
  42.   defined  explicitely you've got  to insert empty  def's for all keys you
  43.   don't need in your  mykeys.e file (In fact that's the way I did it in my
  44.   mykeys.e file).
  45.  
  46.   I used  the EPM 6.03  beta version  but there should be no problem  with
  47.   OS/2 2.*'s 5.51 version or any later 6.x release. I've made some changes
  48.   to my stdkeys.e and ckeys.e files  to make them compile with EPM 5.x. It
  49.   _seems_ to work - though there might still  be some routines called that
  50.   EPM 5.x can't handle. You'll have to fix that yourself! Of course, macro
  51.   sources and macro compiler are absolutely necessary.
  52.  
  53.  
  54.   Files in this Package
  55.   ~~~~~~~~~~~~~~~~~~~~~
  56.   stdkeys.e     :  Patched StdKeys.e - defines commands for each keystroke
  57.                    triggered action. Needs herbert.e.
  58.   mykeys.e      :  My key definitions (bit like WS / qedit).
  59.   mymenu.e      :  My menu file (with the key binding descriptions defined
  60.                    in mykeys.e in the pulldown menus).
  61.   herbert.e     :  Contains helper routines.  These are a function for en-
  62.                    hanced handling of the enter key (must be activated via
  63.                    the HOLD_INDENT_IN_STREAM_MODE constant) which  is cal-
  64.                    led from my  stdkeys.e,  an extra  routine  for special
  65.                    handling of the '}' character under C/C++ and a routine
  66.                    for a smarter backspace (like in Borland ide's) .
  67.   mystuff.e     :  Just in case you  don't already use one!  Contains only
  68.                    one line "tryinclude 'herbert.e'".
  69.   epmhelp.qhl   :  Text file with quick key reference for my own keymap
  70.   mycnf.e       :  My own mycnf.e - modify it as you like it!
  71.   stdkeys.org   :  Original stdkeys.e from my EPM package. You may want to
  72.                    have a look at it to find out the difference from yours
  73.   readme.txt    :  This file.
  74.   COPYING       :  The GNU public license.
  75.   license.txt   :  License for EPM files.
  76.  
  77.  
  78.   Installation of the keymap patches for EPM
  79.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80.  
  81.   1. Backup your std*.e files.
  82.   2. Unzip the hkeysepm.zip archive into an own directory (assuming you've
  83.      already done this :-)
  84.   3. Get my versions of stdkeys.e  installed.  You could do this either by
  85.      taking my adds from my files and put them into  yours (looks like too
  86.      much  work normally)  or by  just taking  my version of stdkeys.e and
  87.      trying it. It should not be too difficult to fix  problems that might
  88.      occur (EPM gives you  messages like 'unknown  procedure ...'   in the
  89.      status line when a routine  calls something EPM  doesn't know, so all
  90.      you've got to do is  grep for this  name through your macro directory
  91.      and fix it!). What I changed with my stdkeys.e file:
  92.      - replaced most  'def <keyname> = <sequence of commands>'  occurances
  93.        to 'def <keyname> = call <procname>'  and then  'defproc <procname>
  94.        <sequence of commands>'.  So there  still are  the default key bin-
  95.        dings active if you don't override them.
  96.      - changed the  definition of the enter  command to use my own routine
  97.        'henter_common()' instead of 'enter_common()'. This only applies to
  98.        stream mode and will behave the default way if you set the constant
  99.        HOLD_INDENT_IN_STREAM_MODE to 0  in your  mycnf.e  file. This makes
  100.        the file herbert.e necessary.  If you don't  like this  just change
  101.        any occurrence of 'henter_common' to 'enter_common' in stdkeys.e.
  102.      - added some conditional stuff to make it compile under EPM 5.x.
  103.   4. Copy the mykeys.e file into the  E sources directory and modify it if
  104.      you like - maybe  better wait until  all that stuff works!  ;-)
  105.   5. Edit your  mycnf.e file the way  you like it. Be sure that VANILLA is
  106.      not set to 1.
  107.   6. If you've just copied my stdkeys.e file over yours copy herbert.e in-
  108.      to your sources directory.  Then add "tryinclude 'herbert.e'" to your
  109.      mystuff.e file (create one if necessary!)
  110.   7. If you  want to use my  key definitions you may also want to use my
  111.      menus and my keyboard summary file:
  112.      - Copy my epmhelp.qhl into  your E source directory  (backup your own
  113.        before, be sure you replace it),  it contains a  short key bindings
  114.        summary when you press Alt-F1.
  115.      - Copy the file mymenu.e into your  E source directory and change the
  116.        value of "STD_MENU_NAME" in mycnf.e to the new menu file name.
  117.   8. Now change into  your .ex files directory (if different from  your  E
  118.      sources  directory) and recompile your epm.ex and extra.ex (etpm epm,
  119.      etpm extra).
  120.   9. If it all works  now  you  can  redefine your key  bindings simply by
  121.      editing your mykeys.e file and recompiling epm.ex.
  122.  
  123.  
  124.   Confused now?
  125.   ~~~~~~~~~~~~~
  126.  
  127.   If this is your first  experience  in configuring  EPM you might like to
  128.   read this - it's meant as a SHORT summary of EPM's concepts for primers.
  129.   If you take a look into the directory containing EPM's files you'll find
  130.   a file EPM.EXE  and several .ex files. Roughly speaking all that EPM.EXE
  131.   does is initializing a PM window and then reading the macro files EPM.EX
  132.   and (if existent)  EXTRA.EX. Those files completely define EPM's behavi-
  133.   our as an editor. They also  tell EPM  which other  .ex files it  has to
  134.   read at startup. The EPM toolkit contains all macro sources and the mac-
  135.   ro compile ETPM.EXE you need to compile those sources.
  136.  
  137.   To install this EPM toolkit you've  got to copy all dll's to a directory
  138.   in your libpath (I'd suggest to backup your old ET*.DLL files and simply
  139.   replace them).  Then put the exe's, ex's and hlp's into their own direc-
  140.   tory (I'd suggest  not to use \os2\apps as  there will be  quite a large
  141.   number of files). Add this directory to your path and help statements in
  142.   your config.sys file. Put the macro sources  into the same or a seperate
  143.   subdirectory  (I prefere the latter).  Change the epmpath  statement  in
  144.   your config.sys file to the dir[s] you  now use to store EPM's exe's and
  145.   sources.  If necessary change  the settings  of your  EPM object on your
  146.   desktop and then - finally - reboot.  Try your 'new' EPM.  If you've had
  147.   a non English version  before - you might wonder now. Sorry, there is no
  148.   alternative, you'll  either have to  learn English  or know  your EPM by
  149.   heart :-)
  150.  
  151.   Now the  main modules EXTRA and EPM consist  of the sources  EXTRA.E and
  152.   EPM.E that include  several other files by  default. If you want to make
  153.   any changes - like include own routines - you can do this in files star-
  154.   ting with 'my' like mycnf.e, mystuff.e, mykeys.e. ETPM always _tries_ to
  155.   include them when compiling - so if there is a file of that name present
  156.   when compiling it will be read.
  157.  
  158.   If you only want to modify EPM's key bindings you'll have to take a clo-
  159.   ser look at STDKEYS.E. It uses a construction like "def c_u = 'undodlg'"
  160.   to bind  the key Ctrl-U to the (very neat) undo dialog. If - like here -
  161.   there is a name in quotes  ('undodlg') this means we  deal with a pseudo
  162.   command that you can  use from EPM's command dialog.  This makes the .ex
  163.   files rather large and should not be used too excessively. The other way
  164.   is simply  calling a  procedure like "def enter = call my_enter_proc()".
  165.   This is the preferred way  to handle things you don't need to enter from
  166.   the command dialog.
  167.  
  168.   For performance reasons  the folks at IBM did not define a procedure for
  169.   all complex  command sequences performed by key commands but if you want
  170.   to do serious  key remapping there  is  no alternative to this (and this
  171.   just what I  did for this package!).  If you now add  a file MYKEYS.E to
  172.   your sources and compile it  it will be  automatically included by ETPM.
  173.   All key definitions in there will simply override those from stdkeys.e -
  174.   this is no error and just normal.
  175.  
  176.   OK, back to recompiling EPM (I know I sometimes talk too much <g>) - you
  177.   have changed a little  something to EPM's standard behaviour, now you've
  178.   got to recompile all  modules affected by  this. In our case this is the
  179.   file EPM.EX. If  you've changed  any constants in mycnf.e (You can use a
  180.   quite large number of constants  [with rather self explaining names]  to
  181.   switch on / off features before compiling - play around with them if you
  182.   like, it's a real powerful means) you should also recompile EXTRA.EX, so
  183.   let's just get used to always recompile both!
  184.  
  185.   To recompile your EPM now first change into the directory containing the
  186.   .ex files (no matter where  the sources are - as long as their directory
  187.   is in the EPMPATH) and  then enter  the command  "etpm epm". If this was
  188.   successful put "etpm extra".  I'd suggest  to first leave out my patches
  189.   to  try if it  all works  well but include  the sample file OS2TOOLS.CFG
  190.   (rename it to mycnf.e first) even if you haven't the slightest idea what
  191.   it all means. There's just a couple of definitions that should make sure
  192.   you get no unnecessary trouble when  compiling the package for the first
  193.   time! As long as you don't  modify any modules using  their own .ex file
  194.   you should never need to recompile any other files than EPM and EXTRA.
  195.  
  196.  
  197.   Almost Finally
  198.   ~~~~~~~~~~~~~~
  199.  
  200.   OK, I hope you were lucky to get all  this  properly  installed.   After
  201.   having  been  on this for about a week this all seems absolutely natural
  202.   and easy but I guess it won't be  for you :-) However I think it's worth
  203.   it - my EPM now behaves (almost) absolutely the way I like it to.
  204.  
  205.   There  are  still some features left that I miss - read block from file,
  206.   write block to  file,  faster  bookmark  handling  (1..9 like in Borland
  207.   Ide's).  You are free to modify and distribute this freely, if there are
  208.   any serious enhancements, problems or just good ideas (this is still  my
  209.   first experience with E programming!) that could be made - please let me
  210.   know.
  211.  
  212.  
  213.   Known problems
  214.   ~~~~~~~~~~~~~~
  215.  
  216.   There are a few things that just would not work or had to be modified:
  217.   1. The enhanced  KWHelp.e by Mat Kramer did  not work properly ('invalid
  218.      numeric reference') - some define statement did not work properly, so
  219.      I had to change all occureces of EPM_CURSOR to TEXT_CURSOR.
  220.   2. EPM wouldn't accept  any definitons of  the c_up and c_down and stick
  221.      to stack  commands instead. This is a problem of EPM's key processing
  222.      routine that can't handle c_up and c_down.
  223.  
  224.   License Stuff
  225.   ~~~~~~~~~~~~~
  226.   This is free  software. You can  use distribute, and modify it under the
  227.   terms of the GNU General Public License as published by the Free Softwa-
  228.   re Foundation - either version 2, or (at your option) any later version.
  229.   For files from the original EPM package see the EPM and ETK docs.
  230.  
  231.   This program is  distributed in the  hope that  it will  be useful,  but
  232.   WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHANTABI-
  233.   LITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Li-
  234.   cense for more details.
  235.  
  236.   You should have received  a copy of the GNU General Public License along
  237.   with this program; if not, write  to the Free Software Foundation, Inc.,
  238.   675 Mass Ave, Cambridge, MA 02139, USA.
  239.  
  240.   You can reach me via Email:
  241.  
  242.     herbert@wiloyee.shnet.org
  243.  
  244.