e93 version 1.4r2 (X Windows version)
http://www.e93.org

Todd Squires
Core Technologies
215 N. Valley Hill Rd.
Bull Valley, IL 60098
(squirest@e93.org)

What is e93?
---- -- ---

e93 is a portable window based text editor oriented to the needs of
programmers. It was begun in 1993 (thus the name). It uses the mouse,
selections, cut/copy/paste, and closely follows the model of editors
on the Macintosh and NeXT platforms.

e93 is portable to environments other than Unix/X Windows -- as long as
those environments support virtual memory.

e93 supports columnar selection. It achieves this by allowing multiple
pieces of the text to be selected simultaneously (this is perhaps its
most unique feature).

e93 imposes no limits on the line length, file length, or number of
simultaneous files which it can edit.

e93 is able to handle all 8-bit binary codes without complaint, or
confusion.

e93 is highly configurable without recompiling because scripts which
control the editor can be written in Tcl.

e93 supports user-configurable syntax highlighting.


To Install
-- -------

Please read "LICENSE.TXT" if you agree with it, follow
the instructions given in the file "INSTALL."


What's the deal with those version numbers?
------ --- ---- ---- ----- ------- --------

The version numbers in e93 work as follows:

e93 1.4r2X means:

Major version: 1    If it is ever rewritten, this will increment, and the
                    numbers below will be reset to 0.
Minor version: 4    If really significant changes are made, this will increment.
Revision:      2    Any change will cause this will increment.
Machine:       X    X windows implementation.


Additional Information
---------- -----------

The material README.regex is taken from The GNU Emacs Manual, 9th edition.
Copyright 1985, 1986, 1987, 1993 Free Software Foundation, Inc.
and from the GNU regex library version 0.11.
Copyright 1992 Free Software Foundation, Inc.


Mail From e93 Users
---- ---- --- -----

Mail me useful tips, and I will place them here so that
other users can benefit from them.

From: Michael Zuelsdorff <micha@dolbyco.han.de>
Subject: e93 on german linux box

The only problem I ran into was my German keyboard. You
might know, that we have Umlauts and other special characters
instead of all those brackets and braces. My solution are
some additional lines in my e93rc.tcl:

