README for mini editor e3 release 2.3

(c) GPL 2000-02 Albrecht Kleine  
mailto:kleine@ak.sax.de


1. OVERVIEW
===========
e3 is a collection of micro text editors with an executable code
size between 3500 and 20000 bytes, depending on used assembler options,
platform and self compressor.
Except for 'syntax highlighting', the e3 binary supports all of the basic
functions one expects plus built in arithmetic calculations. If you have 
installed the stream editor 'sed' you can use these tools as sub-processes,
getting the full power of regular expressions.

e3 can use Wordstar-, EMACS-, Pico, Nedit or vi-like key bindings,
whichever the user chooses.

Also the user can calculate arithmetics inside the text.

e3's assembler version is available on Linux, FreeBSD, NetBSD, 
OpenBSD, BeOS, QNX, Win9x, Atheos, and just new in a 16 bit version (e3-16) 
for DOS and ELKS (==Embeddable Linux Kernel Subset).

There is also a GNU-C-written version for non-i386-Unix
platforms (e3.c) using Wordstar keybindings only. This README
doesn't further mention e3.c. (Just make it!)

e3 is designed to be INDEPENDENT OF LIBC OR ANY OTHER library,
except on the QNX and Win32 operating systems.
It's been tested using the terminal console, but Xterm, Eterm,
kvt, rxvt, vt220 and vt100 should work too.
It's been tested under several x86 OS:
	* Linux kernels 2.0, 2.2, 2.4
	* FreeBSD 2.2, 3.1, 4.4
	* OpenBSD 2.9
	* NetBSD 1.51
	* BeOS 5PE
	* Win98
	* QNX RTP 6.1
	* Atheos 0.3.7
	* FreeDOS kernel 1.1.24
	* ELKS pre 0.1 (vt52 emulation)


2a. BUILD on Linux/FreeBSD/BeOS/QNX/Atheos
==========================================
A. For assembling of e3 you need NASM assembler v0.98 or v0.98.08

B. Unless you build a debug version ("make debug") Makefile will call
   a compressor for executables, but in Linux only and only if you
   have defined either gzexe or upx in Makefile.
   UPX comes from http://wildsau.idv.uni-linz.ac.at/mfx/upx.html .
   
C. If you don't like the default OS or destination (LINUX , /usr/local/ )
   then edit Makefile (other possible OS are FreeBSD or BEOS or QNX
   or ATHEOS).
   
D. e3 is expecting "sed" at /bin/sed, or "ex" at /usr/bin/ex; otherwise change 
   SEDPATH in e3.asm.  By default /bin/sed is used, but you can
   use /usr/bin/ex instead, if you edit Makefile as appropriate.
   (NOT available for BeOS,QNX,Atheos))

E. Build e3 via typing 'make' (or 'gmake' on FreeBSD)  for building:             
   e3	: the default Wordstar-like version,
   e3ws	: ditto Wordstar,
   e3em	: the Emacs-like version,
   e3pi	: the Pico-like version,
   e3vi	: the vi-like version.
   e3ne	: the Nedit-like version.
   (e3?? are symbolic links to e3. In fact only one executable is built.)

F. Optional: type 'make install' or 
   move or copy e3 and its symlinks wherever you want.

G. Optional: some more editable options are on top of e3.h: 
   for example, if you don't like WS mode, choice an other default mode 
   by setting DEFAULT_MODE to one of EM, NE, PI or VI .
   Also you could activate error beeping in vi mode by uncommenting 
   the BEEP_IN_VI line.
   

