			Typist v2.0 Typing Tutor
			------------------------


Introduction
------------
This program came from a desire to learn 'proper' typing, and not the
awkward keyboard prodding I've been doing for the past 10 years or
more.  Since I usually run Linux rather than Windows or DOS, I looked
around for a tutor program, and surprisingly, found nothing in the
usual places.

Eventually, I stumbled across Typist - a little gem of a program for
UNIX-like systems.  The original worked great, but after a while I
started noticing odd things - some lessons seemed to go missing, and
the programs were apt to exhibit some strange behaviours.  After
fixing a few bugs it seemed that the time was right for something of a
rewrite.

Not being one to be satisfied with learning just one new thing at a
time, this project also became the vehicle for learning C++.  The
result is Typist v2.1.  This has the same lessons in it (I'm by no
means qualified to alter anything in these, except perhaps the most
obvious speling erors), but contains two new, alternative Curses
programs, one written in C, and the other in C++, that run them.  The
lesson file format is new too; the original files were converted
across.


Delivered tar files
-------------------
The package runs on three platforms:

    o Linux
    o SCO OpenServer 5.0
    o SCO UnixWare 7

The following files form the core part of the distribution.  Here, N.N
represents the release (for example, 2.1):

    o typist-N.N.lessons.tar - this contains the basic lessons data
      files that the programs work on (the typing lessons themselves).
      These are required for either simply installng pre-built binaries,
      or for use with any of the compiled sources.
    o typist-N.N.src.tar - these are the source files, in C and C++, for
      the binary programs and the man pages.

The following additional files may be present in a distribution:

    o typist-N.N.*.bin.tar - where "*" is the platform, a set of pre-built
      binaries, and the typist.1 man page.  Posted versions of the program
      will probably contain binaries for Linux only.
    o typist-N.N.man.tar - the typist.1 man page converted into postscript
      and 'cat' format, for use with systems not having *roff installed
      or available.


Installing binaries
-------------------
Whether to use the C++ or C binary is a matter of preference.  The C++
one has better error handling, but uses (predictably) more shared lib-
raries and takes more memory to run.  The binaries are named c_typist
and cpp_typist; when installing, select one to link to typist.

To install the Linux binaries and man pages, as superuser

	UN-tar the lessons archive and the Linux binary archive.
	Copy the files c_typist and cpp_typist to /usr/local/bin, and
		set the mode to 755.
	Link either /usr/local/bin/cpp_typist or /usr/local/bin/c_typist
		to /usr/local/bin/typist, as required.
	Create the directory /usr/local/lib/typist, and copy everything
		from the lessons subdirectory into it.  Link the file
		/usr/local/lib/typist/typist.typ to combined.typ.
	Gzip the files typist.1, and copy the resulting .gz file to the
		directory /usr/local/man/man1, and set the mode to 644.

In Makefile, there is a make 'install' option that will do all this
after the untar for you.  It selects the C++ binary to run by default,
if present.  There's an 'uninstall' option, too.

To install the SCO OpenServer and SCO UnixWare binaries and man pages,
as superuser

	UN-tar the lessons, and the relevant binary archive, if you have it.
		If you don't, stop here - you'll have to build from sources
		first.  Otherwise, unless you have a *roff you should probably
		then go on to UN-tar the man pages archive.
	Unless you create one, there isn't a /usr/local/bin directory
		available by default for the typist binary(s).
		Either create one and copy the binary file(s) there, or
		put it/them elsewhere on your path.
	Create the directory /usr/local/lib/typist, and copy everything
		from the lessons subdirectory into it.  Link the file
		/usr/local/lib/typist/typist.typ to combined.typ.
	Like the binary(s), adding the man pages is a matter of preference.
		The typist.1.cat man page will be easy enough to integrate
		into the UnixWare 'traditional man pages', if they are
		installed.  On OpenServer, it is possible to put the
		typist.1.cat page under /usr/man somewhere, or to add
		an extra directory to the man search path.  For both
		systems, however, it's probably simpler to just print the
		Postscript version.

Again, in Makefile there is an install target you can use to accomplish
much of this.

If you don't want to, or can't, install the program onto the system
as superuser, you can still use it from your home directory.  To do
this, simply copy your selected typist binary into some directory on
your path, and put the *.typ files somewhere; point TYPIST_PATH to that
somewhere, and link typist.typ to combined.typ.  To go the extra mile,
you could, depending on your UNIX system, also copy the man page
somewhere and fiddle with MANPATH to get it to work with man.  Again,
however, it may just be easier to print the Postscript version.


Building the source
-------------------
To build the programs from the source code, first UN-tar the file
typist-N.N.src.tar.  Edit the Makefile to enable the section for one
of the supported platforms.

Remember that you need the lessons as well as the source code, so UN-tar
the file typist-N.N.lessons.tar, if you haven't done so already.

Then, run make on one or more of the following targets:

    o c_typist - this builds the C version of the program, and should
      work pretty much everywhere.
    o cpp_typist - this builds the C++ version.  The C++ version makes
      heavy use of the string class, so if you don't have that available
      then you won't be able to build this one correctly.
    o manpages - on Linux this formats the man page into 'cat' and post-
      script formats, for printing or for use with platforms not offering
      *roff facilities.
    o install - install the binaries, and man pages if appropriate.
    o demo - gives a brief demonstration of the features of typist.
    o uninstall - get the package off the system.

So for example, on Linux with g++ installed, run

    make cpp_typist install

or

    make c_typist cpp_typist install

to give you both binaries to play with.  Without g++, or on a platform
that won't compile the C++ version, type

    make c_typist install

As well as the C source for typist, and the lessons, the source code
tar file also contains a number of additional items.  None of these is
required for the build; they are provided for information only:

    o orig/
	This subdirectory contains a verbatim copy of the original
	typist program and lessons.
    o typv1tov2
	This is an awk script that takes a lesson file in the format
	of the original program, and converts it into a format
	suitable for version 2.  As part of the conversion, a rudi-
	mentary lesson menu is added.
    o typcombine
	This is an awk script that will combine a number of lesson
	files into a single file.  Again, a simple menu is added.
    o mklessons
	This is a small shell script that does the conversion of all
	the lessons from the orig/ directory into a lessons/ directory.
	The lessons are pre-converted in the lessons/ directory in the
	tar files, so there should be no real need to run this script.
    o patch/
	This subdirectory contains files that show the manual changes
	made to the lessons.  The files are the output from diff,
	comparing the files after conversion by typv1tov2 with the
	manually corrected ones.  These files are used by mklessons.

It should be easy to port typist to another UNIX flavour, provided you
have (n)curses, a C/C++ compiler, and a bit of spare time.  It'll
probably compile and run under earlier releases of SCO UNIX and
UnixWare too; I haven't tried it though.


Notes
-----
SCO OpenServer and SCO UnixWare systems don't contain nroff/groff by
default.  The man pages will therefore have to be handled manually.
Cat and postscript versions are available.

This program represents a 'hello world' of C++ for me.  In it, then,
you'll find things that may seem long-winded, or downright obtuse. 
This may be because I was exploring a language or class feature.  Then
again, it may simply be bad programming...


Version Changes
---------------

Version 2.1a:
	- Whole package GPLified.  Otherwise, no changes.  None.
	  Nothing at all.  Really.


And that's it.  Have fun!

Simon Baldwin, simonb@sco.com
