Provided by: xcwcp_3.5.1-3_amd64 bug

NAME

       xcwcp - X Window-based Morse tutor program

SYNOPSIS

       xcwcp     [-s --system=SYSTEM]    [-d --device=DEVICE]    [-w --wpm=WPM]    [-t --tone=HZ]
       [-v --volume=PERCENT]  [-g --gap=GAP]   [-f,   --infile=FILE]   [-F,   --outifile=FILE]
       [-h --help] [-V --version]

       xcwcp  installed  on  GNU/Linux  systems understands both short form and long form command
       line options.  xcwcp installed on other operating systems may understand  only  the  short
       form options.

       There are no mandatory options.

       Options  may  be  predefined in the environment variable XCWCP_OPTIONS.  If defined, these
       options are used first; command line options take precedence.

DESCRIPTION

       xcwcp is a X Window-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.

   COMMAND LINE OPTIONS
       xcwcp  understands  the  following command line options.  The long form options may not be
       available in non-LINUX versions.

       -s, --system=SYSTEM
              Specifies the way that xcwcp generates tones.  Valid values are: console for  tones
              through the console speaker, alsa for tones generated through the system sound card
              using ALSA sound system, oss for tones generated through system  sound  card  using
              OSS  sound system, soundcard for tones generated through the system sound card, but
              without explicit selection of sound system. These values can be shortened  to  'c',
              'a', 'o', or 's', respectively. The default value is 'oss'.

       -d, --device=DEVICE
              Specifies  the  device file to open for generating a sound.  xcwcp will use default
              device if none is specified.  The  default  devices  are:  /dev/console  for  sound
              produced  through  console, default for ALSA sound system, /dev/audio for OSS sound
              system.  See also NOTES ON USING A SOUND CARD below.

       -w, --wpm=WPM
              Sets the initial sending speed in words per minute.  The value must  be  between  4
              and 60.  The default value is 12 WPM.

       -t, --tone=HZ
              Sets  the  initial sounder pitch in Hz.  This value must be between 0 and 4,000.  A
              value of 0 selects silent operation, and can be used for  timing  checks  or  other
              testing.  The default value is 800Hz,

       -v, --volume=PERCENT
              Sets  the  initial sending volume, as a percentage of full scale volume.  The value
              must be between 0 and 100.  The default value is 70 %.  Sound  volumes  work  fully
              for sound card tones, but xcwcp cannot control the volume of tones from the console
              speaker.  In this case, a volume of zero is silent, and all other volume values are
              simply sounded.

       -g, --gap=GAP
              Sets  the  initial  extra gap, in dot lengths, between characters (the 'Farnsworth'
              delay).  It must be between 0 and 60.  The default is 0.

       -f, --infile=FILE
              Specifies a text file that xcwcp can read to  configure  its  practice  text.   See
              CREATING CONFIGURATION FILES below.

       -F, --outfile=FILE
              Specifies a text file to which xcwcp should write its current practice text.

   USER INTERFACE
       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.

       The main GUI window is used to display the characters that xcwcp sends or receives.

       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).

   RANDOM CHARACTERS AND WORDS
       xcwcp sends random characters in groups of five, with a space between each group.

       When  sending  random  words, xcwcp sends the complete word, followed by a space.  Because
       short words are easier to copy without writing, xcwcp's default dictionary  contains  only
       three, four, and five-letter words in its random words list.

       xcwcp  chooses  at random from a list of around 3000 words in its default dictionary.  You
       can change  this  text  using  a  configuration  file,  read  at  startup.   See  CREATING
       CONFIGURATION FILES below.

   RECEIVING MORSE
       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.

       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.

       You can also use the keyboard for keying.  In this case, any of  the  Up  or  Down  cursor
       keys,  Space,  Enter,  or  Return  may be used as the straight key, and the Left and Right
       cursor keys act as the two paddles of an Iambic keyer.

       By default, xcwcp 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.

       The speed tracking in xcwcp 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.

       At any time, the mode selection combowidget can get focus by using Alt+M.   You  can  then
       use  the  space bar or the up/down keys to change the mode.  The Tab key moves to the next
       widget, so you can change speed, etc.  Shift+Tab moves backwards.

   NOTES ON USING A SOUND CARD
       By default, xcwcp tries to open OSS device "/dev/audio" to access the system  sound  card.
       This is generally the correct device to use, but for systems with special requirements, or
       those with multiple sound cards, the option -d or --device, combined with -s  or  --system
       can  be  used  to specify the device and audio system for sound card access.  If the sound
       card device cannot be set up, xcwcp prints the error message

              cannot set up soundcard sound

       and exits.

       Sound card devices, when opened  through  OSS  sound  system,  are  usually  single-access
       devices,  so  that  when  one process has opened the device, other processes are prevented
       from using it. In such cases xcwcp will of course conflict with any  other  programs  that
       expect  exclusive use of the system sound card (for example, MP3 players).  If xcwcp finds
       that the sound card is already busy, it prints the error message

              open /dev/audio: Device or resource busy

       and exits.

       The sound card device is not used if xcwcp is only sending tones on the console speaker.

   AUDIO OUTPUT - DEFAULTS AND SELECTION
       xcwcp first tries to access sound card using PulseAudio sound system, using default device
       name, unless user specifies other audio device with option -d or --device.

       xcwcp  then tries to access sound card using OSS audio system and default OSS audio device
       name ('/dev/audio'), unless user specifies other audio device with option -d or --device.

       If opening soundcard through OSS fails, xcwcp tries to access the sound  card  using  ALSA
       audio  system, and default ALSA audio device name ('default'), unless user specifies other
       audio device with option -d or --device.

       If opening soundcard through ALSA also fails, xcwcp tries to access system console  buzzer
       using  default buzzer device '/dev/console', unless user specifies other audio device with
       option -d or --device.

       It is very common that in order to access the console buzzer device user has to have  root
       privileges.   For  that reason trying to open console buzzer almost always fails.  This is
       not a program's bug, this is a result of operating system's restrictions.  Making xcwcp an
       suid  binary  bypasses this restriction.  The program does not fork() or exec(), so making
       it suid should be relatively safe.  Note however that this  practice  is  discouraged  for
       security reasons.

       As  stated,  user  can tell xcwcp which device to use, using -d or --device option.  Which
       device files are suitable will depend on which operating system is running,  which  system
       user ID runs xcwcp, and which user groups user belongs to.

   CREATING CONFIGURATION FILES
       xcwcp  contains  a  default  set of modes and practice text that should be enough to begin
       with.  It can however read in a  file  at  startup  that  reconfigures  these  to  provide
       different character groupings, word sets, and other practice data.

       To read a configuration file, use the -i or --infile command line option.  The file should
       introduce each xcwcp mode with a section header in '[' ... ']' characters, followed by the
       practice text for that mode, with elements separated by whitespace.  Lines starting with a
       semicolon or hash are treated as comments.  For example

              ; Simple example mode
              [ A to Z ]
              A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

       xcwcp will generate five  character  groups  for  modes  whose  elements  are  all  single
       characters,  and  treat  other  modes  as  having  elements that are complete words.  As a
       starting point for customized modes, xcwcp will write its default configuration to a  file
       if given the undocumented -# option, for example "xcwcp -# /tmp/xcwcp.ini".

NOTES

       xcwcp is an X Window rewrite of cwcp.  Both programs borrow heavily from the the DOS Morse
       code tutor CP222C.EXE, by VU2ZAP.

       The characters echoed in the main GUI window may be ASCII equivalents of Morse  procedural
       signals; see the cw(7,LOCAL) man page for details.

   HINTS ON LEARNING MORSE CODE
       Here are a few hints and tips that may help with the process of learning Morse code.

       Firstly,  do NOT 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.

       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.

       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 effective 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.

       Learn in stages.  Start by learning the EISH5 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.

       Once you have completed all the groups EISH5 to ,?.;)/ (or 23789 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.

       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.

       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
       xcwcp 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.

       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.

       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.

       Do  not  worry  if you reach a speed 'plateau'.  This is common, and you will soon pass it
       with a little perseverance.

       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.

       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.

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.

SEE ALSO

       Man    pages   for   cw(7,LOCAL),   libcw(3,LOCAL),   cw(1,LOCAL),   cwgen(1,LOCAL),   and
       xcwcp(1,LOCAL).