$Id: README.txt,v 1.9 2003/04/03 15:11:01 flaterco Exp $


Preface
-------

IMPORTANT

Incompatible changes occurred on 2003-03-18, and again on 2003-03-27.

- The order of arguments to build_tide_db changed.
- The encoding of slack offsets changed.
- "Simplified" offset records were abolished.

See changelog below for more information.


Intro
-----

TCD Utils includes:

 * build_tide_db to convert harmonics.txt, offsets.xml, and NAVO
   formats to harmonics.tcd;

 * restore_tide_db to generate harmonics.txt and offsets.xml from
   harmonics.tcd;

 * tideEditor to edit harmonics.tcd directly.

These programs were written by Jan C. Depner.

build_tide_db and restore_tide_db are unclassified, distribution
unlimited, public domain.  They are distributed in the hope that they
will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

tideEditor is covered by the GNU General Public License.


Requirements
------------

All three utilities require libtcd, which is included with XTide.

tideEditor furthermore requires Qt 3.0.5 or compatible version.


Installation
------------

This distribution and the XTide distribution are available from
http://www.flaterco.com/xtide/files.html.

You need to have compiled libtcd.a, which is bundled in the libtcd
subdirectory of the XTide distribution.  There is a standalone
makefile in the libtcd subdirectory so that you need not compile XTide
if you don't want to.

In tcd-utils, edit the Makefile to point to your libtcd:
  # Change this!
  LIBTCD_DIR = ../xtide/libtcd

If you are compiling tideEditor, you need to have installed Qt 3.0.5
or a compatible version.  The free edition of Qt is included in some
Linux distributions and is available from http://www.trolltech.com/.

If you did not set QTDIR to the location of your Qt installation
already, then uncomment the relevant line of the Makefile and set it
there.

CC and CXX are supposed to point to your C and C++ compilers.  Set
these too if you have to.

Now type either
  'make' to make all three utilities, or
  'make some' to make only the converters.


Converter Usage
---------------

NOTE:  The order of arguments to build_tide_db changed 2003-03-18.

nameless> ./build_tide_db harmonics.tcd harmonics.txt offsets.xml
[... diagnostics ...]
7124 records written

nameless> ./restore_tide_db harmonics.tcd restored
nameless> ls restored*
restored.txt  restored.xml


Editor Usage
------------

nameless> export HFILE_PATH=harmonics.tcd
nameless> ./tideEditor

If you have set up the World Vector Shoreline files and the WVS_DIR
environment variable as described at
http://www.flaterco.com/xtide/installation.html#WVS you will get a map
of the world with tide stations shown as dots.  Otherwise, you will
just get dots.

Left click zooms in on the map.  Middle click retrieves a station for
modification or deletion.  Right click creates a new station.  Cursor
keys will move you around and there's a button in the toolbar to zoom
back out.

There is some on-line help ("What's This?" button).

Sorry, that's all the documentation we have at the moment.


See also
--------

PDF documentation for libtcd and the TCD format:  Jan Depner, "Format
for the Oceanographic and Atmospheric Master Library (OAML) Tide
Constituent Database", available from
http://www.flaterco.com/xtide/files.html.


Changelog
---------

For tideEditor history, see version.h.

2003-04-03
David Flater

    Incorporated changes from Jan Depner to fix fandango on core and
    broken country parsing that occurred when processing NAVO files
    with build_tide_db.

2003-03-27
David Flater

    Abolished "simplified" type 2 records.  See
    http://www.flaterco.com/xtide/tcd_notes.html

2003-03-19
David Flater

    Fixed buffer overflow in build_tide_db.c that was causing
    "Missing country [nothing]" messages on some platforms.

    Realized that version.h is only used for tideEditor and has
    nothing to do with build_tide_db or restore_tide_db.  Moved
    changelog for everything else into README.txt.

2003-03-18
David Flater / August Hahn

    Incorporated patches from August Hahn:

    - complain about but make do with subordinate station fields with
    missing units (ugh).

    - modified build_tide_db.c to:

      1) process multiple files in one pass.  I changed the order of
      the arguments to the tool, so watch out for this.

      2) try to locate the country code for each station.  This
      handles the various states into the United States, as well as
      several other locations that don't quite fall right.

      3) flag countries that are missing but take no action for now
      since the country locating is not perfect yet.

    Problems with units in subordinate stations are now flagged better.

    Fixed bug where stations having slack offsets were incorrectly
    "simplified."

    Fixed bug where slack offsets of zero were equated to omitted slack
    offsets.  Omitted slack offsets are now represented with the value
    NULLSLACKOFFSET defined in libtcd/tcd.h.


--
DWF, 2003-03-18
