xdx - tcp/ip DX-cluster and ON4KST chat client for Amateur Radio
================================================================

Xdx is a DX-cluster client which shows a list with DX announcements and a
separate text widget with WWV, WCY, 'To ALL' and other server messages.
It is also suited to connect to ON4KST chat.

Quick keystroke reference
=========================
Main menu:
        Alt-P           Open Program menu
            Ctl-L       View connection log
            Ctl-Q       Exit Xdx with a close dialog
        Alt-H           Open Host menu
            Ctl-O       Connect to cluster server
            Ctl-C       Disconnect from cluster server
        Alt-S           Open Settings menu
            Ctl-K       Toggle function keys window
            Ctl-R       Toggle auto reconnect
            Ctl-S       Toggle highlight window
            Ctl-P       Open preferences dialog
        Alt-E           Open Help menu
            Ctl-H       View this manual
            Ctl-A       About Xdx

Function keys window:
        F1 - F8         Saved F1 to F8 commands

Highlights window:
        Alt-1 - Alt-8   Switch between highlight entries
        Ctl-1 - Ctl-8   Activate highlights (toggles check boxes)

General:
        Alt-0           Return focus to the command entry window

What is a DX Cluster?
=====================
A DX Cluster is a means for Amateur (Ham) Radio operators to tell each other,
in realtime, about DX stations (interesting or rare Amateur Radio stations
from all over the world).

Users who are connected to a DX Cluster are capable of announcing DX spots
and related announcements, send personal talk messages, send and receive mail
messages, search and retrieve archived data, and access data from information
databases.

For a list of DX Clusters see:
http://www.ng3k.com/Misc/cluster.html

ON4KST chat is more suited for VHF and UHF operators. It is a place where
hams meet for planning long distance radio contact, moonbounce and
meteor scatter. For more info on ON4KST chat see http://www.on4kst.com.

Commands
========
Here are some basic DX-cluster commands to get started:

announce/full 'msg': Send a line of text to all connected stations.
bye: Exit the DX Cluster.
dx 'frequency' 'callsign' 'comment': Send DX spot information.
show/dx: View previously logged DX spots.

ON4KST uses a DX-cluster command subset. It is best if you type '/help'
after being connected. All of the commands need to start with '/'.

DX-cluster Command examples
===========================
1) dx 28002.2 xz7a worked with 80m dipole!!
2) sh/dx on hf/cw 50

Callsign and autologin
======================
The callsign in the first page of the preferences dialog is used for
recognizing the DX-cluster prompt (so xdx can colorize it) and for autologin.
When autologin is enabled, a number of commands can be send to the cluster.
You may enter them in the 'Commands' entry, separated by a comma,
e.g. set/page 0,unset beep' will disable paging and stop beeps.
You can also use commands when a password is needed. There is a
0.5 second delay between commands.

Keepalive packets
=================
If you have a bad network and experience random disconnects, you can try
to enable keepalive in the settings dialog. This will send a backspace to the
server every 5 minutes.

Saving DX info
==============
Individual messages can be saved to a file when activated from the preferences
dialog.

$HOME/.xdx/dxspots  DX spots as displayed in the top list.
$HOME/.xdx/wwv      WCY/WWV anouncements with propagation info.
$HOME/.xdx/toall    Chat messages as displayed in the bottom text widget.
$HOME/.xdx/wx       Weather information.

When wwv data is saved, files with "tab seperated values" will be saved for
every WWV host. This is useful for creating graphs. The format of this file:

YYYMMDDHH	SFI	A	K	R

Where SFI is the 10.7 cm solar flux index, A and K both indicate geomagnetic
activity and R refers to sunspot numbers. An example script is included in
the xdx data directory which uses gnuplot to display data from DK0WCY. It is
called with 'gnuplot wwv.gnuplot'. It writes a plot to $HOME/.xdx/DK0WCY.png.

Hamlib support
==============
When double clicking on a dxspot in the top window this will set your rig's
frequency. You need the rigctl binary from the hamlib distribution for this.
Please modify the ID for your rig in the rigctl command line in preferences
dialog, e.g. 'rigctl -m 210 -r /dev/rig set_freq %d' will use ID 210
(Kenwood TS-870), see 'rigctl ---list' for a list of models.

