.\"
.\" UnixCW CW Tutor Package - XCWCP
.\" Copyright (C) 2001  Simon Baldwin (simonb@caldera.com)
.\" 
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version 2
.\" of the License, or (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
.\"
.\"
.TH XCWCP 1 "CW Tutor Package" "G0FRD" \" -*- nroff -*-
.SH NAME
.\"
xcwcp \- Xwindows-based Morse tutor program
.\"
.\"
.\"
.SH SYNOPSIS
.\"
.B xcwcp
[\-d \fIdevice\fP] [\-\-device=\fIdevice\fP]
[\-t \fItone\fP] [\-\-tone=\fItone\fP] [\-\-hz=\fItone\fP]
[\-w \fIWPM\fP] [\-\-wpm=\fIWPM\fP]
[\-g \fIgap\fP] [\-\-gap=\fIgap\fP]
.PP
.B xcwcp
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 \fBXCWCP_OPTIONS\fP.
If defined, these options are used first; command line options take
precedence.
.PP
.\"
.\"
.\"
.SH DESCRIPTION
.\"
.PP
.B xcwcp
is a Xwindows-based interactive Morse code tutor program.  It lets you
choose from a number of options for practice, including sending random
characters, random words, and characters from the keyboard.  It will
also receive Morse code that you send using the keyboard or mouse as
a Morse keyer, and display the characters it sees.
.PP
.\"
.\"
.\"
.SS COMMAND LINE OPTIONS
.\"
.B xcwcp
understands the following command line options.  Only the short form
options are available in non-LINUX versions.
.TP
.I "\-d, \-\-device"
Specifies the device file to open for sound ioctls.  The default
is to generate tones using standard output; this is often sufficient,
as the standard output of a program that is launched from a window
manager or desktop (KDE, for example) may be a character-mode system
multiscreen.  If it is not, a console device file, capable of KIOCSOUND,
should be given.  See \fISELECTING SUITABLE SOUND DEVICE FILES\fP below.
.TP
.I "\-t, \-\-hz, \-\-tone"
Sets the initial sounder pitch in Hz.  This value must be between 0
and 10,000.  The default value is 800Hz.
.TP
.I "\-w, \-\-wpm"
Sets the initial sending speed in words per minute.  The value must be
between 8 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 20.  The default
is 0.
.\"
.\"
.\"
.SS USER INTERFACE
.\"
.B xcwcp
offers GUI controls for changing the speed, tone frequency, 'Farnsworth'
gap, and mode of the program.  All of the major controls are placed on
the application toolbar.
.PP
The main GUI window is used to display the characters that \fBxcwcp\fP
sends or receives.
.PP
To find out more about what a particular GUI control does, use the "What's
this..." icon (the '?' at the far right of the toolbar).
.\"
.\"
.\"
.SS RANDOM CHARACTERS AND WORDS
.\"
.B xcwcp
sends random characters in groups of five, with a space between each
group.
.PP
When sending random words, \fBxcwcp\fP sends the complete word, followed
by a space.  Because short words are easier to copy without writing,
\fBxcwcp\fP contains only three, four, and five-letter words in its
random words list.
.PP
.B xcwcp
chooses at random from a list of around 3000 words.
.PP
.\"
.\"
.\"
.SS RECEIVING MORSE
.\"
.B xcwcp
can receive Morse code, and display it in its main GUI window.  To key
Morse code into the program, select the Receive Keyed CW mode, and press
the stop/start button.  Now, place the mouse cursor over the central
window of the program.  By pressing the middle mouse button, you should
be able to key Morse into the program as if the mouse button was a straight
Morse key.
.PP
For better keying, you can use the left and right mouse buttons as if they
were paddles on an Iambic keyer.  This will send Morse code at the exact
rate set on the Speed control.
.PP
You can also use the keyboard for keying.  In this case, the Alt key is
used as a straight key, and Control and Shift as the two paddles of an
Iambic keyer.
.PP
By default, \fBxcwcp\fP will try to follow the speed of the Morse code that
you send to it.  It is possible to switch this tracking off, in which case
the program switches to receiving only at the exact speed set on the Speed
control.  However, fixed speed receiving is very, very picky about receiving
only extremely accurately timed Morse code, so unless you are striving for
complete perfection, you may find that speed tracking is more comfortable.
.PP
The speed tracking in \fBxcwcp\fP can sometime be confused by very wide
and abrupt changes in speed.  If it is having difficulty finding the speed
you are sending at, you can use the File pulldown menu to synchronize the
receive speed to the speed set on the Speed control.
.\"
.\"
.\"
.SS SELECTING SUITABLE SOUND DEVICE FILES
.\"
.B xcwcp
can sound Morse code only to the UNIX console speaker; for this, it
uses the KIOCSOUND ioctl.  By default, it will use standard output
unless the \fI-d\fP or \fI\-\-device\fP option is used.  If the
device refuses to create tones, \fBxcwcp\fP prints the error message
.IP
output device won't do sound
.PP
and exits.
.PP
Unless its standard output is connected to a character-mode console
multiscreen, \fBxcwcp\fP will need to be told which device to use.
Which device files are suitable will depend on which operating system
is running, and which system user ID runs \fBxcwcp\fP.  They must
however be console multiscreen devices; \fI/dev/tty1\fP and up on
LINUX, \fI/dev/tty01\fP and up on OpenServer, and \fI/dev/vt01\fP and
up on UnixWare and OpenUNIX.
.PP
On LINUX, it is normally possible to run \fBxcwcp\fP as superuser, and
specify \fI/dev/tty1\fP as the sound device; this combination will
usually work no matter which physical tty or pseudo-tty is being used.
Unless running as superuser, \fBxcwcp\fP will not have the necessary
permission to access a 'foreign' tty.  Making \fBxcwcp\fP an suid binary
avoids this problem; the program does not fork() or exec(), so making it
suid should be relatively safe.
.\"
.\"
.\"
.SH NOTES
.\"
.B xcwcp
is an Xwindows rewrite of \fBcwcp\fP.  Both programs borrow heavily
from the the DOS Morse code tutor CP222C.EXE, by VU2ZAP.
.PP
The characters echoed in the main GUI window may be ASCII equivalents
of Morse procedural signals; see the \fBcw\fP(7,LOCAL) man page for
details.  The following translations are made, in addition to the
standard procedural signals and punctuation, 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
Do not 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
Do not 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 do not 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 will not 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, is not 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 \fBxcwcp\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 do not 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 do not 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
Do not worry if you reach a speed 'plateau'.  This is common, and you
will soon pass it with a little perseverance.
.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
Neither the mouse buttons nor the keyboard are ideal for use a keys
or keyer paddles, for sending practice.  Try to use a proper key for
sending where possible; it is hard even for experienced operators to
get good keying using the mouse or keyboard.  Of the two, the mouse is
probably the better option, though, in a pinch.
.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
.\"
.\"
.\"
.SH SEE ALSO
.\"
Man pages for \fBcw\fP(7,LOCAL), \fBcwlib\fP(3,LOCAL), \fBcw\fP(1,LOCAL),
\fBcwgen\fP(1,LOCAL), and \fBxcwcp\fP(1,LOCAL).
.\"