.\"
.\" CW Tutor Package, (c)1997, Simon Baldwin G0FRD
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\"
.\"
.TH CWCP 1 "CW Tutor Package" "G0FRD" \" -*- nroff -*-
.SH NAME
.\"
cwcp \- curses-based Morse tutor program
.\"
.\"
.\"
.SH SYNOPSIS
.\"
.B cwcp
[\-x \fIunixcwcommand\fP] [\-\-cwcommand=\fIunixcwcommand\fP]
[\-t \fItone\fP] [\-\-tone=\fItone\fP] [\-\-hz=\fItone\fP]
[\-w \fIWPM\fP] [\-\-wpm=\fIWPM\fP]
[\-g \fIgap\fP] [\-\-gap=\fIgap\fP]
[\-p \fItime\fP] [\-\-time=\fItime\fP]
[\-a \fIadj\fP] [\-\-adj=\fIadj\fP]
[\-c \fIcolourset\fP] [\-\-colours=\fIcolourset\fP]
.BR
[\-m] [\-\-mono]
[\-q] [\-\-no73]
.PP
.B cwcp
also accepts the \-h, \-\-help, \-v and \-\-version options.
.PP
The LINUX version understands both short form and long form command
line options.  Other versions understand only the short form options.
.PP
Options may be predefined in the environment variable \fBCWCP_OPTIONS\fP.
If defined, these options are used first; command line options take
precedence.
.PP
.\"
.\"
.\"
.SH DESCRIPTION
.\"
.PP
.B cwcp
is a curses-based interactive Morse code tutor program.  It allows
menu selection from a number of sending modes, and also permits
character sounding options, such as the tone pitch, and sending
speed, to be varied from the keyboard using a full-screen user
interface.
.PP
.B cwcp
uses \fBunixcw\fP to generate the actual Morse code sounds.  \fBcwcp\fP
automatically runs \fBunixcw\fP as a background process, communicating
with it through UNIX pipes.
.PP
When \fBcwcp\fP exits, it kills the background \fBunixcw\fP process.
During normal running, \fBcwcp\fP switches off the standard error
reporting from \fBunixcw\fP.
.PP
.\"
.\"
.\"
.SS COMMAND LINE OPTIONS
.\"
.B cwcp
understands the following command line options.  Only the short form
options are available in non-LINUX versions.
.TP
.I "\-x, \-\-cwcommand"
The sets the command used to start the underlying \fBunixcw\fP sender
program.  The default value is 'unixcw \-d /dev/tty'.  The
device \fI/dev/tty\fP is passed because the background \fBunixcw\fP sender
would otherwise be unable to use sound ioctls on its standard output,
since this is redirected by \fBcwcp\fP to be a UNIX pipe.
.TP
.I "\-t, \-\-hz, \-\-tone"
Sets the initial sounder pitch in Hz.  This value must be between 10
and 4000.  The default value is 800Hz.
.TP
.I "\-w, \-\-wpm"
Sets the initial sending speed in words per minute.  The value must be
between 4 and 60.  The default value is 12 WPM.
.TP
.I "\-g, \-\-gap"
Sets the initial extra gap, in dot lengths, between characters
(the 'Farnsworth' delay).  It must be between 0 and 99.  The default
is 0.
.TP
.I "\-p, \-\-time"
Sets the initial practice time, in minutes.  \fBcwcp\fP stops after
generating random Morse code for this period.  The value must be
between 1 and 999.  The default is 15 minutes.
.TP
.I "\-a, \-\-adj"
Allows an adjustment of +/\- several percent on the sending speed
of the underlying \fBunixcw\fP program.  The value may be
between \-50 and +50.  The default is 0%.  There is no user interface
method of adjusting this value while \fBcwcp\fP is running.
.TP
.I "\-c, \-\-colours"
This option specifies an initial colour set for \fBcwcp\fP.  The colour
set is specified as four integers, in the range 0 to 7, separated by
commas.  These integers set the display foregrounds, the display
backgrounds, the box foregrounds, and the box backgrounds.  The
available colours are, in order, black, red, green, yellow, blue,
magenta, cyan, and white.  The default colour set is "7,4,7,0".
If \fI\-m\fP or \fI\-\-mono\fP is given, this option is ignored.
.TP
.I "\-m, \-\-mono"
This option tells \fBcwcp\fP not to attempt to produce a colour
display.  Where colours are not possible, or monochrome
requested, \fBcwcp\fP will use reverse video within its windows to
create its interface.  If this option is given, any \fI\-c\fP
or \fI\-\-colours\fP is ignored.
.TP
.I "\-q, \-\-no73"
This suppresses the cheery little '73' that \fBcwcp\fP sends when
you exit the program.  Set this option if you are feeling especially
miserable.  The default is to send '73'.
.PP
.\"
.\"
.\"
.SS USER INTERFACE
.\"
.B cwcp
is a curses-based program that takes over the complete operation of
the terminal on which it is run.  If colours are available on the
terminal, it will produce a colour interface.
.PP
The \fBcwcp\fP screen is divided into several distinct areas:
.TP
.I "The Title bar"
This window simply shows a title for the program.
.TP
.I "The Menu Selection window"
The Menu Selection window shows the main modes that \fBcwcp\fP
offers.  Use the \fIF10\fP and \fIF11\fP or \fIKEY_DOWN\fP and \fIKEY_UP\fP
keys to select the mode.  \fIF9\fP or \fIReturn\fP start sending,
and \fIF9\fP again or \fIEsc\fP stop sending.  Changing mode also
stops sending.
.TP
.I "The Morse Code Display window"
This window displays each Morse code character after it has been
sent.
.TP
.I "The WPM Setting window"
The WPM window shows the current Morse code sending speed in words per
minute.  Pressing the \fIF2\fP or \fIKEY_RIGHT\fP keys increases the speed;
pressing the \fIF1\fP or \fIKEY_LEFT\fP keys decreases the speed.
.TP
.I "The Hz setting window"
This window shows the current Morse code tone pitch.  Use the \fIF4\fP
or \fIKEY_HOME\fP key to increase the pitch, and the \fIF3\fP
or \fIKEY_END\fP key to decrease it.  Values change in steps of 10Hz.
.TP
.I "The Gap setting window"
This window shows the current additional 'Farnsworth' gaps to be
appended after each Morse code character is sounded.  Use \fIF6\fP
or \fIKEY_PPAGE\fP to increase the gap, and \fIF5\fP or \fIKEY_NPAGE\fP
to decrease it.
.TP
.I "The Time setting window"
This window shows the selected practice time.  After generating Morse
code in a particular mode for this amount of time, \fBcwcp\fP stops
automatically.  Use \fIF8\fP to increase the time, and \fIF7\fP to
decrease it.  During sending, the value in this window counts down to
one, and after final minute of sending has elapsed, \fBcwcp\fP stops
sending.  The timer operates like a microwave or kitchen timer; it
counts down on its own, but the time remaining can also be altered
manually while the timer operates.
.PP
The following keys vary the screen colours:
.TP
.I "/ key"
Changes the foreground colour of the window boxes.
.TP
.I "* key"
Changes the background colour of the window boxes.
.TP
.I "\- key"
Changes the foreground colour of the window contents.
.TP
.I "+ key"
Changes the background colour of the window contents.
.PP
Eight screen colours are available for each: black, red, green,
yellow, blue, magenta, cyan, and white.  Use a key to cycle round
these colours for the particular part of the display controlled by
that key.  On a change of colours, the complete screen is repainted.
.PP
Use \fICtrl\-L\fP to repaint the complete screen, in case of screen
corruption.  This also forces \fBcwcp\fP to reload a full set of
operating parameters (speed, WPM, gap, etc) into \fBunixcw\fP; useful
if \fBunixcw\fP becomes confused.
.PP
To leave \fBcwcp\fP, press \fIF12\fP or \fICtrl-C\fP, or select \fIQuit\fP
on the mode menu.
.PP
All of the above command keys may be used while random characters are
being sent.  When keyboard input is being sent, most commands will work,
but the colour ones will not.  This is because these keys are also valid
Morse code characters, and so are passed to the sender program, rather
than being interpreted by \fBcwcp\fP as commands.
.PP
If function keys are not available on the terminal, \fICtrl-<key>\fP
combinations can be used.  On the top row of letter keys on the
keyboard, the keys \fICtrl-Q\fP to \fICtrl-I\fP may be used as
alternatives for \fIF1\fP to \fIF8\fP, and on the second row of
letter keys, \fICtrl-A\fP to \fICtrl-F\fP as alternatives for \fIF9\fP
to \fIF12\fP.
.\"
.\"
.\"
.SS RANDOM CHARACTERS AND WORDS
.\"
.B cwcp
sends random characters in groups of five, with a space between each
group.  After a period of sending, set in
the \fITime setting window\fP, \fBcwcp\fP stops automatically.  It can
also be stopped manually, before this time period expires.
.PP
When sending random words, \fBcwcp\fP sends the complete word, followed
by a space.  Because short words are easier to copy without writing,
\fBcwcp\fP contains only three, four, and five-letter words in its
random words list.
.PP
.B cwcp
chooses at random from a list of well over 1400 words.
.PP
.\"
.\"
.\"
.SH NOTES
.\"
.B cwcp
owes its existence to the DOS Morse code tutor CP222C.EXE, by VU2ZAP.
CP222C.EXE seemed to offer the right range of facilities for learning
Morse code in a simple, easy-to-use, and compact package.  \fBcwcp\fP
is very much modeled on that DOS program, and should prove useful
both for learning the code, and for experienced CW users who want (or
need) to improving receiving speed.
.PP
When running \fBcwcp\fP under X-Windows, it may be tricky to find a
device for \fBunixcw\fP that works correctly.  At the least, you will need
to be running as \fIroot\fP in order to have permission to open
a console device other than that on which you are logged in.  For
LINUX, try \fI/dev/tty1\fP or \fI/dev/console\fP.  For SCO OpenServer
and SCO UnixWare, try the base tty on which your X session is running
(for example, if X is running on console multiscreen 2, \fICtrl\-Alt\-F2\fP
or \fIAlt-SysRq-F2\fP, use \fI/dev/tty02\fP).  For SCO UnixWare, you
might also want to try \fI/dev/console\fP.  It is best to experiment
with the \fBunixcw\fP command on its own first, then when a working
combination is found, use that as the \fI\-x\fP argument for \fBcwcp\fP.
.PP
If you have problems getting \fBcwcp\fP to start, or it starts but won't
send, it's likely that there are problems in the underlying \fBunixcw\fP
process.  In this case, try redirecting standard error to a file; the
curses screen management may be erasing error messages.
.PP
On LINUX, the command
.IP
cwcp \-x "unixcw \-d /dev/tty1"
.PP
executed as root usually works, no matter where you are logging in from.
However, if you are out of earshot of the console, don't expect to
hear the Morse code generated.
.PP
Curses imposes a delay when recognising the \fIEsc\fP key alone, as
this character is often the first of a sequence generated by a
function key.  \fBcwcp\fP responds instantly to \fIF9\fP.
.PP
The characters echoed in the Morse Code Display window may be ASCII
representations of Morse procedural signals; see the \fBunixcw\fP(1) man
page for details.  The following translations are made, in addition to
those of \fBunixcw\fP, when sending from the keyboard:
.IP
.TS
l l l l l l
l l l l l l .
Key	Eqvt	Code	Key	Eqvt	Code
%	[VA]	...-.-	*	[AS]	.-...
!	[BK]	-...-.-	&	ES	. ...
@	[AR]	.-.-.	#	[KN]	-.--.
^	[AA]	.-.-			
.TE
.PP
.\"
.\"
.\"
.SS HINTS ON LEARNING MORSE CODE
.\"
Here are a few hints and tips that may help with the process of
learning Morse code.
.PP
Firstly, do \fBNOT\fP think of the elements as dots and dashes.  Instead,
think of them as dits and dahs (so 'A' is di-dah).  If you think of
them in this way, the process of translating sound into characters
will be learned much more easily.
.PP
Don't learn the characters from a table.  Learn them by watching the
groups appear on the screen, and listening to the sounds produced as
each is sent.  In the very initial stages, it may be beneficial if you
can find a person to take you through the first stages of recognising
characters.
.PP
Don't waste your time learning Morse code at 5 WPM.  Set the speed to
12 or 15 WPM, but use extra spacing (the Gap window) to reduce the
effective speed to much lower - around four or five WPM \fIeffective\fP
speed.  This way, you will learn the rhythm of the characters as they
are sent, but still have plenty of time between characters.  As you
practice, decrease the gap to zero.
.PP
Learn in stages.  Start by learning the \fIEISH5\fP group, then progress
down through the menu as each group is mastered.  The groups contain
characters which are in some way related, either by sound, or by type
of character.
.PP
Once you have completed all the groups \fIEISH5\fP to \fI,?.;)/\fP
(or \fI23789\fP if you don't want to learn procedural signals yet),
use the full character set options, and the words and CW words
options, to sharpen your skill.  If you have difficulties with
particular characters, return to that group and practice again with a
smaller character set.
.PP
Resist the temptation to try to learn or improve your speed by copying
off-air.  You won't know what speed you are working at, and much
hand-sent Morse is not perfectly formed.  What you can gain off-air
though is a general 'resilience'; a tolerance for Morse code where
the timing of individual elements, or spacing between characters and
words, isn't 100% accurate.
.PP
If working to attain a particular speed for a test, always set the
speed slightly higher; for example, if aiming for 12 WPM, set the
tutor speed to 14 or 15 WPM.  This way, when you drop back to 12 WPM
you will feel much more relaxed about copying.  Be aware that \fBunixcw\fP
is not necessarily going to send at exactly the speed you set, due
to limitations in what can be done with UNIX timers.  It often sends
at a slower speed than you set, so be very careful with this if you
have a target speed that you need to reach.
.PP
Use the program to make cassette tapes that you can take with you in a
walkman or in the car, for long journeys.  You don't have to write
down everything you hear to practice Morse code; simply listening to
the shapes of characters over a period will help to train your brain
into effortless recognition.  In fact, slavishly writing everything
down becomes a barrier at speeds of 15-20 WPM and above, so if you can
begin to copy without writing each character down, you will find
progress much easier above these speeds.  But don't over-use these
tapes, otherwise you will quickly memorise them.  Re-record them with
new contents at very regular intervals.
.PP
Try to spend at least 15-30 minutes each day practicing.  Much less
than this will make progress glacially slow.  But significantly more
than an hour or so may just result in you becoming tired, but not
improving.  Recognise when it is time to stop for the day.
.PP
At higher speeds, CW operators tend to recognise the 'shape' of whole
words, rather than the individual characters within the words.  The CW
words menu option can be used to help to practice and develop this
skill.
.PP
.\"
.\"
.\"
.SH ERRORS AND OMISSIONS
.\"
The calibration option is a bit ropy.  It simply sends PARIS
repeatedly, and relies on you to time the sending and then work out if
any adjustment to the speed is really necessary.  Automatic
calibration by making measurements over a given period would be a lot
better.
.PP
Sending from the keyboard may not be completely clean.  In particular,
the echoing of characters sent may be delayed until there are no
characters remaining in the keyboard input queue, giving a jerky
appearance to the user interface at times.  This appears to be a
problem relating more to the LINUX and UnixWare environments than to
OpenServer.
.PP
Generating random CW QSOs would be fun to do.
.PP
No accented characters are available from the program.
.PP
A facility to allow a user to key Morse into the system, and to have
it send code, and measure the accuracy of keying, would be nice.
.PP
.\"
.\"
.\"
.SH SEE ALSO
.\"
Man pages for \fBunixcw\fP(1,LOCAL), and \fBcwgen\fP(1,LOCAL).
.\"