$Id: README 2421 2007-04-13 00:20:26Z flaterco $


Intro
-----

tideEditor is an editor for Tide Constituent Database (TCD) files.  It
was originally written by Jan C. Depner but is now maintained by David
Flater.

The tideEditor distribution is available from
http://www.flaterco.com/xtide/files.html.

tideEditor is covered by the GNU General Public License.


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

libtcd 2.2 or compatible newer version.  libtcd is available from
http://www.flaterco.com/xtide/files.html#libtcd.

Qt 3.x.  The free edition of Qt is included in some Linux
distributions and is available from http://www.trolltech.com/.

tideEditor is expressly NOT tested or supported with Qt 4.x at this
time.


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

The normal route:

    bash-3.1$ ./configure
    bash-3.1$ make
    bash-3.1$ su
    bash-3.1# make install

tideEditor is packaged with the popular and portable GNU automake, so
all usual GNU tricks should work.  Help on configuration options can
be found in the INSTALL file or obtained by entering ./configure
--help.

An optional icon (icon-64x64.png) is included in the tarball for use
with desktop environments.


Usage
-----

nameless> tideEditor harmonics.tcd [Qt switches...]

If you have set up the World Vector Shoreline files 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).

A tutorial on the minimum steps necessary to add a subordinate station
is available at http://www.flaterco.com/xtide/harmonics.html.


Crashes
-------

If tideEditor crashes, you will be left with two files.
  harmonics.tcd            The one you've been editing
  harmonics.tcd.running    A copy of what you started with

The .running file works like a file lock.  tideEditor will refuse to
open harmonics.tcd in read-write mode unless you do something about
the .running file.

You have two options:

1.  Delete harmonics.tcd.running (or move it out of the way) and
retain what changes you made in harmonics.tcd.

2.  Replace harmonics.tcd with harmonics.tcd.running, which reverts
your edits.


See also
--------

TCD documentation:
http://www.flaterco.com/xtide/libtcd.html

tcd-utils, available from
http://www.flaterco.com/xtide/files.html#extras


Bugs
----

1.  The window containing the location list is too big.

2.  If the location list is closed from the window manager, tideEditor
doesn't notice and crashes the next time it tries to update it.

3.  Buffer overflows, memory leaks, general lack of robustness.


Non-bugs
--------

When viewing old TCD files, might see:

QComboBox::setCurrentItem: (unnamed) Index 511 out of range

This message occurs when the TCD file contains an out of range value
in the country field or another, similar field.  Old versions of
libtcd allowed someone to initialize the field to -1, which is
unfortunate since the field is unsigned.  Qt correctly traps the error
and resets the value to 0, and no harmful consequences result.
