			UNIX Morse Code Tutor
			---------------------


Introduction
------------
This Morse code tutor package grew out of a desire to have a program
available under Linux that was very similar to the one I was used to
under DOS.  Whilst several Linux tutors were available, I never quite
found one that did stuff the way I wanted.  Also, I wanted to try
writing two things I've never written in anger before - a curses
application, and nroff man pages.  So here's the result.  I'm sure
that much of it could be rewritten more elegantly.  Feel free.


Installing binaries
-------------------
The package runs on three platforms:

	Linux
	SCO OpenServer 5.0
	SCO UnixWare 2.1

Binaries and source code are both available.  The binary archives are
unixcw-N.N.*.bin.tar, where * is the platform, and N.N is the release.
Manual pages for all platforms are in unixcw-N.N.man.tar.  The source
code archive is unixcw-N.N.src.tar.

To install the Linux binaries and manpages, as superuser

	Untar the Linux binary archive, and the man pages archive.
	Copy the files cw, cwcp, and cwgen to /usr/local/bin, and set the
		mode to 755.
	Gzip the files cw.1, cwcp.1, and cwgen.1, copy the resulting
		.gz files to the directory /usr/local/man/man1, and set
		the mode to 644.
	In Makefile.Linux in the sources, there is a make 'install'
		option that will do all this for you.  There's an
		'uninstall' option, too.

To install the SCO OpenServer and SCO UnixWare binaries and manpages,
as superuser

	Untar the relevant binary archive, and the man pages archive
	Unless you create one, there isn't a /usr/local/bin directory
		available by default for the cw, cwgen, and cwcp binaries.
		Either create one and copy the binary files there, or
		put them elsewhere on your path.
	Likewise, adding the manpages is a matter of preference.  The
		*.cat manpages will be easy enough to integrate into
		the UnixWare 'traditional man pages', if they are
		installed.  It won't be possible to work them into the
		Dynatext version, however.  On OpenServer, it is
		possible to put the *.cat pages 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 versions.


Building the source
-------------------
To build the programs from the source code, first untar the file
unixcw-N.N.src.tar.  Select the correct makefile from

	Makefile.Linux		- for Linux
	Makefile.SCO		- for SCO OpenServer
	Makefile.UnixWare	- for SCO UnixWare

and run make.  Using a target of 'all' for make will build and install
the binaries and man pages, and run tests on the cw binary to ensure
that sounds are produced correctly.  Using no target ('default') will
just build the binaries, and man pages if possible.

It shouldn't be hard to port to another UNIX flavour, provided you
have itimers, (n)curses, a 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.


The programs
------------
There are three programs in the package:

  cw -    This is a CW sending 'engine',  that reads  characters
          from stdin,  sounds them on the  console speaker,  and
          echoes them to stdout.   It needs to use a device that
          understands the KIOCSOUND ioctl - a good way to run it
          on a system (character mode) console is with

              cw -d/dev/tty

  cwgen - This is a simple random character generator,  that can
          be used as a 'feed' for cw.  Example usage:

              cwgen | cw -d/dev/tty

  cwcp -  This is a curses-based menu program that will generate
          random morse, groups of characters from selected sets,
          words, and CW abbreviations randomly, sound them using
          'cw', and can handle changes of WPM and pitch from the
          keyboard.  It owes much to CP222.EXE, by VU2ZAP.

The package is organised to contain a generic CW sending 'engine' so
that a variety of front-ends is possible.  As yet, there's really only
one - cwcp.  However, some day, maybe, I'll complete the Java
front-end.


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.

SCO OpenServer contains a 'cw' binary as standard, in /usr/bin/cw.
Make sure that /usr/local/bin appears first in your $PATH, to be
certain that the CW sender program is found, by cwcp, for example.

I couldn't persuade the A_REVERSE curses attribute in UnixWare to
behave correctly, and didn't have the time to figure it out.  So the
cwcp modes menu is done with a nasty hack.  Sorry.

There's no support for soundcards because I don't have one (which at
the very least makes testing somewhat tricky).  If anyone wants to add
soundcard support into the 'cw' program, go right ahead.

Finally, the boring bit:  This package is free for Amateur and
Non-commercial use.  You may do anything you like with it except claim
that you wrote it, or sell it as part of a business concern.


Have fun
--------


Version changes
---------------
Version 1.1:
cw	- Added CW_OPTIONS environment variable processing
	- Fixed itimer value set error that caused setitimer to
		fail under SCO with speeds less than 6 WPM
	- {} comments no longer converted into uppercase
cwgen	- Added CWGEN_OPTIONS environment variable processing
	- Tidied away some unused variable declarations
cwcp	- Added CWCP_OPTIONS environment variable processing
	- Augmented the list of CW words
	- Increased maximum timer to 999 mins, and made time display
		count down the remaining time
	- Added ^C as a key that terminates the program
	- Added a cute little warble for when CW sending stops
	- Corrected the short-form-options help message
	- Tidied exit-and-clear-up code
	- Moved to UNIX pipes proper, rather than files in /tmp
		(don't know why I overlooked these first time round)
	- Hacked round the UnixWare A_REVERSE thing by creating a
		whole new colour pair just for reversed mode strings


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 G0FRD               | AX25 BBS Packet  - G0FRD @ GB7BEN.#43.GBR.EU
 Simon Baldwin       | AMPR.NET TCP/IP  - g0frd@g0frd.ampr.org
 Leighton Buzzard    | INTERNET at work - simonb@sco.COM
 Beds (IO91PV, SP92) | INTERNET at home - Probably never
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
