tlf.1.in

.\"
.\" Tips for formatting with the roff man macros.  Borrowed from the Vim nroff
.\" help text.
.\"
.\" In order to obtain the best formatted output g/troff can give you, you
.\" should follow a few simple rules about spacing and punctuation.
.\"
.\" 1. Do not leave empty spaces at the end of lines.
.\"
.\" 2. Leave one space and one space only after an end-of-sentence period,
.\"    exclamation mark, etc.
.\"
.\" 3. For reasons stated below, it is best to follow all period marks with a
.\"    carriage return.
.\"
.\" The reason behind these unusual tips is that g/n/troff have a line breaking
.\" algorithm that can be easily upset if you don't follow the rules given
.\" above.
.\"
.\" In addition, these tips aid vertical spacing.
.\"
.\" 1. Start all sentences on a new line.
.\"
.\" 2. Use the empty request--a single dot on a line--to provide vertical
.\"    spacing.
.\"
.\" 3. Use two empty requests before and one after all SH macros.
.\"
.\" 4. Use one empty request and one after all SS macros.
.\"
.\" 5. Use one empty request before all P, IP, and TP macros.
.\"
.\" The man(7), man-pages(7) and groff_man(7) manual pages offer many more
.\" rules and tips.
.
.
.\" Update the date when this page is committed.
.TH TLF 1 "@PACKAGE_NAME@ @VERSION@, 2022-09-18" TLF "Ham radio"
.
.
.SH NAME
.
@PACKAGE_NAME@ \- amateur radio contest keyer/logging program for Radiosport
.
.
.SH SYNOPSIS
.
.SY @PACKAGE@
.OP \-?dilnrvV
.OP \-f config_file
.OP \-s user:password@host/dir/logfilename
.OP \-\-debug
.OP \-\-config=\fIconfig_file\fP
.OP \-\-import
.OP \-\-list
.OP \-\-no-cluster
.OP \-\-no-rig
.OP \-\-sync=\fIuser:password@host/dir/logfilename\fP
.OP \-\-verbose
.OP \-\-version
.OP \-\-help
.OP \-\-usage
.YS
.
.
.SH DESCRIPTION
.
.B @PACKAGE_NAME@
is a console (ncurses) mode general purpose
.SM CW
keyer, logging and contest program for amateur radio operators.
.
It supports the
.SM CQWW,
.SM WPX,
.SM ARRL-DX,
.SM ARRL-FD,
.SM STEWPERRY,
.SM PACC,
.SM FOC Marathon
and
.SM EU SPRINT
contests as well as a lot more basic contests, general QSO and DXpedition mode.
.
It interfaces with a Morse Code generator, a number of radios via the
.B Hamlib
library, and with a
.B "DX Cluster"
via telnet or packet radio.
.
@PACKAGE_NAME@ can project DX cluster data into the excellent Xplanet program,
written by Hari Nair.
.
.P
Contest operation mimics the popular
.B TR-Log
program for DOS, the output file is TR-Log compatible.
.
The log can be exported in
.SM ADIF
or
.B Cabrillo 3.0
format.
.
.P
The program was written for console mode on purpose, which allows it to run on
smaller machines, or remotely via
.SM SSH
or a modem link.
.
.P
CW keying via
.B cwdaemon
is fully supported, featuring direct mode for the keyboard and output to
parallel and serial ports and speed and weight control from the keyboard, and
band info output on the parallel port.
Likewise, CW keying via
.B Hamlib
is supported for rigs that feature the capability. Tlf can set the CW speed,
and at the same time read back the speed if changed using the knob on the rig.
.
.P
For users of the K1EL series of \(lqWin Keyers\(rq, the
.B winkeydaemon
is available from
.UR https://github.com/N0NB/winkeydaemon
GitHub
.UE .
.
Setup is the same as for
.BR cwdaemon (1).
.
.P
For radio control @PACKAGE_NAME@ works with Hamlib (version >= 1.2.8), you
can find it at
.UR https://www.hamlib.org/
www.hamlib.org
.UE .
.
.P
@PACKAGE_NAME@ provides full
.SM TCP/IP
networking between @PACKAGE_NAME@ nodes, syncing/distributing log, packet
data, frequency data, local talk, serial numbers, time sync etc.
.
.
.SH OPTIONS
Options given to @PACKAGE_NAME@ on the command line.
.
.TP
.BR \-? , \ \-\-help
Print a summary of options to the screen and exit.
.
.TP
.BI \-f\  config_file
.TQ
.BI \-\-config= config_file
Start with a non-default configuration file:
.
.IP
.EX
@PACKAGE@ \-f PA0R
.EE
.
.IP
Defaults to
.I logcfg.dat
in the current working directory.
.
.TP
.BI \-s\  user:password@host/dir/logfilename
.TQ
.BI \-\-sync= user:password@host/dir/logfilename
Synchronize log with other node
.
.IP
.EX
@PACKAGE@ \-s user:password@host/dir/logfilename
.EE
.
.TP
.BR \-n , \ \-\-no-cluster
Start without packet/cluster.
.
.TP
.BR \-r , \ \-\-no-rig
Start without radio control.
.
.TP
.BR \-l , \ \-\-list
List all built-in contests.
.
.TP
.BR \-i , \ \-\-import
Import an existing Cabrillo file and generate @PACKAGE_NAME@ log files.
.
.IP
When @PACKAGE_NAME@ starts, it looks for
.I YOURCALL.cbr
file in the current directory, reads the configuration and rule files, and
based on the current setup generates the log(s).
.
If the contest is WAE and you have QTCs in Cabrillo, then @PACKAGE_NAME@
generates the QTC logfiles.
.
@PACKAGE_NAME@ will not write over the existing log(s).
.
.IP
The generated import will be
.IR IMPORT_CONTEST.log ,
where the CONTEST is the name of contest in the config.
.
If QTC exists, then the files
.I IMPORT_QTC_sent.log
and
.I IMPORT_QTC_recv.log
will be created.
.
.TP
.BR \-v , \ \-\-verbose
Verbose startup.
.
.TP
.BR \-d , \ \-\-debug
Debug
.BR rigctld (1).
.
.TP
.BR \-V , \ \-\-version
Print the version information to the screen and exit.
.
.TP
.B \-\-usage
Print a short usage message to the screen and exit.
.
.
.SH USAGE
.
@PACKAGE_NAME@ has been written for
.BR "console mode" \.
.
If you want to run @PACKAGE_NAME@ from a terminal in
.B X
or
.BR Wayland ,
you will probably get the best results if you set \fBTERM\fR=\fIlinux\fR and
use a Linux console terminal.
.
Both KDE and GNOME terminals have a facility to start a Linux console in an X
terminal as does Xfce-terminal.
.
.P
By default,
.BR xterm (1)
or
.BR urxvt (1)
may give unreadable colours.
.
If so, you will have to set different colours in
.I logcfg.dat
or prepare
.I $HOME/.Xresources
to the preferred colour scheme (a sample Xresources file that contains usage
instructions is included in the doc directory).
.
One advantage of xterm or urxvt are that they do not consume the
.B F11
key which other terminal emulators reserve for full screen mode nor
.BR Ctrl\-PgUp / Ctrl\-PgDn
which may be used for tab switching in other emulators.
.
.P
Recent efforts have resulted in improved keyboard handling.
.
If you find keys that do not work, the developers would like to receive your
report of which keys and which terminal have the problem.
.
Please send the report to the mailing list shown in the
.B BUGS
section below.
.
.P
There are excellent results with the latest KDE, GNOME, and Xfce terminal
emulators (vi colours are preferred by some).
.
As @PACKAGE_NAME@ uses ncurses to format its display you must use a proper
font.
.
(Good choices are the Linux font, Inconsolata, Hack, or any monospace font that
dots or slashes the zero character).
.
If you have problems, try the linux text console first and work from there.
.
.P
Normally you start or restart @PACKAGE_NAME@ in fast mode with
\(lq\fB@PACKAGE@\fR\(rq.
.
During debugging of a
.I logcfg.dat
file you can start in verbose mode, to have a look at the startup messages.
The config file can also be specified on command line:
.
.IP
.EX
@PACKAGE@ \-f config_file
.EE
.
.P
If you have the packet cluster enabled you will first see the packet screen
(if you are using telnet and you have provided your callsign in
.IR logcfg.dat \,
you will be automatically logged in switched to the main logging screen).
.
Log in with your callsign, if needed, and switch to the main logging screen
with the \(oq:\(cq command.
.
You can come back to the packet screen later with the
.BR :PAC ket
command from the call input field of the main logging screen.
.
.P
You can exit and close @PACKAGE_NAME@ with the
.BR :EXI t
or
.BR :QUI t
commands or with
.BR Alt\-X \.
.
.P
At restart @PACKAGE_NAME@ recalculates the score, which may take some time
depending on the number of QSOs in the logfile and the speed of your system.
.
@PACKAGE_NAME@ takes the points as they are in the log, and calculates the
multiplier from either callsign or exchange field (depending on the contest).
.
.
.SH COMMANDS
.
These commands are entered in the
.B callsign
field of the main logging screen.
.
Each command consists of the leading \(oq:\(cq and at minimum the upper case
characters of the command name plus any needed parameters separated by
\(oqSpace\(cq.
.
.TP
.BR :ADI f
Writes the log to an Amateur Data Interchange Format (ADIF) file
.IR logfile.adif \.
.
.TP
.BR :CHA r
Input the number of characters for CW auto-start or \(oqm\(cq for manual
start.
.
Possible values are: \(oq0\(cq (off), \(oq2\(cq...\(oq5\(cq or \(oqm\(cq
(manual).
.
.IP
After typing as many characters in the input field or after pressing the
\(oqEnter\(cq key in manual mode @PACKAGE_NAME@ starts sending the callsign
without further keystrokes.
.
You can type in the rest of the call (but quickly).
.
As soon as the sending catches your last typed character @PACKAGE_NAME@
automatically sends the exchange and the cursor jumps to the exchange field.
.
.IP
\(oqEscape\(cq stops sending.
.
.IP
This works only in CW contests in RUN mode.
.
.TP
.BR :CHE ck
.TQ
.BR :NOC heck
Turn the dupe check window On|Off.
.
.TP
.BR :CQD elay
Change Auto_CQ delay (in 1/2 seconds, with PageUp/PageDown keys).
.
.TP
.BR :CLO ff
No cluster information (non-assisted contest operation).
.
.TP
.BR :CLU ster
.TQ
.B :MAP
Show cluster window or bandmap.
.
.TP
.BR :CON test
Toggle contest mode On|Off.
.
.TP
.B :CTY
.TQ
.BR :ZON e
.TQ
.BR :MUL t
Show needed country multipliers, zones, multipliers per continent (depends on
the contest).
.
.TP
.BR :CW mode
.TQ
.BR :SSB mode
.TQ
.BR :DIG imode
Switch TRX to
.BR CW | SSB | DIG i
mode.
.
.TP
.BR :EDI t
Edit the log with your favourite editor.
.
Be careful!
.
.TP
.BR :EXI t
.TQ
.BR :QUI t
Exit @PACKAGE_NAME@ (synonym to
.BR Alt\-X ,
but without asking for confirmation).
.
.TP
.BR :FIL ter
Filter cluster info (announce, dx-spots, all).
.
.TP
.BR :FRE q
Show frequency or band/score information of your other @PACKAGE@ nodes.
.
.TP
.BR :FLDIGI
Toggle Fldigi communication On|Off.
.
.TP
.BR :HEL p
Show online help (displays
.I help.txt
from working directory or from
.I @prefix@/share/@PACKAGE@
if no local one exists).
.
.TP
.BR :INF o
Show network status.
.
.TP
.BR :MES sage
Edit CW (Morse Code) messages.
.
.TP
.BR :MOD e
Toggle TRX mode
.RB ( CW | SSB | DIG ).
.
.TP
.BR :PAC ket
Switch to the packet terminal.
.
Switch back to the main logging screen with \(oq:\(cq.
.
.TP
.BR :REC onnect
Re-opens the connection to the DX cluster in case it was disconnected.
.
.TP
.BR :RES core
Recalculates the values in the score window (e.g. after deleting or editing
QSOs).
.
.TP
.BR :RIT clear
Toggle the RIT reset after QSO On|Off.
.
.TP
.B :SET
.TQ
.B :CFG
Edit various parameters in
.I logcfg.dat
file and reload it.
.
.TP
.BR :SCO re
Toggle the score window On|Off.
.
.TP
.BR :SCV olume
Adjust the soundcard volume for the sidetone (Up|Down).
.
.IP
Range: 0\(en99.
.
.TP
.BR :SIM ulator
Toggle simulator mode On|Off.
.
In simulator mode you can work a complete CQWW CW contest in TR-Log mode.
.
Set \fBCONTEST\fR=\fIcqww\fR.
.
.TP
.BR :SOU nd
.
Opens the sound recorder menu.
.
.IP
The sound recorder is a utility for recording the voice keyer messages and
enables recording a complete contest in chunks of 1 hour to the hard drive.
.
.IP
Using the sound recorder requires the installation of the
.BR sox (1)
package, which provides the
.B rec
utilities used by the script.
.
.IP
For recording voice messages, the keys
.BR F1 \(en F12\c
.RB ,\  s ,\ or\  c
will record the voice keyer message for that key.
.
.IP
The sound recorder uses the
.I @prefix@/bin/soundlog
script which should already be installed to a location in the
.IR $PATH .
.
The recording is written to the
.I ./soundlogs
directory by default.
.
.IP
The
.I soundlog
script now defaults to the
.I rec
utility provided with the Sox package.
.
The command syntax is not compatible with the previous default
.I rec
utility.
.
.IP
The previous default
.I rec
utility is assumed to be from the Open Sound System (OSS) package (sound
system used on Linux prior to ALSA).
.
Its default soundcard device is
.IR /dev/dsp .
.
To enable the OSS version uncomment the needed line in the
.I soundlog
script and comment the Sox
.I rec
line.
.
.IP
The recorded file extension is
.IR .au ,
the Sun \[*m]\(enlaw format.
.
.IP
The recorder produces less than 60 MegaBytes per hour in single channel mode.
.
Recording a complete 48 hour CQWW event requires less than 3 GigaBytes of disk
space.
.
If local disk space must be preserved, the sound file can be moved to another
host using FTP, rsync, scp, or any other network transfer protocol.
.
.IP
Sound recorder menu:
.IP
.
.BR 1 :
Start/Stop contest recording to
.IR ddhhmm .au.
.
.IP
.BR 2 :
List contest recordings and play back selected recording
.IR ddhhmm.
.
.IP
To create a new file every hour add a
.BR crontab (1)
job to run the following command every hour (syntax for SoX
.I rec
shown):
.
.RS
.RS
.
.P
.EX
/usr/bin/pkill \-x rec
.EE
.
.P
Running the crontab job at other intervals will create sound recordings of the
interval period in length.
.RE
.RE
.
.IP
Once started the recorder will run until the lock file
.I $HOME/.VRlock
is removed and the script gets stopped (performed by menu item 1).
.
.IP
If you leave TLF with the recorder running TLF will ask for confirmation.
Depending on your answer TLF can stop it or keep it running. In the latter
case just restart TLF and use :sound again to stop it.
.
.IP
Cabling and setting up the radio to record both received and transmitted audio
is left as an exercise for the reader simply due to the variety of radios and
station configurations.
.
.IP
To ease the adaption to the local environment record and play back commands
for voice keyer messages and contest audio can be configured by the following
keywords:
.I VK_RECORD_COMMAND,
.I VK_PLAY_COMMAND,
.I SOUNDLOG_RECORD_COMMAND
and
.I SOUNDLOG_PLAY_COMMAND. 
The directory where soundlogs gets stored can be configured with 
.I SOUNDLOG_DIRECTORY.
See \(lqSound Commands\(rq section below.
.
.TP
.BR :SYN c
Synchronize the logfile of this node with the logfile pointed to by the
parameter \fBSYNCFILE\fR=\fIuser:password@host/dir/logfile\fR.
.
@PACKAGE_NAME@ will
.BR wget (1)
the logfile from the relevant node, make a dated backup of your local logfile,
and merge the 2 files.
.
The score will be recalculated.
.
.TP
\fB:TON\fRe [\fIdd\fR]\fId\fR
Set PC sidetone frequency in Hertz.
.
.IP
Range: 300\(en900, 0 = Off.
.
.TP
.BR :TRX control
Toggle rig control On|Off.
.
.IP
Default is Off unless
.B RADIO_CONTROL
is given in
.I logcfg.dat
(only makes sense with rig control capability).
.
.TP
.BR :VIE w
View the log with
.BR less (1).
.
.TP
.BR :WRI te
Write Cabrillo file according to specified format (see
.B CABRILLO
statement in the
.B RULES
section).
.
.IP
The file is created in the current directory as
.I YOURCALL.cbr
(with slashes as part of YOURCALL converted to underscores, such as
WX9XYZ/8.cbr to WX9XYZ_8.cbr).
.
.
.SH KEYS
.
Work has been ongoing to unify the key map between the Linux text console and
the various X terminals.
.
It may be slightly different on certain X terminals depending on which keys
they consume for their own use.
.
Turn off any key recognition by the terminal for its own purposes (menu
access, help display, etc.) if possible.
.
Pay special attention to the F1-F12 and Alt-<\fIchar\fR> keys.
.
Moreover, on some systems you must set the \fBTERM\fR=\fIlinux\fR or
\fBTERM\fR=\fIrxvt\fR environment variable, although variables such as
.IR xterm ,
.IR xterm-color,
or
.I xterm-256color
should work.
.
.\" What works under VNC???
This also works under VNC.
.
.P
Certain key combinations will probably not be usable as the Linux console
consumes Alt-F1 through
.RI Alt-F x
(often F7, but could be greater) for switching its virtual consoles.
.
Likewise, the various desktop environments consume key combinations for their
own use.
.
Ctrl-F1 through
.RI Ctrl-F x
are used to switch desktop workspaces.
.RI Alt-F x
combinations are used for various desktop features and are unavailable
for @PACKAGE_NAME@ use.
.
.P
Some desktop terminal emulators are capable of being configured to allow the
application running in them to get all of the keys the desktop environment
does not consume.
.
In testing good choices seem to be Gnome Terminal, Rox Terminal, or the
classic Xterm (although its default color presentation differs slightly from
the Linux console and other terminal emulators) or URxvt (with a very distinct
default color palette).
.
Xfce Terminal is known to consume F11 and Ctrl-PageUp and Ctrl-PageDown.
.
The @PACKAGE_NAME@ developers have implemented Alt-PageUp and Alt-PageDown as
a work-around for the Ctrl counterparts.
.
Reports of success with other terminals are welcome.
.
.SS Call Input and Exchange Fields
.
The Call Input and Exchange Fields are the two main entry fields of
@PACKAGE_NAME@ where the majority of the keyboard entry takes place.
.
The call input field is active when @PACKAGE_NAME@ completes its
initialization and presents the main screen.
.
.P
Most key sequences are the same in both fields.
.
Differences are noted as necessary.
.
.TP
.BR A-Z ,\  0-9 ,\  /
.BR Call\ input :
ASCII letters, numerals, and the
.B /
character that make up an internationally recognized amateur radio callsign
plus temporary location identifiers.
.
Spaces are not allowed.
.
.IP
.BR Exchange :
information provided by the other station possibly separated by spaces, such
as ARRL Field Day and ARRL Sweepstakes.
.
.TP
.B Space
Switch from call input to exchange field.
.
.IP
Separates exchange field elements when multiple exchange elements must be
entered, such as ARRL Field Day and ARRL Sweepstakes.
.
.TP
.B Tab
Switch between call input and exchange fields (jump back to call input from
exchange field).
.
.TP
.B Enter
Smart key depending on contest mode.
.
.IP
@PACKAGE_NAME@ follows the TR operating style which has two modes,
.B CQ
and
.B S&P
(Search and Pounce).
.
.IP
.B CQ
mode is used for \(lqrunning\(rq, that is staying on one frequency and
having other stations answer your call.
.
.IP
.B S&P
mode is for tuning up or down the band and answering the calls of other
stations.
.
.IP
.B In CQ Mode:
.RS 7
.
.IP \(bu 2
With the call input field empty,
.B Enter
sends the
.B F12
message (Auto CQ).
.
.IP \(bu 2
With characters in the call input field,
.B Enter
answers the calling station by sending the
.B F3
message (RST) and moves the cursor to the exchange field.
.
.IP \(bu 2
If the exchange field is empty,
.B Enter
repeats the
.B F3
message (RST).
.
.IP \(bu 2
After the exchange information received from the other station is entered,
.B Enter
sends the
.B CQ_TU_MSG
message if defined, or \(lqTU\(rq (CW mode) and your call otherwise.
.
Afterwards it logs the QSO, and returns the cursor to the call input field to
answer the next call.
.RE
.
.IP
.B In S&P Mode:
.RS 7
.
.IP \(bu 2
When the call input field is empty,
.B Enter
sends the
.B S&P_CALL_MSG
if defined, or your call otherwise.
.
.IP \(bu 2
When the exchange field is empty,
.B Enter
sends the
.B S&P_CALL_MSG
if defined, or your call otherwise.
.
.IP \(bu 2
When the call input field has been filled,
.B Enter
sends the
.B S&P_CALL_MSG
if defined, or your call otherwise.
.
Afterwards it moves the cursor to the exchange field.
.
.IP \(bu 2
Once the exchange has been received,
.B Enter
sends the
.B S&P_TU_MSG
if defined, otherwise it sends your call followed by the
.B F3
message (RST).
.
Afterwards it logs the QSO and returns the cursor to the call input field to
answer the next call.
.RE
.
.TP
.B Backspace
Erase the character to the left of the cursor and moves the cursor one
position to the left.
.
.\" FIXME: Update Escape section when changes are made in source.
.TP
.B Escape
Stop CW transmission, clears characters, returns to call input field, keyboard
off (universal undo).
.
.br
.BR Note :
Some changes are being considered to modify the behavior of
.B Escape
slightly.
.
The intent will be to have
.B Escape
only stop sending on first press and not clear any entered information.
.
It is planned that
.B Escape
will stop the playback of the voice keyer as well.
.
.IP
As an example, characters have been entered in both the call input and
exchange fields, the cursor is in the exchange field, and the transmission of
a CW message is in progress.
.
.IP
The first press of
.B Escape
will stop the CW transmission and clear the exchange field and position the
cursor to the leftmost position of the exchange field.
.
.IP
The second press of
.B Escape
will move the cursor to the right of the last character in the call input
field.
.
.IP
The third press of
.B Escape
will clear the call input field.
.
.IP
You can disable the above described UNDO functionality by setting
.BR ESC_STOPS_TX_ONLY
(see below).
.
.TP
.BR \(<-\  (Left-Arrow)
Call input field is empty: change to next band lower in frequency or wrap to
highest band if already on the lowest band.
.
.IP
Characters in the call input field: enter edit mode while moving the cursor
to the left onto the rightmost character.
.
In edit mode successive presses will move the cursor left until the first
character is reached.
.
.TP
.BR \(->\  (Right-Arrow)
Change to next band higher in frequency or wrap to the lowest band if already
on the highest band when call input field is empty.
.
.TP
.B F1
In
.B CQ
mode, send message
.B F1
(CQ).
.
.IP
In
.B S&P
mode send message
.B F6
(MY).
.
.TP
.B Shift-F1
Restore previous CQ frequency from MEM and send message
.B F1
(CQ).
.
.TP
.B F2-F11
Send CW, RTTY or VOICE messages 2 through 11. If the callsign field is empty
the messages will be sent with the preceding qso data.
.
.TP
.B F12
Start
.B Auto_CQ
(only activated from the call input field).
.
Sends
.B F12
message repeatedly pausing for Auto_CQ delay time between messages.
.
Auto_CQ is cancelled with first character entry into the call input field.
.
.TP
.BR +\  (Plus)
Toggle between the
.B CQ
and
.B S&P
modes.
.
.TP
.B PgUp
Increase CW (Morse Code) speed (from call and exchange fields).
.
.IP
If the cursor is in the call input field and it is not empty and
.B CHANGE_RST
is set: increase sent RST.
.
.IP
If the cursor is in the exchange field and it is not empty and
.B CHANGE_RST
is set: increase received RST.
.
.TP
.B PgDown
Decrease CW (Morse Code) speed (from call input and exchange fields).
.
.IP
If the cursor is in the call input field and it is not empty and
.B CHANGE_RST
is set: decrease sent RST.
.
.IP
If the cursor is in the exchange field and it is not empty and
.B CHANGE_RST
is set: decrease received RST.
.
.TP
.B Ctrl-PgUp
.TQ
.B Alt-PgUp
Increase Auto_CQ delay pause length (+1/2 sec).
.
.IP
Set Auto_CQ delay to message length + pause length.
.
.TP
.B Ctrl-PgDown
.TQ
.B Alt-PgDown
Decrease Auto_CQ delay pause length (\-1/2 sec).
.
.IP
As some terminals, Xfce Terminal is one such, consume
.BR Ctrl-PageUp / Ctrl-PageDown ,
the
.BR Alt-PageUp / Alt-PageDown
combinations allow for setting the Auto_CQ delay pause length.
.
.IP
.BR Note :
If neither key combination works try
.B :CQD
instead.
.
.TP
.BR ?\  (Query)
In CW or DIGIMODE sends the partial call followed by \(lq ?\(rq.
.
In VOICE mode sends recorded message 5 (F5).
.
.TP
.BR ;\  (Semicolon)
Insert note in log.
.
.TP
.BR ,\  (comma)
.TQ
.B  Ctrl-K
Activate keyboard mode.
All message and keying control keys work the same way as in log input mode.
To close the keyer window without stopping the ongoing transmission
press either
.BR Ctrl\-K ,
.BR Alt\-K ,
.B `
(Grave Accent),
.BR \[da]\  (Down-Arrow)
or
.BR Enter
(in CW mode only).
.B Escape
closes the window and also stops keying.
.
.TP
.BR \(dq\  "(Double quotation)"
Send talk message to other @PACKAGE_NAME@ nodes.
.
.TP
.BR \-\  (Minus)
Delete last QSO (Use
.BR :RES core
to correct scoring afterward).
.
.TP
.BR \[ua]\  (Up-Arrow)
In empty call input field: Edit last QSO: Insert, overwrite, and delete; + log view.
.
.IP
Increment serial number in exchange input field.
.
.TP
.BR \[da]\  (Down-Arrow)
Decrement serial number in exchange input field.
.
.TP
.BR =\  (Equals)
Confirm last call.
.
.TP
.BR _\  (Underscore)
Confirm last exchange.
.
.TP
.BR {\  "(Open brace)"
In RTTY (DIGIMODE), keyboard mode switch TX on.
.
.TP
.BR }\  "(Close brace)"
In RTTY (DIGIMODE), keyboard mode switch TX off (RX).
.
.TP
.BR \e\  (Backslash)
Log QSO without CW output.
.
.IP
In RTTY (DIGIMODE), keyboard mode switch controller to command mode
(back to operating mode with
.RB \(oqK\(cq Enter ).
.
.TP
.BR #\  (Hash)
Transceiver VFO frequency \(-> MEM, MEM \(-> transceiver VFO frequency.
.
.TP
.BR $\  (Dollar)
Pop MEM frequency: MEM \(-> transceiver VFO frequency and clear MEM.
.
.TP
.BR %\  (Percent)
Swap transceiver VFO frequency and MEM.
.
.TP
.BR !\  (Exclamation)
Get a new shell.
.
Come back with \(lqexit\(rq.
.
.TP
.B Alt-,
.TQ
.BR .\  (Period)
Change bandmap filter configuration.
.
You can filter to show spots from all or own band only, from all/own mode only
and if you want to see dupes or not (see the help
.RB ( Alt-H )
display), only new multiplier or all call (only CQWW).
.
.TP
.B Ctrl-A
Add a spot to bandmap and broadcast it on the local network.
.
.TP
.B Ctrl-B
Send a spot to the DX Cluster (a connection to a DX cluster must exist). TLF
prepares a minimal spot line and allows you to edit it. Finish editing and
send the spot with 
.BR ENTER 
or abort sending by pressing the 
.BR ESCAPE 
key.
.
.TP
.B Ctrl-E
End modem capture for RTTY mode in QTC window (started with
.BR Ctrl-S ).
.
.IP
See
.I @prefix@/share/doc/@PACKAGE@/Manual.md
for more information.
.
.TP
.B Ctrl-F
Set frequency.
.
Use
.BR Up / Down -Arrow
for 100Hz steps and
.BR Pg-Up / Pg-Down
for 500Hz steps.
.
Return to logging with
.BR Escape .
.
.TP
.B Ctrl-G
Grab next DX spot from bandmap.
.
The indicator on the right of the bandmap shows the current grabbing
direction.
.
It can be toggled with
.BR Ctrl-V .
.
.TP
.B Ctrl-L
Reset the screen.
.
.TP
.B Ctrl-P
Maximum Usable Frequency (MUF) display.
.
.TP
.B Ctrl-Q
Open the QTC window for receiving QTCs if \fBQTC\fR=\fIRECV\fR or
\fBQTC\fR=\fIBOTH\fR or sending QTCs if \fBQTC\fR=\fISEND\fR is set in
.IR logcfg.dat .
Same as
.B Ctrl-S
if \fBQTC\fR=\fISEND\fR.
.
.IP
See
.I @prefix@/share/doc/@PACKAGE@/Manual.md
for more information.
.
.TP
.B Ctrl-R
Toggle
.I /dev/lp0
pin 14 (Mic/Soundcard switch | trx1/trx2 switch).
.
.TP
.B Ctrl-S
Open the QTC window for sending QTCs if \fBQTC\fR=\fISEND\fR or
\fBQTC\fR=\fIBOTH\fR in \fIlogcfg.dat\fR.
.
Saves QTCs while in QTC window.
.
.IP
In RTTY mode starts capture from the modem after the window has been opened
with
.BR Ctrl-Q .
End capture with
.BR Ctrl-E .
.
.IP
See
.I @prefix@/share/doc/@PACKAGE@/Manual.md
for more information.
.
.TP
.B Ctrl-T
Show talk messages.
.
In the QTC window shows RTTY lines.
.
.TP
.B Ctrl-U
Wipe out whole input line (call input and exchange), clear all
information about current contact.
.
If entered by accident a second
.BR Ctrl-U
restores the line.
.
.TP
.B Ctrl-V
Toggle grabbing direction in which
.B Ctrl-G
looks for a spot.
.
.TP
.B Ctrl-W
Wipe actual field the cursor is in (call input OR exchange).
.
If entered by accident a second
.BR Ctrl-W
restores the field.
.
.TP
.B Ctrl-Z
Suspend @PACKAGE_NAME@ returning to shell prompt.
.
To return to @PACKAGE_NAME@ use the \(oqfg\(cq command (Bourne Shell) or the
equivalent command for your shell.
.
.TP
.BR Alt-0 ... Alt-9
Send alternate CW (Morse code) messages. If the callsign field is empty the
messages will be sent with the preceding qso data.
.
.TP
.B Alt-A
Cycle cluster window: NOCLUSTER \(-> CLUSTER \(-> BANDMAP \(-> ...
.
.TP
.B Alt-B
Band up in TR-Log mode.
.
.TP
.B Alt-C
Toggle display of checkwindow.
.
.TP
.B Alt-E
Enter QSO edit mode.
.
.TP
.B Alt-G
Grab first spot from bandmap which has the characters in the call input field
in its call.
.
Allows the operator to selectively grab a specific call from the bandmap.
.
.TP
.B Alt-H
Show help file
.IR @prefix@/share/@PACKAGE@/help.txt .
.
.TP
.B Alt-I
Show talk messages.
.
.TP
.B Alt-J
Show the frequencies of other local station(s).
.
.TP
.B Alt-K
Keyboard mode, same as
.RB Ctrl-K .
.
.TP
.B Alt-M
Show multipliers.
.
.TP
.B Alt-N
Add Note to log.
.
.TP
.B Alt-P
Toggle PTT (via \fBcwdaemon\fR).
.
.TP
.B Alt-X
Exit @PACKAGE_NAME@ (synonym to
.BR :EXI "t "
and
.BR :QUI "t, but asks for confirmation)."
.
.TP
.B Alt-R
Toggle score window.
.
.TP
.B Alt-S
Toggle score window.
.
.TP
.B Alt-T
Tune your transceiver (via
.BR cwdaemon ).
.
Activates PTT and Key output, by default for 6 seconds.
.
Stop tuning by pressing any key.
.
You can override the default value using the
.B TUNE_SECONDS
configuration statement.
.
In addition to
.BR cwdaemon ,
tune also works with
.B winkeydaemon
(tested with v1.0.10).
.
.TP
.B Alt-V
Band down.
.
.TP
.B Alt-W
Set CW weight.
.
.TP
.B Alt-Z
Show zones worked.
.
.SS CT Compatible Mode
.
@PACKAGE_NAME@ has limited support for the logging sequence keys used in the
once popular
.B CT
logging program.
.
Unlike the default
.I Enter \ Sends \ Message
.RB ( ESM )
mode, the CT Compatible mode uses the
.B Insert
and
.B +
keys in the logging sequence and
.B Enter
logs a complete QSO.
.
Unlike ESM mode, CT mode does not have separate
.B CQ
or
.B S&P
modes.
.
.P
CT Compatible mode is enabled with the
.B CTCOMPATIBLE
keyword in
.I logcfg.dat
(see the
.B PREFERENCES
section below).
.
.P
The following keys differ in behavior in CT Compatible mode.
.
.TP
.B Enter
Log the complete QSO without sending any message macro.
.
.IP
If the callsign field is empty, pressing
.B Enter
will activate the
.B Auto-CQ
function.
.
If the exchange field is empty, pressing
.B Enter
in either the callsign or exchange field will result in no action.
.
.TP
.B Insert
Send the
.B RST
(F3) macro.
.
.IP
Since the
.B RST
macro includes the other station's callsign by default, the
.B HIS
macro is not sent first.
.
This differs from classic CT, but is a compromise to use the default
@PACKAGE_NAME@ macros.
.
.TP
.BR + \ (Plus)
Send the
.B TU
macro and log the QSO.
.
.IP
The
.B +
key checks if the exchange field is empty and if it is nothing is sent or
logged.
.
In rare cases where nothing needs to be entered in the exchange field, such as
when working DX from USA in ARRL 160, simply enter a space to allow the
.B +
key to send the
.B TU
message and log the QSO.
.
.TP
.B Alt-V
Change CW speed.
.
.
.SH PREFERENCES
.
@PACKAGE_NAME@ can be fully configured by editing the
.I logcfg.dat
file.
.
Normally you keep one
.I logcfg.dat
file, setting up your callsign, the log file name, the ports and addresses for
packet, the radio, the network etc., and a separate rules file per contest.
.
.P
The
.I logcfg.dat
file can be edited from within @PACKAGE_NAME@ by the
.BR :CFG \ or \ :SET
commands (or with any other plain text editor before starting @PACKAGE_NAME@).
.
It contains keyword-argument pairs, one per line.
.
Lines starting with \(lq#\(rq and empty lines are interpreted as comments and
are ignored.
.
.P
You can set your favourite editor in the
.IR logcfg.dat \ file.
.
.P
The rules file is associated with the statement
\fBRULES\fR=\fIcontest_rules_file_name\fR in
.IR logcfg.dat .
.
.P
.BR Note :
Both
.I logcfg.dat
and
.I rules
file support the same configuration parameters except \fBRULES\fR which is
allowed only in
.IR logcfg.dat .
.
.P
@PACKAGE_NAME@ will first look in the current working directory for a
.I logcfg.dat
file, and if it cannot find one it will look in
.I @prefix@/share/@PACKAGE@
for a default one.
.
Make sure you edit the
.I logcfg.dat
file for at least your callsign and your preferred system configuration.
.
.P
Parameters requiring a boolean value (like \fItrue\fR/\fIfalse\fR)
can have an optional case-insensitive argument.
Alternatively, both \fIyes\fR and \fIon\fR are treated as \fItrue\fR.
Similarly instead of \fIfalse\fR also \fIno\fR or \fIoff\fR can be used.
Without the argument the default assigned value is \fIyes\fR.
.
.
.SH logcfg.dat STATEMENTS
.
Configuration parameters are set in
.I logcfg.dat
which is located in the working directory (where @PACKAGE_NAME@ is started).
.
.SS @PACKAGE_NAME@ Setup Commands
.
.TP
\fBRULES\fR=\fIcontest_rules_filename\fR
Name of the rules file to load.
.
.IP
It helps to name the rules file according to the contest you want to describe.
.
The rules file is located under the
.I rules
directory of the working directory.
.
.TP
\fBSYNCFILE\fR=\fIuser:password@host/dir/syncfile\fR
File on remote host you want to synchronize with (use
.BR wget (1)
syntax).
.
.TP
\fBCTCOMPATIBLE\fR[=<\fION\fR|\fIOFF\fR>]
Do not use the TR-Log QSO sequence, but use
.BR + ,
.B Insert
and
.B Enter
to log the QSO.
.
.IP
The default mode of operation is the TR-Log sequence which uses
.B +
to
switch between CQ and S&P modes, in which
.B Enter
is the sole key used to call the other station, send the exchange, and log the
QSO.
.
.TP
\fBTLFCOLOR\fIn\fR=\fIFG\fR/\fIBG\fR
Defaults:
.RS 14
\fBTLFCOLOR1\fR=\fI23\fR (Header and footer)
.br
\fBTLFCOLOR2\fR=\fI67\fR (Pop up windows)
.br
\fBTLFCOLOR3\fR=\fI70\fR (Log window)
.br
\fBTLFCOLOR4\fR=\fI57\fR (Markers/dupe colour)
.br
\fBTLFCOLOR5\fR=\fI43\fR (Input fields)
.br
\fBTLFCOLOR6\fR=\fI63\fR (Window frames)
.RE
.
.IP
The numbers are given in octal, FG/BG or BG/FG (some experimentation likely
required).
.
.IP
You should only specify these if you wish to modify the standard colours of
@PACKAGE_NAME@.
.
In some Terminals you can set a special profile for @PACKAGE_NAME@ with your
own colours.
.
Another way is to define the colours via the
.I $HOME/.Xresources
file for
.B XTerm
and
.BR rxvt .
.
.IP
.BR Note :
A sample
.I @prefix@/share/doc/@PACKAGE@/Xresources
file has been provided that sets the colour scheme for
.B XTerm
and
.B rxvt
to the same colour pallet as the Linux console.
.
Most other terminals have their own way of setting the colour pallet.
.
.TP
\fBRXVT\fR[=<\fION\fR|\fIOFF\fR>]
Use \fBrxvt\fR's colours.
.
.TP
\fBEDITOR\fR=\fInano\fR | \fIvi\fR[\fIm\fR] | \fI<your_favorite_editor>\fR
Editor used to modify the QSO log or logcfg.dat.
.
The command specified receives the file name as an argument.
.
.IP
When using a GUI editor that runs in the background (such as gvim) make sure
to exit the editor before logging new stations.
.
Use the
.B :RES
command to rescore the log.
.
It is best to force such an editor to stay in the foreground (such as with
\(oqgvim -f\(cq).
.
.TP
\fBCALL\fR=\fIPA0R\fR
The station callsign used in messages; also used to determine the station's
country, zone and continent.
.
.TP
\fBOPERATING_MODE\fR=\fICQ\fR|\fIS&P\fR
Set operating mode for start up. Use \fICQ\fR for "run" and \fIS&P\fR for "search and pounce".
The default mode is \fICQ\fR.
.
.TP
\fBTIME_OFFSET\fR=\fI0\fR
Used to shift the @PACKAGE_NAME@ time with respect to the computer clock.
.
Normally 0.
.
.IP
Range: 0\(en23.
.
.TP
\fBTIME_MASTER\fR[=<\fION\fR|\fIOFF\fR>]
This node transmits the time over the network (only one master allowed!).
.
.TP
\fBADDNODE\fR=\fINode_address\fR[\fI:Port_number\fR]
Adds an IP address (and optionally a port number) to which we broadcast stuff.
.RB ( WARNING :
Only add addresses of other nodes).
.
.TP
\fBTHISNODE\fR=\fIA\fR
Node designator (default \(lqA\(rq).
.
If @PACKAGE_NAME@ hears its own node ID on the network it will exit and ask
you to pick another one!
.
.IP
Range: A\(enH.
.
.TP
\fBLAN_PORT\fR=\fIPortnumber\fR
Specifies on which port number (default \(lq6788\(rq) @PACKAGE_NAME@ is
listening for broadcasts from other instances.
.
.TP
.B LANDEBUG
Activates the debug function for recording @PACKAGE_NAME@ network traffic.
.
.IP
Dumps all @PACKAGE_NAME@ net traffic received on this node into a file named
.I debuglog
in the working directory.
.
This log can be used as a backup log for the whole network, as it is easy to
retrieve QSO data, cluster messages, gab messages etc. after the contest.
.
Some users have this enabled all the time.
.
.TP
.B SSBMODE
Start @PACKAGE_NAME@ in SSB mode (default is CW).
.
.TP
.B RTTYMODE
Start @PACKAGE_NAME@ in RTTY mode (default is CW)
.
.TP
\fBGMFSK\fR=\fI$HOME/gMFSK.log\fR
Tell \fBminiterm\fR(1) where to get the data.
.
.TP
\fBDIGIMODEM\fR=\fI$HOME/gmfsk_autofile\fR
Tell @PACKAGE_NAME@ where to send the macros.
.
.TP
\fBMARKERS\fR=\fIfile_name\fR
Generate marker file for
.IR Xplanet .
.
.IP
.I Xplanet
(a GUI program for the X Window System) will show the last 8 DX cluster spots
on an azimuthal map.
.
See the relevant Xplanet documentation.
.
.IP
Use azimuthal projection and center the map on your QTH (station location).
.
.TP
\fBBAND_\fINN\fR=\fIbottom,cw_end,ssb_start,top\fR
Define band edges. \fINN\fR is the band designator (wavelength), allowed values are:
160, 80, 60, 40, 30, 20, 17, 15, 12, 10.
.
.IP
All 4 comma separated parameters are mandatory and
shall be specified in integer Hz units with an optional
\fIk\fR suffix.
.IP
Example specification for Region\ 1 40\ m band:
.IP
    \fBBAND_40\fR = \fI7000k, 7040k, 7050k, 7200k\fR
.
.IP
Internal default band definitions are based on a superset of all Regions.
For example, 40\ m ends by default at 7300\ kHz.
In addition to configuring the legal limits
\fBBAND_\fINN\fR can also be used to fine tune actual band configurations
for a specific contest.
.
.SS Morse Code Keyer Commands
.
.TP
.B NETKEYER
Activates the CW keyer.
.
.IP
Only the IP networked keyer
.B cwdaemon
or any other program that emulates cwdaemon such as
.B winkeydaemon
is supported.
.
You may also need the keyer for PTT control or band info output.
.
.TP
\fBNETKEYERPORT\fR=\fIport_number\fR
Default port is 6789.
.
.TP
\fBNETKEYERHOST\fR=\fIhost_address\fR
Default host is 127.0.0.1 (localhost).
.
.TP
\fBHAMLIB_KEYER\fR
Activate CW keying via Hamlib.
.
.IP
.B Note:
The + and - macros to control speed from within messages are not yet supported.
.
.TP
\fBMFJ1278_KEYER\fR=\fIserial_port\fR
Activates support for the MFJ-1278B multi-mode controller.
.
.IP
The MFJ-1278 supports CW as well as RTTY contesting.
.
The serial port rate is fixed at 9600 bps.
.
.TP
\fBCWSPEED\fR=\fIspeed_in_WPM\fR
Set the initial CW (Morse Code) speed.
.
.IP
Can be changed with
.B PgUp
(increase), or
.B PgDn
(decrease) while sending CW messages or logging.
.
.IP
Range: 4\(en69.
.
.TP
\fBWEIGHT\fR=\fIweight_ratio\fR
Set the CW (Morse Code) dot to dash ratio.
.
.IP
Only for the
.IR NETKEYER .
.
.IP
Range: \-45\(en50.
.
.TP
\fBTXDELAY\fR=\fIPTT_delay_in_mS\fR
Delay activation of the Push To Talk pin.
.
.IP
Range: 0\(en50.
.
.TP
\fBKEYER_BACKSPACE\fR[=<\fION\fR|\fIOFF\fR>]
Support backspace key in keyer window.
.
.SS Sound Commands
.
.TP
\fBSOUNDCARD\fR[=<\fION\fR|\fIOFF\fR>]
Use soundcard for CW sidetone output.
.
.TP
\fBSIDETONE_VOLUME\fR=\fIsoundcard_volume\fR
Set soundcard sidetone volume (default is
.IR 70 ).
.
.IP
A value of
.I 0
turns off sidetone output (even for the console speaker).
.
.IP
Range: 0\(en99.
.
.TP
\fBCQDELAY\fR=\fIAuto_cq\fR
Set automatic CQ pause delay in 1/2 seconds increments between message
transmissions.
.
.IP
Range: 3\(en60.
.
.TP
\fBCWTONE\fR=\fIsidetone\fR
Set the PC speaker or soundcard frequency.
.
.IP
A value of
.I 0
switches the sidetone off.
.
.IP
Range: 0\(en999.
.
.IP
(Due to a bug in cwdaemon it also turns off the
.B Alt-T
tune function.
.
Use \fBSIDETONE_VOLUME\fR=\fI0\fR instead).
.
.TP
\fBVK_PLAY_COMMAND\fR=\fIcommand\fR
The command to play a voice keyer message file.
.
.IP 
It default to \(lqplay_vk $1\(rq, where \(lq$1\(rq will be replaced by the file
name to play.

.
.TP
\fBVK_RECORD_COMMAND\fR=\fIcommand\fR
Command to record voice keyer messages.
.
.IP
\(lqrec -r 8000 $1 -q\(rq is used by default. Again \(lq$1\(rq stands for the
file to write during recording.
.
.TP
\fBSOUNDLOG_PLAY_COMMAND\fR=\fIcommand\fR
Playback command for soundlog recordings (default is \(lqplay -q $1 2>
/dev/null\(rq):
.
.TP
\fBSOUNDLOG_RECORD_COMMAND\fR=\fIcommand\fR
Command to record contest audio stream. Runs out of the SOUNDLOG_DIRECTORY.
.
.IP
The script \(lqsoundlog\(rq which is part of TLF is used by default. See
:Sound for details.
.
.TP
\fBSOUNDLOG_DIRECTORY\fR=\fIdirectory\fR
The directory in which recorded contest sound files are stored (default
\(lq./soundlogs\(rq).
.
.SS Band Switching Commands
.
.TP
.B BANDOUTPUT
Outputs band information to pins 2, 7, 8, 9 on the parallel port.
.
.IP
Output is 1 (160m), 2 (80m) ... 9 (10m).
.
.IP
This format is compatible with the standard interface for antenna switches,
band filters etc.
.
.TP
\fBBANDOUTPUT\fR=\fI124181818\fR
Output pin 2 for 160, 30, 17 and 12, pin 7 for 80, pin 8 for 40, and pin 9
for 20, 15 and 10.
.
.IP
This comes in handy when you have 3 dipoles and a 3-band beam (...).
.
.TP
\fBNO_BANDSWITCH_ARROWKEYS\fR[=<\fION\fR|\fIOFF\fR>]
This will prevent unwanted band switching when you are not using rig control.
.
.IP
Band up =
.BR Alt-B ,
band down =
.B Alt-V
(TR-Log mode).
.
.SS DX Cluster Commands
.
.TP
\fBTELNETHOST\fR=\fIcluster_address\fR
Use Telnet to connect to a DX Cluster node using a DNS name or IP address,
such as claudia.esrac.ele.tue.nl or 131.155.192.179.
.
.TP
\fBTELNETPORT\fR=\fItelnet_port_of_cluster\fR
DX Clusters often use a non-standard port for Telnet, e.g. 8000.
.
.TP
\fBCLUSTERLOGIN\fR=\fIyourcall\fR
Automatic login for the telnet client.
.
.TP
\fBCLUSTER_LOG\fR[=<\fION\fR|\fIOFF\fR>]
Write clusterlog to disk.
.
.TP
\fBTNCPORT\fR=\fIserial_port\fR
You can use
.IR /dev/ttyS0 ,
.IR /dev/ttyUSB1 ,
etc. anything that looks like a tty.
.
.TP
\fBTNCSPEED\fR=\fIserial_rate\fR
@PACKAGE_NAME@ supports 1200, 2400, 4800 and 9600 bps.
.
.TP
.B FIFO_INTERFACE
The FIFO (First In First Out) interface is used when you want to receive
cluster info from the network, or from another source.
.
The FIFO interface uses a special FIFO file in the working directory called
.IR clfile .
.
Anything you dump into this FIFO will be displayed by the packet interface.
.
.SS Radio Control Commands
.
.TP
\fBRADIO_CONTROL\fR[=<\fION\fR|\fIOFF\fR>]
Switches the radio interface on.
.
The rig interface makes use of the
.B Hamlib
library which supports a number of different rigs.
.
.TP
\fBRIGMODEL\fR=\fIrig_number\fR
Look at the Hamlib documentation for the rig_number.
.IP
Hint:
.B rigctl\ \-l
and its manual page
.RB ( rigctl (1)).
.
.TP
\fBRIGSPEED\fR=\fIserial_rate\fR
Speed of the serial port for rig control.
.
.TP
\fBRIGPORT\fR=\fIserial_port\fR
You can use
.IR /dev/ttyS0 ,
.IR /dev/ttyUSB1 ,
etc. anything that looks like a tty.
.
.IP
For
.BR rigctld (8)
set
\fBRIGPORT\fR=\fIlocalhost\fR and \fBRIGMODEL\fR=\fI2\fR.
.
In this case
.B RIGSPEED
is ignored.
.
.TP
\fBRIGCONF\fR=\fIrig_configuration_parameters\fR
Send rig configuration parameters to Hamlib.
.br
e.g. \fBRIGCONF\fR=\fIcivaddr=0x40,retry=3,rig_pathname=/dev/ttyS0\fR
.
.TP
\fBRIT_CLEAR\fR[=<\fION\fR|\fIOFF\fR>]
Clears the RIT after logging the qso.
.
.IP
This only works if the rig, and the Hamlib routine supports it (tested on the
OMNI 6+).
.
.TP
.B RIGPTT
Declares that Hamlib CAT PTT capability should be checked at startup and if
available used to activate the radio's PTT for sending voice messages instead
of the \fBcwdaemon\fR PTT.
.
.TP
\fBCWBANDWIDTH\fR=\fIwidth\fR
Sets the CW bandwidth of your rig when changing bands.
.
.IP
If unset or
.I 0
the default bandwidth (as determined by Hamlib) is used. (a valid bandwidth for
the radio model must be used).
.
.TP
\fBDIGI_RIG_MODE\fR=\fImode\fR
If set along with \fBRADIO_CONTROL\fR option, specifies the mode to change the
radio to when
.B :DIG
mode is selected.
.
.IP
.I mode
may be one of \(lqUSB\(rq, \(lqLSB\(rq, \(lqRTTY\(rq, or \(lqRTTYR\(rq.
.
If this parameter is not set, \(lqUSB\(rq is used if the FLDIGI parameter is
set else \(lqLSB\(rq is used.
.
.SS User Interface Commands
.
.TP
.B CLUSTER
Show DX Cluster window at startup.
.
.TP
.B BANDMAP
Shows cluster bandmap on startup.
.
.IP
Use
.B .
(period) to change bandmap filtering.
.
.TP
\fBBANDMAP\fR=\fIxyz[,number]\fR
Show cluster bandmap on startup and set start values for filtering.
.
.IP
.RI  < xyz >
string parsed for:
.br
	\(lqB\(rq - show DX spots only on operating band
.br
	\(lqM\(rq - show DX spots only on operating mode
.br
	\(lqD\(rq - do not show dupes
.br
	\(lqS\(rq - skip dupes during grab_next
.RB ( Ctrl-G )
.br
	\(lqO\(rq - show only new multipliers
.br
	\(lqX\(rq - show also out-of-band spots when in all-band mode
.br
.RI < number >
lifetime for new spots in seconds (number >=
.IR 30 )
.
.TP
\fBSCOREWINDOW\fR[=<\fION\fR|\fIOFF\fR>]
Show the score window (same as \fBAlt-R\fR).
.
.TP
\fBCHECKWINDOW\fR[=<\fION\fR|\fIOFF\fR>]
Show the country/call check window.
.
.TP
\fBPARTIALS\fR[=<\fION\fR|\fIOFF\fR>]
Show a list of possible contest calls.
.
.IP
See
.B CALLMASTER
in the
.B RULES
section below for partials file specification.
.
.TP
\fBUSEPARTIALS\fR[=<\fION\fR|\fIOFF\fR>]
Use the auto-complete utility (takes some practice...).
.
.IP
@PACKAGE_NAME@ will complete the call as soon as it is unique in the database.
.
.IP
This can lead to strange effects, but in practice there are far more hits than
misses.
.
Sometimes you must edit the call because it has locked on a unique call.
.
Try it, and switch it off when you don't like it.
.
.TP
\fBLOGFREQUENCY\fR[=<\fION\fR|\fIOFF\fR>]
Put frequency (kHz) into QSO number to enable logging of frequency (only in
.B QSO
or
.B DXPED
modes).
.
.TP
\fBIGNOREDUPE\fR[=<\fION\fR|\fIOFF\fR>]
Enables logging multiple QSOs in a contest with the same station (considered a
good idea these days as contest bots that parse the submitted Cabrillo file
will determine such dupes (duplicate contacts)).
.
.TP
\fBSUNSPOTS\fR=\fISSN\fR
Set the
.I sunspots number
value which is used to do a rough calculation of the MUF (Maximum Usable
Frequency).
.
.IP
If the cluster interface is used the SSN will be updated by WWV or WCY
messages.
.
.\" FIXME: Describe how this relates to SUNSPOTS.
.TP
\fBSFI\fR=\fISolar_flux_value\fR
Set SFI used to calculate SSN.
.
.IP
The SSN value is used to do a rough calculation of the MUF.
.
If the packet interface is used the SSN will be updated by WWV or WCY
messages.
.
.TP
.B CHANGE_RST
If set in logcfg.dat,
.B PgUp
and
.B PgDown
will change sent/received RST instead of CW speed if you are in call/exchange
field and call field is not empty.

.IP
Default is these keys only change CW speed.
.
.TP
\fBCHANGE_RST\fR=\fI33, 43, 47, 499, ...\fR
Provide a comma separated list of RS(T) values which are used for the sent RST.
.
.IP
Received RST will always be 33\(en39, 43\(en49, or 53\(en59.
.
.IP
Providing a value for T is optional but will be ignored.
.
.IP
In CW and DIGI modes T will always be 9.
.
.TP
\fBNOB4\fR[=<\fION\fR|\fIOFF\fR>]
Do not send automatic \(lqQSO B4\(rq message.
.
.IP
Default is to send such messages.
.
.TP
\fBNOAUTOCQ\fR[=<\fION\fR|\fIOFF\fR>]
No automatic CQ when pressing
.B Enter
or
.BR F12 .
.
.IP
Default is that these keys will start an automatic CQ (see their descriptions
in the
.B KEYS
section above).
.
.TP
\fBESC_STOPS_TX_ONLY\fR[=<\fION\fR|\fIOFF\fR>]
Pressing ESC key does only stop sending CW or voice macros. No further action
is taken.
.
.TP
\fBSEND_DE\fR[=<\fION\fR|\fIOFF\fR>]
Sends a \(lqDE\(rq word before your callsign, as in \(lqDE W1AW\(rq.
.
.IP
There is a special case; if
.B SEND_DE
is present in
.IR logcfg.dat ,
and @PACKAGE_NAME@ if is in
.BR :DIG imode,
then the other station's callsign will be sent before \(lqDE\(rq, such as
\(lqDL1A DE W1AW\(rq.
.
.TP
.B RESEND_CALL=\fIFULL\fR | \fIPARTIAL\fR
Sends the full or partial callsign again at the end of the QSO
in RUN mode if the call of the other station was corrected.
In case of \fIFULL\fR the whole callsign will be sent again.
If the value is \fIPARTIAL\fR, then TLF figures out which part of callsign
has to be sent. Eg.: if the received call was
.B AB1CD,
but later it is corrected to
.B AB1CB,
then
.B CB
is sent.
.
.TP
\fBSHOW_TIME\fR[=<\fION\fR|\fIOFF\fR>]
Show last worked time instead of QSO number in the worked window.
.
.SH RULES
.
The contest rules can be put into separate files.
.
@PACKAGE_NAME@ will first look for a directory called
.I rules/
in the working directory, and a file named for the contest, for example,
.IR cqww .
.
If @PACKAGE_NAME@ cannot find such a file, it will look into the directory
.IR @prefix@/share/@PACKAGE@/rules .
.
A rules file contains contest specific parameters like multipliers, scoring
rules, CW and voice keyer messages, etc.
.
.P
.BR Note :
The rules file overrides settings from the
.I logcfg.dat
file!
.
.P
.B WARNING!
It is your own responsibility to try these rules well BEFORE the contest.
.
The authors of @PACKAGE_NAME@ cannot possibly check all rules for all
contests :) and during the contest there is normally no time to fix it.
.
Of course, Murphy's Law always applies!
.
These commands can generally appear in any order.
.
.SS RULES Configuration
.
General configuration options for the
.B RULES
file.
.
.TP
\fBCONTEST\fR=\fIxxxxx\fR
Name of the contest (same as the file name
.I contest_rules_filename
given to the
.B RULES
parameter referenced above in
.IR logcfg.dat ).
.
Some contests, like CQWW and WPX, are pre-programmed.
.
Look for the relevant rules file in
.IR @prefix@/share/@PACKAGE@/rules .
.
.TP
\fBLOGFILE\fR=\fIlog_file_name\fR
Mandatory!
.
.IP
By convention
.IR contest_rules_filename.log ,
but can be anything meaningful.
.
.TP
\fBCABRILLO\fR=\fIformat\fR
Specify the name of the Cabrillo QSO and QTC line format.
.
For most cases
.I UNIVERSAL
is a good choice.
.
For further Cabrillo related information see
.B CABRILLO CONFIGURATION
below.
.
.TP
\fBCONTEST_MODE\fR[=<\fION\fR|\fIOFF\fR>]
Sets @PACKAGE_NAME@ into contest mode.
.
.IP
Do not use this parameter for normal QSO logging!
.
.TP
.B SHORT_SERIAL
Uses short form for serial number (9=N, 0=T).
.
.TP
.B LONG_SERIAL
Uses long form for serial number (default).
.
.TP
\fBLEADING_ZEROS_SERIAL\fR[=<\fION\fR|\fIOFF\fR>]
Controls sending leading zeros in serial number. By default serial numbers
are sent with (up to 2) leading zeros.
.
.TP
\fBNO_RST\fR[=<\fION\fR|\fIOFF\fR>]
Do not use RST in contest, such as for CW Open, ARRL Sweepstakes, ARRL Field
Day, or various QSO parties and such events.
.
.IP
In such a case when writing a Cabrillo log format template you must provide a
conforming format definition without RST values.
.
.TP
\fBMIXED\fR[=<\fION\fR|\fIOFF\fR>]
Stations can be worked in any mode (CW, SSB and DIG) on a given band
without being counted as a DUPE.
.
.TP
.B SSBMODE
Start @PACKAGE_NAME@ in SSB mode.
.
.IP
If radio control is active, the radio will be placed in SSB mode, if not in
SSB mode already.
.
Normally @PACKAGE_NAME@ starts in CW mode and will set the radio to CW mode if
needed.
.
.IP
.BR Note :
At this time @PACKAGE_NAME@ does not follow mode changes on the radio.
.
When switching modes use the
.BR :CW ,
.BR :SSB ,
or
.BR :DIG
commands to set both @PACKAGE_NAME@ and the radio mode.
.
.TP
.B CQWW_M2
Put the node ID into the logline (just after the QSO number) to support
Multi/2 operation where the station logging the QSO must be in the Cabrillo
file.
.
This can also be used for M/1 and M/M, to enable post-contest analysis of the
nodes.
.
.TP
\fBFKEY-HEADER\fR=\fI"short description of your defined F-keys"\fR
The actual F-key assignments shown on the top of the main logging screen.
.
Maximum length is 59.
.
The default is:
\(lq1=CQ\ \ 2=DE\ \ 3=RST\ 4=73\ \ 5=HIS\ \ 6=MY\ \ 7=B4\ \ \ 8=AGN\ \ 9=?\(rq
.
.TP
\fBTUNE_SECONDS\fR=\fItuning-seconds\fR
Specify how many seconds you allow tune (Alt-T) remain active before
automatically terminating transmit.
.
.IP
Range: 1\(en100.
.
.IP
The default value is
.IR 6,
to maintain compatibility with previous TLF versions.
.
After 100 seconds, tuning will automatically be terminated, to allow your PA
(and perhaps you too ;-) ) to cool down a bit...
.
.TP
.B CALLMASTER\fR=\fIcallmaster\fR
Use a different file name as the callmaster database
(default is
.I callmaster
in the working directory).
.
.IP
Often downloaded as
.I MASTER.SCP
from the Supercheck Partials Web site.
.
See the
.B PARTIALS
and
.B USEPARTIALS
commands in the
.B User Interface Commands
section above and the
.B FILES
section below for obtaining Supercheck Partials updates.
.
.TP
\fBBMAUTOGRAB\fR[=<\fION\fR|\fIOFF\fR>]
If set along with the
.B RADIO_CONTROL
and
.B BANDMAP
(mandatory for this parameter) options, @PACKAGE_NAME@ will grab the callsign
from the bandmap, if the TRX (radio) frequency is equal with the displayed
bandmap frequency.
.
.\" FIXME: To what is the call added?
.TP
\fBBMAUTOADD\fR[=<\fION\fR|\fIOFF\fR>]
If set along with the
.B RADIO_CONTROL
and
.B BANDMAP
(mandatory for this parameter) options, @PACKAGE_NAME@ will add the callsign
from callsign field, if at least 3 characters have been entered.
.
.IP
Use \(lqS\(rqkip dupes in BANDMAP settings to control if it should also grab
dupes.
.
.TP
\fBSPRINTMODE\fR[=<\fION\fR|\fIOFF\fR>]
If set, @PACKAGE_NAME@ will automatically switch its mode between LOG and S&P
after every QSO.
.
.TP
.B FLDIGI
If you work RTTY (or any other digital modes), you can communicate with Fldigi
through
.BR XMLRPC .
.
This parameter activates the interface.
.
.IP
By default @PACKAGE_NAME@ connects to:
.
.IP
.UR http://localhost:7362/RPC2
http://localhost:7362/RPC2
.UE .
.
.IP
If you run Fldigi's XMLRPC server on an different port use
\fBFLDIGI\fR=\fIhttp://localhost:port_#/RPC2\fR
.
.TP
\fBMINITEST\fR[=\fINNN\fR]
Use this option when the contest is a minitest like contest.
.
.IP
In such contests the full contest interval is divided into shorter sections
(e.g. 6 * 10 minute sections in an hour).
.
Any station can be worked once in each of the time sections without counting
as a dupe.
.
The default length of the sections is 600 seconds (10 minutes), but you can
pass another value (in seconds) after the \(oq=\(cq sign.
.
.IP
There must be an integral number of time sections per hour!
.
.SS CW, Digimode and Voice Keyer Macros
.
The following parameters configure the CW, Digimode and voice mode keyer
message macros.
.
.TP
.B Macro characters in the message strings
.B %
= my call,
.B @
= his call,
.B #
= serial number,
.B [
= RST,
.B +
= increase cw speed,
.B \-
= decrease cw speed,
.B *
= AR,
.B =
= BT,
.B <
= SK,
.B (
= KN,
.B !
= SN,
.B &
= AS,
.B > 
= BK,
.B !
= his serial (e.g. confirm exchange of station in
.BR DIG imode),
.B |
= carriage return (only in digi mode messages).
.
.P
Be aware that unspecified digimode messages gets the value of their CW
counterpart prepended with '|'.
.
.TP
\fBF1\fR=\fI"cw message 1"\fR
CQ message, (e.g. CQ de PA0R TEST).
.
.TP
\fBF2\fR=\fI"cw message 2"\fR
S&P call message, (e.g. @ de %).
.
.TP
\fBF3\fR=\fI"cw message 3"\fR
Exchange message, (e.g. @ ++5NN--#).
.
.TP
\fBF4\fR=\fI"cw message 4"\fR
TU message, (e.g. TU 73 %).
.
.TP
\fBF5\fR=\fI"cw message 5"\fR
Call of the other station (e.g. @).
.
.TP
\fBF6\fR=\fI"cw message 6"\fR
Your call (e.g. %).
.
.TP
\fBF7\fR=\fI"cw message 7"\fR
QSO B4 message (e.g. @ sri qso b4 gl).
.
.TP
\fBF8\fR=\fI"cw message 8"\fR
Again message (e.g. AGN).
.
.TP
\fBF9\fR=\fI"cw message 9"\fR
Query message (e.g. ?).
.
.TP
\fBF10\fR=\fI"cw message 10"\fR
QRZ message (e.g. QRZ?).
.
.TP
\fBF11\fR=\fI"cw message 11"\fR
Please reply message (e.g. PSE K).
.
.TP
\fBF12\fR=\fI"cw message 12"\fR
Auto-CQ message (e.g. +++TEST %---).
.
.TP
\fBCQ_TU_MSG\fR=\fI"cw message 13"\fR
Auto Exchange message in CQ mode (TR-Log mode), (e.g. TU %).
.
.TP
\fBS&P_TU_MSG\fR=\fI"cw message 14"\fR
Auto Exchange message in S&P mode (TR-Log mode), (e.g. TU 5NN #).
.
.TP
\fBS&P_CALL_MSG\fR=\fI"cw message 25"\fR
Custom call message in S&P mode.
.
.IP
Allows replacing the auto-generated S&P call message.
.
.TP
\fBAlt_0\fR=\fI<...>\fR ... \fBAlt_9\fR=\fI<...>\fR
Up to 10 additional messages.
.
.TP
\fBVKM1\fR=\fIvoice message file name 1\fR ... \fBVKM12\fR=\fIvoice message file name 12\fR
Use F1 ... F12 keys to send recorded messages for phone.
.
.TP
\fBVKCQM\fR=\fIvoice_message_file_name\fR
Auto Exchange voice message in CQ mode (TR-Log mode)
.
.TP
\fBVKSPM\fR=\fIvoice_message_file_name\fR
Auto Exchange voice message in S&P mode (TR-Log mode)
.
.TP
\fBDKF1\fR=\fIdigi keyer message 1\fR ... \fBDKF12\fR=\fIdigi keyer message 12\fR
Use F1 ... F12 keys to send recorded messages for digital.
.
.TP
\fBDKCQM\fR=\fImessage\fR
Auto Exchange TU digi message in CQ mode (TR-Log mode)
.
.TP
\fBDKSPM\fR=\fImessage\fR
Auto Exchange TU digi message in S&P mode (TR-Log mode)
.
.TP
\fBDKSPC\fR=\fImessage\fR
Auto Exchange call digi message in S&P mode (TR-Log mode)
.
.SS Scoring
.
The following parameters configure @PACKAGE_NAME@'s scoring calculations.
.
.TP
.B ONE_POINT
One point per QSO (regardless of mode).
.
.TP
.B TWO_POINTS
Two points per QSO (regardless of mode).
.
.TP
.B THREE_POINTS
Three points per QSO (regardless of mode).
.
.TP
\fBCWPOINTS\fR=\fId\fR
Points per CW QSO.
.
.TP
\fBSSBPOINTS\fR=\fId\fR
Points per SSB QSO.
.
.IP
.BR Note :
SSBPOINTS and CWPOINTS need to be set for both to work!
.
.TP
\fBMY_COUNTRY_POINTS\fR=\fId\fR
Points for working your own DXCC entity (often zero (0)).
.
.TP
\fBMY_CONTINENT_POINTS\fR=\fId\fR
Points for working countries in your own continent.
.
.TP
\fBDX_POINTS\fR=\fId\fR
Points for working a station in other continents.
.
.TP
.B 2EU3DX_POINTS
Deprecated.
.
.IP
Use
.B MY_CONTINENT_POINTS
and
.B DX_POINTS
instead.
.
.TP
\fBCOUNTRY_LIST_POINTS\fR=\fId\fR
Points for countries in country list.
.
.TP
\fBUSE_COUNTRYLIST_ONLY\fR[=<\fION\fR|\fIOFF\fR>]
Score zero points for countries not in the list.
.
.TP
\fBCOUNTRYLIST\fR=\fI"comma separated list of prefixes"\fR
e.g. SM,LA,OZ,OH.
.
.TP
\fBCOUNTRYLIST\fR=\fIfile_name\fR
File with a list of prefixes.
It can contain multiple records (lines).
The one starting with the current contest name is selected.
E.g. Scandinavia:SM,LA,OZ,OH.
.
.IP
Not to be confused with so-called "country" files maintained by AD1C.
.
.TP
\fBPORTABLE_MULT_2\fR[=<\fION\fR|\fIOFF\fR>]
Multiply points x2 for portable stations (e.g. R1 field day).
.
.TP
\fBLOWBAND_DOUBLE\fR[=<\fION\fR|\fIOFF\fR>]
Double all points for lowband (40, 80, and 160m) QSOs (can be combined with
any other value).
.
.IP
(Will be deprecated in future! Use BANDWEIGHT_POINTS instead.)
.
.TP
\fBPOWERMULT\fR=\fIpower_multiplier\fR
Use this value to multiply the final points.

.IP
If the contest rule allows one to use the power multiplier (such as Stewperry,
ARRL-FD, various QSO parties), set it here.
.
.IP
.BR Note :
The value type of
.B POWERMULT
is a float, as in \fBPOWERMULT\fR=\fI1.5\fR, but the final score will be
rounded by the C library
.BR floor (3)
function, which gives the largest integer value that is not greater than
multiplied score.
.
.TP
\fBWYSIWYG_MULTIBAND\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is the multiplier, per band, whatever you enter.
.
.IP
@PACKAGE_NAME@ builds its own list of multipliers as QSOs are logged.
.
.TP
\fBWYSIWYG_ONCE\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is multiplier, whatever you enter.
.
.IP
Counts once per contest, not per band.
.
.TP
\fBWAZMULT\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is the CQ zone (per band).
.
.TP
\fBITUMULT\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is the ITU zone (per band).
.
.TP
\fBPFX_MULT\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is prefix (PA0, DA2, VE7, etc.).
.
.IP
Counts once per contest, not per band.
.
.\" FIXME: Reference CQ WPX handling elsewhere.  CQ-WW-WPX is confusing as it
.\" is not a parameter keyword and only appears here in the repository.
.TP
\fBPFX_MULT_MULTIBAND\fR[=<\fION\fR|\fIOFF\fR>]
Same as WPX, but the WPX only used CQ-WW-WPX, and there a single prefix
multiplier only once, not all band.
.
.IP
With this option, the PFX counts as multiplier on all band.
.
This usable in the All Asia DX contest (AA-DX).
.
.TP
\fBCOUNTRY_MULT\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is the DXCC entity (per band).
.
.IP
Relies on a so-called "country" file by AD1C.
.
An outdated version is supplied in
.IR @prefix@/share/@PACKAGE@/cty.dat .
.
See the
.B FILES
section below.
.
.TP
\fBMULT_LIST\fR=\fIfile_name\fR
Name of multipliers file (often sections, provinces, states, counties).
.
.IP
May contain comment lines starting with \(lq#\(rq in the first column.
.
Each multiplier resides on a single line by itself.
.
.IP
Starting from Tlf-1.4 aliases may be defined for the multipliers.
.
Define the aliases as:
.IP
    \fImultiplier:alias1,alias2,alias3\fR
.
.IP
If you log a QSO with one of the aliases it will be counted as the
multiplier.
.
You can have more than one line for the same multiplier.
.
.IP
This is useful for state QSO parties as an instate participant where instate
operators exchange county abbreviations rather than the state but the state
can only count once (Kansas QSO Party is once such example).
.
.TP
\fBSECTION_MULT\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is section from multipliers file.
.
.IP
Counts per band.
.
.TP
\fBSECTION_MULT_ONCE\fR[=<\fION\fR|\fIOFF\fR>]
Multiplier is section from multipliers file.
.
.IP
Counts once per contest, not per band.
.
.TP
\fBCONTINENTLIST\fR=\fI"comma separated list of continents"\fR
Valid values are: SA, NA, EU, AF, AS and OC.
.
.TP
\fBCONTINENT_LIST_POINTS\fR=\fId\fR
Points for stations from continents in CONTINENTLIST
.
.TP
.B USE_CONTINENTLIST_ONLY
Score zero points for station from continents not in the list.
.
.TP
.B BANDWEIGHT_POINTS
Define a point weighting factor for different bands.
.
.IP
For example, setting:
.
.IP
    \fBBANDWEIGHT_POINTS\fR=\fI160:3,80:2,40:1,20:1,15:1,10:2\fR
.
.IP
for use in the All Asia DX (AADX) contest will multiply all QSO points by 3 on
160m, by 2 on 80m and 10m and on all other bands only by 1.
.
.IP
Bands not in the list are weighted by 1.
.
.TP
.B BANDWEIGHT_MULTIS
Allow a weighting factor for multipliers on different bands.
.
.IP
For example, setting:
.
.IP
    \fBBANDWEIGHT_MULTIS\fR=\fI80:4,40:3,20:2,15:2,10:2\fR
.
.IP
for use in the Worked All Europe DX Contest (WAEDC) will multiply the number
of multipliers on 80 by 4, on 40 by 3 and on 20/15/10 by 2.
.
.IP
The multiplication is executed after any other multiplier calculation.
.
.IP
Bands not in list will be weighted by 1.
.
.TP
.B PFX_NUM_MULTIS
In WAEDC (and maybe with other contests too) the multipliers are the different
countries, but there are some exceptions where the prefix of certain countries
is a different multiplier.
.
.IP
In WAEDC these countries are: W, VE, VK, ZL, ZS, JA, PY, RA8/RA9 and RAØ.
.
With this option, you can define the country prefixes:
.
.IP
    \fBPFX_NUM_MULTIS\fR=\fIW,VE,VK,ZL,ZS,JA,PY,UA9\fR.
.
.IP
@PACKAGE_NAME@ will read this list, perform a lookup in a countrylist for a
country code, and that code will be used.
.
If you include the UA9 prefix and then make a QSO with a station from Asiatic
Russia, the PFX number will evaluated with a new multiplier, but European
Russia will not.
.
.TP
.B EXCLUDE_MULTILIST
Some contests have a special multipliers list, which is easier to write
by excluding a predefined set.
.
.IP
For example, the main set could be
.BR COUNTRY_MULT ,
and you need to exclude from that list just a few countries, (e.g. the SAC
contest excludes the Scandinavian countries as they are not multipliers).
.
In that case you can use this configuration:
.
.IP
    \fBCOUNTRY_MULT\fR
    \fBCOUNTRYLIST\fR=\fIJW,JX,LA,OF1,OF0,OJ1,OJ0,OX,OW,OZ,SM,TF\fR
    \fBEXCLUDE_MULTILIST\fR=\fICOUNTRYLIST\fR
.
.IP
Another useful example is the WAEDC RTTY contest where all stations can work
each other, however, for EU stations only the non-EU stations are the
multipliers, and the opposite for non-EU stations where only the EU stations
are the multipliers.
.
In that case the EU stations can use this configuration:
.
.IP
    \fBCONTINENTLIST\fR=\fIEU\fR
    \fBCOUNTRY_MULT\fR
    \fBEXCLUDE_MULTILIST\fR=\fICONTINENTLIST\fR
.
.IP
and all countries are multipliers, except for the EU stations.
.
.IP
Also, in this contest the non-EU stations can use this configuration:
.
.IP
    \fBCONTINENTLIST\fR=\fISA,NA,AF,AS,OC\fR
    \fBCOUNTRY_MULT\fR
    \fBEXCLUDE_MULTILIST\fR=\fICONTINENTLIST\fR
.
.IP
and all EU countries are multipliers and not those from the SA, NA, AF, OC and
AS continents, so only the EU stations remain as multipliers.
.
.TP
\fBUNIQUE_CALL_MULTI\fR=\fIALL\fR|\fIBAND\fR
Multiplier is the callsign.
.
.IP
The argument tells @PACKAGE_NAME@, how to score the callsigns as multipliers:
.br
.B ALL
means the callsign is a multiplier once per the contest, independent of band.
.br
.B BAND
means the callsign counts as a multiplier per band.
.
.TP
\fBGENERIC_MULT\fR=\fINONE\fR|\fIALL\fR|\fIBAND\fR
Use generic multiplier determined by the contest plugin.
.IP
The argument specifies the multiplier counting rule (see above).
Default value is NONE (disabled).
.
.TP
\fBPLUGIN_CONFIG\fR
Specifies the argument to the contest plugin's \fBinit\fR function.
See the
.B PYTHON PLUGIN
section below.
.
.SS Exchange
The following parameters configure @PACKAGE_NAME@'s handling of the exchange.
.
.TP
\fBSERIAL+SECTION\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is serial number and section, multiplier is section from multiplier
file.
.
.IP
Counts per band.
.
.TP
\fBSERIAL_OR_SECTION\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is serial number or section.
.
.IP
This option is similar to SERIAL+SECTION, except the exchange could be a
serial OR the section.
.
This option was introduced for HA-DX, where HA stations give the shortest form
of their county, other stations give serial.
.
.TP
\fBSERIAL+GRID4\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is serial number and grid (e.g. 001 JO21QI), multiplier is 4-character
grid (JO21).
.
.IP
Counts per band.
.
.TP
.B DX_&_SECTIONS
Multiplier is DXCC country or section from multiplier file.
.
.TP
.B RECALL_MULTS
Exchange can be recycled, will be filled into exchange field when it is known
(see also
.BR INITIAL_EXCHANGE ).
.
.TP
\fBINITIAL_EXCHANGE\fR=\fIexchanges.txt\fR
The file must contain a comma-separated list of exchanges.
.
.IP
If the exchange is the name of the operator, the file should contain lines
like:
.
.IP
    PA0R,rein
.br
    PG4I,joop
.br
    OK1RR,martin
.
.IP
If
.B RECALL_MULTS
is set, @PACKAGE_NAME@ will look in this list for the exchange and fill it in
for you.
.
There are various contests which have a standard exchange, such as the FOC
Marathon.
.
The module also recognises embedded calls (e.g. CT3/PA0R/QRP).
.
.TP
\fBCONTINENT_EXCHANGE\fR[=<\fION\fR|\fIOFF\fR>]
Exchange is a continent (NA, SA, EU, AS, AF, OC).
.
.TP
.B SERIAL_EXCHANGE
Exchange is a serial number (formats received exchange
and configures Cabrillo exchange).
Set this only if \fIboth\fR sent and received exchanges
are plain serial numbers.
.
.TP
.B MYQRA
For the \(lqStewperry\(rq contest, this option is used to set the QRA
(Maidenhead) locator, (e.g. JN97, or the full form: JN97OM).
.
.IP
In Stewperry, the points are calculated based on the distance between the
stations as calculated between this setting and the locator entered into the
exchange field.
.
.SS QTC
.
The following parameters configure @PACKAGE_NAME@ for the Worked All Europe DX
Contest (WAEDC) exchange of QTCs.
.
.TP
\fBQTC\fR=\fIdirection\fR
Send or receive QTCs in a contest (usually on WAEDC).
.
.IP
.I direction
is one of: RECV, SEND, BOTH
.
.IP
.BR Note :
Currently just the RECV direction is implemented.
.
For more information, please see the
.I @prefix@/share/doc/@PACKAGE@/Manual.md
file.
.
.TP
\fBQTC_CAP_CALLS\fR=\fIlist_of_qtc_capable_callsigns.txt\fR
Indicate that the station is QTC capable and highlight it in the bandmap or
worked window.
.
.IP
Put the callsigns of such stations in a file in the working directory, one
callsign per line, and give its name as an argument to this parameter.
.
.TP
\fBQTC_AUTO_FILLTIME\fR[=<\fION\fR|\fIOFF\fR>]
If you use the QTC feature and you are an EU station in CW or SSB modes, then
you can only RECEIVE the QTCs.
.
.IP
Most sending stations send their QTCs as a short form.
.
For example, after the first line the first two characters of time field are
not sent.
.
.IP
If you set this option, then when you fill the first QTC line, @PACKAGE_NAME@
will fill the other time fields, but only the first two characters.
.
If you change the hour (e.g. if there is a time of 2059 and the next one is
2100), then all next time fields will be changed.
.
.TP
\fBQTC_RECV_LAZY\fR[=<\fION\fR|\fIOFF\fR>]
If you use the QTC feature, and you are an EU station in CW or SSB modes, then
you can use this feature.
.
.IP
By default, @PACKAGE_NAME@ validates all received QTC lines (i.e. the time
field must be four characters long; callsign and serial fields must not be
empty).
.
.IP
If you set this parameter, @PACKAGE_NAME@ will not perform validation.
.
.
.SH CABRILLO CONFIGURATION
.
This section covers the configuration of Cabrillo processing.
.
.P
The fields of the generated Cabrillo file can be either
.RS 2
.IP \(bu 2
set to a fixed value,
.IP \(bu
input interactively,
.IP \(bu
or disabled.
.
.P
.BR Note :
A
.I template
file defines the values used in the headers of the Cabrillo file.
.
A
.I format
file defines the fields of the QSO lines in the Cabrillo file.
.
.SS Using a Cabrillo template
.
A Cabrillo template is used to provide station specific values that will be
placed into the generated Cabrillo file.
.
@PACKAGE_NAME@ will not prompt for values listed in this file when the
.B :WRI
command is issued.
.
.P
.BR Note :
The template keywords are the same as the parameters below with the
.B CABRILLO\-
prefix omitted.
.
Cabrillo keyword definitions can be found at the
.UR https://wwrof.org/cabrillo/
World Wide Operators Foundation
.UE
Cabrillo specification page.
.
.TP
\fBCABRILLO\-TEMPLATE\fR=\fIfile.cbr\fR
The specified file is parsed and the values from relevant lines are taken the
same way as if they were added via a config file.
.
.IP
The header, footer, comment and QSO lines are ignored.
.
.IP
One can, for example, re-use a file from a previous contest or use a sample
file provided for the contest.
.
Another possibility is to summarize the station-specific values in a
.I station.cbr
file (see as an example
.IR @prefix@/share/doc/@PACKAGE@/station-sample.cbr ).
.
As multiple
.B CABRILLO\-TEMPLATE
parameters can be specified, it allows for separating the contest and station
specific parts.
.
.IP
This is an optional configuration as the same effect can be reached
by plain configs (via the
.I logcfg.dat
and
.I rules
files).
.
.IP
.BR Note :
The
.B CABRILLO\-
prefix is required in the config files.
.
.SS Internal configuration
.
Following parameters control the generation of QSO lines.
.
.TP
\fBCABRILLO\-EXCHANGE\fR=\fIformat\fR
.
Specifies the sent exchange format.
.
.IP
The hash mark (\(lq#\(rq) stands for QSO serial number.
.
For a contest using a fixed exchange enter the value here (limited to 39
characters).

.TP
\fBCABRILLO\fR=\fIformat\fR
.TQ
\fBCABRILLO\-QSO\-FORMAT\fR=\fIformat\fR
Set the format of QSO and QTC lines including the separator character for the
received exchange.
.
.IP
The format descriptions are contained in
.I cabrillo.fmt
either in the current directory or in
.IR @prefix@/share/@PACKAGE@ .
.
The specified format file is used both to generate Cabrillo output and also
for Cabrillo import.
.
For technical details see
.IR @prefix@/share/doc/@PACKAGE@/Manual.md .
.
.IP
A
.I cabrillo.fmt
format file is used to generate a Cabrillo file when a predefined format in
.I @prefix@/share/@PACKAGE@/cabrillo.fmt
does not exist.
.
For many events the
.B UNIVERSAL
format is adequate, otherwise you'll need to roll your own based on the log
submission rules of the contest organizers.
.
.
.SS Configuring header information
.
Cabrillo header fields can be set using the keywords listed below.
.
The value assigned to the keyword controls the processing of the field:
.RS 2
.IP \(bu 2
value not in parentheses, e.g. \(lq9ACW\(rq taken verbatim,
.
.IP \(bu
value in parentheses, e.g. \(lq(YES,NO)\(rq will be asked interactively, with
the provided text as hint
.
.IP \(bu
a single dash \(rq\-\(lq value disables the field (neither asked nor output)
keeping its value,
.
.IP \(bu
no value (i.e. a keyword without equal sign) just enables the field without
changing its value.
.RE
.
.P
.BR Note :
The order of the headers in the Cabrillo file is fixed and independent of the
order they are present in a config or template file.
.
.SS Header Keywords
.
.BR Note :
These keywords and the internal ones can also be used in a Cabrillo template
just by removing the
.I CABRILLO\-
prefix and using \(rq:\(lq as value separator.
.
.TP
.B CABRILLO\-CONTEST
.TQ
.B CABRILLO\-CATEGORY\-ASSISTED
.TQ
.B CABRILLO\-CATEGORY\-BAND
.TQ
.B CABRILLO\-CATEGORY\-MODE
.TQ
.B CABRILLO\-CATEGORY\-OPERATOR
.TQ
.B CABRILLO\-CATEGORY\-POWER
.TQ
.B CABRILLO\-CATEGORY\-STATION
.TQ
.B CABRILLO\-CATEGORY\-TIME
.TQ
.B CABRILLO\-CATEGORY\-TRANSMITTER
.TQ
.B CABRILLO\-CATEGORY\-OVERLAY
.TQ
.B CABRILLO\-CERTIFICATE
.TQ
.B CABRILLO\-CLAIMED\-SCORE
(Score value is replaced with the calculated score.
It can be disabled but not set.)
.TQ
.B CABRILLO\-CLUB
.TQ
.B CABRILLO\-LOCATION
(Locator automatically filled, if enabled and \fBMYQRA\fR is set.)
.TQ
.B CABRILLO\-GRID\-LOCATOR
.TQ
.B CABRILLO\-NAME
.TQ
.B CABRILLO\-EMAIL
.TQ
.B CABRILLO\-ADDRESS
(3 generic address lines available)
.TQ
.B CABRILLO\-ADDRESS(2)
.TQ
.B CABRILLO\-ADDRESS(3)
.TQ
.B CABRILLO\-ADDRESS\-CITY
.TQ
.B CABRILLO\-ADDRESS\-STATE\-PROVINCE
.TQ
.B CABRILLO\-ADDRESS\-POSTALCODE
.TQ
.B CABRILLO\-ADDRESS\-COUNTRY
.TQ
.B CABRILLO\-OPERATORS
.TQ
.B CABRILLO\-OFFTIME
.TQ
.B CABRILLO\-SOAPBOX
(3 soapbox lines available)
.TQ
.B CABRILLO\-SOAPBOX(2)
.TQ
.B CABRILLO\-SOAPBOX(3)
.
.SH PYTHON PLUGIN
.
@PACKAGE_NAME@ uses Python plugins to customize or extend functions beyond
the built-in features. Two notable use cases are adding a specific
scoring logic and determining multipliers.
.P
.
The Python plugin file is loaded the same way as the RULES
file but the file must have \fIpy\fR extension.
.
.
.SS tlf Python module
.
@PACKAGE_NAME@ core functionality and constants can be accessed via
the pre-imported \fItlf\fR module.
.
.TP
.B Constants
.TQ
  \fBCWMODE\fR: \fIint\fR
.TQ
  \fBSSBMODE\fR: \fIint\fR
.TQ
  \fBDIGIMODE\fR: \fIint\fR
.TQ
  \fBMY_CALL\fR: \fIstr\fR
.TQ
  \fBMY_LAT\fR: \fIfloat\fR
.TQ
  \fBMY_LONG\fR: \fIfloat\fR
.
.P
.TP
.B Functions
.TQ
  \fBdef get_qrb_for_locator(locator: str) -> Qrb:\fR
Returns the distance (in km) and bearing (in degrees)
to the specified locator from the current location.
.TQ
  \fBdef get_dxcc(call: str) -> Dxcc:\fR
Returns the DXCC information for the given call using the \fIcty.dat\fR file.
.
.SS Data structures
.
.TP 20
.B Qso
.TQ
  \fBcall\fR: \fIstr\fR
callsign
.TQ
  \fBexchange\fR: \fIstr\fR
received exchange
.TQ
  \fBband\fR: \fIint\fR
band in meters
.TQ
  \fBmode\fR: \fIint\fR
one of \fItlf.CWMODE\fR, \fItlf.SSBMODE\fR or \fItlf.DIGIMODE\fR
.TQ
  \fButc\fR: \fIint\fR
time in integer seconds since epoch
.TP 20
.B Qrb
.TQ
  \fBdistance\fR: \fIfloat\fR
distance in km
.TQ
  \fBbearing\fR: \fIfloat\fR
bearing in degrees
.TP 20
.B Dxcc
.TQ
  \fBcountry_name\fR: \fIstr\fR
.TQ
  \fBmain_prefix\fR: \fIstr\fR
.TQ
  \fBmain_cq_zone\fR: \fIint\fR
.TQ
  \fBmain_itu_zone\fR: \fIint\fR
.TQ
  \fBmain_latitude\fR: \fIfloat\fR
.TQ
  \fBmain_longitude\fR: \fIfloat\fR
.TQ
  \fBmain_continent\fR: \fIstr\fR
.TQ
  \fBmain_timezone\fR: \fIfloat\fR
.TQ
  \fBstarred\fR: \fIbool\fR
.TQ
  \fBprefix\fR: \fIstr\fR
.TQ
  \fBcq_zone\fR: \fIint\fR
.TQ
  \fBitu_zone\fR: \fIint\fR
.TQ
  \fBlatitude\fR: \fIfloat\fR
.TQ
  \fBlongitude\fR: \fIfloat\fR
.TQ
  \fBcontinent\fR: \fIstr\fR
.TQ
  \fBtimezone\fR: \fIfloat\fR
.TQ
  \fBexact\fR: \fIbool\fR
.
.SS Functions
.
All plugin functions are optional.
.
.TP
\fBdef init(cfg: str) -> str:\fR
.
Called once on @PACKAGE_NAME@ start up. It shall initialize the internal
state of the plugin.
.
.IP
The parameter \fIcfg\fR contains the value provided to
PLUGIN_CONFIG. It can be used to control the internal
logic of the plugin. If no PLUGIN_CONFIG is specified then
an empty string is passed.
.
.IP
The return value is a string specifying the minimal required
@PACKAGE_NAME@ version (e.g. '1.5'). In case of no version dependency
\fINone\fR shall be returned.
.
.TP
\fBdef setup() -> None:\fR
.
Called whenever the QSO list is initialized (e.g. on inital loading of
the log file or before rescoring it). It shall reset any internal
structures related to QSOs.
.
.TP
\fBdef score(qso: Qso) -> int:\fR
.
Called before actually logging a QSO.
It shall return a non-negative score value.
.
.TP
\fBdef check_exchange(qso: Qso) -> Dict[str, str]:\fR
.
Called when exchange is received or updated.
From the returned dictionary these (optional) entries are evaluated:
.TQ
          \fBmult1_value\fR: \fIstr\fR
.
.TQ
          \fBnormalized_exchange\fR: \fIstr\fR
.
.IP
\fBmult1_value\fR is used as a multiplier without further conversion.
The handling of this multiplier is controlled by the GENERIC_MULT
parameter.
.IP
\fBnormalized_exchange\fR replaces the received exchange
in the finally logged QSO.
.
.SH FILES
.
.I @prefix@/share/@PACKAGE@/logcfg.dat
is a recent example of a generic configuration file.
.
@PACKAGE_NAME@ will copy it into the current working directory if it does not
find one there.
.
It is recommended to
.B copy it into the working directory
and edit it to match the contest.
.
.P
It contains, amongst other settings, the name if the rules file, your call,
info about ports for CW keying, packet or rig control, etc. related to your
station.
.
You should test your settings well
.I before
the contest!
.
.P
.I @prefix@/share/@PACKAGE@/rules/contestname
contains the rules of the
various contests.
.
You can easily write one for your favourite contest making
use of the various multiplier and points capabilities.
.
Test it before the
contest and send a message to
.MT tlf-devel@nongnu.org
the @PACKAGE_NAME@ development list
.ME
if anything is wrong (or right!).
.
.P
It contains name of the log file, contest rules, points, multipliers, and
other parameters related to the contest,
.
.P
.I @prefix@/share/@PACKAGE@/cty.dat
contains a flat ASCII database of info about countries.
.
.P
This is the same file as used by
.I CT
or
.IR TR-Log .
.
Updated versions from Jim, AD1C, are available from:
.UR http://www.country-files.com/
Country Files
.UE .
.
.P
@PACKAGE_NAME@ looks for this file first in the current working directory,
so an update is possible without root rights to replace the package installed
version (likely well out of date).
.
.P
\fI@prefix@/share/@PACKAGE@/callmaster\fR contains a flat ASCII database of
known contest callsigns.
.
.P
Updates are available from
.UR http://www.supercheckpartial.com/
Super Check Partial
.UE .
.
Save the
.I master.scp
file as
.I callmaster
in the working directory (or use \fBCALLMASTER\fR=\fImaster.scp\fR to use
the default file name).
.
It will take precedence over the system installed
.I callmaster
file which is likely well out of date.
.
.P
.I Section files
contain a flat ASCII database of multipliers like states, sections, provinces,
districts, names, ages, etc.
.
They are used by including \fBMULT_LIST\fR=\fIsection_file_name\fR in the rules file.
.
.P
Some of these files are supplied by @PACKAGE_NAME@ while others will need to
be written by you.
.
Please offer your files to the developers for inclusion in the distribution or
placed on the Wiki (see below).
.
.SH DOCUMENTATION
.
The documentation page at
.UR https://tlf.github.io/
GitHub
.UE
contains some more information.
.
.P
An FAQ and other useful tips are installed
.IR @prefix@/share/doc/@PACKAGE@ .
.
.P
The
.UR https://github.com/Tlf/tlf/wiki
project Wiki
.UE
will host various contest specific information and files.
.
.
.SH BUGS
Please send bug reports to
.MT tlf-devel@nongnu.org
the @PACKAGE_NAME@ development list
.ME .
.
.
.SH AUTHORS
.B @PACKAGE_NAME@
was originally written by
.MT "pa0r at eudxf.org"
Rein Couperus
.ME
aka
.MT "rein at couperus.com"
Rein Couperus
.ME
and is maintained from 2009 onward by
.MT "tb at forth-ev.de"
Thomas Beierlein
.ME .
.
.P
A lot of valuable contributions have been received from PG4I (Joop PA4TU),
PA3FWM, LZ3NY, VA3DB, OM4AA, OK1RR, DH5FS, G4KNO and various other
contributors.
.
(See the AUTHORS file for more).
.
Thanks to all for improving @PACKAGE_NAME@!
.
.P
Beta testers and feedback are always welcome!