$Id: README 7302 2020-06-25 14:51:39Z 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
https://flaterco.com/xtide/files.html#extras

tideEditor is covered by the GNU General Public License.


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

libtcd.  libtcd is available from
https://flaterco.com/xtide/files.html#libtcd

Qt 4.x or Qt 5.x.  The free edition of Qt is included in most Linux
distributions and is available from
https://download.qt.io/archive/qt/


Configuration - simple
----------------------

Assuming libtcd and Qt have been installed in standard places and there are
no conflicting binaries, libraries, or header files around, you should be
able to just:

./configure

Alternatively, you can use Qt's qmake to build a Makefile like this:

qmake -o Makefile tideEditor.pro

If running 'make -j 8' does not then succeed, start over with the more robust
configuration process described in the next section.


Configuration - robust
----------------------

Nowadays it is common for Qt 4 and Qt 5 to be installed simultaneously.  To
be most sure of not mixing versions, you need to locate:

1. The root of the Qt include directory;
2. The directory containing the Qt shared libraries;
3. The matching version of the moc (Meta-Object Compiler) program.

You then should specify these in the CPPFLAGS, LDFLAGS, and MOC variables
when running configure, as shown in the example below.

./configure CPPFLAGS=-I/usr/lib64/qt/include \
            LDFLAGS=-L/usr/lib64/qt/lib \
            MOC=/usr/lib64/qt/bin/moc

If necessary, add the location of the header and library of libtcd, and/or
the -fPIC switch [*]:

./configure CPPFLAGS="-fPIC -I/usr/local/xtide/include -I/usr/include/qt5" \
            CXXFLAGS="-fPIC -O3" \
            LDFLAGS="-L/usr/local/xtide/lib" \
            MOC=/usr/lib64/qt5/bin/moc

* If -fPIC is needed, configuration will fail with this error:

configure: error: cannot find QtCore header; try setting CPPFLAGS.

and config.log will contain a line like the following:

/usr/include/qt5/QtCore/qglobal.h:1135:4: error: #error "You must build your code with position independent code if Qt was built with -reduce-relocations. " "Compile your code with -fPIC (-fPIE is not enough)."


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

When the Makefile has been built by any of the methods above, proceed with:

make -j 8
su
make install
(or sudo make install, if that's how you roll)

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
https://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 https://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:
https://flaterco.com/xtide/libtcd.html

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


Bugs
----

1.  A change to the coordinate format preference does not apply to edit
dialogs that are open.

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


Non-bugs
--------

When viewing old TCD files, one 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.
