Hi,

this is the README for TkEmacs, an emacs widget for the Tk widget set.
This widget gives you COMPLETE access to emacs, what means that this
emacs is completely integrated into your Tk interface.

In the subdirectory ./xfemacs you can find an application that uses
the TkEmacs widget. It is an emacs with scrollbars, menus,
fileselector boxes etc.

If you want to use emacs 18.59 please read the installation guide
carefully, as the emacs 18.59 distribution seems to have a bug, that
must first be fixed before you can use emacs 18.59.

WARNING!
--------
If you use this widget, be aware of the fact that it can lead into
trouble. It was tested, but as emacs is a complex system and Tk is
a complex system, too, there may still be some problems.

If you encounter any problems, please let us know. If you are able to
locate the bug, please send problems, bug fixes and ideas related with
the emacs code to:

	nickel@cs.tu-berlin.de

and problems etc. with Tk and the emacs C code (the modifications
related to TkEmacs, not general problems with emacs C code :-), to:

	garfield@cs.tu-berlin.de

If you don't know which one is the right address for your problem,
it's no problem... Just send it to one of us (you will not be punished
if it was the wrong address ;-).

Feel free to modify/adapt the sources and to write new lisp functions
for improved functionality. If you do so, please let us know, so we
can improve the widget for us and the other users (if there are any).


Requirements:
-------------
	- the Tk-2.3/Tcl-6.4 package or the Tk-3.0/Tcl-6.5 package,

	- emacs 18.58 or emacs 18.59 (other versions should work as
	  well, because there is nothing special done),

	- the tclRawTCP package from Tim MacKenzie
          (this package is part of the distribution)
          The package is also available at:
	    barkley.berkeley.edu


Building a patched wish:
------------------------
	- unpack the Tk distribution and change to the Tk
	  directory,

        - unpack the TkEmacs distribution in the Tk directory,

        - configure the tcl subdirectory as described in the README of
	  the tcl subdirectory. Normally this is something like this:
		cd ./tcl; config; cd ..

	  If this does not work, you should read the README in the tcl
	  subdirectory for more information.

	- on my (new) System V Rel 4 system, tclRawTCP does not work
	  correctly. I had to make a minor (ugly) change that is
	  activated in the file ./tclRawTCP.c with the define
	  MY_SYSVR4_FIX.

	- on my (old) System V Rel 3 system, no UNIX domain sockets
	  are available. So I just removed the inclusion of the
	  file <sys/un.h>, and also the call and the definition of the
	  procedure "unix_connect". I also inserted a warning when the
	  user tries to open a UNIX domain socket. These changes are
	  not part of the distribution.

	- patch tk.h and tkWindow.c with the file tkEmacs2.3.pat or
	  tkEmacs3.0.pat (depends on your Tk version). On my system,
	  the call of the patch program looks like:
		patch -l -p1 < tkEmacs3.0.pat

	- patch main.c with the file tclRawTCP2.3.pat or
	  tclRawTCP3.0.pat (depends on your Tk version). On my system,
	  the call of the patch program looks like:
		patch -l -p1 < tclRawTCP3.0.pat

	- if you not have applied the patches posted by John
	  Ousterhout, you should patch Tk 3.0 with the file tk3.0.pat.
	  It fixes some problems that otherwise make the working with
	  xfemacs a pain (or better... less good :-). On my system,
	  the call of the patch program looks like:
		patch -l -p0 < tk3.0.pat

	- rename the file tkEmacs2.3.c or tkEmacs3.0.c to tkEmacs.c
	  (depends on your Tk version).

	- rename the file tclRawTCP2.3.c or tclRawTCP3.0.c to
	  tclRawTCP.c (depends on your Tk version).

	- rename the file tclRawTCP2.3.h or tclRawTCP3.0.h to
	  tclRawTCP.h (depends on your Tk version).

	- adapt the Tk Makefile. You can either change the original
	  Makefile from the Tk distribution. This requires the
	  following changes:
		- Add the file tkEmacs.o to the WIDGOBJS variable,
		- Add tclRawTCP.o to the OBJS variable,
		- Add -DUSE_TK to the CFLAGS.

	  You can also use the already adapted Makefile which comes
	  with the TkEmacs patch. It is named Makefile2.3.TkEmacs or
	  Makefile3.0.TkEmacs (depends on your Tk version). You may
	  have to adapt it to fit your local site (all the stuff you
	  do to get the normal wish compiling on your system),

	- call "make" in the Tk directory. If you adapted the original
	  Makefile from the Tk distribution, this looks like:
		make     (whow :-),

	  If you adapted the Makefile that is part of the TkEmacs
	  patch, the make call looks like:
		make -f Makefile3.0.TkEmacs    (and again... whow :-),

	- install the wish under a new name. We installed it under the
	  name "ewish". This name is also used in the xfemacs script.


Building a patched emacs:
-------------------------
	- do whatever is necessary to install emacs on your system,

	- patch src/x11fns.c and src/x11term.c with the file
	  emacs18.58.pat or emacs18.59.pat from the TkEmacs
	  distribution,

	- "make" the emacs,

	- install the emacs under a new name. We installed it under
	  the name "TkEmacs". This name is the default name for the
	  widget,

	- install all .el files from the TkEmacs distribution in a
	  emacs lisp directory.

	- the file cl.elc from the standard distribution of emacs
	  18.59 seems to have problems. Please replace or override it
	  with a (local) newly byte compiled version.


Installing xfemacs:
-------------------
	- copy the file xfemacs2.3.tcl or xfemacs3.0.tcl (depends on
	  your Tk version) from the directory ./xfemacs to a global
	  location, where the xfemacs shell scripts can find it,

	- adapt the load path in the shell scripts xfemacs.sh and
	  xfemacsc.sh to the location of the tcl file,

	- install the shell scripts xfemacs.sh and xfemacsc.sh to a
	  global bin location.


Compatibility notes:
--------------------
We tried to keep the changes to Tk and emacs as small as possible.
The changes to Tk only add the TkEmacs widget to the known commands.
If you don't use the TkEmacs widget, you will not notice any changes
compared to the standard wish (only tclRawTCP is new :-). In emacs,
all changes are only active if you call emacs with a special new
option. If you don't call emacs with this option, you should not
notice any changes compared to standard emacs.

The basic concept of this widget is, that the TkEmacs widget provides
a window id that emacs uses for its displaying instead of making an
own new window. Emacs creates a local window that is not mapped, from
which it receives X11 events.  This window id is passed to the TkEmacs
widget. The widget forwards all events to this window id that are
interesting for emacs.

Beside this mechanisms for passing X11 events and displaying the
output of emacs in the widget window, the communication between the
widget and emacs is done via a tcp connection.


Availability:
-------------
TkEmacs is available via anonymous ftp at:
	coma.cs.tu-berlin.de:	pub/tcl/TkEmacs1.3.tar.Z or
                                pub/tcl/TkEmacs.tar.Z (always the last release)
	barkley.berkeley.edu:	tcl/code/TkEmacs1.3.tar.Z


Feedback (Authors):
------------------
Sven Delmas
TU Berlin, Germany
garfield@cs.tu-berlin.de

Juergen Nickelsen
TU Berlin, Germany
nickel@cs.tu-berlin.de

