hlog - A simple, ncurses-based amateur radio contact logger.

The main features are:

 - purely keyboard-based entry based on short commands (instead of
   navigating between fields)
 - uses a simple text-based storage (one file per log entry)
 - automatic continent, DXCC, ITU zone, and CQ zone lookup


Dependencies
============

To build hlog you must have:

  - gcc/clang or other C99 compiler with compatible arguments
  - libjeffpc (http://hg.31bits.net/libjeffpc/)
  - lua 5.3
  - gpsd 3.20
  - hamlib 3.3 or 4.3

To build HTML docs (optional), you need to have:

  - markdown or discount


Building and Installing
=======================

$ cmake . -DCMAKE_INSTALL_PREFIX=/prefix
$ make
$ make install

This will install the binaries under the specified prefix.

Note: If libjeffpc is not installed in a location that's part of the
compiler and linker search path, you'll have to give cmake a hint where to
find it.  You do this by defining these as necessary:

  - WITH_JEFFPC_LIB=x      - directory containing libjeffpc.so
  - WITH_JEFFPC_INCLUDES=x - directory containing jeffpc/jeffpc.h
  - WITH_JEFFPC=x          - same as setting WITH_JEFFPC_LIB=x/lib and
                             WITH_JEFFPC_INCLUDES=x/include

For example:

$ cmake . -DWITH_JEFFPC=/opt/jeffpc <...other cmake args...>


Running
=======

$ ./hlog <path to data directory>

The data directory must contain the following:

 - 'data' subdirectory
   - 'cty.csv' the country data
 - 'qso' subdirectory
 - 'tmp' subdirectory
 - 'config.lua' file


Configuration
=============

The config file (config.lua in the data directory) is a Lua script that
must evaluate to a table with default values and other knobs that affect
behavior.

You can use the included init-data.sh script to generate a sample data
directory.

The possible config table keys are:

 fill_template      - function to set QSO field defaults
 qsoline            - array of tokens to use for qso-line

QSO Line
--------

Logged QSOs are summarized as one line of text.  For example:

2020-11-07 13:49 W1ABC      14.2755    SSB    59  54    80W FN43

The exact information displayed is configurable via the qso-line config file
statement.  The qso-line statement includes a list of tokens representing
the various parts of the QSO entry.

The default value for qso-line is:

 qsoline = {
        "date", "time-hm", "station-call", "freq-mhz", "mode", "rsts",
        "rstr", "tx-power", "grid"
 }

The possible tokens are (width in parentheses):

 band            - band name (5)
 county          - the contacted station's county name (10)
 date            - the start date of the QSO (10)
 freq-mhz        - the frequency in MHz (10)
 grid            - 8-character "dx" grid (8)
 grid4           - 4-character "dx" grid (4)
 grid6           - 6-character "dx" grid (6)
 grid8           - convenience alias for 'grid' (8)
 mode            - the mode (6)
 rstr            - the received RST (3)
 rsts            - the sent RST (3)
 seqr            - the received contest serial (4)
 seqs            - the sent contest serial (4)
 station-call    - the contacted station's callsign (10)
 time-hm         - the start time of the QSO in HH:MM format (5)
 time-hms        - the start time of the QSO in HH:MM:SS format (8)
 tx-power        - the local station's TX power (5)
 de-op-call      - the local station's operator's callsign (10)


Interactive Commands
====================

Everything within hlog is controlled via simple case-insensitive text
commands.  In general, the commands fall into three categories:

 - contact management
 - local station information setting
 - contacted station information setting

The contact management commands start/end a contact.

The commands are:

 new              - start a new contact (saving the previous one), clears
                    everything except local station's call, grid square, and
                    power
 reset            - start a new contact (NOT saving the previous one),
                    clears everything except local station's call, grid
                    square, and power
 save             - save the contact, but continue editing it
 edit <uuid>      - load previously saved contact for viewing or editing
 tab new          - create a new tab
 tab close        - close the current tab
 tab <num>        - switch to the specified tab
 qrz              - open a new Firefox tab with contact's call on qrz.com
 ae7q             - open a new Firefox tab with contact's call on ae7q.com

The local station information commands allow the user to modify the
callsign, location, and power of the local station.  They all start with the
letter 'd' (as in "de").

The commands are:

 de <callsign>    - set local station & operator callsign (e.g., AC1JR)
 dg <grid>        - set local station's Maidenhead grid square (e.g., FN42)
 dpwr <watts>     - set local station's transmit power in Watts (e.g., 80)

Finally, the contacted station information commands allow the user to set
the fields associated with the other station.

The commands are:

 start now        - set the start date and time to the current time
 start <datetime> - set the start date and/or time
 startend now     - set the start & end date and time to the current time
 startend <datetime>
                  - set the start & end date and/or time
 end now          - set the end date and time to the current time
 end <datetime>   - set the end date and/or time
 pwr <watts>      - set contacted station's transmit power (e.g., 200)
 c <callsign>     - set contacted station's callsign (e.g., VO2MPR)
 f <MHz>          - set frequency (e.g., 14.2755)
 m <mode>         - set mode (e.g., SSB)
 rs <rst>         - set sent RST (e.g., 59)
 rr <rst>         - set received RST (e.g., 55)
 nm <name>        - set contacted station operator's name (e.g., Dave)
 qth <string>     - set contacted station's location (e.g., Point Armour)
 g <grid>         - set contacted station's Maidenhead grid square (e.g., GO11)
 country <country>- set contacted station's country (e.g., Canada)
 st <state>       - set contacted station's State/Province/etc. (e.g., NL)
 county <county>  - set contacted station's county
 cont <2 chars>   - set contacted station's continent
 dxcc <prefix>    - set contacted station's DXCC prefix
 itu <zone>       - set contacted station's ITU zone
 cqz <zone>       - set contacted station's CQ zone
 pota <refs>      - set contacted station's POTA references (comma separated)
 sota <refs>      - set contacted station's SOTA references (comma separated)
 wwff <refs>      - set contacted station's WWFF references (comma separated)
 cm <string>      - set (short) comment for this QSO
 seqs <num>       - set sent contest serial (e.g., 123)
 seqr <num>       - set received contest serial (e.g., 456)
 section <name>   - set received section abbreviation (e.g., EMA)

In general, the more common commands try to be short, so one is not forced
to type long strings in the middle of a contact.  As a result, many commands
are only one or two characters long.  While many of the commands are
intuitive, in most cases the field label underlines the characters of the
label that make up the command.

The "underline hint" exceptions are the local station commands, all of which
are prefixed with the letter 'd' (as in "de").  Note however, that the "set
local station's callsign" is "de" and not "dde".

For example, to set the contacted station's callsign (which is displayed
after the "Call:" label - with the letter C underlined), one would use the
'c' command followed by the other station's callsign.  For example:

 > c VO2MPR

This will populate the call field, look up the continent, DXCC prefix, 
the ITU and CQ zones, as well as calculate the distance and direction to the
contacted station based on the country data.


Limitations
===========

hlog assumes the following:

 - the rx and tx frequencies are the same
 - the local station callsign is the same as the local station operator's
   callsign
 - the remote station callsign is the same as the remote station operator's
   callsign

hlog also has the following shortcomings:

 - there is no way to display the contact end date even though it may be
   different from the start date
 - the distance calculation assume a spherical Earth with 6378.137 km radius
 - setting the contest sequence to 0 clears the field instead of using 0 as
   the value