EPM startpage Homepage Contact me SiteMap

The EPM Personalized Reference Background - by Jörg Tiemann

Documentation is like sex: when it is good, it is very, very good;
and when it is bad, it is better than nothing.

   -- Dick Brandon

On this Page:

Existing Sources of EPM documentation
The Personalized EPM Reference Background (PERB) concept
Creating a PERB
E-Macro to switch between current file and your PERB

Existing Sources of EPM documentation  

There are several sources to EPM documentation, each of which cover (slightely) different aspects of our favorite editor:

  The "General Help" (part of epm.hlp)
The General Help is included in the base package.  Though it is an introducing help, dealing with EPM's basic editing concepts, not missing the usual passages of how to work with the mouse, explaining stream and line mode editing etc, it is not only a help for beginners.  Epm.hlp is afaik the only EPM help file available not only in English but in many other languages, too.  If it isn't already in your x:\os2\help directory look for it in your Warp4 distribution.

  The "Quick Reference" (epmhelp.qhl)
Guess what!  It i a quick reference to the used keys, some basic commands and mouse actions.  Moreover it is pure vanilla ASCII and can be edited.  Should you change key definitions it would be a good idea to accordingly change the corresponding entries in this help file.  Unfortunately this file is to long and to make it even worse EPM uses a huge font in a fixed size window to display it.  Sometimes I wish there was an EPM mug (just like the vi mug, surf to NEKOs Homepages to see what I mean).

  The "User's Guide" (epmusers.inf)
This help file is - as the name indicates - the EPM User's compendium of concepts, commands and configuration constants.  It is the most valuable source of information on how to configure and customize your EPM.  Via a configuration constant in mycnf.e ("SUPPORT_USERS_GUIDE") it can be included in the EPM Help menu.

  The "Technical Reference" (epmtech.inf)
EPM's customation doesn't necessarily end at the configuration constants.  Using the E language one can write his/her own macros and thus enhance EPM with (almost) every feature one can think of.  The Technical Reference is introduction to, description of and reference book of this language.  Combined with the many E macros and samples available it should be a sufficient tutorial of that language to enable everyone to write his own E macros.
The Technical Reference can be included in the EPM help menu, too.  This is done by setting the "SUPPORT_TECHREF" configuration constant to 1 (in mycnf.e).

  The Readme (readme.epm)
In the history section of this document you can a find miscancelaneous information not available in the other help files.  One might be a new command line switch, a new highlighting tag or a completely unexpected feature I won't tell you about here.

  The Ultimate Documentation (*.e)
Yes, source is the ultimate documentation.  It can be very helpful and informative to have a look at the E macros and samples available.  They are not only additional features ready to be included, but often give useful hints on how to do something in E.  Finally some of the macros contain information which for one reason or another isn't mentioned anywhere else (for example stdkeys.e conceals the information, that some keys are no longer definable in EPM -- keys mentioned as definable in the Technical Reference).  Thus it is always a good idea to consult pmseek.exe and let it search the *.e files if you know what your looking for.

  The Personalized EPM Reference Background (PERB) concept  

The idea is simple: Just create a screen full of EPM knowledge, shoot it with a screen capture util and use he dead body as your background image in the EPM.  Then load an zero byte file and delete the first line to make sure the whole background is visible.  Finally reserve a hotkey for switching from and to this empty file.  I've written an E macro that does precicely this and attached it to <Crtl-H>.


  Creating a PERB  

This is the hard part.  And to make it worse I leave you mostly alone on this.  As you might have understood by now, a PERB is nothing but a background image for the EPM.  But not all images -- or should I say pics? -- do qualify as a PERB; a PERB has to be quite informative about the EPM key bindings, command syntax or whatever you want to be able to look up fast.  Unfortunately such pics are not distributed in huge numbers in special binary newsgroups or on smudgy web sites.  So it is up to us to create our PERBs ourself.  There are several ways to do that:

A simple approach
Rating: easiest to do, easiest to maintain, ugliest to look at
Just open your usual EPM window, add an .Untitled file and fill the whole visible editing area with whatever you want to appear in your personalized help.  The take a screen capure utility, capture the EPM window, cut the text area with the graphics application of your choice and save it as a bitmap.  Define this bitmap as your background bitmap in the settings notebook of EPM. This is the fastest and the ugliest method at the same time.  If you do some image manipulation with an good graphics application, the result may be acceptable though.

The HTML approch
Rating: pain in the a* to do, relatively easy to maintain, acceptable to look at.
This is what I have done so far, and though the result is good (not overwhelming, but just plain good), I don't know if I should encourage you to follow my example.
First start up your EPM and capture a snapshot.  Use an image manipulation programm to crop the text area and note the size of that area.
You may now discard the snapshot and the cropped image, for now it's HTML design time.  The task is to create a HTML page that does contain all the wanted EPM help information in the dimensions you have just noted.  Because you have to use heavy HTML to create the page and -- as if this wasn't punishment enough -- a browser to display the page, this usually turns out to be an unnerving affair.  More than 20 tabled (most of them nested) in a single HTML document are no fun to deal with.   And with every f* web browser I have found trying to be more clever at displaying tables than the HTML coder(s) at designing them the results are likely to become unpredictable.
Once you have such an page and it displays just fine in your browser, capture the browser window, use a graphics program to crop out the browsing area, convert the image to the OS/2 BMP format, and finally use the EPM settings notebook to set up this image as your EPM background.
Sounds horrifying? It is!  Nevertheless I was desperate enough to choose this way and here is a sample output (.GIF, 160k), already screen capured and cropped.  The html document that created this help background can be obtained on my Downloads page.  Note however that the shown EPM keybindings and some commands are not standard, so you'll probably have to make some modifications.

The GIMP/2 approach
Rating: complicate to create, difficult to maintain, potentially gorgeous to look at.
Haven't tried this yet ...


  E macro to switch between current file and your PERB  

If you're familiar with EPM and the way macros are included this is trivial. I recommend you put the defc in your mystuff.e file and the key definition in your mykeys.e file, recompile and restart the EPM and be happy.

The defc macro:

defc help_screen
   universal callingfile,helpfile
;   call psave_pos(save_pos)
   if .filename <> '.HELP' then
      getfileid callingfile
      getfileid helpfile,'.HELP'
      if helpfile='' then
         "e /q /n .HELP"
         markline -- line 1 hinders the full panorama sight
         deleteline --  and thus has to be deleted
         'readonly on'
         .filename = '.HELP'
         getfileid helpfile
         activatefile helpfile
      activatefile callingfile

The keybinding (defines <Ctrl-H> as the key to switch to and from the .help-file):

def c_H = 'help_screen'

EPM startpage Top Homepage Contact me SiteMap

Copyright © 1998-2001 - Jörg Tiemann Last modified: Mon, 3 Sep 2001

gratis SMS verschicken im Uboot.com gratis HTML checken bei w3.org gratis quer denken mit Wau Holland