2b. BUILD on Win9x / ME / DOS
=============================
A. For assembling of e3 you need  NASM assembler v0.98,
   and ALINK (Anthony's Linker) and Win32 Import Library (win32.lib)
   Both are available for free on the net:
   	http://www.octium.net/nasm/
	http://alink.home.dhs.org/

B. Type 'make' , i.e. run make.bat, and move e3.exe, e3-16.com 
   and e3*.bat wherever you want.

C. Optional: some more editable options are on top of e3.h: 
   for example, if you don't like WS mode, choice an other default mode 
   by setting DEFAULT_MODE to one of EM, NE, PI or VI . In this
   case you would not need to call one of the batches to run
   your favourite mode.


2c. BUILD on NetBSD,OpenBSD
===========================
Here are 2 Makefile for BSD-make included.
In general you don't need to change that files.


2d. BUILD for ELKS
==================
This is done on usual 32 bit x86 Linux systems either
by typing "make elks" or changing to elks/ and typing "make".
You need to have installed the ld86 linker. (If you are interested
in ELKS systems I think you have it already on the harddisk.)



3. RELEASE NOTES
================
* Added a 16 bit version of e3 (aka e3-16) supporting DOS and
  ELKS (==Embeddable Linux Kernel Subset) in one source code.
  This initial release supports WS keys only.
  With e3-16 now we have e3 editors on the 9th and 10th operating system.
* Changed the Win32 version by replacing the DOS stub with e3-16 to 
  do something useful instead of complaining about "it can run 
  only under Win32".
  So you have TWO different editor executables in ONE file!



4. BASIC USAGE
==============
* All versions of e3 accept a filename as argument; see the man page.

* There is a status and input line, where you can enter filenames, 
  find-texts, line numbers  etc.  In the lower right corner you will find
  a code like "WS" showing the selected editor mode and a help
  pointer (EXCEPT vi).

* e3 changes the appearance of the cursor (to reverse) depending on 
  insert/overwrite mode (on Linux text console only). 

* For details on key bindings read each e3xx's initial page or 
  type Alt-H during edit (for vi use  ESC:h). 
  
* On some computers (BeOS, QNX etc.) Alt-key combinations won't work: 
  press <ESC> followed by the key, e.g. press ESC and H instead of Alt-H.

* e3 shows a dot for characters below ASCII 20h and between 80h and 9Fh
  (except win9x).

* At the end of an edit cycle, e3 asks you something like "SAVE? Ynl".  Press
  "n" to NOT save, "l" for SAVE and LOAD new, any other for SAVE and EXIT.


5. ARITHMETICS
==============
You can do some simple arithmetic calculations inside your text. 
For example:
                 1234+56*78=
place cursor here^ and press one of:

   ^KN  for WSTAR mode
   ^QC  for PICO mode
   ^X^N for EMACS mode
   #    for VI command mode
   ^K   for NEDIT mode
This should insert the result of 5602 into text.


Use values -999999999999.999999 ... -0.000001, 0, 0.000001 up to
999999999999.999999  and operators +-*/ and ( ) .

Some more examples:
 2+4*8=34
 2/3*3=2
 -4*-3--5*-4=-8
 4-3--4-3=2
 -5*-(13+-2*(3+4))+2=-3
 (7*(((((6+2+(((((1)))))))))))=63
 (13120-9972)/9972=0.315684
 100000000+0.000001=100000000.000001
 10000000000+1=10000000001
 1+1*2*3*4*5*6*7*8*9*10=3628801
 7.627891*2.643189=20.161958
 10000000000/8=1250000000
 100000000000+1.00001=99999997953.00001	<--loss of precision!
 8/0=					<--not possible. You know.
 100000000*100000000=			<--overflow 

Some specials: 
 12*p=37.699112				<--p is PI 3.14.....
 r+20=57.699112				<--r is result of last calculation
 
This arithmetic calculator is the smallest and simplest I could write.
It takes only some hundred byte in the executable because it does NOT use 
precise BCD arithmetics, but built in x87-coprocessor features. So please 
do NOT expect very high precision. 



6. MIXED HINTS
==============
* The emacs-mode version has currently a kill buffer but no kill ring,
  so be careful about that. I'm sure, inside 10000 byte you won't 
  expect a complete Emacs key set, but IMHO you get the most important part.

* The Pico mode is both: extended and incomplete compared to some Pico options,
  new are some ^J (delete) and ^Q (quick_move) keys.

* The size of files you edit is currently limited to the maximum of either 
  100k or twice the file's size if you start with a file on command line, i.e.,
  for example, starting e3 with a 2MB_sized_file gives you another 2 MB space 
  for inserts.

* You can choose inside the edit session (w/o leaving e3) between the 
  different edit modes, for example:
	-start  e3em <filename>
		---> now using Emacs style keys.
	-type   altX
	-type	e3vi
		---> welcome in the land of vi!
	-type   <ESC>;
	-type   e3ws
		---> you are entering Wordstar emulation sector!
	....etc....
  This VERY hot keys are ^KM (for WS), ^QM (for Pico), altX (for Emacs),
  ^E (for Nedit) and <ESC>; (for vi-mode).
  
  Note: on some computers press ESC X instead of altX.

* Everytime if e3vi does not recognize a vi-mode ex command, e3vi will pipe
  the whole editor text buffer through /bin/sed or /bin/ex. I.e. you can use 
  pure sed or ex commands like:
	1,6 s/foo/bar/
	2,$ d
	8,$ w filecopy
	/remove_me/d
  ***TAKE CARE***: "sed" or "ex" won't know your current cursor position in e3!
  What call to subprogram (either ex or sed) is compiled in
  you can find in helptext:
	"pipe buffer through /bin/sed"    
	vs.    
	"pipe buffer through /bin/ex"
  You should know this because the syntax is not equal:
	s/./\./		<--sed syntax
	1,$ s/./\./g	<-- ex syntax
  Also you should know what "sed" version you have installed,
  because sed 2.x and sed 3.x are quite different.
  You can use this new buffer pipe features also from WS-, Pico- and Emacs modes
  by pressing ^KP (Wordstar), or ^JP (Pico), or ^X^P (Emacs).

* There is no predefined UNDO level count. You can expect to UNDO at least
  one last insert-, delete-, overwrite- or sed_pipe-operation, but in most 
  cases there are lots of UNDO stages available.  e3 has a fixed size undo buffer
  and will use an external helper file if some deleted data is bigger sized 
  than the undo buffer. This buffer is organized as a ring, overwriting 
  older UNDO information if neccessary. So one never can say exactly 
  how many UNDO operations are possible. 
  For using the UNDO press one of:
   ^U   for WSTAR mode
   ^QU  for PICO mode
   ^_   for EMACS mode
   u    for VI command mode
   ^U   for NEDIT mode


7. FILES
========
Makefile	- (edit destination path and OS if desired)
e3.asm
e3-16.asm
e3.h		- NASM source code
e3.man		- man page (copied by default to /usr/local/man/man1)
e3.html		- man page, HTML version
e3.spec		- spec file for building RPM archives
README		- you are reading this
ChangeLog	- version history
COPYING.GPL
COPYRIGHT	- please read before using e3!
test/*		- partial test suite 
e3c/*		- C stuff for non x86 systems, e.g. Alpha
contrib/*	- useful things
doswin9x/*	- specials for Win9x and its derivates
elks/*		- specials for ELKS
binaries/*	- binaries separated for some operating systems
		  NOTE: binaries for QNX,AtheOS,BeOS are no more included.
		  Sorry, but there never was any feedback.


8. THANKS
=========
Konstantin Boldyshev <konst at voshod.com>
Mark Zealey <mark at itsolve.co.uk>
Urs Rau <urs.rau at uk.om.org>
Terry Loveall <loveall at qwest.net>
David Douthitt <n9ubh at callsign.net>
Bjrn De Meyer <bjorn.demeyer at pandora.be>
Matthias Kopfermann <kopfermann at trio-hittfeld.de>
Tim Wegner <twegner at swbell.net>
Michele Andreoli <m.andreoli at tin.it>
Aaron Lehmann <aaronl at vitelus.com>
Zas <lmonin at metaconcept.com>
Sergei Viznyuk <sviznyuk at hotmail.com>
Philippe Corbes <philippe.corbes at laposte.net>
Charles Steinkuehler <charles at steinkuehler.net>
Adrian Bunk <bunk at fs.tum.de>


9. TM note
==========
Some names are trademarks of their owners: 
Linux BSD BeOS QNX Unix WordStar Unox DOS Win Alpha BSE Atheos ELKS..etc.
