Copyright (C) 1999, 2000 Chris Vine, G3XXF

    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.

    A copy of the GNU General Public License version 2 is set out
    in the file COPYRIGHT accompanying this distribution.  You can
    also obtain a written copy from the Free Software  Foundation,
    Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

		INSTALLATION: FROM SOURCE FILES

To install, place the distribution file in a local source directory
(eg ~/src).  Untarring/unzipping it will create a sub-directory
'kam-qt' where the source code can be found.  Edit the file kamrc
(which will be placed by "make install" in /etc) so that it matches
your serial port, speed setting for your Kam, and callsign (see
further below under "setup" for more on this file).  kamrc specifies
run-time not compile-time options, but you might as well edit it now
so that the version installed by "make install" is correct.

NOTE: the format for specifying the serial port in kamrc has changed
with the latest release - you must now specify the port device name
(eg. ttyS0) rather than the COM port number.  (See kamrc for further
details).

Then check the Makefile.  Most of it contains standard defaults, and
can be run `as is'.  However the first two items relating to your Qt
installation may need to be adjusted.  You must set QTDIR (the base Qt
directory) and MOC (the full path of the moc compiler).  There are
three options provided in the Makefile for each of these, one of which
should suit your system.  (Redhat 6.1 users will probably set QTDIR to
/usr/lib/qt-2.0.1 and MOC to /usr/lib/qt-2.0.1/bin/moc).  To pick an
option "uncomment" it by removing the `#' at the beginning of the line
concerned, and insert a `#' at the beginning of the line of the option
to be excluded.

Then type "make", and then "make install".  "make install" must be run
as root.  "make" can be run as user.  The program and configuration
files (other than kamrc) will be installed in the directory specified
in makefile (makefile is set to install them in /usr/local/kamdir by
default).

The name of the executable is "kam-qt".

"make install" will give suid and sgid permissions to the installed
binary.  If appropriate permissions are given to the serial device
(/dev/ttyS*), this can be refined and changed for the security
conscious.

This program can safely be installed in the same directory as the
"kamplus" program for ncurses, as they can share the same
configuration and other files.

To compile and link, qt-1.4* or qt-2.* must be installed.  You must
have both the qt and qt-devel packages installed if you use the Red
Hat rpms.

	INSTALLATION: FROM PRE-COMPILED LINUX BINARY FILES

To install, place the distribution file in a local source directory
(eg ~/src).  Untarring/unzipping it will create a sub-directory
'kam-qt' where the source code can be found.  Edit the file kamrc
(which will be placed by "make libc5_install" or "make libc6_install"
in /etc) so that it matches your serial port, speed setting for your
Kam, and callsign (see further below under "setup" for more on this
file), then type "make libc5_install" or "make libc6_install",
depending on your version of libc.

NOTE: the format for specifying the serial port in kamrc has changed
with the latest release - you must now specify the port device name
(eg. ttyS0) rather than the COM port number.  (See kamrc for further
details).

"make libc5_install" or "make libc6_install" must be run as root.  The
program and configuration files (other than kamrc) will be installed
in the directory specified in Makefile (Makefile is set to install
them in /usr/local/kamdir by default).

The pre-compiled version for libc6 has been compiled with egcs, and
the libc5 version has been compiled with gcc-2.7.2.  egcs and
gcc-2.7.* use different C++ name mangling schemes, so if you use some
other distribution than the ones mentioned above the binary may not
dynamically link with the libc++ and qt shared library files in your
distribution, if the distribution has been compiled with the "wrong"
compiler.  If so, compile kamplus-qt from the source files - see above
for further details, it is very easy.  The pre-compiled versions have
also been compiled against qt-1.4*.

Furthermore, the libc6 version has been compiled with glibc-2.1.*.  It
will not work with glibc-2.0.* (as used in Red Hat 5.*).  If you get a
segmentation fault when trying to start the program, library
incompatibility is probably the reason.  You will have to compile the
program from source.  This is very easy (see above), and recommended
in any event.

If you don't have 'make' installed (shame on you), you will need to
copy by hand kam-qt, endhost, cq, messages and helpfile to your chosen
install directory as specified in kamrc, copy tnc.parms, home and away
into the sub-directory "parms" in the install directory, copy kamrc to
/etc, and give kam-qt and endhost the necessary permissions to write
to the serial port device (/dev/ttyS*).  This can be done by setting
'kam-qt' and 'endhost' suid root (chmod +s kam-qt), although there are
other ways of doing it (eg make /dev/ttyS* writable by a group such as
uucp and make 'kam', 'endhost' and 'xkam' members of that group and
setting sgid).

The name of the executable is "kam-qt".

This program can safely be installed in the same directory as the
"kamplus" program for ncurses, as they can share the same
configuration and other files.

To run the pre-compiled binaries, qt-1.4* must be installed.  If you
use KDE-1.1*, then you will already have this installed.

                            SETUP

Before being used, the kam configuration file (kamrc) must be
completed with (a) your callsign, (b) the serial port on which the Kam
tnc operates, (c) the speed to which the Kam has been initialised (or
to which it is to be initialised) and (d) the directory in which other
relevant kam files (such as "messages") can be found and in which the
capture file capture.txt and certain temporary files will be written.
The directory must therefore be one in which there will be write
permission (this is not so much of an issue if kam is set suid root -
see above).

It is recommended that this directory should either be the same one in
which the kam executable is installed - normally /usr/local/kamdir, as
"make install" "make libc5_install" or "make libc6_install" will
automatically give the necessary permissions to that directory.

In looking for kamrc, the program first searches for a file
$HOME/.kamrc, and if that is not found looks for the global
configuration file /etc/kamrc.  "make install", "make libc5_install"
or "make libc6_install" will install a global /etc/kamrc file, which
you should have previously edited as mentioned above.

The kam configuration file (kamrc) may also specify your Amtor
selcall, but it does not need to do so.  If you do not specify a
selcall, then the standard four letter selcall matching your callsign
will automatically be generated by the program for you.

The sample file /etc/kamrc which comes with this distribution gives
further details - it is much easier than this explanation sounds.

Before using the program you must also have initialised the Kam (if
you have already used your Kam with another program then it will
already be initialised, and you can skip this part, subject to the
comment about speeds below).  To do this you can put the program in
terminal mode instead of host mode by typing "kam-qt setup" instead of
"kam-qt" when starting the program.  To see how to go from there, look
at the handbook under "Initializing the KAM Plus".

The SPEED: setting in the Kam configuration file (kamrc) must match
the speed the Kam has been initialised for.

Note that if you have previously initialised the kam using the DOS
Pacterm program which comes with the Kam Plus, Pacterm operates at
1200 baud Kam/Computer link speed, whereas you will be better off with
9600 baud, as host mode involves additional tnc/computer traffic in
order to keep track of the Kam status information.

It is therefore best to set up the Kam for 9600 baud.  One way of
doing this if the Kam has previously been initialised for a lower
speed is to put the SPEED: setting in kamrc to the speed the Kam has
previously been initialised for, start the program as "kam-qt setup"
so that you are in terminal mode, and then enter the Kam command
RESTORE DEFAULTS.  This will cause the Kam to re-initialise.  Then
quit the program, amend the speed setting in /etc/kamrc to 9600,
restart the program with "kam-qt setup", wait for the auto-baud detect
prompt and press '*'.  See the Kam Plus handbook for further details.

		      USE OF THE PROGRAM

When first used in host mode, the Kam must be switched on before the
program is run, so the program will place the Kam in Host mode.  Once
the program is started for the first time, Press F9 to send the Kam
parameters in file "tnc.parms".  Until this is done, the program will
not interface with the Kam correctly.

The program will leave the Kam in Host mode.  If you want to get out
of host mode, either use the "endhost" utility installed in the same
directory as "kam-qt", or start the program again using "kam-qt setup"
so that the Kam is placed in terminal mode.

The first time you use the program, you will be asked if you accept
the terms of the General Public Licence, version 2.

The program can be operated from the mouse, using the buttons and
pull-down menus.  However the program can also be operated by using
the following hot keys, which for compatability are the same as those
used by the console based "kam" program which uses the ncurses
library.

The keyboard hot keys operate as follows:

(Note Alt-P has changed its meaning in release 0.97: to send FEC
Pactor in Tor mode, now press Alt-T)

Cursor up - Scroll up.
Cursor down - Scroll down.
Cursor right - Scroll out (end scroll).

Page Up - changeover to transmit (HF modes).
Page Down - changeover to receive (HF modes).

Ctrl-A: change to Amtor mode (or send Ctrl-A - see below).
Ctrl-C: change to CW mode (if not in CW mode) or set the speed (if in CW
	mode).
Ctrl-D: disconnect (Packet, Pactor, Amtor and Gtor).
Ctrl-F: change to FEC.
Ctrl-G: change to G-tor.
Ctrl-L: change to Lamtor.
Ctrl-O: change to Gmon.
Ctrl-P: change to Pactor.
Ctrl-R: change to RTTY (Baudot).
Ctrl-S: change to ASCII.
Ctrl-T: change to TOR mode (or send Ctrl-T - see below).
Ctrl-X: change to HF Packet.
Ctrl-Z: send Ctrl-Z (see below).

Alt-B: print the current scroll buffer.
Alt-C: send an auto-cq (Pactor, Amtor, Gtor or Tor)
       or (if in auto-cq mode) end auto-cq.
       (see also Alt-T below).
Alt-D: Download a 7plus/uuencoded file to a local file (Packet, Pactor
       or Gtor) (this makes no translations other than CR -> LF).
Ctrl- Alt-D: Download a binary file to a local file (Packet, Pactor or
       Gtor) (this saves the raw data to disk).
Alt-I: send ident ([CALL IN STORE] de [YOUR CALL]).
Alt-L: toggle whether receive speed locked to 100 baud (Pactor or Gtor).
Alt-P: set a print mark, or if one is already set, print from the mark.
Alt-R: enter an RST report to be stored in the RST buffer.
Alt-S: sync the transmit speed to the current receive speed (CW), or
       resync the Amtor decoder when monitoring (Amtor/Lamtor).
Alt-T: send an auto-cq when listening in Tor-standby mode but using
       Pactor FEC to send the CQ.
Alt-U: Upload a 7plus/uuencoded file (Packet, Pactor or Gtor) (this
       makes no translations other than LF -> CR).
       (Press again to abort the upload).
Ctrl-Alt-U: Upload a binary file (Packet, Pactor or Gtor) (this
       sends raw data and makes no translations).
       (Press again to abort the upload).
Alt-X: abort (Pactor, Amtor, Gtor or Tor)
Alt-0 to Alt-9: send the messages specified in the "messages" file.

F1: toggle display of Help file.
F2: toggle on/off capture of current stream to file [KAMDIR:]/capture.txt.
F3: toggle transmitting of text after word/line or with a guard in
    non-packet mode (see below).  
F4: connect with another station (Packet, Pactor, Amtor and Gtor).  
F5: send a command to the Kam (press again to run a configuration script).
F6: send a text file.
F7: enter another station's callsign in the callsign store.  
F8: toggle the callsign lock (see below).  
F9: send the Kam parameter file tnc.parms to Kam.  
F10: toggle the screen display between VHF and HF port of Kam.  
F11: go down a stream on the screen display (e.g. from stream C on current
     port to stream B).  
F12: go up a stream on the screen display (e.g. from stream A on current
     port to stream B).

Pressing Ctrl-A when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-A character instead of asking whether to change to
Amtor mode (some BBSs use Ctrl-A to abort a message being sent)

Pressing Ctrl-T when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-T character instead of asking whether to change to
Tor mode (some BBSs use Ctrl-T to abort a telnet session)

Pressing Ctrl-Z when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-Z character (some BBSs use Ctrl-Z to end a message as
an alternative to /EX)

If Alt-C or the "auto-cq" button is pressed when in Pactor, Amtor,
Gtor or Tor-Standby modes, the program will run the CQ message found
in the file 'cq' placed in the directory specified by 'KAMDIR:' in
kamrc, repeating until a link is made.  It can be turned off by
pressing Alt-C or the "auto-cq" button again.  The delay between the
end of one CQ message and the start of the next may be specified by
the AUTOCQ: parameter in kamrc.  If none is specified, the default is
90 seconds (don't cook your output stage).  If in Tor-Standby mode,
pressing Alt-T will do the same, except that the CQ message will be
sent in Pactor FEC not Amtor FEC mode.  Pressing the "auto-cq" button
when in Tor mode will bring up a dialog, offering the choice of Amtor
FEC or Pactor FEC.  To stop an auto-cq session, press Alt-C or the
"auto-cq" button again.

Files can be uploaded, or downloaded to local disk, by choosing from
the upload and download menus.  The same can be done by hot-keys: if
Alt-D is pressed and the Kam is connected in Packet, Pactor or Gtor
mode, you can download a 7-plus file to local disc.  If Alt-U is
pressed, a 7-plus file can be sent.  The only character tranlations
made are LF -> CR when uploading, and CR -> LF when downloading, as
required by the Packet network.  These differ from sending a text file
via F6 or from the upload menu, or capturing a file via F2, by making
no other character translations.  With an ordinary compile, if a
stream is being captured, or if a text file is being uploaded from the
upload menu or by pressing F6, the stream will be captured or the file
sent using continental characters with a Latin-1 (computer) <-> Code
Page 437 (packet network) translation.  To work, the Kam parameters
are best set so that AUTOLF is OFF, AUTOCR is 0, CRADD is OFF, CRSUP
is OFF, LFADD is OFF and LFSUP is OFF.  (Running tnc.parms via F9 will
set these correctly automatically and the program will carry out all
the necessary CR/LF insertions (HF Tor modes) and CR <-> LF
translations (Packet mode).

When a binary download is chosen from the menu or Ctrl-Alt-D is
pressed, if the Kam is connected in Packet, Pactor or Gtor mode, a
download can be made of raw data to local disc with no character
translations, and if a binary upload is chosen from the menu or
Ctrl-Alt-U presssed, the program will upload raw data.  However, these
do not use any special protocal such a YAPP, so they are as yet only
really suitable for 7plus or UUencoded files which are being sent on a
direct station to station link not involving the Packet network, or
which have already had a LF -> CR translation made to them.  To send
raw data, it is essential that the Kam parameters are set so that
AUTOLF is OFF, AUTOCQ is 0, CRADD is OFF, CRSUP is OFF, LFADD is OFF
and LFSUP is OFF as mentioned above.

If the lock button or Alt-L is pressed when in Pactor or Gtor mode,
the receive speed will be locked to 100 baud, and the bottom status
line will show "LOCK".

If Alt-1 to Alt-5 are pressed, the message specified in the file
"messages" will be sent ("messages" will be looked for in the
directory specified by KAMDIR: in kamrc).  Such a message should not
exceed MESSAGE_SIZE defined in prog_defs.h (276 bytes in the standard
distribution).  If Alt-6 to Alt-0 are pressed, the file specified in
the "messages" file will be sent.  There is no maximum message size
for a file sent with Alt-6 to Alt-0.  See the specimen "messages" file
installed by "make install" for further details.  Also see the
specimen "kamrc" file for the NOPROMPT option which will send the
relevant message without asking for confirmation first.

When sending a message or file via Alt-0 to Alt-9, six shortcuts are
provided - $a is translated to your call, $b is translated to your
selcall, $c will be translated to the call in the callsign store
buffer for the currently active screen, $d will be translated to the
current time in UTC (hours and minutes),$e will be translated to the
current date (day-month-year) and $f will be translated to the value
(if any) currently held in the RST report buffer.  These translations
do not apply to any file sent via the F6 key - files sent via F6 are
sent exactly as they appear.

The "Command" button or F5 can be used to send configuration scripts
as well as sending Kam commands entered directly at the keyboard.
Such scripts must be placed in the KAMDIR:/parms/ directory.  The
distribution comes with two scripts - 'home' and 'away', which contain
the kind of Kam parameters suitable for attended and unattended
operation.  To run a script, instead of entering a command directly at
the keyboard, press the "script" button in the connect dialog or F5
again, and then choose the script file.

When the HF port is not in a packet mode, it will send text to the Kam
depending on the setting chosen from the "Hf Send" menu or toggled by
F3.  If set to "Word", it will send text at the end of each word, if
set to "Line" it will send it at the end of each line (when Return is
pressed).  If set to "Guard", a minimum of 10 characters in any line
will be retained in the transmit queue, which can be erased from the
keyboard before being sent to enable correction of errors.  This can
be useful in Amtor and RTTY modes which do not allow the transmission
of backspace characters.  Pactor and Gtor do allow transmission of
backspace/delete, so this setting is not so important for those modes.

When the HF port is not in a packet mode, the program will search
incoming text for a valid callsign format, and if it finds one, enter
it in the Call Sign buffer (and also generate a SELLCALL for calling a
station in Amtor).  Pressing the "Toggle callsign lock" button or
pressing F8 will lock the Call Sign buffer to the current displayed
callsign so that the buffer will not be updated.  When locked, an
asterisk will be displayed in front of the callsign shown on the
screen.  Pressing the button or pressing F8 again will unlock the
displayed callsign, so that it will be displaced by the next detected
valid callsign.

	              SLOW COMPUTERS

RTTY, CW and similar modes are not very efficient in terms of the
updating of the display, because host packets from the Kam consist of
packets containing single letters.  For full-speed 45.45 baud RTTY
traffic, X Window can place quite a high processor load on old, slow
machines by such letter by letter updating of the display.  The kamrc
configuration file therefore now contains a new option.  If
SLOW_WRITE: is set true, when in RTTY and similar modes the screen
will only be updated on a word by word basis or if more than 8
characters have been received, thus reducing processor load.  If you
have a Pentium, you will not need to use this option.

The option has no effect on modes where the text is received in decent
sized "packets", such as Pactor, Gtor and Packet modes.

                      CONNECT SCRIPTS

The program can ease the task of making Packet connects via nodes by
running automatic connect scripts.  See the file CONNECT_SCRIPTS with
this distribution for further details.

                         CLIPBOARD

Received text can be imported into other programs by copying it onto
the clipboard via the File pull-down menu or the right-mouse pop-up
menu.  (It can of course also be downloaded to file or captured to
capture.txt as mentioned above.)

                 CONTINENTAL CHARACTERS (LATIN-1)

To display continental characters, compile the program with CHARSET in
Makefile defined as LATIN_1 (this is the default).

                   LINE WRAP IN RECEIVE WINDOW

The program now has an option in the "Settings" menu enabling
automatic line wrap of received text once the text reaches an end
stop.  The start up default can be set in the kamrc configuration
file.

                       PROGRAM APPEARANCE

The program will default to the Qt "Motif" style.  If you want to
start it in "Windows" style, start it with the command line:

kam-qt -style=windows

The command line:

kam-qt -style=motif

will explicitly start the program in Motif style.

The default font size of the menu bar and status bars is 12 point.  It
can be set to 10 point or 11 point with the fontsize parameter, as
follows:

kam-qt -fontsize 10
kam-qt -fontsize 11

(This does not affect the fontsize of the display windows - that can
be set from the pull down menu once the program has started).

                           PRINTING

Received text can be printed in three ways:

1.  From the File pull-down menu or the right-mouse pop-up menu, or by
pressing Alt-B, the entire contents of the scroll buffer for the
stream currently displayed can be printed.

2.  From the File pull-down menu or the right-mouse pop-up menu, or by
pressing Alt-P, a print mark can be made in the stream currently
displayed.  At any later time, the text following the print mark can
be printed, either by pressing Alt-P again or via the menus.

3.  If text in the receive window is highlighted using the mouse, the
selected text can be printed out from the appropriate entry in the
File pull-down menu or the right-mouse pop-up menu.

The default printer command used is 'lpr'.  A special printer command
can be set with the PRINT_CMD: setting in kamrc (see the sample kamrc
file for further details).

		     CONTACTING THE AUTHOR

I can be reached at:

chris@cvine.freeserve.co.uk
G3XXF@GB7MSW.#33.GBR.EU

Updates can be obtained from:
http://www.cvine.freeserve.co.uk/

I am happy to arrange skeds on HF.

73, Chris.
