$Id: README 4046 2011-09-07 21:43:34Z flaterco $


    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.


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 4.7 or compatible newer version.  The free edition of Qt is included in
some Linux distributions and is available from http://qt.nokia.com/.


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

tideEditor makes use of three Qt modules:  QtCore, QtGui, and Qt3Support.
To find the necessary headers and libraries, CPPFLAGS and LDFLAGS must be
set accordingly:

  bash-3.1$ ./configure \
    CPPFLAGS="-I$QT4DIR/include/QtCore -I$QT4DIR/include/QtGui -I$QT4DIR/include/Qt3Support" \
    LDFLAGS="-L$QT4DIR/lib"
  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.