bindkey 7      {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\{"};
bindkey 8      {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\["};
bindkey 9      {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\]"};
bindkey 0      {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\}"};
bindkey ssharp {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\\"};
bindkey q      {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\@"};
bindkey plus   {00100000000} {InsertAndHome [ActiveWindowOrBeep] "\~"};
bindkey less   {00100000000} {InsertAndHome [ActiveWindowOrBeep] "|"};
----------------------------------------------------------------

Please send all bug reports to squirest@e93.org. (Todd Squires)

Release of 1.4r3
------- -- -----

Cleaned up some math that wrapped around when buffers grew larger than
2GB. Scroll bars, etc should now all handle 4GB buffers.

Added the control key as a selection modifier. When holding the
control key and clicking in the document, it is now possible to easily
make multiple disjointed selections.

Got rid of cache of top level X window that was associated with each
editor window. This was used to keep track of windows when the WM
reparented them, but breaks when the WM is restarted, or a new WM
is started. Instead, the code now hunts windows the hard way whenever
it might be dealing with something that was reparented. This is slower,
but shouldn't break as easily.

Modified clipboard handling to export both XA_PRIMARY, and XA_CLIPBOARD
to get along with more applications when cut/copy/pasting.

Release of 1.4r2
------- -- -----

Added XSetClassHint calls to the various windows to help the Gnome
Window List applet to figure out that all of our windows belong to the
same class (so it groups them correctly).

Added support for Xinerama (multiple head displays). e93 will now pick
the 0th display as the "primary" one, and will open windows and menus
on that display.

Release of 1.4r1
------- -- -----
Sun Jan  4 18:25:40 CST 2009

I had some time to play with e93 over the holiday. It had been a while
since I had done any serious messing with the code.

The new version of the X11 libraries that came with FC10 contain an
assert if an application calls back into X from within a predicate
routine. It turns out this is not allowed. The "XCheckIfEvent" man
page says:

"Your predicate procedure must decide if the event is useful without
calling any Xlib functions."

e93 had an errant case of this which triggered the assert. The problem
has been corrected.

All of the C variables called "theWhatever" have been renamed to just
"whatever". Adding the "the" before variable names was a bad habit
which I have broken since e93 was written, and I had always meant to
go back and get rid of them. They're all gone now.

The long-ago-broken-and-never-fixed user abort code has been repaired.
It is now possible to hit 'escape' while a Tcl script is running, or
while the editor is busy performing a search, and have the process
abort. This is trickier than it seems, so if you notice any problems
with it, be sure to let me know.

Tk was removed from the editor. On some machines, Tk made the editor
slow to load, and it never was really used very effectively anyway
(mainly used for the about screen). If this really bothers anyone, let
me know. It would not be incredibly hard to add back, but I'd probably
work to make it a build option.

Windows and dialogs have been made to update using an offscreen
buffer. This reduces flicker as e93's windows are updated. The result
should look cleaner than before without much of a performance hit.
This change helps especially with window managers that do live updates
as windows are resized.

The code which draws the text cursor has changed. Previously, e93
tried hard to manage the cursor outside of the usual invalidate/update
mechanism that is used for all other screen updating (it used XORs to
draw the cursor to the screen). This made sense in the days of old, as
it was much more efficient. However, on modern machines the code
complexity of the old method makes no sense given how little it
matters speed-wise. Now the cursor is drawn just like everything else.

Previously each editor window had its own graphics context. This was
not necessary. Now there is only a single graphics context that is used
for all drawing.

Dialogs have been modified so that they can be sized. The editor does
not yet remember the last size you asked for, not does it yet allow
you to specify the size when they are opened, but I'll eventually get
around to making those changes.

Error handling has been improved.

Release of 1.3r5
------- -- -----
Mon Dec 22 16:05:31 CST 2008

Ok, I admit it. I had been upgrading my kernel happily without ever
upgrading my Linux distribution (I have been using Fedora Core 2 for a
very long time). Anyway, I finally decided it was time to upgrade to
FC10. The upgrade brought with it a new version 4 gcc compiler, and a
new version of the Metacity window manager.

Both found reasons to complain about some of the things e93 was doing.

IMHO, only gcc had any right to complain. Metacity wrongly decided to
start ignoring XRaiseWindow requests... I'm sure the author thinks it
was a good idea. It wasn't. One day, I would enjoy having a chat with
him about it.

Also, I've been sitting on a bunch of other little fixes given to me
by various folks (especially Michael Manning (thanks, and sorry for
taking so long to get these out)).

So, here it is. No new features have been added. Just compile fixes
and a few minor tweaks.


Release of 1.3r4
------- -- -----

A bug in shellcmd.c which could cause 2 error messages to be output
when the "setcolors" command was passed an invalid color was fixed --
thanks to Michael Manning for pointing this out.

Gordon J Milne added some missing keywords to the C syntax
highlighting rules.

Makefile was modified to link against libstdc++.

Fixed a bug in Replace where the selection would be corrupted
after a replace Tcl script failed.

Added a check in xgui/misc.c to check to see if a window has
children before deleting the child list -- thanks to Fred Allen
for pointing that out.

Mouse wheel support added -- also thanks to Fred Allen.

Default fonts for all the various editor functions may now be
specified in the startup scripts. Thanks to Adam Yellen for this
change.

"extract" Tcl function was added -- Thanks to John Duncan for the
suggestion.

New syntax maps added courtesy of Michael Manning.

Modified the C Get Prototypes menu item to improve recognition of
certain kinds of prototypes.

Removed support for paletted displays -- colors are no longer
allocated and freed. If you are still running in 8 bit color
mode, you need help.

Renamed a bunch of types to make them easier to read and more
consistent with my current programming style.

Added some new Tcl commands to the editor for manipulating
marks in the text. Also added ability to have marks be visible
in the view.

Removed some outdated Tcl commands, and changed the names of some
others. e93rc.tcl and other scripts were modified accordingly.

Release of 1.3r3
------- -- -----

A variable called "not" in regex.c was changed to a new name, since
"not" is a reserved keyword in 'C', and new compilers have started to
complain.
(Thanks to Adam Yellen, and Mark Maxon)

The version of Gnome shipping with RedHat 7.0 did not like the way
that dialog windows were being set up and was causing an inability
to click in them. dialogs.c was modified to solve the problem.

The following changes are thanks to Michael Manning:
    Unnecessary "strings.h" was removed from includes.h.
    Tcl commands: setmodal and getmodal were removed in favor of a
      more transparent method of determining when a grab has occurred.
    Dummy version of ShellCommand added to make errors in the startup
      script a little less catastrophic.
    fromfile was removed from the Tcl script GetDefaultStyleInfo
    The about box was changed so that it no longer calls "uname" making
      it more portable.
    Some other problems were corrected in the startup script.

Michael Manning also contributed the docsource directory which
contains the beginnings of some real documentation for e93.

Adam Yellen supplied some icons (in the e93lib/images directory) which
can be used for Gnome or KDE.

Adam also supplied the "colorme.tcl" module which can be used to
dynamically modify the background color of editor windows.

channels.c was changed to account for a change in the Tcl_ChannelType
data structure. (Thanks to everyone who reported this.)

Release of 1.3r2
------- -- -----

e93r was modified to allow files to be piped to it on its stdin.
(Thanks to aweigp@autelca.ascom.ch)

Setlocale is called at startup to allow keyboard input to work in other
parts of the world. (Thanks to y_kozlov@chat.ru)


Release of 1.3r1
------- -- -----

Fixed a crash bug which happens when replacing using tcl script as the
replacement text, and the script is using "puts" to write to another buffer.

Fixed a problem with closing stderr in Tcl which was causing e93's
stderr to be closed as well -- this caused no error messages to be
generated.

Removed EDITORUNIVERSE concept -- folded it into EDITORBUFFER.

Modified smart-open to take "# include" (with whitespace between
the # and the include).

Added private color map handling for X windows. If the
environment variable E93_COLORMAP exists, e93 will use a private
colormap. Otherwise, it shares the system's default color map.

Many thanks to Peter TEX Weigand <aweigp@autelca.ascom.ch> for the following changes:
    Modified Makefiles for easier multi-platform configuration
    Added "install-strip" target to Makefile
    Added SA_RESTART for Solaris in xgui/events.c
    Added "Modified" icon for documents
    Moved start-up scripts to "lib" instead of "bin"
    Added vertical scroll-bar left/right-hand preference "scrollbarplacement"
    Added "PrintWindows" command to e93rc
    Modified e93rc mail command to use "sendmail" instead of "mail"
    Added "subject" to mail dialog in e93rc
    Added "MailWindows" menu item to e93rc
    Enhanced "buffer info" dialog box
    Enhanced find-selection so that empty selections work better
    Enhanced modules/c.tcl so that prototype location is more robust for different coding styles
    Updated the README.e93 document (BIG THANKS!)
    Added .src to the extensions recognized as assembly code
    Removed errno and sys_errlist from errors.c
    Created "e93r" script for remote execution -- this allows you to pass files to a running e93
    Fixed "dirty" flag so that it tracks the "undo" status of a buffer


Release of 1.2r8
------- -- -----

Changed the way e93 finds and runs its startup scripts.

Added the long awaited Syntax Highlighting.

Changed the way e93 internally deals with fonts and colors.

Modified the way e93 internally deals with selections.

Added < and > to regular expression matcher to allow matches on
word boundaries.

Changed regular expression matcher to allow empty groups (as this
helps with the syntax highlighting rules).

Modified text drawing to allow fonts with characters which overhang
their cell boundaries (such as serifed and italic fonts) to work
without having the overhanging portions clipped.

More code formatting changes.

Bug fix: Reverting to a document which contained 0 bytes did not
work correctly.

Bug fix: When doing a replace, the cursor did not always end up
in the correct spot.

Modified task code to keep e93 from using pause() to give time
back to the system when tasks have data for the editor. This resulted
in a 30% speed increase when reading task data into buffers on fast
machines.

Allowed menu key definitions to be overwritten by subsequent menu
definitions.

Added "the Hand" function to the middle mouse button to allow
easier text movement.

Changed .e93rc to show modified files in the "Choose window" dialog.

Changed .e93rc to remember the contents of some dialogs across invocations.

Changed the function of SHIFT-Arrow keys to work more as expected:
previously, the selection was always expanded. Now, it expands and
contracts in a more intuitive way.

Changed the columnar paste algorithm:
OLD way: delete all selections in document, paste columnarly.
NEW way: paste each selection of the clipboard over each selection in the
document until we run out of selections in the clipboard or document.
If there are no more selections in the document, then paste the remaining
clipboard selections columnarly. If there are no more selections in the
clipboard, delete the remaining selections in the document.

Changed behavior of the horizontal scroll bar so that it is possible
to scroll the text beyond the right-most position dictated by the
thumb. This makes it possible to see and edit the ends of very long
lines, but does add a small bit of strangeness to the behavior of the
scroll bar.

Changed the way the editor homes the view when text is being sent to
a buffer from a task. Now, the editor will not scroll horizontally
when it homes. This makes it much easier to see what is happening
when tasks dump long lines into the view.

Allowed the escape key to be used to abort searches and scripts.

Release of 1.2r7
------- -- -----

Code formatting changes.

Some problems with SIGALRM fixed under Linux and IRIX.


Release of 1.2r6
------- -- -----

The fallback font list (fonts e93 looks for when it cannot locate the
one it really wants) has been changed. This was done to make e93
behave better on machines that do not have b&h fonts.

Opening and closing of e93's menus has been made slightly more
efficient. This was done to make it faster with some window managers
(like fvwm) which tend to behave very slowly when e93 changes the size
of its menu window.

The open and save dialogs have been changed slightly to make them
more friendly.

The startup procedure which reads the .e93rc file has been improved to
handle some error cases in a more friendly way.

4 new Tcl commands have been added:

  buffervariables
  setbuffervariable
  unsetbuffervariable
  getbuffervariable

These allow variables to be created which are local to any given buffer.
This will make it much easier for Tcl scripts to hang information off
of a buffer, and reference it later.

Finally, .e93rc has been changed in the following way:

Checks were added to see if the modification time of a file has
changed while the file was being edited. (Warning you that another
application did something to the file).

Capitalization of function names has been standardized.

The open selection command has been improved to handle globbing, and
selecting the cursor line to open if no selections exist.

Open Clipboard was added to the Edit/Clipboards menu.

Release of 1.2r5
------- -- -----

Some minor cleanup to code calling Tcl.

Some bugs related to reporting errors at inopportune times were
located and removed. These usually showed themselves during very low
memory conditions.

Double click timer is now reset in the file dialog boxes. Clicking
rapidly on the file list now works as expected.

The initial delay before repeated scrolling/paging with scroll bars
has been lengthened slightly.

The allowable delay between consecutively typed characters in list
boxes has been lengthened slightly.

A bug in the menu code was removed. The bug was caused by clicking
multiple mouse buttons at the same time while tracking menu items.

The directory dialog has been modified to show only directories.
Previously it also showed files.

Color handling has been altered so that named colors are now
recognized. Previous to this, all colors had to be specified as 6 hex
digits RRGGBB. Now, if a machine supports color names, e93 will also
accept them.

.e93rc was modified:
  Strip EOL Whitespace and line termination functions were added.
  Align Left was added.
  "About" was slightly modified.
  Color names were added.
  Line Wrap functions were added.

Characters with diacritical marks such as umlauts and other special
characters which are contained in the upper half of the character set
will now be displayed properly by e93. Previously, any character above
0x7F would have been displayed as its hexadecimal equivalent. e93 will
now use the character contained in the current font (as long as it is
not of 0 width, in which case, it will display the hex equivalent as
before).

Two new relative cursor movement modes have been defined:
STARTPARAGRAPH and ENDPARAGRAPH which will move the cursor to the
start or end of a paragraph. These modes can be used with the
following commands:

movecursor
delete
expandselection
reduceselection


Release of 1.1r4
------- -- -----

.e93rc was modified:
  Mark, Directory and C menus were added. Some more cleanup.
  Views menu became Windows menu. Printing menus were added.

All dialogs were modified to handle error conditions more
consistently.

The Ok dialog was modified to wrap text instead of drawing it off the
edge.

Open/save file dialogs were modified to handle more cases. Also a "/"
was added after all items in the dialogs which point to directories.

A new Path selection dialog was written, and a Tcl command
(pathdialog) was added.

Menus were modified so that you do not have to hold the mouse button
down while making menu selections. You can now click on the various
submenus one at a time to make a selection. This is more consistent
with most window managers, and easier to use.

Text routines were sped up by adding a cache mechanism that allows e93
to locate positions in the text more quickly. The speed increase
should be especially noticeable when editing large files (>1MB).
Assuming you have enough virtual memory, e93 should now be able to
edit very large (<2GB) files without a noticeable slow down.

When treating replacement text as a Tcl script, 10 new variables (in
addition to $found) are available if the search string was a selection
expression: $0 - $9 are now set to the \0 through \9 matches of the
selection expression.

A bug that caused a rare memory leak related to search and replace was
found and fixed.

A bug in realpath2 that caused extra '/' characters to appear in its
output was fixed.

The clipboard interface with X windows has changed. Previously, e93
used the clipboard mechanism to import/export to the X windows
environment. However, most X windows applications do not use the
clipboard. Instead, they use the X selection mechanism. Users
complained that they could not easily communicate with programs that
used only the selection mechanism (most programs). So, e93 now does
the following to support communication with other X applications:
Whenever text is copied into e93's current clipboard, e93 takes
ownership of the current selection. If another application does a
"paste selection" (many use the middle mouse button for this) while
e93 owns the selection, the application will get the text in e93's
current clipboard. Conversely, If another application owns the current
selection, attempts to paste from the current clipboard within e93
will cause it to copy the selected text from the current selection
owner into the current clipboard before pasting. This all seems
somewhat convoluted, but since e93 supports multiple selections
simultaneously across multiple windows, and X does not, this is the
best solution I can currently offer.

The editor startup scheme was modified so that it looks for the .e93rc
file in your home directory first, but if it is not found, it will now
also look through the path given by $PATH in its environment. As soon
as it locates a .e93rc file that it can open, it will execute it and
stop looking. A Tcl global variable SCRIPTPATH is set to the path of
the script that is executed.

The font selection dialog was written. It is better than what it
replaces (a dialog that made you type in the font you wanted) but it
still could use some work.

Release of 1.0r3
------- -- -----

The increment of the minor version number (1.0->1.1) indicates lots
of changes.

.e93rc was modified:
  Some new functions added, some old ones cleaned up slightly. The
  "unknown" function was modified so that if it launches a task that
  wants input from stdin, it will get an EOF, instead of hanging
  e93.

README.e93 was written, as a first cut at a manual. Read it, if you
have suggestions, let me know. There is a lot more to do in this
arena, but I hate writing documentation, so this is it for a while.

A proper open/save file dialog was written. It is kind of different.
Let me know how you like it.

There is also a new listdialog function which allows choices from a
Tcl list. This dialog was used to implement the new "Windows..." menu
function.

Dialog management has changed significantly.

Color handling was improved, so the editor should not just quit if it
cannot get colors at startup. The new behavior is to just get either
black, or white depending on which color is closer to the one asked
for.

Tasks are now hung off of buffers, instead of windows as they were
previously. This allows for tasks to be running in buffers which do
not have associated windows.

EOF can now be sent to a task by closing the input pipe.

Task error handling has been improved.

A speed governor was installed on all scrolling items so you folks
with screaming fast machines will not have things scrolling so fast as
to be annoying. This should not slow down slow machines.

LOTS of minor source code changes.

Release of 1.0r2
------- -- -----

.e93rc was modified:
  Some defaults were made easier to change.
  Error reporting during file save functions was improved.
  Menu names were made more consistent.
  Some features were added to the "Misc" menu.

The call to the library function "realpath" in xgui/misc.c was
replaced by a call to a new internal routine "realpath2" which does
the same thing. This was done for those machines that do not include
"realpath" in their libraries.

Release of 1.0r1
------- -- -----

xgui/includes.h was modified to include <sys/time.h> because some
machines require it.

Two bugs in keybind.c were found and corrected.

Error reporting at init time was enhanced so that users would know if
e93 failed to start up because of a lack of available colors.

Startup script execution has been changed so that the editor will not
startup if it cannot locate the startup script.

The default .e93rc was slightly modified to change the colors of some
windows.

guidefs.h was modified to get rid of an array of 0 length that
offended some compilers.

Release of 1.0r0
------- -- -----

The makefile was altered to get rid of -L$(LIB) in the link line which
was causing trouble.

killpg in xgui/tasks.c was modified to kill(-pid...) because some
systems do not have killpg.

xgui/events.c was modified to make sigaction a little more portable.

The clipboard is now imported when the editor starts.

A new Tcl command called "version" was added to allow users to find
out which version of the editor they are using.

e93 Manual
July 19, 2000

e93 is a portable window based text editor oriented to the needs of
programmers. It was written to take advantage of the windowing systems
found on today's workstations, and PCs. e93 is based on the Tcl
scripting language, and relies on this language for most of its high
level functionality.

e93 supports a model of editing which emphasizes limiting the number
of modes, and maximizing the use of a small, easily learned set of
editing commands.

To install e93, please read the file "INSTALL" that came with this
distribution.

NOTE: Since e93 is portable, I have attempted to keep this manual
machine/OS independent to a reasonable extent. However, since e93 was
first written for UN*X machines, there is a slight bias towards them
in this documentation.


Starting e93
-------- ---
To start e93 from a command line interface (if your machine/OS has
one), type:

e93 <fileToEdit> <fileToEdit> ...

e93 will start up, and open all of the specified files for editing.
There are no command line options, just filenames.

NOTE: each time you run e93 it creates an entirely new instance
of the editor.


Environment variables
----------- ---------
There is one environment variable that will affect the operation of
e93 (X windows version only).

E93_COLORMAP

If this variable is defined, e93 will attempt to allocate its own
color map at start-up. This may allow it to work better on 256-color
displays.

If it is not defined, e93 will attempt to share the system's default
colormap.


Windows and Buffers
------- --- -------
When e93 opens a file for editing, it reads the contents of the file
into a "buffer", and then closes the file. All editing takes place
within the buffer, and changes are not written back to the file until
the buffer is "Saved".

A buffer is an area of memory where text is stored while it is being
edited. Buffers can contain arbitrary amounts of text, and do not
place any limits on the characters they contain (ASCII \0 is allowed
in a buffer). Although buffers are usually used to hold the contents
of files, they are also used to hold other things, like new documents,
clipboards, and the text that is used by the Find and Replace
functions.

All buffers have names. These names are needed so that buffers can be
referred to from Tcl scripts. The name of each buffer must be unique.
buffer names can be of arbitrary length, and can contain any character
except '\0'. A buffer open to a file is typically named with the full
path name of that file. Buffer names are case sensitive.

Buffers can have "windows" associated with them. A window can be
thought of as a view onto the contents of a buffer. Windows are where
most editing commands are carried out. It is important to understand
that buffers do not NEED to have windows associated with them. In
fact, certain buffers (like clipboards) typically are not associated
with windows.

Each window on the other hand, is always associated with a buffer.
Windows also have names, and each takes the name of the buffer it is
associated with.

Many of the features of a window can be changed from Tcl scripts.
Some of these are:
	Foreground Color
	Background Color
	Font
	Tab Size
	Location
	Width/Height

See Appendix A for detailed information on commands that modify
windows.

e93 maintains the concept of an "active window". This is the window
that is top-most. Most menu commands operate on the active window.

Each window has a "Status bar" which gives useful information about
the buffer being edited. The status bar indicates if a buffer has been
modified, how many lines of text it contains, how many characters of
text it contains, and gives information about the current
cursor/selection position. Also, if there is a task running in the
window, the status bar will let you know.


Cursors
-------
The cursor is a small flashing vertical line that appears in the text
of the active window. Its position indicates where the next editing
operation will take place. e93's editing model considers the cursor to
be akin to a selection of 0 characters. By contrast, in some editors,
you can have both a cursor, and a selection active simultaneously. In
e93, the selection and the cursor are really the same thing, so if you
have a selection, that IS your cursor.


Selections
----------
e93's selection mechanism is one of its more distinguishing features.
At first glance, e93 selects text in the same way as many other modern
editors, namely:

To select text for cut, copy, paste, or other operations, first move
the mouse pointer to the position where the selection should begin,
click the left button, and while holding it down, drag the mouse
pointer to the end of the desired selection. The process "highlights"
the selected text (by drawing it in inverse colors). The highlighted
selection can then be operated on by a number of editor functions. e93
also supports word, line, and document selection by double, triple,
and quadruple clicking respectively. (Double clicking is clicking the
mouse button twice in rapid succession). If you double click, holding
the left button down after the second click, e93 will then select words
as you drag the mouse along. This also works for lines when triple
clicking.

To adjust a selection, hold down the shift key on the keyboard, and
click the left mouse button in the document. This will either enlarge,
or reduce the current selection, depending on where you click.
Clicking outside the current selection will enlarge it so that it
extends to the point where you clicked. Clicking inside the selection
will reduce it by pulling the nearest edge in to the point where you
clicked. You can also shift-double, shift-triple or shift-quadruple
click, and get the expected results.

Segmented Selection

A powerful feature of e93 not found in most other modern editors is
known as "Segmented Selection." This means that e93 is capable of
creating a discontiguous selection (one which has "holes" in it). This
feature is used by e93 to implement a more familiar form of selection:

Columnar Selection

To create a columnar selection, click the right mouse button (if your
mouse has more than one button) and drag the mouse over the document.
This will create a selection that is rectangular. NOTE: if your mouse
only has one button, you can create a columnar selection by holding
the "Command" key on the keyboard down, while clicking and dragging.
You would typically use columnar selection to manipulate data that
appears in columns of text. As above, double clicking will force the
selection to begin and end at word boundaries. Triple and quadruple
clicking will also work as expected. You can also use the shift key as
described above to expand or reduce the columnar selection.

NOTE: although a columnar selection looks rectangular to you, it is
important to understand that e93 does not really think of it that way.
As far as e93 is concerned, a columnar selection is nothing more than
a discontinuous selection which spans pieces of the text. (In this
case, a small portion of one line, followed by a portion of the line
below it, and so on...) This distinction will become important as
operations that work on selections are discussed.


Marks
-----
Sometimes it is desirable to remember a given place in the text, and
be able to return to it later. Most editors refer to this feature as
"marking", or "book-marking". In e93, marks do not simply remember a
place in the text. Instead, they remember an entire selection. e93
allows for an arbitrary number of marks of arbitrary complexity. As
you edit the text, e93 attempts to update each mark so that it points
to what it used to, even though you may be making modifications above
or in the text which is marked. The default e93rc.tcl file sets things up
so that marks can be set in a buffer by typing CMD-F1 through CMD-F4
on the keyboard. The respective mark can be recalled by F1 through F4.


Cut, Copy, and Paste
---  ----  --- -----
Like other editors, e93 supports Cut, Copy, and Paste. When the
selected text is Cut from a buffer, it is removed from that buffer,
and placed into another buffer referred to as the "clipboard." When
the selected text is Copied from a buffer, it is not removed, but is
just copied into the clipboard. Each time a Cut or Copy operation
takes place, the text that is placed into the clipboard completely
overwrites the text that was there. Once you have text in the
clipboard, it can be placed into another buffer by pasting. Pasting
does not destroy the contents of the clipboard.

The clipboard in e93 is nothing more than a buffer which has been
designated as the clipboard. It is possible to designate any buffer as
the clipboard, and it is also possible to switch on the fly. This
allows e93 to support an arbitrary number of clipboards. The default
e93rc.tcl creates 10 buffers to be used as clipboards, and provides menu
operations to switch between these buffers.

NOTE: clipboard buffers in e93 do not typically have windows open onto
them, but it is possible, and sometimes desirable to attach a window
to a clipboard. The command to open a window onto clipboard 0 would
be:

OpenDefaultWindow clip0

NOTE: the command OpenDefaultWindow is not a command built into e93,
instead, it is a Tcl procedure, defined in the e93rc.tcl file (described
below).

Cut, Copy, Paste, and fun with Segmented Selections

Since e93 allows a selection to have "holes" in it, Cut, Copy, and
Paste take on a slightly different flavor than in most other editors.
When a selection is Cut, or Copied, the text of each segment of the
selection is placed into the clipboard sequentially. As each segment
is placed into the clipboard buffer, it is also selected as a segment
in the clipboard buffer. The result is a clipboard that not only
contains the pieces of text that were selected, but also one that
remembers where each piece begins and ends (since each piece is
selected individually in the clipboard).

When text is pasted from the clipboard, each segment is pasted
individually. The process works as follows:

Each selection in the clipboard is pasted over each selection in
the document until e93 runs out of selections in the clipboard or
document. If there are no more selections in the document, then the
remaining clipboard selections are pasted columnarly with each
successive segment placed into the line immediately below the
previous one..... If there are no more selections in the clipboard,
then the remaining selections in the document are deleted.

NOTE: e93 does not care how selections were placed into the clipboard.
It always pastes them in this columnar fashion. Also note that in the
case of a selection with just one segment (no discontinuity) that the
paste operation works exactly as it would in an editor without
segmented selection.


Scripting
---------
e93 utilizes the Tcl scripting language. This allows it great
flexibility. Users of e93 are able to write scripts to perform complex
editing tasks, as well as use them to configure the editor to personal
taste.

When e93 starts, it attempts to locate a file with the name e93rc.tcl
(some implementations use slightly different names). This file is
meant to contain a Tcl script. The script is charged with the task of
setting up all menus, key bindings, and defaults that will be
available when the editor starts. It is also the responsibility of
this script to interpret all of the command line parameters passed to
e93. That includes opening any files present on the command line.
Without this script, e93 would not do very much. Therefore, if the
script cannot be located at startup, e93 will complain, and quit.

This script is the primary means by which e93 is customized to the
taste of the user. Given the number of things defined by this script,
a fair amount of customization is available, but at the cost of some
complexity. See Appendix B for information on how to customize
e93 at startup time.

Once e93 has started, Tcl commands may be executed by typing them into
any window, and pressing the enter key on the numeric keypad. The
results of the command (if they are not piped elsewhere) are then
placed into the window.

If you are viewing this file from within e93, do the following:
Place the cursor anywhere on the following line, and press keypad
enter:

beep; okdialog {Hmmm, that was interesting}

You should hear a beep, and then a dialog should pop up with a useless
message in it. This works, because the e93rc.tcl script has bound the
keypad enter key to a function that grabs the line the cursor is on
(or the currently selected text), and sends it to Tcl for processing.

The list of built in commands that e93 currently understands is given
in Appendix A.


Keyboard Input
-------- -----
e93 separates the keyboard into three types of keys: modifiers,
characters, and functions.
There are 11 modifier keys defined by e93:
	caps-lock
	shift
	control
	modifier 0  (command)
	modifier 1  (option)
	modifier 2 - modifier 7 (implementation specific)

The character keys are a-z, numbers, tab, escape, return, etc...
These are the keys which would be expected to insert a character
when typed.

The function keys are:
Arrows, Backspace, F1, F2, Undo, Help, Break, etc... These are keys
which do not insert characters, but instead, perform actions.

When no keys are bound (See the section on Key binding below), e93
relies on a default set of bindings that are "hardwired" into the code.
NOTE: key bindings can be used to override this default behavior. Here
is a list of keys, and default actions:

All unmodified, or shift modified characters are inserted into the
active window.

All control modified characters are inserted into the active window
(e93 does not treat the control key specially by default, since
programmers often want to be able to enter control sequences into text
with a minimum of bother).

Unmodified Arrows move the cursor up/down by line, left/right by character.
Control Left/Right Arrow moves cursor by word left/right.
Control Up/Down Arrow scrolls the document down/up without moving the cursor.
Command Left/Right moves to start or end of line.
Command Up/Down moves up or down by page.
Shift can be used with the above combinations to expand or reduce the
selection.

Page up, Page down move the cursor up or down by a page.
Shift can be used with the page up/down to expand or reduce the
selection.

Home, and End move the cursor to the start or end of a line.
Command Home/End moves to start/end of the document.
Shift can be used with the home/end to expand the selection.

Unmodified Backspace deletes the character to the left of the cursor.
Command Backspace deletes to end of line.
Command Shift Backspace deletes to beginning of line.
Command Option Backspace deletes to end of buffer.
Command Shift Option Backspace deletes to beginning of buffer.
Control Backspace deletes word left.
Control Shift Backspace deletes word right.

Unmodified Delete deletes the character to the right of the cursor.
Command Delete deletes to beginning of line.
Command Shift Delete deletes to end of line.
Command Option Delete deletes to beginning of buffer.
Command Shift Option Delete deletes to end of buffer.
Control Delete deletes word right.
Control Shift Delete deletes word left.

Return does an autoindent (except in some dialog windows where it
selects the "Ok" option). NOTE: if you wish to place a new-line
character into the text of a dialog window, type Control J.

Tab inserts a tab (except in some dialog windows where it may move
between fields). NOTE: if you wish to insert a tab character into the
text of a dialog window, type Control I.

Escape inserts an escape (except in some dialog windows where it
selects the "Cancel" option). NOTE: if you wish to insert an escape
character into the text of a dialog window, type Control [.

Cut, Copy, Paste, Undo, Redo (if you have these keys) perform their
respective actions.


Menus and Key Bindings
----- --- --- --------
Menus are used to place functions that are executed often in a
convenient place where they can be accessed quickly. The menuing
system in e93 is dynamic. Menus can be added or deleted at any time.
There are two Tcl commands used to add/delete menus:

addmenu    - adds or replaces a menu in the menu bar.
deletemenu - deletes a menu, and its children from the menu bar.

Examples:

addmenu {} LASTCHILD 1 "Test" {\KA} {okdialog "Testing 123"}

This command adds a menu at the end (LASTCHILD) of the root menu {}.
The new menu is called Test, it has a keyboard equivalent of
CMD-SHIFT-a, and when selected, it will bring up a dialog box with a
test message in it. NOTE: if you are viewing this file from e93, place
the cursor on the example line above, and press keypad enter. You
should see the menu item being added to the menu bar.

To delete the menu:

deletemenu {Test}

Appendix A contains a more detailed description of these commands.

Keys can also be bound to functions within e93. Key binding is much
the same as defining menus. The major difference is that key bindings
have no visual representation (as in a menu item that the user can
see). Also depending on the implementation of e93, key bindings may be
more versatile than menu key equivalents, allowing a richer set of key
combinations to be bound to functions. For example, in the X windows
version of e93, menu key equivalents only function when the command
key is pressed, but bound keys can be bound to virtually all
combinations.

There are two major key binding functions:

bindkey   - bind a key combination to a Tcl script.
unbindkey - remove a bound key combination.

Using the menu example from above, if we wanted to bind the function
key F5 to bring up the test dialog box, the command would be:

bindkey F5 00000000000 {okdialog "Testing 123"}

To get rid of the binding:

unbindkey F5 00000000000

All those 0s are called the "modifier string" they tell which modifier
keys should be in which states for the binding to take effect. In this
example, no modifiers can be pressed when F5 is pressed if the binding
is to take effect. As usual, see Appendix A for a more detailed
description.

NOTE: the key binding, and menu key equivalent functions are
completely separate. If you define a menu that has a key equivalent,
and also bind that combination of keys to some other function, e93
does not guarantee which will take precedence, only that one of them
will be executed, and not both.


Find and Replace
---- --- -------
e93 performs search and replace like most other modern editors, with
the following exceptions:

Find All

This simply locates, and selects (using a segmented selection) all
occurrences of the search string.

Limit Scope

e93 can limit the scope of Find All/Replace All functions so that they
do not go outside the boundaries of the current selection (even if the
current selection is discontiguous (in which case it searches the
pieces individually)).

Tcl Procedures as Replacement Text

You can specify that e93 should treat the text of the replacement
string as a Tcl script to execute each time it is about to replace
something. e93 will execute the script, using the results of that
execution as the text to actually replace with. NOTE: when doing this,
the editor creates a set of Tcl variables which contain various
portions of the matched text. These variables can be used from within
the script to reference the text which is about to be replaced. The
variables are:
$found   - contains the entire text which is about to be replaced.
If the search is done using regular expressions, then:
$0-$9    - contain the contents of the matching subexpressions.

Information on e93's regular expression syntax is contained in the
file 'README.regex'.

As an example of why this might be useful, consider the task of
changing a bunch of numbers in a document from decimal to hex.
To do this in e93, you could enter the following into the find/replace
dialog:

Find (selection expression):
[0-9]+

Replace (treated as a Tcl script):
format 0x%X $found

The find part will locate numbers, the replace part will pass
these numbers to the Tcl "format" command which will convert
them to hex, and return the converted string. e93 takes this
string, and uses it as the replacement.


Undo and Redo
---- --- ----
e93 remembers undo/redo information only for operations which change
the text of a buffer. It does not remember cursor movements, or
selections.

Unlimited amounts of undo information are recorded separately for each
buffer. e93 groups multiple contiguous character insertions and
deletions so that they become single undo items.

Each time you undo in a buffer, e93 remembers what was undone as redo
information. However, once you make a change in a buffer, all redo
information is lost.


                                Appendix A
                                -------- -
This appendix lists the Tcl commands which are implemented by e93, and
gives a short description of each. These are in logical, not
alphabetical order.

Buffers and Windows
------- --- -------
	newbuffer bufferName
Create a new buffer with the name bufferName. If bufferName already
exists, this will return an error.

	openbuffer pathName
Open a buffer to the file at the end of pathName. This will return the
fully expanded path name for the buffer if it is successfully opened.
If asked to open a buffer to a file which is already opened, this will
return the previously opened buffer name. If asked to open a file
which cannot be opened, this will return an error.

	closebuffer bufferName
Close bufferName. NOTE: this does not ask any questions, it just
closes the buffer.

	savebuffer bufferName
If bufferName is linked to a file, this will save the buffer to its
file.

	savebufferas bufferName newPath
Save bufferName to newPath, if the save succeeds, the buffer is
renamed, and the new name is returned.

	savebufferto bufferName newPath
Save bufferName to newPath, do not rename the buffer, only complain if
the save could not be completed.

	revertbuffer bufferName
Revert bufferName to last loaded state, no questions asked.

	isdirty bufferName
Return a boolean value that tells if bufferName has been modified
since it was last loaded, or saved.

	fromfile bufferName
Return a boolean value that tells if bufferName is associated with a
file. A buffer is associated with a file, if e93 has read the buffer
from a file, or has done a savebufferas.

	haswindow bufferName
Return a boolean value that tells if bufferName has an associated
window.

	cleardirty bufferName
Set bufferName as unmodified.

	bufferlist
Return a Tcl list of all of the currently open buffer names.

	windowlist
Return a Tcl list of all of the currently open window names.

	openwindow bufferName x y w h fontName tabSize foregroundColor backgroundColor
Open a window onto bufferName. Place the window at x,y and give it size w,h.
The text will be displayed in font fontName. NOTE: if e93 cannot
locate the specified font, it will default to one of its own choosing.
tabSize is used as the initial tab size.
foregroundColor specifies the foreground color of the window as 3
hexadecimal digits, one each for R, G, B. (e.g. white=FFFFFF,
green=00FF00, gray=808080) backgroundColor specifies the background
color of the window.

	closewindow windowName
Close windowName if it exists, but do not close its associated buffer.

	setrect windowName x y w h
Change the position and size of windowName.

	getrect windowName
Report the position and size of windowName.

	setfont windowName fontName [styleIndex]
Change the font used by a window. If the font cannot be located,
default to one that can.

	getfont windowName [styleIndex]
Report the font in use by windowName.

	settabsize windowName tabSize
Set the tab size for windowName.

	gettabsize windowName
Report the tab size for windowName.

	setcolors windowName foregroundColor backgroundColor [styleIndex]
Set the colors for windowName.

	getcolors windowName [styleIndex]
Report the colors for windowName.

	buffervariables bufferName
Report all variable definitions assigned to bufferName.

	setbuffervariable bufferName variableName variableText
Assign a variable with variableName to bufferName. These variables are
kept local to each buffer. This makes it convenient for Tcl scripts to
hang information off of each buffer, then reference it later.

	getbuffervariable bufferName variableName
Get the text of variableName contained in bufferName. If no such
variable exists, an error is returned.

	settopwindow windowName
Make windowName the top-most window.

	minimizewindow windowName
attempt to minimize (in whatever way the current OS supports) the given document window

	unminimizewindow windowName
attempt to un-minimize (in whatever way the current OS supports) the given document window

	activewindow
Report which window is top-most.

	updatewindows
Redraw all invalid areas of all windows.

	screensize
Report the screen's width, and height.


Menus and Key bindings
----- --- --- --------
	addmenu menuPathList relationship active menuName menuModifiers menuFunction
Add a menu to the menu tree.
menuPathList is a Tcl List that tells where the add should take place.
relationship tells how the new item should be linked to the path:
	NEXTSIBLING	- link as next sibling of the given path.
	PREVIOUSSIBLING - link as previous sibling of the given path.
	FIRSTCHILD - link as the first child of the given path.
	LASTCHILD - link as the last child of the given path.
menuName is the name of the new element to add.
menuModifiers is a string that is used to change the menu item:
	\FfontName can be used to specify a new font for the menu item.
	\S makes the item a separator line.
	\KkeyName assigns keyName as a command key for the menu item.
menuFunction is a Tcl script to run when the menu item is selected.

	deletemenu menuPathList ?menuPathList ...?
Delete the menus at the end of menuPathList. (e.g. to delete all
menus, use deletemenu {})

	bindkey keyName modifiers keyFunction
Set up a binding between a keyboard key, and a Tcl script.
keyName is the system dependent name of the key to bind.
	(in X windows, it is the keysym name)
modifiers is a string of 11 characters that tell e93 which
	modifier keys should be in which states for this binding to
	take effect. The string can contain X, 0, or 1 in each character
	position.
		X - don't care which state the modifier is in.
		0 - modifier must not be pressed.
		1 - modifier must be pressed.
	The 11 modifier keys are (in order:)
		Caps lock
		Shift
		Control
		Mod 0	- system dependent modifiers
		Mod 1
		Mod 2
		Mod 3
		Mod 4
		Mod 5
		Mod 6
		Mod 7
For example: binding the combination Control-F5 to beep:
bindkey F5 00100000000 {beep}

	unbindkey keyName modifiers
Remove binding of keyName, modifiers.
Example:
unbindkey F5 00100000000

	keybindings
Report current list of keys, modifiers, and what they are bound to.

	waitkey
Wait for user to type a key, report keyName, and modifiers.

	getkey
See if a key has been pressed, if so, return keyName and modifiers
if not, return error.


Undo and Clipboard
---- --- ---------
	undotoggle bufferName
If there is redo information for bufferName, redo. If not, then if
there is undo information for bufferName, undo. If not, return an
error.

	undo bufferName
Perform a undo on bufferName. If there are no undos, return an error.

	redo bufferName
Perform a redo on bufferName. If there are no redos, return an error.

	breakundo bufferName
Put a break into the flow of undo information for bufferName.

	flushundos bufferName
Throw away all undo-redo information for bufferName.

	cut bufferName ?clipboardbuffer?
Cut the selected text from bufferName into the current clipboard, or
clipboardbuffer if specified.

	copy bufferName ?clipboardbuffer?
Copy the selected text from bufferName into the current clipboard,
or clipboardbuffer if specified.

	paste bufferName ?clipboardbuffer?
Paste the contents of the current clipboard, or clipboardbuffer if
specified into bufferName in a columnar fashion.

	getclipboard
Report the buffer which is currently assigned as the clipboard.

	setclipboard clipboardbuffer
Set the current clipboard as the buffer given by clipboardbuffer.


Dialogs
-------
	textdialog dialogTitle ?initialText?
Open a text entry dialog, with dialogTitle, and if specified, place
initialText into the dialog. If the user exits the dialog with Ok,
return the text that was entered. If he exits with cancel, return an
error.

	listdialog dialogTitle inputList
Open a list selection dialog, with dialogTitle, and place inputList
(which is a Tcl list) into the dialog. If the user exits the dialog
with Ok, return the sub-list (which is a Tcl list) of items that were
selected. If he exits with cancel, return an error.

	opendialog dialogTitle ?initialText?
Open a file open dialog, with dialogTitle, and if specified, place
initialText into the dialog. If the user exits the dialog with Ok,
return the list of files that were selected. If he exits with cancel,
return an error.

	savedialog dialogTitle ?initialText?
Open a file save dialog, with dialogTitle, and if specified, place
initialText into the dialog. If the user exits the dialog with Ok,
return the file name that was selected. If he exits with cancel,
return an error.

	pathdialog dialogTitle ?initialText?
Open a path choose dialog, with dialogTitle, and if specified, place
initialText into the dialog. If the user exits the dialog with Ok,
return the path name that was selected. If he exits with cancel,
return an error.

	okdialog dialogText
Open a dialog with just one button, containing dialogText.

	okcanceldialog dialogText
Open a dialog with Ok, and Cancel buttons, containing dialogText. If
the user exits the dialog with Ok, return without error. If he exits
with cancel, return an error.

	yesnodialog dialogText
Open a dialog with Yes, No, and Cancel buttons, containing dialogText.
If the user exits the dialog with Yes, return 1, if he exits with No,
return 0. If he exits with cancel, return an error.

	fontdialog dialogTitle ?initialFont?
Open a font selection dialog, with dialogTitle, and if specified,
place initialFont into the dialog. If the user exits the dialog with
Ok, return the font that was entered. If he exits with cancel, return
an error.

	searchdialog dialogTitle findbuffer replacebuffer backwardsVar wrapAroundVar selectionExprVar ignoreCaseVar limitScopeVar replaceProcVar
Open a search/replace dialog, with dialogTitle.
findbuffer is the name of the buffer that find text will be placed into.
replacebuffer is the name of the buffer that replace text will be placed into.
backwardsVar is the name of a variable which contains a boolean that tells
	if search should be done in reverse.
wrapAroundVar tells if search should wrap around.
selectionExprVar tells if find text should be interpreted as a regex.
ignoreCaseVar tells if case should be ignored during the search.
limitScopeVar tells if the scope of the search should be limited to the
	current selection.
replaceProcVar tells if the replace text should be interpreted as
	a Tcl script.
This dialog has 5 buttons which can be clicked on to exit
Find        - returns string "find".
Find all    - returns string "findall".
Replace     - returns string "replace".
Replace all - returns string "replaceall".
Cancel      - returns Tcl error.


Search and Replace
------ --- -------
the following options are available (see the command to know which options may apply):
	-backward		search backwards.
	-wrap			wrap the search or replace around the end of searchInbuffer.
	-regex			treat findbuffer as a regular expression.
		NOTE on replace:
		also, treat the contents of replacebuffer as a selection expression
		replacement string (unless -replacescript is present).
	-ignorecase		ignore case during the search.
	-limitscope		search only the selected text of searchInbuffer.
		NOTE: when limiting the search scope by the selected text of searchInbuffer,
		the regular expression characters ^, and $ will match the ends of a
		selection segment.
	-replacescript		treat the contents of replacebuffer as a Tcl
		script that should be executed when a match is found, the results
		of which will be placed into searchInbuffer. NOTE: when a match
		is found, the text that matched is copied to a Tcl global variable
		called $found, this variable can be referenced by the replace procedure.

	find searchInbuffer findbuffer [options]
Attempt to locate the text contained in findbuffer in searchInbuffer.
	options: -backward, -wrap, -regex, -ignorecase

	findall searchInbuffer findbuffer [options]
Attempt to locate all occurrences of the text contained in findbuffer
	in searchInbuffer.
	options: -backward, -wrap, -regex, -ignorecase, -limitscope

	replace searchInbuffer findbuffer replacebuffer [options]
Attempt to locate the text contained in findbuffer in searchInbuffer,
	if it is found, replace it with the contents of replacebuffer.
	options: -backward, -wrap, -regex, -ignorecase, -replacescript

	replaceall searchInbuffer findbuffer replacebuffer [options]
Attempt to locate all occurrences of the text contained in findbuffer
	in searchInbuffer, when each is found, replace it with the contents
	of replacebuffer.
	options: -backward, -wrap, -regex, -ignorecase, -limitscope, -replacescript


Cursors and Selection
------- --- ---------
	selectall bufferName
Select all of the text in the given buffer.

	selectedtextlist bufferName
Return a Tcl list, each element of which is a segment of the selection
in bufferName.

	selectline bufferName lineNumber
Select lineNumber in bufferName. If lineNumber is out of range, select
the line closest to the one given.

	getselectionends bufferName
Return the start and end positions (in characters) of the current
selection in bufferName. If there is no selection, the cursor position
is reported as both the start, and the end.

	setselectionends bufferName startPosition endPosition
Set the start and end positions of the selection in bufferName. If the
start and end positions are the same, place the cursor at that
position. If either position is out of range, it will be substituted
with the position nearest it.

	getselectionendlist bufferName
return offsets of the ends of each selection segment
if there is no selection, an empty list is returned

	addselectionendlist bufferName list
add list of ends given to the selection
if any position is out of range, it will be forced in range
if there is any overlap, the new segment boundaries will remain

	getselectionatposition bufferName position
return information about the selection at the given character position in the text
The result is a value (0 if no selection, 1 if selection) and the position <= the given
one where the current selection begins, and the position just after the end of the selection

	setmark bufferName markName
Create a mark with the given name in bufferName. If there is already a
mark in bufferName with markName, it will be overwritten.

	clearmark bufferName markName
Delete markName from bufferName. If either the mark, or buffer
specified does not exist, and error is returned.

	gotomark bufferName markName
Set the selection in bufferName to the one marked by markName. If
either the mark, or buffer specified does not exist, and error is
returned.

	marklist bufferName
Return a Tcl list, each element of which contains the name of a mark
in bufferName.

	homewindow windowName ?position? ?STRICT|SEMISTRICT|LENIENT?
Move the view of windowName so that position (in characters) is
showing, if position is not specified, the current cursor position, or
start of the current selection is used.
STRICT     - Forces the view to change so that the given position is
	1/3 the way down the window.
SEMISTRICT - If the given position is off the view, this does the same
	thing as STRICT, else it does nothing.
LENIENT    - Move the view as little as possible to get the given
	position to be displayed.

	gettopleft windowName
Report the line number that is currently positioned at the top of
windowName, and the offset in pixels from the left.

	settopleft windowName topLine leftPixel
Set the line number to display at the top of windowName, and the
number of pixels from the left that windowName should display. NOTE:
if any value is out of range, it will be set to the nearest allowable
value.

	textinfo bufferName
Return the total number of lines and characters contained in
bufferName. NOTE: the total number of lines is actually the total
number of newline characters.

	selectioninfo bufferName
Return the following information about the selection in bufferName:
startPosition      - position where selection starts (in characters).
endPosition        - position where selection ends (in characters).
startLine          - line number where selection starts.
endLine            - line number where selection ends.
startLinePosition  - offset into startLine where selection starts.
endLinePosition    - offset into endLine where selection ends.
totalSegments      - total number of selection segments.
totalSpan          - total number of character selected.

	positiontolineoffset bufferName position
Given a character position within bufferName this will return the line
number which contains that position, and the offset into the line of
that position. NOTE: if position is out of range, it will be set to
the nearest legal position.

	lineoffsettoposition bufferName lineNumber offset
Inverse of positiontolineoffset. Given a line number, and a character
offset within the line, return the position in bufferName. NOTE: if
lineNumber, or offset is out of range, they will be set to the nearest
legal value.

	movecursor windowName relativeMode
Move the cursor in windowName in the direction given by relativeMode.
Valid modes are:
	LEFTCHAR       - move left by one (wrap to previous line if needed).
	RIGHTCHAR      - move right by one (wrap to next line if needed).
	LEFTWORD       - move left by one word (wrap lines as needed).
	RIGHTWORD      - move right by one word (wrap lines as needed).
	UPLINE         - move up by one line, attempt to stay at same horizontal offset.
	DOWNLINE       - move down by one line, attempt to stay at same horizontal offset.
	STARTLINE      - move to the start of the current line.
	ENDLINE        - move to the end of the current line.
	STARTPARAGRAPH - move to the start of the current paragraph.
	ENDPARAGRAPH   - move to the end of the current paragraph.
	UPPAGE         - move up by one page (as defined by the window size).
	DOWNPAGE       - move down by one page (as defined by the window size).
	STARTDOC       - move to the start of the document.
	ENDDOC         - move to the end of the document.

	delete windowName relativeMode
Delete the characters in windowName between the cursor, and relative
mode away from it. relativeModes are the same as in movecursor.

	expandselection windowName relativeMode
Expand the selection in windowName, by growing in relativeMode.
relativeModes are the same as in movecursor.

	reduceselection windowName relativeMode
Reduce the selection in windowName, by shrinking in relativeMode.
relativeModes are the same as in movecursor.


Editing functions
------- ---------
	clear bufferName
Delete all selected characters in bufferName.

	extract bufferName startOffset endOffset
Extract characters from bufferName between startOffset and endOffset.

	insert bufferName textToInsert
Delete all selected characters in bufferName, then insert textToInsert
at the cursor position.

	insertfile bufferName pathName
Delete all selected characters in bufferName, then insert the contents
of the file given by pathName at the cursor position.

	autoindent bufferName
Delete all selected characters in bufferName, insert a new line, then
move over by the amount of white space that is contained at the start
of the previous line.


Styles and Syntax highlighting
------ --- ------ ------------
Information on e93's styles and syntax highlighting is contained in the
file 'README.syntaxmaps'.

	getstyleatposition bufferName position
return information about the style at the given character position in the text
The result is a value (style index) and the position <= the given
one where the style begins, and the position just after the end of the
style

	setstyle bufferName startPosition endPosition styleNum
set the style of text of the passed buffer
if the given end position is < the start position,
the positions will be reversed
if any position is out of range, it will be forced in range

	selectiontostyle bufferName styleNum
Set the style of a buffer to a given value anywhere text is selected

	styletoselection bufferName styleNum
Set the selection in a buffer everywhere a given style is in the buffer
NOTE: this does not clear the old selection, it will just add to it

	addsyntaxmap syntaxMapName syntaxMap
create a syntax highlighting map from a list of expressions and a list of
mappings from expressions to styles
NOTE: this can be used to replace an existing syntax map, but
if the existing map is in use by any buffer which is busy, this will fail
before it does anything

	deletesyntaxmap syntaxMap
delete a syntax map that was created by "syntaxmap"
Remove the map from all buffers which are using it
NOTE: if any buffer which is using the map is currently busy, this will
fail before it does anything.

	syntaxmaps
return the list of currently defined syntax maps

	setsyntaxmap bufferName syntaxMapName
Set the syntax map in use for the given buffer
If an empty map string is specified, then remove any map from the current buffer

	getsyntaxmap bufferName
read back the syntax map in use for the given buffer

	syntaxmapbuffers syntaxMapName
Return the list of buffer names which are currently using the given syntax map


Misc
----
	setwordchars wordCharacters
Set the editor's understanding of which characters are considered part
of words, and which are not. wordCharacters is a string containing all
of the characters to be considered parts of words. The editor uses
this information when double clicking, and when moving the cursor in a
relative direction by word.

	getwordchars
Get the string which lists all the characters which are parts of words.

	execute bufferName script
Execute the given Tcl script, place the results in bufferName if it still
exists after the script is finished, otherwise throw them away.

	task bufferName taskData
If there is no task running in bufferName, start one running by passing
taskData to a shell. If there is a task running, place taskData on its
stdin.

	updatetask bufferName
If there is a task running in bufferName, see if it has any output
ready, and if so, get it, and place it into bufferName.

	eoftask bufferName
If there is a task running in bufferName, send it an EOF.

	killtask bufferName
If there is a task running in bufferName, send it a Kill signal.

	taskbytes bufferName
return the number of characters the last/current task has dumped into the given buffer
NOTE: this count is only reset when a task is launched

	hastask bufferName
Return TRUE if there is a task running in bufferName.

	beep
Make e93 emit an annoying beep sound.

	checkbuffer bufferName
Run a sanity check on bufferName. If there is no problem (which there
never should be unless there is a bug in e93) report some statistics
about bufferName. If there is a problem, e93 may CRASH, or if you are
lucky, it will tell you what is wrong. This should NEVER report any
problems. If it does, please let me know!

	forceQUIT
Rude unforgiving command which will make e93 QUIT without saving, or
asking to save any modified buffers. This is the only way to ask e93
to quit, so Tcl scripts must take care of the niceties of asking to
save modified buffers before this is executed.

	version
Report the version number of the e93 that you are running.

	settclstdout
set the buffer to be used for Tcl's stdout
if the buffer does not exist, complain, but if it is deleted while it
is being used as the output, that's ok -- the output is just discarded

	gettclstdout
return the buffer being used for Tcl's stdout
if the buffer does not exist, fail

	settclstderr bufferName
set the buffer to be used for Tcl's stderr
if the buffer does not exist, complain, but if it is deleted while it
is being used as the output, that's ok -- the output is just discarded

	gettclstderr
return the buffer being used for Tcl's stderr
if the buffer does not exist, fail


Environment-specific commands
-------------------- --------
There are some commands in e93 which are specific to the environment
it was compiled for. These commands allow for a more fine-grained
integration of e93 into various OSs and windowing systems.

X-Windows:

	raiserootmenu
Force the root menu window to the top of the window hierarchy.

	scrollbarplacement where
sets the scrollbar position to the left (where="left") or right
(where="right") for the next opened document/dialog windows. Default
is "right".


M$ Windows:
(these will be documented in detail later)
	windowscascade
	windowstilehorz
	windowstilevert
	windowsarrangeicons
	windowsprint
	windowssetglobalstatusfield
	windowssetglobalstatusbutton
	windowssetglobalstatusbarfont
	windowssetwindowstatusbarfont
	windowsgetstatusbarstringwidth
	windowsgetlocaltime
	windowswinhelp
	windowsgetregistrystringvalue
	windowssetregistrystringvalue
	windowssettaskseperator
	windowsdopopupmenu
	windowssetfiletranslationmode
	windowsgetfiletranslationmode
	windowsgetmousescrollspeed
	windowssetmousescrollspeed
	windowsgetscrollbarspeed
	windowssetscrollbarspeed
	windowsopenanothere93
	windowssetwindowtitle
	windowsrunapplication



                                Appendix B
                                -------- -
e93 can be customized by creating scripts that are executed when the
editor starts up. By default, e93 locates and executes the script
"e93rc.tcl". This script contains the base information for a typical
e93 setup. Although it is possible to modify this script to change
e93's configuration, it is not generally recommended, since with each
update of e93, you will have to reintegrate your changes with the new
version.

To help reduce the need to modify the "e93rc.tcl" script, and to allow
each user on a given machine to have a customized version of the
editor, the base startup script attempts to locate and execute various
user-specific script files.

In Unix, these files reside in the user's home directory (in the
directory ~/.e93), and allow the user to add to e93's functionality in
a convenient way.

The user's ".e93" directory may contain the following sub-directories:

syntaxmaps
syntaxmaps_aux
highlightschemes
highlightschemes_aux
modules
modules_aux
prefs

If the "syntaxmaps" directory is present, e93 will use the syntax map
definition files it contains in preference to the defaults it would
normally load. When this directory exists, e93 will NOT load its
default syntax maps. All syntax map definition files contained in this
subdirectory must have a name which ends in ".tcl" to be recognized.

If the "syntaxmaps_aux" directory is present, e93 will add the syntax
map definitions it contains to the defaults it normally loads. All
syntax map definition files contained in this subdirectory must have
a name which ends in ".tcl" to be recognized.

If the "highlightschemes" directory is present, e93 will use the
highlight schemes it contains in preference to the defaults it would
normally load. When this directory exists, e93 will NOT load its
default highlight schemes. All highlight scheme definition files
contained in this subdirectory must have a name which ends in ".tcl"
to be recognized.

If the "highlightschemes_aux" directory is present, e93 will add the
highlight schemes it contains to the defaults it normally loads. All
highlight scheme definition files contained in this subdirectory must
have a name which ends in ".tcl" to be recognized.

If the "modules" directory is present, e93 will use the modules (just
additional Tcl scripts, menu items, or whatever) it contains in
preference to the modules it would normally load. When this directory
exists, e93 will NOT load its default modules. All modules contained
in this subdirectory must have a name which ends in ".tcl" to be
recognized. Modules are typically used to define functions specific
to any given user's tasks.

If the "modules_aux" directory is present, e93 will add the modules it
contains to the defaults it normally loads. All modules contained in
this subdirectory must have a name which ends in ".tcl" to be
recognized.

Finally, if the "prefs" directory is present, e93 will execute all the
scripts contained within it as the last step in the initialization
procedure. It is at this point, that you can alter any preferences
that you desire before the editor opens any files.

Here is a collection of random rants from e93's author.

This may help you understand why the editor does some things and does
not do others.

If this sounds pompous to you, it is because I can be a pompous
bastard. Please excuse me.

Control key vs. Alt key
-----------------------
This is for all Windows users out there who might be wondering why e93
uses the "Alt" key to select menus (like Alt-X for cut, or Alt-C for
copy...) instead of the "Control" key which they might be used to using...

Let's see. Hmmm. How to put this gently...

When the Mac came out, (and introduced the world at large to windowing
systems) it had that strange looking clover key which was used to
select menu items. It was quickly learned by users that that key did
one and only one thing -- it accessed menu items from the keyboard.

The Mac also had a Control key. That key did what all Control keys are
supposed to do -- It allowed users to enter control codes which could
be used to Control TTY style devices -- you remember those things??
Guess what. Those things still exist, and although admittedly they are
less important today than they used to be, the Control key is still
needed.

Anyway, if I ever had to write a Telnet client or terminal program for
Windows, I would probably get fairly angry when I realized that I
needed to give my users the ability to copy text (which is Control-C
in Windows) AND the ability to send an ETX character to a process
(which is Control-C in the rest of the world). If I used Control to
send control codes (the original purpose for the Control key), it
means that my users would not be able to access menus in the way that
they were accustomed to. If I used the Control for menu shortcuts,
users would have a difficult time using my program for its intended
purpose (try using Telnet without a Control key).

I don't know why the "engineers" at M$ chose the Control key over the
Alt key when they were copying the Mac, but it is clear that they did
not consider the consequences too carefully.

Since I (thankfully) spend most of my time working in Unix, I think
I'll use the Control key for its traditional purpose -- entering
control codes.

BTW: the above applies only to the Unix/X version of e93. For the
Windows version (which fortunately I do not work on), it is clear that
Control needs to be used for menu keys, since trying to use Alt when
every other application uses Control (except maybe the terminal
program ;-) would annoy people more than an inability to enter control
codes into their documents.

Oh, and if this rant gave you the impression that I am in love with
the way X handles user interface, let me correct you now: X is my
*least* favorite windowing system. It addresses almost no user
interface issues, and in the process, causes every application running
under it to be different. I tolerate X because it is the only GUI
environment which runs on top of Unix, and is open source.
(If there is another, I would appreciate someone letting me know.)


Copy/Paste -- X style vs. Mac style
-----------------------------------
What could be more convenient? Just select some text with the left
mouse button, and then paste it by pressing the middle button. Your
hand would never have to leave the mouse. Sounds better than having to
select the text with the mouse, then go to a menu, or hit a key
combination to copy it, then do the same thing to paste -- right?

Perhaps. But in practice I find the X selection mechanism annoyingly
cumbersome.

First, it is far too easy to hit the middle mouse button by accident,
and paste unwanted text into whatever you happen to be working on. How
many people reading this have ever pasted a bunch of garbage into an
xterm, and ended up creating random files, or worse yet, deleting or
over-writing important ones??

Second, the copy-on-select mentality means that if I want to select a
bunch of text to delete it, I end up putting it into the clipboard,
writing over what I really wanted there. A good example of this is
trying to copy a URL from some document into the address entry window
of a browser -- Invariably I select the text of my document containing
the URL, bring the browser window forward, notice that the address
entry field is occupied by the last address I was looking at, select
that address to get rid of it, hit delete, then try to paste... Oops.
Damn. Now I go back to the original document and get the address
again... Grrrr.

Finally, having one selection for the entire windowing system means
that I cannot leave text selected in one window or application, move
to another to do something, then come back to the first without having
my selections wiped out.


Bracketing style
----------------
I do not really have a rant here, except that

    if(blah)
    {
        printf("blah\n");
    }
    else
    {
        printf("no blah\n");
    }

is MUCH easier for me to follow than the K&R style.

    if(blah) {
        printf("blah\n");
    }
    else {
        printf("no blah\n");
    }

If you submit code to be added to e93, do me a favor, and put it in
the style I like :-) It will save me the time of doing the conversion
myself, and make it more likely that I will take your code.


Tabs vs. Spaces
---------------
This one is a bit more sticky. Lots of people like to use only spaces
in their text documents. The argument is that spaces are always
spaces, and the text will always look the same to anyone who reads it.
If tabs are used, the argument is that different tools expand tabs
differently, and therefore, documents with tabs in them may not always
look as expected.

I understand this argument.

However, spaces are not as convenient as tabs when editing code.

If you are editing code, it is nice to have the various indentation
levels of the code represented as tabs. Tabs make it convenient to
move over to the next indent level, or back up to the previous one.

Many editors attempt to solve this tab/space issue by trying to guess
what the user intends. When the tab key is hit, these editors add the
correct number of spaces to the document to take the cursor to the
next tab stop. When the user hits a backspace, the editor must guess
that the intention was to back up over the "tab" and get rid of the
correct number of spaces. The problem is that the editor cannot really
know if what it is backing up over was typed as a tab, or was typed as
spaces. Therefore, it can guess wrong, which I find confusing/bad.

The best solution in my opinion is to have the editor do what the
user asked it to do with a minimum of guessing. This means that if the
user types a tab, he gets a tab. If the user hits backspace, he gets a
backspace. To me, this is the most convenient way to edit code.

If I need to export code to others who might be using tools which
are different than mine, and I want them to be able to see the code
as I intended it to look, I will convert tabs to spaces as a separate
step. See expand(1), unexpand(1).


Magic
-----
Some editors try to do things for their users by guessing what they
would find useful, then doing those things without being asked.
Here are some examples:

Changing line termination into the default for the current platform.
For example, some Unix editors might read a file which contained CRLF line
termination, and convert it to LF-only line termination without asking.

Adding a linefeed to the last line of a document.
For example, some editors may discover that the last line of a document
is lacking a line feed character, and automatically add one in.

Deletion of extraneous control characters.

Deletion of excess whitespace at the ends of lines.

Conversion of tabs to spaces, or spaces to tabs.

etc...

e93 can be made to do any of these. But by default, it will never do
*anything* to the text of a document without being explicitly
commanded to do so. This guarantees that you can load any document
into e93, make changes, save it, and know that the only differences are
the changes *you* made.
As a programmer's tool, I find this to be an important ability.

If you want the editor to do these things automatically for you, e93
is scriptable in Tcl. As a programmer, hopefully you will find such
scripts easy to create.

This material is derived from The GNU Emacs Manual, 9th edition.
Copyright 1985, 1986, 1987, 1993 Free Software Foundation, Inc.
and from the GNU regex library version 0.11.
Copyright 1992 Free Software Foundation, Inc.

The Free Software Foundation gives permission for the use of this
material in e93, with different distribution terms from those stated
in the Emacs manual, because e93 is free software, and thus worthy
of cooperation.


NOTE: this has been modified to reflect e93's syntax.
1/22/00 TMS (squirest@e93.org)

Regular Expression Syntax

Common Operators

* Match-self Operator::                 Ordinary characters.
* Match-any-character Operator::        .
* Concatenation Operator::              Juxtaposition.
* Repetition Operators::                *  +  ? {}
* Alternation Operator::                |
* List Operators::                      [...]  [^...]
* Grouping Operators::                  (...)
* Back-reference Operator::             \digit
* Anchoring Operators::                 ^  $  <  >

Repetition Operators

* Match-zero-or-more Operator::  *
* Match-one-or-more Operator::   +
* Match-zero-or-one Operator::   ?
* Interval Operators::           {}

List Operators (`[' ... `]' and `[^' ... `]')

* Range Operator::          start-end

Anchoring Operators

* Match-beginning-of-word Operator::  <
* Match-end-of-word Operator::        >
* Match-beginning-of-line Operator::  ^
* Match-end-of-line Operator::        $


Overview
********

  A "regular expression" (or "regexp", or "pattern") is a text string
that describes some (mathematical) set of strings.  A regexp R
"matches" a string S if S is in the set of strings described by R.

  Some regular expressions match only one string, i.e., the set they
describe has only one member.  For example, the regular expression
`foo' matches the string `foo' and no others.  Other regular
expressions match more than one string, i.e., the set they describe has
more than one member.  For example, the regular expression `f*' matches
the set of strings made up of any number (including zero) of `f's.  As
you can see, some characters in regular expressions match themselves
(such as `f') and some don't (such as `*'); the ones that don't match
themselves instead let you specify patterns that describe many
different strings.

Regular Expression Syntax
*************************

  "Characters" are things you can type.  "Operators" are things in a
regular expression that match one or more characters.  You compose
regular expressions from operators, which in turn you specify using one
or more characters.

  Most characters represent what we call the match-self operator, i.e.,
they match themselves; we call these characters "ordinary".  Other
characters represent either all or parts of fancier operators; e.g.,
`.' represents what we call the match-any-character operator (which, no
surprise, matches any character); we call these characters
"special".

  In the following sections, we describe these things in more detail.

The Backslash Character
=======================

  The `\' character quotes (makes ordinary, if it's special,
  or possibly special if it's ordinary) the next character.

	'\' sequences:

	\n			-- stands for new line (0x0A).
	\b			-- stands for backspace (0x08).
	\r			-- stands for return (0x0D).
	\t			-- stands for tab (0x09).
	\x##		-- allows specification of arbitrary characters in hex
				   for example \x0A is equivalent to \n.
	\0 to \9	-- backreference to register (not valid within [])


Common Operators
****************

  You compose regular expressions from operators.  In the following
sections, we describe the regular expression operators.


* Match-self Operator::                 Ordinary characters.
* Match-any-character Operator::        .
* Concatenation Operator::              Juxtaposition.
* Repetition Operators::                *  +  ? {}
* Alternation Operator::                |
* List Operators::                      [...]  [^...]
* Grouping Operators::                  (...)
* Back-reference Operator::             \digit
* Anchoring Operators::                 ^  $  <  >


The Match-self Operator (ORDINARY CHARACTER)
============================================

  This operator matches the character itself.  All ordinary characters
represent this operator.  For example, `f' is always an ordinary character,
so the regular expression `f' matches only the string `f'.
In particular, it does *not* match the string `ff'.


The Match-any-character Operator (`.')
======================================

  This operator matches any single printing or nonprinting character except
  newline (it is equivalent to `[^\n]').

  NOTE: if you wish to match absolutely anything, use `[-]', or `[^]'.

  The `.' (period) character represents this operator.  For example,
`a.b' matches any three-character string beginning with `a' and ending
with `b'.

The Concatenation Operator
==========================

  This operator concatenates two regular expressions A and B. No
character represents this operator; you simply put B after A.  The
result is a regular expression that will match a string if A matches
its first part and B matches the rest.  For example, `xy' (two
match-self operators) matches `xy'.

Repetition Operators
====================

  Repetition operators repeat the preceding regular expression a
specified number of times.

* Match-zero-or-more Operator::  *
* Match-one-or-more Operator::   +
* Match-zero-or-one Operator::   ?
* Interval Operators::           {}

The Match-zero-or-more Operator (`*')
-------------------------------------

  This operator repeats the smallest possible preceding regular
expression as many times as necessary (including zero) to match the
pattern. `*' represents this operator.  For example, `o*' matches any
string made up of zero or more `o's.  Since this operator operates on
the smallest preceding regular expression, `fo*' has a repeating `o',
not a repeating `fo'.  So, `fo*' matches `f', `fo', `foo', and so on.

  Since the match-zero-or-more operator is a suffix operator, it may
not be applied when no regular expression precedes it.  This is the
case when it:

   * is first in a regular expression, or

   * follows a match-beginning-of-line, match-end-of-line, open-group,
     or alternation operator.

  The matcher processes a match-zero-or-more operator by first matching
as many repetitions of the smallest preceding regular expression as it
can. Then it continues to match the rest of the pattern.

  If it can't match the rest of the pattern, it backtracks (as many
times as necessary), each time discarding one of the matches until it
can either match the entire pattern or be certain that it cannot get a
match.  For example, when matching `ca*ar' against `caaar', the matcher
first matches all three `a's of the string with the `a*' of the regular
expression.  However, it cannot then match the final `ar' of the
regular expression against the final `r' of the string.  So it
backtracks, discarding the match of the last `a' in the string.  It can
then match the remaining `ar'.

The Match-one-or-more Operator (`+')
------------------------------------

  This operator is similar to the match-zero-or-more operator except
that it repeats the preceding regular expression at least once; *note
Match-zero-or-more Operator::., for what it operates on, and how Regex
backtracks to match it.

  For example, supposing that `+' represents the match-one-or-more
operator; then `ca+r' matches, e.g., `car' and `caaaar', but not `cr'.

The Match-zero-or-one Operator (`?')
------------------------------------

  This operator is similar to the match-zero-or-more operator except
that it repeats the preceding regular expression once or not at all;
*note Match-zero-or-more Operator::., to see what it operates on, and
how Regex backtracks to match it.

  For example, supposing that `?' represents the match-zero-or-one
operator; then `ca?r' matches both `car' and `cr', but nothing else.

Interval Operators (`{' ... `}')
----------------------------------

Supposing that `{' and `}' represent the open-interval
and close-interval operators; then:

`{COUNT}'
     matches exactly COUNT occurrences of the preceding regular
     expression.

`{MIN,}'
     matches MIN or more occurrences of the preceding regular
     expression.

`{MIN, MAX}'
     matches at least MIN but no more than MAX occurrences of the
     preceding regular expression.

  The interval expression (but not necessarily the regular expression
that contains it) is invalid if:

   * MIN is greater than MAX

The Alternation Operator (`|')
==============================

  Alternatives match one of a choice of regular expressions: if you put
the character(s) representing the alternation operator between any two
regular expressions A and B, the result matches the union of the
strings that A and B match.  For example, supposing that `|' is the
alternation operator, then `foo|bar|quux' would match any of `foo',
`bar' or `quux'.

  The alternation operator operates on the *largest* possible
surrounding regular expressions.  (Put another way, it has the lowest
precedence of any regular expression operator.) Thus, the only way you
can delimit its arguments is to use grouping.  For example, if `(' and
`)' are the open and close-group operators, then `fo(o|b)ar' would
match either `fooar' or `fobar'.  (`foo|bar' would match `foo' or
`bar'.)

  The matcher tries each combination of alternatives in order until it
is able to make a match.

List Operators (`[' ... `]' and `[^' ... `]')
=============================================

  "Lists", also called "bracket expressions", are a set of zero or more
items.  An "item" is a character, or a range expression.

  A "matching list" matches a single character represented by one of
the list items.  You form a matching list by enclosing one or more items
within an "open-matching-list operator" (represented by `[') and a
"close-list operator" (represented by `]').

  For example, `[ab]' matches either `a' or `b'. `[ad]*' matches the
empty string and any string composed of just `a's and `d's in any
order.  Regex considers invalid a regular expression with a `[' but no
matching `]'.

  "Nonmatching lists" are similar to matching lists except that they
match a single character *not* represented by one of the list items.
You use an "open-nonmatching-list operator" (represented by `[^')
instead of an open-matching-list operator to start a nonmatching list.

  For example, `[^ab]' matches any character except `a' or `b'.

  Most characters lose any special meaning inside a list.  The special
characters inside a list follow.

`]'
     ends the list unless quoted by '\'.

`\'
     quotes the next character.

`-'
     represents the range operator unless quoted by '\'.

All other characters are ordinary.  For example, `[.*]' matches `.' and
`*'.

The Range Operator (`-')
------------------------

  Regex recognizes "range expressions" inside a list. They represent
those characters that fall between two elements in the current
collating sequence.  You form a range expression by putting a "range
operator" between two characters. `-' represents the range operator.
 For example, `a-f' within a list represents all the characters from `a'
through `f' inclusively.

  Since `-' represents the range operator, if you want to make a `-'
character itself a list item, you must quote it with '\'.

  Ranges do not need a start and end, if the start is omitted
for example, `[-a]' matches all characters through lowercase 'a';
if the end is omitted: '[a-]' matches lowercase 'a' through 0xFF;
[-] matches all characters.

Grouping Operators (`(' ... `)')
=================================================

  A "group", also known as a "subexpression", consists of an
"open-group operator", any number of other operators, and a
"close-group operator".  Regex treats this sequence as a unit, just as
mathematics and programming languages treat a parenthesized expression
as a unit. Groups can be empty.

  Therefore, using "groups", you can:

   * delimit the argument(s) to an alternation operator (*note
     Alternation Operator::.) or a repetition operator (*note
     Repetition Operators::.).

   * keep track of the indices of the substring that matched a given
     group. *Note Using Registers::, for a precise explanation. This
     lets you:

        * use the back-reference operator (*note Back-reference
          Operator::.).

        * use registers (*note Using Registers::.).

The Back-reference Operator ("\"DIGIT)
======================================

A back reference matches a specified preceding group.
The back reference operator is represented by `\DIGIT' anywhere after
the end of a regular expression's DIGIT-th group (*note Grouping
Operators::.).

  DIGIT must be between `0' and `9'.  The matcher assigns numbers 0
through 9 to the first ten groups it encounters.  By using one of `\0'
through `\9' after the corresponding group's close-group operator, you
can match a substring identical to the one that the group does.

  Back references match according to the following (in all examples
below, `(' represents the open-group, `)' the close-group, `{' the
open-interval and `}' the close-interval operator):

   * If the group matches a substring, the back reference matches an
     identical substring.  For example, `(a)\0' matches `aa' and
     `(bana)na\0bo\0' matches `bananabanabobana'.  Likewise, `(.*)\0'
     matches any string that is composed of two identical halves; the `(.*)'
     matches the first half and the `\0' matches the second half.

   * If the group matches more than once (as it might if followed by,
     e.g., a repetition operator), then the back reference matches the
     substring the group *last* matched.  For example, `((a*)b)*\0\1'
     matches `aabababa'; first group 0 (the outer one) matches `aab'
     and group 1 (the inner one) matches `aa'.  Then group 0 matches
     `ab' and group 1 matches `a'.  So, `\0' matches `ab' and `\1'
     matches `a'.

   * If the group doesn't participate in a match, i.e., it is part of an
     alternative not taken or a repetition operator allows zero
     repetitions of it, then the back reference makes the whole match
     fail.

  You can use a back reference as an argument to a repetition operator.
 For example, `(a(b))\1*' matches `a' followed by one or more `b's.
Similarly, `(a(b))\1{3}' matches `abbbb'.

  If there is no preceding DIGIT-th subexpression, the regular
expression is invalid.

Anchoring Operators
===================

  These operators can appear anywhere (except lists) within a pattern
and force that point in the pattern to match only at the beginning or end of a word or line.

* Match-beginning-of-word Operator::  <
* Match-end-of-word Operator::        >
* Match-beginning-of-line Operator::  ^
* Match-end-of-line Operator::        $


The Match-beginning-of-word Operator (`<')
------------------------------------------

  This operator can match the empty string either at the beginning of
the text or the beginning of a word. Thus, it is said to "anchor" the
pattern to the beginning of a word.

The Match-end-of-word Operator (`>')
------------------------------------

  This operator can match the empty string either at the end of the text
or the end of a word. Thus, it is said to "anchor" the pattern to the
end of a word.

The Match-beginning-of-line Operator (`^')
------------------------------------------

  This operator can match the empty string either at the beginning of
the text or after a newline character.  Thus, it is said to "anchor"
the pattern to the beginning of a line.

The Match-end-of-line Operator (`$')
------------------------------------

  This operator can match the empty string either at the end of the
text or before a newline character in the text.  Thus, it is said
to "anchor" the pattern to the end of a line.

VERY PRELIMINARY DOCUMENTATION ON SYNTAX MAPS

NOTE: while reading this, it will be very helpful to be looking
at an addsyntaxmap command from the e93rc.tcl file....

The addsyntaxmap command in Tcl creates a new syntax map.

A syntax map is the data structure which gives e93 all the information
it needs to search through a document, and apply styles to the text
which the map specifies.

The first argument of the addsyntaxmap command is the name of the map,
and the second argument is the mapping data itself.

Syntax maps are assigned to e93 windows with the command:
setsyntaxmap bufferName syntaxMapName

The mapping data is composed of keyword, parameter pairs. The only
valid keywords are:

exp
map
at
root

"exp" defines a regular expression in the map. You can define as many
as you want but the more you have, the slower the highlighting. The 2
parameters to exp are simply its name, and the expression being
defined. The expressions are matched using e93's regular expression
matching routines (The same ones which are used when you specify a
regular expression in the "Find" dialog.)

"map" describes how expressions are mapped to styles. There are 6
parameters to the map command.

The first is the name of the map. This will be important later. The
second parameter is the name of the expression which introduces a
given mapping -- it is called the start expression.

The third parameter is a (potentially empty) list of names of ending
expressions.

The remaining 3 parameters are the start-style, the between-style, and
the end-style. Styles are nothing more than integers which index
styles assigned to text. You can assign styles to the text by using
e93's commands:

setcolors windowName foregroundColor backgroundColor ?styleNum?
setfont windowName fontName ?styleNum?

maps work like this:
If e93 encounters text which matches the starting expression, it is
colored in start-style. If the list of ending expressions is
non-empty, then e93 searches for text which matches any of the ending
expressions. The text between the start and ending expression is
colored in the between-style. Finally, the text of the matching ending
expression is colored in the end-style. If the ending expression list
is empty, then e93 ends the mapping immediately after the text which
matches the start expression.

The "at" keyword is used to tell e93 which mappings to search for, and
when. "at" works like this: The first parameter is the name of the
mapping during which this "at" takes place -- the "parent map". The
next parameter is a list of mappings which are allowed to start within
the "parent map".

During the text between the starting and ending expressions of a given
mapping, e93 will search for the starting expressions of any mapping
which is specified by an "at" command for the given mapping.

The "root" keyword is just a special case of "at". It tells which
mappings are in effect when no other mapping is in effect.

As an example, consider rules to color 'C' strings. To color them, you
need to locate the start quote, and the end quote. But, while looking
at the string, you may encounter a '\' character which tells 'C' to
treat the next character specially. So.... The mapping would look like
this:

addsyntaxmap "C Strings" \
{
        exp {e_string_delimiter         "\""}	<<< expression which matches a double quote character
        exp {e_quoted_char              "\\\\\[-\]"}    <<< expression which matches a \ followed by ANYTHING

        map {m_string                   e_string_delimiter	{e_string_delimiter}	$style_delimiter	$style_string	$style_delimiter}
        map {m_string_quoted_char       e_quoted_char		{}						$style_char			0				0}

        at {m_string                    {m_string_quoted_char}} <<< within strings, look for \'s

        root {m_string}					<<< look for strings at the root level
}

NOTE: in the above example, \'s need to be quoted multiple times to
hide them from Tcl.

So, if you are not thoroughly confused, you are ready to write
syntax highlighting rules. :-)

There is one more tiny little detail that is very useful, but
was difficult to explain in the midst of the discussion above.

When specifying a "map", the start and end expressions are allowed to
take the form:

e_expressionName:#

where # is a number from 0-9. This number corresponds to the tagged part
of the regular expression given by e_expressionName.
For instance, if I had an expression, say...
        exp {e_sample_expression		"([a-z]+)([0-9]+)"}

I could have a mapping:

        map {m_sample_mapping	e_sample_expression:0		{}		$style_blah	0	0}

This means that the entire expression e_sample_expression needs to be
matched to start the mapping, but that the part which is used as the
start-expression is simply the [a-z]+ (tag 0)