%
% sccsid("@(#)README	1.10          94/09/12").
% sccscr("@(#)  Copyright 1993 ECRC GmbH ").
%

This is ProTcl (pronounced pro-tickle), the Prolog interface to Tcl/Tk,
version 1.3. It is a rather lightweight interface, it allows to evaluate
Tcl expressions in Prolog and has also a rudimentary possibility
of callbacks from Tcl to Prolog.

Changes in 1.3:
- the 'nodisplay' option makes it start without a window, just Tcl

- most of the stuff is now autoconfigures

- the interface can now be statically linked into Eclipse, if dynamic
  loading does not work (HP700) or is too slow (SunOS).

Changes in 1.2:

- tcl_eval/2 is like tcl_eval/1 but its second argument is unified with
  the value returned by Tcl. This passes data from Tcl to Prolog.

- The 'prolog' command in Eclipse now supports flat lists and variables.
  A variable can be passed to Prolog and its value can be accessed in a Tcl
  array. This passes data from Prolog to Tcl.

- argv/1 option for tk/1 which goes into the Tcl argv variable.

- Initialization uses proper Tcl_AppInit mechanism to allow loading
  of extensions. For Eclipse, the library(tkext) is provided
  to load extensions with their Tcl_AppInit() function.

- Porting the eclipse version to Solaris 2.x.

This version corresponds to Tcl7.3/Tk3.6. The distribution
of these Tcl/Tk versions may be found in ftp.ecrc.de:/pub/eclipse/progs
as well as on other machines:

    sprite.berkeley.edu
    ftp.uu.net:             /languages/tcl
    ftp.x.org:              /contrib/tk*, /contrib/tcl*
    harbor.ecn.purdue.edu:  /pub/tcl
    ftp.ibp.fr              /pub/tcl
    gatekeeper.dec.com:     /pub/UCB/tcl/sprite
    syd.dit.csiro.au:       /pub/tk

To find out more about Tcl/Tk, read the README files in the Tcl/Tk
distribution.

The interface has been tested with ECLiPSe 3.4 and SICStus 2.1 on
a Sparc 10. I expect it to work with Quintus, however interactive
use and callbacks must be implemented by someone else as I don't
have Quintus 3.x. If you change the code to run on other machines,
please send me the diffs so that I can update the source.

The software is delivered as is, without any explicit or implied warranty.
Questions regarding Tcl/Tk itself can be sent to the Usenet group
comp.lang.tcl, questions regarding Prolog to comp.lang.prolog,
ECLiPSe questions to eclipse_users@ecrc.de and SICStus questions
to sicstus-users@sics.se.

Bugs and suggestions please to micha@ecrc.de.

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

1) Install Tcl and Tk.
2) For ECLiPSe, ProTcl files should be installed in the directory
   $ECLIPSEDIR/lib_graphic/tk. When you install ECliPSe, ProTcl is already
   included, so it is not necessary to ftp and install them separately.
   When getting only a ProTcl update, the files should be in the directory
   $ECLIPSEDIR/lib_graphic/tk. The simplest way is to remove the current
   lib_graphic/tk directory, unpack ProTcl in lib_graphic and rename
   protcl1.3 to tk.
3) Run configure of ProTcl. This creates a Makefile. configure recognizes the
   following options:
#
#	inst=DIR
#		DIR is the directory where Tcl and Tk are installed
#	src=DIR
#		DIR is the directory where the source of Tcl and/or Tk
#		rezides. It is necessary to run the Tcl and Tk test suite.
#	eclipse
#		Make an eclipse configuration, default.
#	sicstus
#		Make a sicstus configuration.
#	quintus
#		Make a quintus configuration.
#
   So e.g. to configure ProTcl for sicstus use
	./configure sicstus
   configure tries to locate Tcl/Tk and X11 in usual places. If it
   does not find it, you can specify the inst/src parameters or
   modify the Makefile after configuration.

   If your Tcl/Tk or X11 installation is in a non-standard path, you might
   have to change some paths in the Makefile.
4) make
5) The interface is loaded into prolog by :- use_module(library(tk))
   (in SICStus and Quintus it is necessary to change the library path first).
   The Makefile itself does not create a saved state, it only sets up
   the necessary files. Saved states with loaded .o files do not work
   in many Prologs, anyway.

   If it is not possible to load the interface dynamically, or if it is too
   slow, you can link it statically into the Prolog binary. For Eclipse,
   this can be done with 'make tkeclipse' in $ECLIPSEDIR/boot/$ARCH.

Bugs and problems
-----------------

I see a potential problem with SICStus and other Prologs that
do not have explicit volatile strings - when atoms are used
to send commands to Tcl, the Prolog atom table can be soon
filled up. To avoid this, ProTcl should be extended to provide
direct interface to the Tk functions so that the Tcl interpreter
does not have to be invoked. This, one one hand, would make the interface
tighter and better (one can use Prolog variables directly), on the
other hand it would become more dependent of the Tk source.
I guess we shall wait and see.

To port the whole functionality of ProTcl to another Prolog, two
nontrivial tasks must be accomplished:
1) To use Tk interactively, it is necessary that the Prolog system
   checks for X events frequently enough. In practice, this means
   that while waiting in the top-level loop for the next query,
   the Prolog process cannot block, but it has to process X events.
   Many Prolog systems have hooks in the top-level loop or in the
   read predicate itself, which allow to call a user-defined predicate
   before issuing a blocking read. This predicate should call
   Tk's function DoOneEvent and after return it should check if
   there is data on the input stream and if so, read the query,
   otherwise wait for the next event. This is possible because
   data on input will also cause an X event.

2) One way to call Prolog callbacks is to
   call Prolog from C. In this case a function call_prolog()
   should be written, which will be called when the Tcl command
   'prolog' is executed.

3) Another and better possibility is to use the prolog_event
   command which stores its arguments and returns, and these
   arguments can be retrieved in Prolog and used to call
   a Prolog callback predicate.

I intended to keep the source reasonably up to date for all three Prolog
systems, but as new and more complex features are added, I tend to do this
only for the Eclipse version, because I don't know enough about
the other two (and because I'm not pressed to port them).