Web browsers and mail programs
==============================
A URL in the chat window will appear blue and underlined when your mouse is
over it. Clicking on it will open the link in your preferred browser or mail
program (see the preferences dialog):

Start the gnome web-browser when clicking a URL: 'epiphany %s'.
Start mozilla-mail on clicking a mail URL: 'mozilla -compose "to=%s"'.

By default the browser and email apps are not set in the preferences dialog.
Leaving them blank will cause your preferred desktop apps to be run to
handle these URIs.  In some cases it may be necessary to check the desktop
configuration for preferred applications.  If that fails, it may be necessary
to manually edit ~/.local/share/applications/mimeapps.list to force your
preferences to be honored.  This change is due to changes in GTK+ 2.24 which
made the previous way of handling URIs obsolete.

Highlights
==========
The 'chat sidebar' allows entry of 8 different words, which can be highlighted
in the chat window. When the checkbox is used xdx will search for a highlight
in all of the incoming text. When not used, only the text after the prompt is
searched. Colors for the highlights are configured in page 3 of the settings
dialog. You can quickly turn checkboxes on/off with Ctrl-1 to Ctrl-8, you
can switch between entries with Alt-1 to Alt-8. Alt-0 switches back to the
send widget.

Function keys
=============
Selecting 'Ctl-k' toggles the function key window.  Commands may be assigned
to keys F1 through F8 by right-clicking on the mouse and entering the command
into the pop-up dialog.  Commands will only be sent when a connection to a
cluster is active.  Commands may be sent even when the function key window
is hidden.

Sound support
=============
When a highlight is active in the chat window, a sound can be played.
In order for the sound to work you must use a secondary program and
set it in the first page of the preferences dialog: 'play %s' will use
play, which is part of the sox package, 'esdplay %s' uses esdplay which
is useful when using gnome and esound.  'aplay %s' uses aplay which
is from the ALSA utilities.

Smileys
=======
There is support for a limited number of smileys in the chat window:
:)  :-)  :))  :-))  ;)  ;-)  :(  :-(  :((  :-((

Country file support
====================
Included with the Xdx distribution is cty.dat that provides information for
determining the country of origin of the spotted callsign.  The country
file is maintained by Jim Reisert, AD1C and the latest version can be
downloaded from:

	http://www.country-files.com/cty/cty.dat

The specification for the country file is:

	http://www.country-files.com/cty/backup/format.htm

Updates to the country file are released before major DX contests.  This file
will be updated more often than Xdx so the version included in the source
archive will become out of date in a short period of time.  Rather than
release new versions of Xdx just to update cty.dat, support has been added to
load the file from your home directory.  This can be done in one of two ways.

1. Place the updated cty.dat into the Xdx preferences directory which is
   $HOME/.xdx on POSIX platforms.

2. If cty.dat is kept in another directory for use with a logging program, set
   the XDX_CTY environment variable to the path of cty.dat, e.g.
   $HOME/log/cty.dat or use the '-c' or '--cty_dat' option on the xdx command
   line to set the path.

The command line option overrides the setting of the environment variable.

When the environment variable or the command line option is set the cty.dat in
the preferences directory will not be loaded unless the path does not end in
"cty.dat" or cty.dat is not a regular file, i.e. is a directory. In such cases
the preferences directory will be checked.  The system installed version of
cty.dat will be loaded as a fallback should the simple tests fail and the
prefences directory does not contain cty.dat.  There is currently no test of
whether the given cty.dat conforms to the specification.

If, for whatever reason, country determination is not desired, creating a 0 byte
file named cty.dat and using one of the above means to have Xdx load it will
disable country processing.

License and support
===================
Xdx is free and published under the GNU GPL license. It is written by
Joop Stakenborg <pg4i@amsat.org>.
Nate Bargmann <n0nb@n0nb.us> (current maintainer)

Please send a report if you find bugs or if you want enhancements.
