WHAT IS TKSOL
-------------
TkSol is a version of the card game solitaire written with the Tcl/Tk
language.  It requires Tcl 7.0 or above and Tk 3.3 or above.  A color
monitor is highly recommended, especially if you want to get addicted 
to the game, as trying to see which card is black and which is red 
under monochrome can be rather eye soring :(.  TkSol comes with a set 
of cardfront [faceup card] bitmaps created by Joseph L. Traub (see
cardbitmaps/copyright.h).  An initial set of cardback [facedown card]
bitmaps was hacked up by James da Silva <jds@cs.umd.edu>. 


WHERE TO OBTAIN TKSOL
---------------------
The current version of TkSol, version 0.9 Beta 1/5/94, can be obtained
by anonymous ftp from:

    harbor.ecn.purdue.edu 	in 	/pub/tcl/code/
    ftp.cs.umd.edu		in	/pub/tksol/


INSTALLING TKSOL
----------------
To test drive TkSol before installing it, type

    wish -f tksol.in -card_dir cardbitmaps -down_dir downbitmaps

in the directory where you unpacked the tksol distribution, and
replace `wish' with the pathname of the wish binary if necessary.

The tksol script and its man page can go into the appropriate places.
The bitmaps for the faceup cards can go into its own directory (eg.
cardbitmaps below).  Likewise for the bitmaps for the facedown cards
(eg. downbitmaps below).  I would recommend that you create a tksol
subdirectory somewhere under the directory where you installed the Tk
scripts and demos (ie. TK_LIBRARY), and put both bitmap directories
under this tksol subdirectory, eg.

   /usr/local/include/lib/tk/demos/
   ...
   /usr/local/include/lib/tk/tksol/
   /usr/local/include/lib/tk/tksol/cardbitmaps/
   /usr/local/include/lib/tk/tksol/downbitmaps/

Future versions of TkSol may contain more than a single .tcl file,
which can all reside in the above tksol subdirectory.  You can, of
course, put all the bitmaps into a single directory if you wish.

To install TkSol:

    1) edit the Makefile accordingly

You will have to specify, among other things, the location of your
wish executable, the default faceup bitmap directory, and the default
facedown bitmap directory.

    2) type `make' to create (1) the tksol script from the template 
       tksol.in, and (2) the tksol.1 manpage from the template
       tksol.man

This step hardcodes the location of your wish executable, the default
faceup bitmap directory, and the default facedown bitmap directory
into the tksol script and manpage.

    3) type `make install'

This installs the tksol script, its manpage, and the bitmaps.


BUGS AND NOTES
--------------
TkSol does not currently check for the colormodel.  As a result, on a
monochrome monitor, a button's text will not be visible if the cursor
is not over the button.  Hopefully, newer versions will come with a 
more decent monochrome setup.

There are couple of locations where, in order to find the item under
the pointer, I have used [find item closest $x $y] instead of using
[find item withtag current].  The latter has randomly been returning
nothing, ie. no item.  Repeated clicking on the same location gave the
same result.  However, if I moved the cursor away from the object and
then back to it, the correct item is returned.  I am not knowledgeable
enough with the Tcl/Tk internals to even try to figure out whether
this is a bug on my part or Tcl/Tk part.  As a result, I have stuck to
using `closest' which has, so far, always returns the correct item.
If you have an idea of what may be wrong with my usage of `current',
please let me know.

Also, a `tcl' stack is kept for each of the seven card `stacks' on the
bottom of the canvas.  I recently realized that this is redundant as
you can get all the necessary info from the [find item withtag <tag>]
command, which returns the items of a `stack' already in stacking, ie.
display, order.  The `tcl' stacks will probably be removed in a future
version.


FUTURE ENHANCEMENTS
-------------------
Currently, there are tons of enhancements/{mis}features that I would
like to add to TkSol.  Among the few things that may be available in
the next version (though probably not in the first post-beta version)
are:

- pixmap (gif/xpm3) support for those with TkPixmap support [I
  already have a version of this running, but I still have to merge
  it back in with the bitmap version and color 9 more cards]
- a configuration menu for things like changing facedown bitmap,
  changing the number of flip cards, etc.
- the ability to `peek' at a facedown card
- a better, ie. more graphically stimulating, endgame
- a smarter routine for autofinish'ing
- a better scoring formula
- allow the user to autoload his/her own routines, ie. if you don't
  like the provided endgame, you can write your own, put it in front
  of the default endgame on the autoload path, and bingo

I wrote TkSol as a way to learn Tcl/Tk, so there will be things in
TkSol that aren't as efficient as they could be.  If you see anything
that could be improved coding wise, please let me know.  Otherwise,
if you have any comments or bug reports, or make any changes to the
script or bitmaps, I would appreciate hearing it.  Oh, donations of
better, more colorful (for the pixmap version) card and back artwork
will be eagerly accepted.

1/5/94
Bao Trinh
bao@cs.umd.edu
