			Typist v3 Typing Tutor
			----------------------


Introduction
------------
Here is yet another reworking of the Typist typing tutor program, this
one in Java.

I have thrashed about with this program several times now.  I first
rewrote it in C/Curses, then in C++/Curses, and now, finally, I've
done it with a complete GUI front-end.

Because I have rewritten this same thing over and over, I can now
tupe jusy finr, so ironically, have little need for the finished item.


Delivered zip files
-------------------
The package runs on anything with a Java runtime that supports AWT.
The primary development system was Linux, but that should be largely
immaterial if the promises of Java are fulfilled (and as you may find
when you run the program, under AWT 1.1 some of these promises go
unfulfilled).

In the spirit of platform-portability, Typist comes delivered not as a
tar file but as a zip file.  (Un)zip is standard on Linux, and available
for just about all other UNIX's it seems, and failing having unzip on
your system, you may instead find 'jar' (the Java archiver).  Jar is
really only zip in disguise, and can probably unpack just about any
zipped file.  Hopefully, then, delivering Typist as a zip file will not
prove too much of an annoyance.

The following files form the core part of the distribution.  Here, N_N
represents the release (for example, 3.1), and x the optional release
letter:

    o typist-N_Nx_src.zip - these are the source files, in Java, the
      Makefile, and an example HTML file to launch the program as an
      applet.

The following additional files may be present in a distribution:

    o typist-N_Nx_bin.zip - a set of pre-built class files, and a built
      TypistNN.html (for example, Typist31.html) documentation file.


Installing binaries
-------------------
Just unzip, set your class path if necessary, and using Typist.class,
run either the application version or the applet version (within an
applet-aware browser).  And off you go.  That's the joy of Java.  

Full instructions for running Typist are in the file TypistNN.html. 
To get started quickly, here's a list of the important files:

    o TypistNN.html - the main 'User's Guide' for the program.  It's
      built by the HelpHTML class from data in the HelpText class, so
      it's a good idea to build this first for further information, if
      it didn't arrive in the download.  The Makefile target for it
      is 'doc'.
    o Typist.class - the main() method for this class is the one that
      implements the overall application.  Many of the other classes have
      main() methods too; these are generally test code for the classes
      they are in.  The init() method for Typist.class is also the code
      that runs the program as an applet.  Note that the applet form is
      nothing more than a single pushbutton that starts the complete
      application in a separate set of frames; this is necessary because
      the restrictions of the main in-browser applet window don't allow
      the full GUI to function.
    o TypistApplet.html - example HTML file that invokes Typist.class as
      an applet.


Convenience application installation
------------------------------------
If you wish to run the application version of the program, there is a
convenience form of installation available; this will create a .jar file
of all the required classes in the file

    /usr/local/lib/jtypist/JtypistN.N.jar

and create a wrapper script, /usr/local/bin/jtypist, to run the program
for you.  After installing like this, you should then be able to run the
complete application with the single command

    jtypist

The wrapper program passes all of its command line options to the Typist
application.  It will also let you vary some things about its operation
using environment variables, if you wish.  You can control the Java
runtime that is used with JTYPIST_JAVA, the directory to search for the
jar file of classes with JTYPIST_LIBRARY, the jar file name with
JTYPIST_JAR, and the actual class run with JTYPIST_CLASS.  So, to take
a contrived example, to use Kaffe as a runtime, and run the HelpHTML
class to generate the HTML documentation, the command would be

    JTYPIST_JAVA="kaffe" JTYPIST_CLASS="HelpHTML" jtypist

The default without any of these variables set is to run the Typist class,
which is the main typing tutor, using the command "java", and this is what
you'll want 99% of the time.

Use "make install_application" in the Makefile to create this form of
the installation.  Use "make uninstall_application" to uninstall the two
files.


Building the source
-------------------
To build the programs from the source code, first unzip the file
typist-N_Nx_src.zip.  If you have make, try that on the supplied Makefile.
If not, try 'javac *.java'.  Be prepared to wait if you have a modest
system; a full build on my 486 machine took around half an hour.


Modifications history
---------------------
3.0a, 4th March 1999
		- Corrected the calculation of adjusted WPM.  The original
		  was far too harsh in subtracting one WPM for each error.
		  The correction is to only subtract one effective word
		  typed for each error.  This has one fifth the effect.

		- Corrected ExerciseGUI so that if it has not yet run any
		  exercises, attempting to restart the lesson will not
		  result in a Java null pointer error (non-fatal).

		- Moved the JVM hints from README into the HelpText class.

		- Moved to lazy conversion of HTML into online help in the
		  HelpGUI class.

3.0b, 21st April 1999
		- Added word processing modes to exercises.  This allows
		  space to be used instead of Return at line ends, con-
		  denses multiple spaces into a single space, and also will
		  hop forwards over paragraphing and indents in the
		  exercises when a real Return is used.

		- Added dynamic loading of lesson data classes, to cut
		  down on startup time, especially when the program is run
		  as an applet.

		- Moved to JDK-1.1.7 build environment.

		- Cleaned up some code that wouldn't compile under guavac.

3.0c, 22nd April 1999
		- Fixed a bug in the ExerciseGUI to do with drill lines that
		  ended in a hyphen.  Not a major issue, but annoying enough
		  to not want to wait until the AWT 1.1 or SWING one.

