			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, NN
represents the release (for example, '31' for Typist 3.1):

    o JtNNsrc.zip - these are the source files, in Java, the Makefile,
      and an example HTML file to launch the program as an applet; you
      may unzip this archive and build the complete application, or you
      may use the pre-built class files instead, if you have them.

The following additional files will probably be present in a distribution.
All of these are replicate in, or can be built from, the above source
file archive::

    o JtNNcla.jar - a set of pre-built class files, encased in a jar
      file for convenient access.
    o JtNNdoc.html - a built Typist User's Guide documentation file.
      If you don't have this file, you can readily build it from the
      source files.
    o JtNNapp.html - a Typist applet launch HTML file.  This file will
      run Typist for you in a selection of canned configurations,
      assuming you have an applet-capable Web browser to hand.
    o COPYING - a copy of the GNU license
    o Makefile - a Makefile to enable instant installation
    o README - this file

A few files in JtNNsrc.zip are repeats of additional files listed
above, for one reason or another.  If you unpack the source archive in
the same directory where you unpacked the main distribution archive,
you may be asked whether you want to overwrite an existing file.  It
doesn't matter here whether you choose to overwrite the existing file
or not, since the files will be identical.


Installing binaries
-------------------
Unzip the main distribution, to obtain the JtNNcla.jar and JtNNapp.html
files listed above.

To get started quickly, do the following:

    o To run Typist as an application, set your class path to point to
      the jar archive, and run Typist.class with the JVM.  For example,
      on UNIX, Linux, and other UNIX-like systems, the command
      'CLASSPATH=`pwd`/JtNNcla.jar java Typist' should work.

Or...

    o To run Typist as an applet, point an applet-aware browser at the
      file JtNNapp.html.

And off you go.  That's the joy of Java.  

Full instructions for running Typist are in the file JtNNdoc.html. 
To summarise briefly, here's a list of the important files:

    o JtNNdoc.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 JtNNcla.jar - this is a jar archive that contains all the
      classes and properties files for the runnable program.  Use this
      file for both the application and the applet form of the program.
      Within this file, the most important class is the Typist class.
    o JtNNapp.html - example HTML file that invokes Typist.class,
      from within JtNNcla.jar, as an applet.

Here's a list of the important classes:

    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 HelpHTML.class - this class builds the Typist HTML User's Guide
      document, when its main() method is called.


Convenience application installation
------------------------------------
If you wish to run the application version of the program, there is a
convenience form of installation available; this will copy the file
JtNNcla.jar to

    /usr/local/lib/jtypist/JtNNcla.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

    JtNNsrc.jar

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.

3.1e, 24th January 2000
		- Moved program 'data' completely out of the Java source, and
		  into properties files.  Messages, help text, GUI colours,
		  lesson series, and even the keyboard maps can now be altered
		  without the need for a Java compiler.  The properties file
		  syntax isn't completely intuitive, but it's probably no
		  worse than dealing with the Java source code.

		- Fixed some of the colour contrast problems by shuffling
		  the colours around a little.

		- The binaries are now all supplied as a single jar file.
		  For the most part, this is to do with the fact that the
		  program needs to be in a jar file so a browser can access
                  the properties files.

		- Minor optimization in keypress event handling, and in the
		  use of class variables to save a bit of memory; nothing
		  spectacular, though.

		- Got rid of the -l flag for specifying a locale.  You should
		  now use LANG, or whatever your system offers, for setting
		  the locale of the JVM when you run the program.

		- Changed the distribution zip files, to get the lesson text
                  and keyboard layouts into their own zip files, and remove
		  the duplication of them in both source and binary zip files.

		- Small tidy-up of the Makefile, which was getting a little
		  out of hand.  Plus, of course, the changes necessary to
		  handle the new jar file requirements for applets.

		- Added Francais and Deutsch synonyms to the French and
		  German keyboards, for a laugh.

		- Put CLASSPATH at the front of the classpath passed to the
		  JVM by the jtypist wrapper, so that classes and properties
		  on the CLASSPATH can override those in the jtypist jar file.

3.1f, 21st February 2000
		- Fixed the init progress gauge non-appearance in applets.

		- Tweaks to the help text.  Added some colour control for the
		  HTML document produced by HelpHTML class.

		- Added an attempt at a Spanish keyboard.

		- Extended colour control for more freedom, and added some
		  simple font control.  Set up the fonts so that the GUIs,
		  in particular the Exercise Window, are much easier to
		  read (for example, by using a monospaced font for input).

		- Added an annoy-your-friends beep option on incorrect
		  keypresses in exercises.  You'll be happy to hear this one
		  is off by default.  It also seems not to work on Windows.

		- Relaxed the tolerance some more on keying rhythm, to make
		  it much less fussy.

3.1g, 26th March 2000
		- Fixed a bug in the Help text, that caused a largeish chunk
		  of help on the Exercise Window to disappear.  (Thank you Vim
		  for finding that one!)

		- Formalized LessonType into a class.

		- Replaced all those nasty 'import x.y.*;' things with
		  individual imports for only those classes actually used.

		- Footling minor code tweaks, for readability.

3.1h, 2nd May 2000
		- Typist goes more graphical, with the inclusion of Xpm-
		  capable classes, and image-displaying buttons.  Added
		  image buttons to several toolbars and dialogs.  Why Xpm?
		  It's easily handled with a text editor, and basing it
		  on properties allows images to participate in localization.
		  Watch the image on the "About Typist" dialog closely.

		- Added a Tooltip class, and attached tooltips to several
		  GUI components.  Tooltips don't really work in the applet
		  version, though, so are normally switched off when the
		  program launches as an applet.

		- Moved bulk data (.properties) files into subdirectories
		  to reduce clutter.

		- Major work on the class, source, and doc file naming for
		  the distribution.  This should significantly reduce the
		  amount of unzipping required.  The file names are also very
		  close to DOS 8.3 format, making it simpler to copy the
		  entire application onto a DOS-format floppy disk.

		- Minor improvements to threads handling in cases where the
		  frame associated with a thread is not visible.

That's it.  Have fun!

Simon Baldwin, simonb@sco.com
