********************************************************************************
***                      Usage & Distribution Agreement                      ***
***                            Tk/Lisp Interface                             ***
***                                                                          ***
*** This file is part of the Tk/Lisp Interface (TLI) developed by the        ***
*** Lockheed Artificial Intelligence Center.  Use, duplication,              ***
*** distribution, and disclosure of the TLI is subject to the following      ***
*** restrictions and limitations.                                            ***
***                                                                          ***
*** 1. Lockheed makes no warranty regarding the merchantability or fitness   ***
***    of the TLI for any particular purpose.                                ***
***                                                                          ***
*** 2. Lockheed assumes no responsibility for the TLI and assumes no         ***
***    obligation to support or maintain the TLI.                            ***
***                                                                          ***
*** 3. The TLI can be duplicated and redistributed without restriction,      ***
***    provided that this Usage & Distribution Agreement header is left      ***
***    intact and unaltered in the source code.                              ***
***                                                                          ***
*** 4. The TLI can be modified and/or extended without restriction, provided ***
***    that all modifications and their authors are clearly noted in a       ***
***    header preceding this header in the source code files.                ***
***                                                                          ***
***    Lockheed asks that the authors of any such modifications or           ***
***    extensions to the TLI share them with the Lockheed AI Center in the   ***
***    same open manner as the Lockheed AI Center is sharing the TLI.        ***
***                                                                          ***
*** Please send comments about or enhancements to the TLI to Dan Kuokka      ***
*** (kuokka@aic.lockheed.com)  or Larry Harada (harada@aic.lockheed.com).    ***
***                                                                          ***
*** For more information about the Lockheed AI Center, see our               ***
*** World-Wide Web page @ http://www.rdd.lmsc.lockheed.com.                  ***
********************************************************************************
--------------------------------------------------------------------------------
TkLisp 1.0 Description
--------------------------------------------------------------------------------
The files in this directory implement a simple foreign function interface to 
the Tcl/Tk library.

The interface is based on the C Tcl_Eval() function with a thin layer on top 
to make the syntax more "Lisp-like" (see the file "demo/Notation"). This is
*not* a GUI toolkit (beyond what Tk already provides).

The basic model is essentially:

	1) Create an Tcl interpreter.
	2) Start an event loop in a separate Lisp process.
	3) Send Tcl strings to the interpreter.
	
Steps 1 and 2 are done with the macro tk-init-session. Step 3 is done with
the function Tkcmd. Tk callbacks are defined with def-tcl-command and 
attached with register-tcl-command.

The file "demo/sample.cl" was originally written as a "proof-of-concept" and 
more or less illustrates how TkLisp can be used. (That's all the documentation
we currently have ... sorry! Of course, please feel free to contact us with
bugs, problems, etc.)

The biggest problem with this implementation is that the event loop is 
non-blocking. Also, the Tkcmd function could probably be replaced with a 
macro that translates some of its arguments at compile time.

--------------------------------------------------------------------------------
Software Configuration
--------------------------------------------------------------------------------
The TkLisp software was implemented with the following software configuration 
under SunOS 4.1.3:

	1. Allegro Common Lisp 4.2
	2. Tcl 7.1
	3. Tk 3.4

The optional Tk tree widget used:

	1. Tk Tree 3.4
	2. gcc 

--------------------------------------------------------------------------------
Files
--------------------------------------------------------------------------------
a) Basic distribution 

	defsystem.cl	  	- System definition
	tk.cl		  	- Foreign function interface
	tkutils.cl	  	- Event loop, callbacks & misc utilities.
	
	foreign/tkutils.c 	- Utility functions.

	wish.tcl		- Tcl/Tk initialization script.

b) Tree widget support (optional)

	tktreecmd.cl	  	- Foreign function interface

	foreign/tktreecmd.c 	- Tree command

c) Demo 

	Readme			- Demo directions
	Notation		- Notes on the Lisp Tkcmd syntax

	defsystem.cl		- Demo system definition
	sample.cl		- Demo 

	sample.opt		- Tk options file
	emacs.tcl		- Tk emacs 
	wish.tcl		- Tcl/Tk initialization script

--------------------------------------------------------------------------------
Installation
--------------------------------------------------------------------------------

The following variables should be changed for your site before compiling the
files.

a) In the defsystem.cl files:

	*tk-foreign-file-directory* is the full pathname of the directory 
		of the ./foreign directory.

	*tk-foreign-library-directory* is the full pathname of the 
		directory containing libtk.a and libtcl.a at your site.

	*tktree-foreign-library-directory* is the full pathname of the
		directory containing libtktree.a and libOS.a from the
		tree widget distribution.	

	*gcc-foreign-library-directory* is the pathname of the directory
		containing libgcc.a and lib/libg++.a at your site.

	The default-pathnames in each defsystem should be changed to the
	installation or demo directory as appropriate.
  
b) In the foreign/Makefile file:

	TK_LIB  is the path for libtk.a
	TCL_LIB is the path for libtcl.a

	GCC	is the g++ compiler.

c) In the wish.tcl files:

	tclDir  is the location of init.tcl from the Tcl distribution
	tkDir   is the location of tk.tcl from the Tk distribution

	scriptDir is the location of the demo directory