3.1, 1st July 1999
		- Major refactoring of the class structure; several new classes
		  formalized, and some class names were changed to alleviate
		  the confusion that was starting to accrue.  One of the re-
		  factorings created an inner class in StatisticsGUI, so
		  unfortunately the program no longer compiles completely under
		  my guavac :-(

		- Added dynamic loading of KBLayout's, allowing new layouts to
		  be added without recompiling.  The -kb flag understands
		  how to use these.

		- Run flag/option added to allow the lesson series that the
		  program offers to be controlled.  With the series dynamic
		  loading, new series can now be added without recompiling.

		- Lazy initialization of the help text data added, to speed
		  startup, especially for applets.

		- Added code to automatically refresh the statistics gauges
		  in the background every second.  Made the gauge graphics
		  update much smarter.

		- Finally updated to AWT 1.1, and so all those deprecation
		  compiler messages are gone.  Sorry if you don't have a
		  1.1 AWT to run the program on :-(

		- Lots of code tidying, and a bit of extra polish added.
		  Added some javadoc commentary to the code.

3.1a, 6th November 1999
		- Minor tidy-up to the run() method in ExerciseGUI, to
		  sharpen the way the code runs.

		- Added an Introduction to the HelpText, since nowhere else
		  did the program actually say what it did.

		- Added a history feature to TutorialGUI and ExerciseGUI,
		  allowing easy redisplay of the most recent tutorials or
		  exercises.

		- Made lesson series T the default on startup; it's the most
		  comprehensive and helpful of the courses.

		- Fixed the tutorial text in all the lesson series to match
		  the way the Java application operates; prior to this fix,
		  they all still gave instruction based on the original
		  C/Curses version of the program.

		- Updated the N series from some ancient terminal type or
		  another to the PC numeric keypad, and added several
		  exercises to work with the non-numeric keys on this keypad
		  (/, *, -, +).

		- Added the convenient form of application installation to
		  the Makefile.  Use "make install_application" to create a
		  single .jar file of all the required classes, and a
		  simple wrapper script /usr/local/bin/jtypist to run the
		  application out of this .jar file.

3.1b, 15th November 1999
		- Minor tweaks to the Gauge class to make it more convenient
		  to use.

		- Added Keyboard Window, to present a keyboard map showing
		  the expected, error, and correctly typed keys.  Extended the
		  keyboard layout classes to cope with the new requirements.

		- Added Rhythm monitor, to evaluate the smoothness and
		  apparent regularity of keystrokes in an exercise.

		- Added replace and delete functions to KBLayout, allowing
		  keyboard layouts to be created as modifications to existing
		  ones; savings on typing, and to a lesser extent on
		  distribution size.

		- Added -r, realkbtype flag, to allow translations between
		  keyboard layouts on-the-fly.  Now, by giving the combination
		  "-k Dvorak -r US", you can type on your US keyboard in
		  the program, and it will behave as if you were in fact using
		  a Dvorak keyboard.  This makes it much easier to try out
		  different keyboard styles.

		- Added the Microsoft 'ergonomic' keyboard layout.

		- Added -d, -doc application option, to print out the user
		  guide in HTML - useful to regenerate user documentation from
		  the installed application.

		- The Caps Lock workround has been in but commented out for
		  a while now.  Since it looks like this JVM bug isn't going
		  to be fixed any time soon, I've finally uncommented it, and
		  we'll see what happens with it.

3.1c, 20th November 1999
		- Some refactoring round KBLayouts, created new Keycode object
		  for better control of keycodes.  Created KBNamespace to
		  make KBLayouts smaller and easier to read.

		- Fixed bugs in KeyboardGUI; numeric keypad keys 0 and 4 were
		  confused, and the window did not respond to X/WM close.
		  Also, added the option to hide key legends to this GUI.

		- Made the Dvorak keyboard more PC/Mac standard, and created
		  a new DvorakANSI type for those wanting ANSI.

		- Tightened the component focus, so that, for example, the
		  ExerciseGUI window has focus automatically placed into the
		  relevant entry text area whenever the window is activated.

3.1d, 17th December 1999
		- Finally worked full internationalization into the program.
		  Messages and online help text are now localizable, as sub-
		  classes of ListResourceBundle classes.  (Now all that's
		  needed are some real translations of the messages and the
		  help text, and, of course, some translated lessons... )

		- Made the rhythm monitor less picky, by using a more reason-
		  able measure of the median keystroke timing.

		- Minor tweaks to the word-processing modes in exercises.

		- Added in the extra shift states required to fully handle
		  international keyboards (for example, AltGr).

		- Improved the translations between keyboards, so that even
		  some 'difficult' translations, such as from US to French,
		  will usually work correctly.  Previous to this change, there
		  was no way to convert US into French and have the AltGr
		  characters handled.  Note however that 'dead' keys aren't
		  done - for this you will need a genuine French, or whatever,
		  keyboard.

		- Improved inheritance among keyboard types, by adding the
		  Basic* keyboard layouts.  Added French and German keyboard
		  types, as an exercise in understanding localized keyboard
		  layouts better.

That's it.  Have fun!

Simon Baldwin, simonb@sco.com
