How to Use the Turing Kit
-------------------------

The Turing Kit is a Java /application/ (not an applet) that
enables the construction, simulation, and study of the abstract
automata studied in CS396.  Deterministic Finite Automata (DFAs) and
Turing Machines (TMs,DTMs) are directly supported now, while 
Pushdown Automata (PDAs) will be presented as a restriction of two-tape
Turing machines.
As a Java application, Turing Kit is not subject to the
limitations of applets, and can freely write and load files.

The application comes in a single Java Archive
(.jar) file, TKit70.jar,
together with necessary startup text files "welcome.tmt" and
"default.pal".  /It runs only under full installations
of Java 1.1.3 or later/, and since our default "java" is 1.0.2,
you'll have to use the special commands below.
If you know what you are doing, you may ask our permission to copy the
{\tt .jar} file to a home machine and run it there, but otherwise we expect
that you will work with it in the CS labs from an X workstation.
(MicroImages ({\tt www.microimages.com}) offers a free X server for
Windows or Mac.)


Special Setup Instructions
--------------------------

The main setup issue is that we want you to be able to run the
single copy in  /u1/faculty/regan/cs396/TKIT70/ , while working in
your own directories---i.e., without having to ``cd'' to ours.
Java provides a mechanism 
for this, using a special environment variable called CLASSPATH,
which you can set in your C-Shell Resource Controller file (.cshrc)
in your home directory (or etc. if you use another shell). 
To do so, include the line:

setenv CLASSPATH .:/u1/faculty/regan/cs396/TKIT70/TKit70.jar

(Or if this is installed in another directory besides /.../TKIT70,
give the appropriate path.)
What's going on is that CLASSPATH requests a list of paths, separated
by colons : .  It is always a good idea to make `.' (``current directory'')
the first entry in this list.  
(If you already have a CLASSPATH line, you may need to check and make
sure that none of our class names, in particular ``Main.class,''
conflicts with a class already in your path.  Yes, we will find
more-distinctive names later!)

[While we're at it, here's a change to your .cshrc file that will
give you a nice prompt that shows your current directory.  Copy the lines

set host = `hostname | cut -f1 -d"."`
set prompt = "$host\<%c""> " 

into your .cshrc file, meanwhile pre-pending a # to
``comment-out'' the existing "set prompt=" line you have.
To make the changes take effect now rather than the next time
you log in, enter the command "source .cshrc" (or etc. for a different
shell).  As always, if you're uncertain about what's going on,
please see a technician in the lab and/or ask the instructor or TA
for assistance.]

Java 1.1.x was a massive overhaul of the Java language when it came
out officially last March.  It is /better/, but still a little
/buggy/, and the rest of the world has been taking longer
than expected to catch up with it.  Indeed, neither Netscape nor
MS Internet Explorer fully support it yet.  The default {\tt java} on
the CS machines is still Java 1.02.  Java 1.1.3 (and 1.1.4 and 1.1.5) are
installed on our machines, but need the full pathname to be invoked.
This can be done by creating one-line shell scripts 
(I call mine ``javac3'' and ``java3'' for Java 1.1.3)
with the lines

/util/lang/JDK-1_1_3/bin/javac $1

in the former, and

/util/lang/JDK-1_1_3/bin/java -ss500K -oss300K $1

in the latter.
I'm assuming that you'll put these into your root directory.
Finally, create a fresh directory in which you will do work for CS396,
and {\em copy the files\/} welcome.tmt and default.pal
from my /u1/faculty/regan/cs396/TKIT70 directory there.  Then enter

~/java3 Main &

\noindent
and you should be off and running.  If you get an error message
``Can't open X display\dots,'' then you will need to enter

\begin{verbatim}
setenv DISPLAY <the name of your workstation>:0.0
\end{verbatim}

\noindent
and try again. 


Running Turing Kit
------------------
	Once you're in, the interface is fairly intuitive.
Sometimes if you call up a menu item, the window may be smaller
than it should be---you can manually resize it, or call
View--->Auto resize in the main menu bar.  For navigation and etc.:

() Single-click on the canvas to add a state or a text box like this one.
() Single-click on any object to edit it:
   () Click on a state to add an instruction ("arc").  Next, click on the
      canvas to place the "middle handle" of the arc, and then click on the
      target state (which can be the same state).  Then (may be automatic):
   () Click on an arc's instruction box (initially "???" or "?") to fill it in,
      or to re-position it ("retract"), or unlink it, or to delete the /box/.
   () Click on an arc's "handle" (orange dot) to edit or delete the /arc/.
   () Click on a text box to edit it.  /"Undo" can undelete a deleted box./
   () Click on a state to make it Accepting and/or Current (e.g. Start) state.
() Menu items---most are standard/obvious; here are some other impt ones:
   () File-->New has a popup that lets you select DFA, DPDA, or TM.
   () View-->Organize rearranges and compacts the diagram.
   () View-->Resize... is currently the only way to expand the /canvas/.
   () Settings-->Lock Tape makes the tape move instead of the head.
   () Settings-->Alphabet allows you to select the alphabet for a new machine.
 
() Single-click on a tape cell to begin typing an input from that point.
   /Double/-click to move the tape head there.
   (Note: The standard Solaris double-click is quicker than on a PC or Mac.)
() To RUN a machine one step, click the green triangle ("Play").  To make it
   auto-run, move the speed-slider to any other position.  To pause/stop,
   click "Play" again.  (Use the rightmost three speeds with care.)
() Printing:  Beware that the "standard Java" printing method produces 
   huge Color PostScript jobs, and these may take a long time to print.

Since this is "alphaware", please save your work frequently.  Enjoy!

