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>.
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
- 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:
; call psave_pos(save_pos)
if .filename <> '.HELP' then
if helpfile='' then
"e /q /n .HELP"
markline -- line 1 hinders the full panorama sight
deleteline -- and thus has to be deleted
.filename = '.HELP'
The keybinding (defines <Ctrl-H> as the key to switch to and from the .help-file):