                XTide: Harmonic tide clock and tide predictor

                           [San Francisco graph]

Preface

Welcome to the verbose documentation for XTide 2. If you are reading this as
a text file, please be aware that the text was extracted from the
illustrated HTML version of the documentation that resides at
http://www.universe.digex.net/~dave/xtide/. The web version may also be more
up-to-date than what you are reading.

This documentation contains images in the Portable Network Graphics (PNG)
format (such as the one at the top of this page). Versions of Netscape or
Internet Explorer older than version 4 will not be able to display these
images.

  ------------------------------------------------------------------------

THE XTIDE SOFTWARE DISTRIBUTION IS AVAILABLE FROM:
http://www.universe.digex.net/~dave/files/

  ------------------------------------------------------------------------

Contents

   * License and disclaimer ("NOT FOR NAVIGATION," "ABSOLUTELY NO WARRANTY")
   * Verbose documentation
        o Introduction
        o System requirements
        o Unix installation
        o Available ports for non-Unix platforms
        o Modes and formats
        o Using the interactive interface
        o Advanced usage
        o Using the command line interface
        o Running the web server
        o Customizing XTide
        o What to do if your location isn't listed
        o Important note about the -l switch
        o Known limitations and bugs
        o FAQ
        o Design notes
        o Credits
        o Bibliography
   * Short attention span documentation for experienced XTide users
        o Differences from XTide 1
        o Quick install instructions
        o Change log
        o News (current XTide developments)
   * About the pictures
   * More pictures

Hint: if you are completely clueless, read the FAQ.

-- dave@universe.digex.net

It pains me to have to do this, but the big web indexing services just
aren't getting the point. I tried using META tags, but it just made it
worse. So here's more food for the WWW line-eaters: xtide xtide xtide xtide
xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide
xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide
xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide xtide
xtide xtide xtide xtide xtide xtide tide prediction tide prediction tide
prediction tide prediction.
[Icon] License and disclaimer

                    XTide Copyright  1998 David Flater

This software is provided under the terms of the GNU General Public License,
either version 2 of the License, or (at your option) any later version.

                             NOT FOR NAVIGATION

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. The author assumes no liability for
damages arising from use of this program OR of the 'harmonics data' that is
distributed with it. For details, see the appended GNU General Public
License.

(Accurate tide predictions can only be made if the 'harmonics data' for the
relevant location is good. Unfortunately, the only way I have of knowing
when the data is bad is when someone with access to authoritative tide
predictions for the affected location tells me so. That is why you should
not use this program or its data files if anyone or anything could come to
harm as a result of an incorrect tide prediction. NOAA and similar agencies
in other countries can provide you with certified tide predictions if that
is what you need.)

XTide's predictions do not incorporate the effects of tropical storms, El
Nio, seismic events, continental drift, or changes in global sea level.

  ------------------------------------------------------------------------

The tide prediction algorithm used in this program was developed with United
States Government funding, so no proprietary rights can be attached to it.
For more information, refer to the following publications:

     Manual of Harmonic Analysis and Prediction of Tides. Special
     Publication No. 98, Revised (1940) Edition (reprinted 1958 with
     corrections; reprinted again 1994). United States Government
     Printing Office, 1994.

     Computer Applications to Tides in the National Ocean Survey.
     Supplement to Manual of Harmonic Analysis and Prediction of Tides
     (Special Publication No. 98). National Ocean Service, National
     Oceanic and Atmospheric Administration, U.S. Department of
     Commerce, January 1982.

  ------------------------------------------------------------------------

                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

        Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>

    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 2 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, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

  ------------------------------------------------------------------------

   * Contents
[Image]
Bass Harbor Head Light, Bass Harbor, Maine, 1997-06-24.  1997 David Flater.

Introduction

XTide is a package that provides tide and current predictions in a wide
variety of formats. Graphs, text listings, and calendars can be generated,
or a tide clock can be provided on your desktop.

XTide can work with X-windows, plain text terminals, or the web. This is
accomplished with three separate programs: the interactive interface
(xtide), the non-interactive or command line interface (tide), and the web
interface (xttpd).

The algorithm that XTide uses to predict tides is the one used by the
National Ocean Service in the U.S. It is significantly more accurate than
the simple tide clocks that can be bought in novelty stores. However, it
takes more to predict tides accurately than just a spiffy algorithm -- you
also need some special data for each and every location for which you want
to predict tides. XTide reads this data from harmonics files that you must
download along with the distribution.

Ultimately, XTide's predictions can only be as good as the available
harmonics data. Due to issues of data availability and of compatibility with
non-U.S. tide systems, the predictions for U.S. locations tend to be a lot
better on average than those for locations outside of the U.S. Nevertheless,
there are satisfied XTide users all over the world. It is up to you to
verify that the predictions for your locale match up acceptably well with
the officially sanctioned ones, and to let me know if they do not.

   * Deviations of 1 minute from official predictions are typical for U.S.
     locations having the latest data.
   * Deviations of 20 minutes are typical for non-U.S. locations or U.S.
     locations that are using obsolete data.
   * Much longer deviations indicate a problem.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] System requirements

XTide is Unix software. Any reasonably modern version of Unix should work.
XTide has been ported to a variety of other operating systems with differing
levels of success. These ports will be discussed in a later section.

As of 1998-05-30, I personally test XTide under Slackware Linux 3.3 and
Solaris 2.6, with the rare foray to Irix. While it is my intention that
XTide will run flawlessly on any flavor of Unix, Linux is the flavor that I
use for development. Infer from that what you will. People run XTide on many
different platforms, and I make portability fixes whenever problems arise.

XTide 2 was targeted for machines with at least as many MIPS as a 166 MHz
Pentium and with at least 5 megs of memory to burn. A Sparc 20 will do OK,
but if what you have is a 33 MHz 386 with 5 megs total memory then you
should probably run XTide 1 instead.

To compile XTide you will need a C++ compiler. XTide is written in a very
portable subset of C++. If there is any problem compiling XTide with any C++
compiler, ANSI-compliant or otherwise, I will attempt to address it. The
compiler used for development was g++ version 2.7.2.2.

In addition to the minimal set of X11 libraries that pretty much everyone
has, you will also need the following libraries:

   * libXpm version 4.3 or later (a.k.a. xpm-3.4, go figure)
   * libpng version 0.96 or later
   * libz version 1.0.4 or later (a.k.a. zlib-1.0.4)

tide and xttpd can be compiled in the absence of X-windows libraries.
However, you will still need libpng and libz.

libXpm comes standard with all Linux distributions, but not with Openwin. If
you need it, you can get it at
http://www.cdrom.com/pub/X11/contrib/libraries/xpm-3.4j.tar.gz, or from one
of the many other mirrors of the X11 directory tree.

Pointers to the latest libpng and libz can be found under the PNG home page
at http://www.cdrom.com/pub/png/pngcode.html. Some Unix installations come
with versions of these libraries that do not work, so take care if using
existing libraries.

The final requirement is only for those who want tide predictions for
non-U.S. locations to have the correct Summer Time (Daylight Savings Time)
adjustments. In order for this to work, your platform must provide a version
of Olson's zoneinfo database that supports the needed time zones.
Slackware's time zone database will work almost anywhere; Solaris's will
work for some locations outside of the U.S.; Irix's will work almost nowhere
except inside the U.S. If necessary, you may be able to upgrade your time
zone database using the latest version from ftp://elsie.nci.nih.gov/pub/. I
have no experience with that since I just use Linux.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Unix installation

These installation instructions assume that you have provided the necessary
libraries and C++ compiler discussed in the previous section.

Downloading

You will need the XTide distribution and at least one harmonics file. The
harmonics files contain the data that is required for XTide to predict tides
for different locations. The distribution and harmonics files are available
from http://www.universe.digex.net/~dave/files/ in gzipped tar and gzipped
ASCII formats respectively.

If you are unfamiliar with gzip, the following commands should be useful. To
unpack the distribution:

     gzip -dc xtide-2.0.tar.gz | tar xvf -

To uncompress a harmonics file:

     gzip -d harmonics.gz

Note that Netscape might automatically uncompress these files when you
download them.

Once you have uncompressed the harmonics files, move them to a permanent
location, e.g., /etc, and make them world readable:

     chmod 644 harmonics harmonics.anchorage
     mv harmonics harmonics.anchorage /etc

Creating a new directory called /usr/local/xtide to hold the harmonics files
might not be a bad choice, but it really doesn't matter where you put them.

Configuring

  1. You need to set the environment variable HFILE_PATH to point to your
     harmonics files. Example:

          export HFILE_PATH=/etc/harmonics:/etc/offsets.xml:\
          /etc/harmonics.anchorage:/etc/harmonics.canadian:\
          /etc/harmonics.admiralty:/etc/harmonics.japan

     If you are installing as root, then it is recommended that you add this
     definition to a system-wide script such as /etc/profile if you have
     one.
  2. If you will be running xttpd, you may want to set the e-mail address
     for feedback. You can do this by changing the value of webmasteraddr in
     config.hh or by setting the environment variable XTTPD_FEEDBACK. You
     should set it to your e-mail address, and definitely not to my e-mail
     address.
  3. You can also change the defaults (colors, etc.) set at the top of
     config.hh if you so choose. However, the easiest way to set all of
     those things is with the Control Panel in the interactive XTide
     program.

Compiling

Everybody except Openwin

Type the following at the shell prompt to compile:

     xmkmf; make depend; make

If your Imake is properly configured, that should do it. When the
compilation is complete, install the binaries and man pages as you see fit,
e.g.:

     chmod 755 xtide tide xttpd
     mv xtide tide xttpd /usr/local/bin
     chmod 644 *.1
     mv *.1 /usr/local/man/man1

Openwin

The Imake and configuration shipped with Solaris are still broken as of
Solaris 2.6, at least for C++. I have produced a hacked Imakefile that
appears to work under Solaris 2.6 Openwin, but it's hard to say whether it
was a net gain over just writing a plain old hard-coded Makefile.

To compile:

     imake -DHasCplusplus -DUseInstalled -I/usr/openwin/lib/config -f Imakefile.openwin

Don't do make depend; it's hopeless. Instead, type make clean before each
compilation attempt.

If all else fails

Copy Makefile.std to Makefile, edit as needed, and type make.

If you don't have any version of X11 installed and just want to compile
xttpd or tide, type make xttpd or make tide.

Troubleshooting

Q: I get link errors related to the PNG library even though I'm using the
latest version.

A: Some Unix vendors (SGI) have stuck crappy old versions of libpng in
/usr/lib. If you can't get rid of it, then you need to add the -nostdlib
switch to your link line, and add -L/usr/lib at the end.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Available ports for non-Unix platforms

IMPORTANT! These ports are all maintained by different people. They may be
significantly different from XTide 2 as documented here. If you have
problems with a non-Unix port, please contact the correct maintainer, not
me. I cannot help with anything but the canonical Unix distribution.

Microsoft Windows

There are two ports to Microsoft Windows, both distributed in binary format:

   * The newer port, "WXTide32" by Mike Hopper (MikeHopper@usa.net), is
     based on XTide 1.6.2 and includes a spiffy new location chooser. It
     works under Windows 95 or Windows NT. It has a web page at
     http://www.geocities.com/SiliconValley/Horizon/1195/wxtide32.html.
   * The older port, "WTide16" and "WTide32" by Paul C. Roberts
     (xtide@cherryjam.prestel.co.uk), was originally based on XTide 1.3 but
     may have been updated somewhat. It works under Windows 3.1 or Windows
     95. It can be found at ftp://ftp.demon.co.uk/pub/ibmpc/win3/apps/wtide.

OS/2

(Ported by Dale DePriest. This information is only current as of XTide
1.6.2.)

Tide now includes support for OS2. This port has been specifically tested
using the gcc/emx version 0.9c. XTide has also been ported specifically to
support the os2 port of XFree86. To build your copy of tide:

  1. copy makefile.os2 to Makefile
  2. run nmake or make.

To build xtide you must have the Xfree86 programming environment. Run 'make
xtide.exe'.

EMX, beginning with 0.9c, does support Daylight Savings Time and Time Zone
data. You will need at least fix01 to support tide and xtide. You must set
the TZ variable to get this to work. An example would be 'set TZ=PST8PDT'.
The -loctz switch will do this for you.

You can pick up a prebuilt copy of tide and xtide from hobbes.nmsu.edu,
under the directory os2/unix. You must have an X environment to use xtide
while tide will work in any environment. Also get os2/unix/emx09c/emxrt.zip
if you don't have it.

DOS

(Ported by Dale DePriest. This information is only current as of XTide
1.6.2.)

If you have the emx/gcc build environment, you can build tide using the os2
makefile without modification. Further, the tide program that was built for
os2 will run unmodified on a dos machine if you have the file emx.exe
present somewhere in your path (or rsxnt.exe if you are using DPMI memory).
See above, under OS/2 installation, for the location of the binaries.

Macintosh

The Macintosh port of the TTY client from XTide 1.3 is supported by Mikhail
Fridberg (fridberg@pfc.mit.edu). It is available at
http://www.universe.digex.net/~dave/files/MacTide133sit.hqx (binhexed
Stuffit archive). A binary is included.

Several people have made ports of the graphical client to Macintosh, but for
some reason they have all so far turned out to be [expletives deleted] who
flout the GNU General Public License. These ports are probably available
somewhere under a bogus name and without any source code, maybe even
commercially, but I'm not tracking them.

Palm Pilot

                  Walt Bilofsky has implemented Tide Tool on this little
                  "palmtop" computer, and judging from the picture it does
produce output that closely resembles that of XTide's text mode. The URL for
Tide Tool is http://www.toolworks.com/bilofsky/tidetool.htm.

  ------------------------------------------------------------------------

   * Next
   * Contents
This page provides an overview of the kinds of things that XTide can do. How
to do them will be explained in the next section.

[Icon] Modes

Graph mode

[San Francisco graph]

Graph mode gives you a plot of the water level (or water velocity, in the
case of currents) versus time. The times of high and low tide (or max flood
and max ebb) are printed across the top. For currents, the times of slack
water are printed across the bottom as shown below. Sunrise and sunset are
denoted with different background colors. A + mark on the graph indicates
the conditions at the time that the graph was generated.

[Golden Gate Bridge Current graph]

Clock mode

                  Clock mode is similar to graph mode, but the captions are
                  different and the window is automatically updated once a
minute to show the latest conditions. The location name is replaced by the
current time, the next high tide is centered at the top and the next low
tide is centered at the bottom. Dates are replaced with "High Tide" and "Low
Tide" captions. In the case of currents you won't get slack water.

[Classic analog tide clock] If you iconify a tide clock, you will get a
small "classic analog" tide clock that gives a vague idea of where you are
in the tide cycle. The icon will try to update once a minute, but this does
not work under some window managers.

Plain mode

Plain mode is just a plain old text listing of tide events. You get more
precise heights, sunrise, and sunset times than with graph mode, and you
also get moon phases which do not appear in the graph.

Washington, D.C.
38.8717 N, 77.0200 W

1998-05-31  1:02 PM EDT   3.00 feet  High Tide
1998-05-31  8:24 PM EDT   0.05 feet  Low Tide
1998-05-31  8:26 PM EDT   Sunset
1998-06-01  1:58 AM EDT   2.82 feet  High Tide
1998-06-01  5:44 AM EDT   Sunrise
1998-06-01  8:37 AM EDT   0.38 feet  Low Tide
1998-06-01  2:03 PM EDT   2.85 feet  High Tide
1998-06-01  8:27 PM EDT   Sunset
1998-06-01  9:11 PM EDT   0.15 feet  Low Tide
1998-06-01  9:44 PM EDT   First Quarter
1998-06-02  2:56 AM EDT   2.82 feet  High Tide

Calendar mode

Calendar mode basically just formats the output of plain mode into a
calendar as shown below. This mode is not available from the interactive
client.

                                February 1998
   Sun 1      Mon 2      Tue 3      Wed 4     Thu 5      Fri 6      Sat 7
                      High Tide
                      12.12 ft
 High Tide High Tide  3:08 AM    High Tide            Low Tide   Low Tide
 12.54 ft  12.40 ft   EST        11.80 ft             0.70 ft    0.76 ft
 1:19 AM   2:12 AM    Sunrise    4:09 AM    High Tide 12:05 AM   1:09 AM
 EST       EST        6:49 AM    EST        11.56 ft  EST        EST
 Sunrise   Sunrise    EST        Sunrise    5:14 AM   High Tide  Sunrise
 6:51 AM   6:50 AM    Low Tide   6:47 AM    EST       11.47 ft   6:44 AM
 EST       EST        -0.18 ft   EST        Sunrise   6:21 AM    EST
 Low Tide  Low Tide   9:28 AM    Low Tide   6:46 AM   EST        High Tide
 -0.86 ft  -0.56 ft   EST        0.13 ft    EST       Sunrise    11.53 ft
 7:30 AM   8:26 AM    High Tide  10:35 AM   Low Tide  6:45 AM    7:24 AM
 EST       EST        11.20 ft   EST        0.26 ft   EST        EST
 High Tide High Tide  3:40 PM    Sunset     11:45 AM  Low Tide   Low Tide
 12.47 ft  11.85 ft   EST        4:46 PM    EST       0.19 ft    -0.03 ft
 1:41 PM   2:37 PM    Sunset     EST        Sunset    12:53 PM   1:55 PM
 EST       EST        4:44 PM    High Tide  4:47 PM   EST        EST
 Sunset    Sunset     EST        10.67 ft   EST       Sunset     Sunset
 4:42 PM   4:43 PM    First      4:47 PM    High Tide 4:49 PM    4:50 PM
 EST       EST        Quarter    EST        10.38 ft  EST        EST
 Low Tide  Low Tide   5:55 PM    Low Tide   5:57 PM   High Tide  High Tide
 -1.15 ft  -0.62 ft   EST        0.42 ft    EST       10.36 ft   10.52 ft
 8:00 PM   8:55 PM    Low Tide   10:59 PM             7:04 PM    8:05 PM
 EST       EST        -0.06 ft   EST                  EST        EST
                      9:54 PM
                      EST

Banner mode

Banner mode is a specialization of graph mode for output on tractor feed dot
matrix or line printers that use continuous reams of paper. The graph is
turned sideways and the aspect ratio is adjusted for Pica type. This mode is
only available in the command line client.

San Francisco, California
37.8067 N, 122.4650 W

-5******3****2****1****0****1****2****3****4*** 5    6    7    8    9
******** **** **** **** **** **** **** **** **
********f****f****f****f****f****f****f****f*   f    f    f    f    f
-6******t****t****t****t****t****t****t****t    t    t    t    t    t
******************************************
****************************************   |    |    |    |    |    |
-7************************************|    |    |    |    |    |    |
***********************************+  |    |    |    |    |    |    |
**********************************    |    |    |    |    |    |    |
-8****************************** |    |    |    |    |    |    |    |
******************************   |    |    |    |    |    |    |    |
*****************************    |    |    |    |    |    |    |    |
-9************************* |    |    |    |    |    |    |    |    |
**************************  |    |    |    |    |    |    |    |    |
*************************   |    |    |    |    |    |    |    |    |
-10*********************    |    |    |    |    |    |    |    |    |
************************    |    |    |    |    |    |    |    |    |1998-05-31
************************    |    |    |    |    |    |    |    |   10:35 AM PDT
-11*********************    |    |    |    |    |    |    |    |    |
************************    |    |    |    |    |    |    |    |    |
*************************   |    |    |    |    |    |    |    |    |
-12***********************  |    |    |    |    |    |    |    |    |
*************************** |    |    |    |    |    |    |    |    |
****************************|    |    |    |    |    |    |    |    |
-1***************************    |    |    |    |    |    |    |    |
******************************   |    |    |    |    |    |    |    |
******************************** |    |    |    |    |    |    |    |
-2*******************************|    |    |    |    |    |    |    |

Stats mode

Stats mode is for finding the highest high tide and lowest low tide within
some period of time. Stats mode is only available in the command line
client.

Bar Harbor, Maine
44.3917 N, 68.2050 W

Mathematical upper bound:  15.41 feet
Mathematical lower bound:  -3.99 feet
Mean Sea Level:   5.71 feet

Searched interval from 1998-01-01 12:00 AM EST to 1998-12-31 11:59 PM EST
Max was  13.86 feet at 1998-11-05 10:56 AM EST
Min was  -2.28 feet at 1998-11-05  5:20 PM EST

Raw mode

Raw mode is for getting machine-readable output that can be fed into other
Unix programs. The first column is a Unix time_t timestamp (seconds since
1970-01-01 00:00Z); the second column is tide heights in whatever units were
selected for the location. The start, end, and step values can be set with
command line switches. This mode is only available in the command line
client.

896624777 0.180580
896628377 1.271889
896631977 3.463100
896635577 6.084148
896639177 8.402840
896642777 9.943272
896646377 10.421064
896649977 9.672793
896653577 7.856022
896657177 5.543402
896660777 3.413487
896664377 1.926805
896667977 1.371479

List mode

List mode does not provide tide predictions at all; it is simply a way to
get the list of supported locations from the command line client.

            Location                    File              Coordinates
 ABA, NAGASAKI (4278)            harmonics.japan    32.7500 N, 129.9500 E
 ABASIRI, HOKKAIDO (0118)        harmonics.japan    44.0167 N, 144.2830 E
 Abbapoola Creek Entrance, South
 Carolina                        harmonics          32.6767 N, 80.0067 W
 Abbot Point, Australia          harmonics.admiralty19.8833 S, 148.0833 E
 Aberdeen, Scotland              harmonics          57.1500 N, 2.0833 W
 Aberdeen, Washington            harmonics          46.9683 N, 123.8533 W

Formats

XTide can render output in four different formats: X-windows, HTML, PNG, or
text. The X-windows format is implicit in the interactive client and can't
be selected explicitly. The others can be selected in the non-interactive
client and are invoked automatically by the the interactive and web clients
(e.g., when you save output to a file).

The currently supported combinations of mode and format are as follows:

        Mode        Legal forms
      banner   text
      calendar text, HTML
      clock    X-windows
      graph    text, PNG, X-windows
      list     text, HTML
      plain    text, X-windows
      raw      text
      stats    text

The HTML and PNG formats are adequately demonstrated by the examples above
in the Modes section. Here is an example of graph mode using the text
format:

                           San Francisco, California
         1998-05-31                   1998-05-31           1998-05-31
        10:36 AM PDT                  6:14 PM PDT         11:41 PM PDT
9 ft --------------------------------------------------------------------------

8 ft --------------------------------------------------------------------------
7 ft --------------------------------------------------------------------------

6 ft --------------------------------------------------------------------------
5 ft -----------------------------------********-------------------------------
                                    ****************
4 ft ----------------------------***********************-------------------****
3 ft -------------------------******************************---------**********
***                         ***************************************************
2 ft*--------------------******************************************************
1 ft***---------------*********************************************************
*******+***       *************************************************************
0 ft***************************************************************************
1 ft***************************************************************************
*******************************************************************************
2 ft***************************************************************************
*******************************************************************************
7***8***9**10*11**12***1***2***3***4**5***6***7***8***9**10**11*12***1***2***3*
|***|***|***|**|***|***|***|***|***|**|***|***|***|***|***|***|*|||**|***|***|*

Here is calendar mode in the text format (note that some information is
truncated to fit into 80 columns):

                                 February 1998

Sun  1     Mon  2     Tue  3     Wed  4     Thu  5     Fri  6     Sat  7
High Tide  High Tide  High Tide  High Tide  High Tide  Low Tide 0 Low Tide 0
1:19 AM ES 2:12 AM ES 3:08 AM ES 4:09 AM ES 5:14 AM ES 12:05 AM E 1:09 AM ES
Sunrise    Sunrise    Sunrise    Sunrise    Sunrise    High Tide  Sunrise
6:51 AM ES 6:50 AM ES 6:49 AM ES 6:47 AM ES 6:46 AM ES 6:21 AM ES 6:44 AM ES
Low Tide - Low Tide - Low Tide - Low Tide 0 Low Tide 0 Sunrise    High Tide
7:30 AM ES 8:26 AM ES 9:28 AM ES 10:35 AM E 11:45 AM E 6:45 AM ES 7:24 AM ES
High Tide  High Tide  High Tide  Sunset     Sunset     Low Tide 0 Low Tide -
1:41 PM ES 2:37 PM ES 3:40 PM ES 4:46 PM ES 4:47 PM ES 12:53 PM E 1:55 PM ES
Sunset     Sunset     Sunset     High Tide  High Tide  Sunset     Sunset
4:42 PM ES 4:43 PM ES 4:44 PM ES 4:47 PM ES 5:57 PM ES 4:49 PM ES 4:50 PM ES
Low Tide - Low Tide - First Quar Low Tide 0            High Tide  High Tide
8:00 PM ES 8:55 PM ES 5:55 PM ES 10:59 PM E            7:04 PM ES 8:05 PM ES
                      Low Tide -
                      9:54 PM ES


  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Using the interactive interface

The first time you run xtide, you will get a license and disclaimer window.
Read it, then click "Don't show this again" and dismiss it.

Meanwhile, you will get a title screen that informs you of progress indexing
the harmonics files. When indexing is complete, you will get a location
chooser. The location chooser consists of a globe window and a location
list. The globe initially shows an entire hemisphere. The location list
enumerates every tide station that is plotted on the globe. Buttons with
labels such as "A-S" and "S-Z" will appear on the location list window if
the list is too long to display all at once; use these buttons to switch
between the different pieces of the list.

[Globe window]

[Location list window]

The Rotate button permits you to access the other side of the world. The
location list updates to contain only those tide stations that are visible.
You can zoom in on an area by clicking on the globe with the left mouse
button; zooming out is accomplished with the button at the bottom of the
globe window. You can cause the location list to include all available
locations at once by clicking on List All. This will also bring up locations
whose coordinates are unknown.

Instead of zooming, you can narrow the list to a small area by clicking on
that area with the right mouse button. A circle will be drawn on the globe
indicating the area selected:

[Globe window with circle]

When you are ready to choose a location, you can either click on it in the
location list or zoom down to it on the globe and click on the appropriate
red dot with the middle mouse button. A tide graph for the selected location
will then pop up.

[Graph window]

The Backward and Forward buttons allow you to move forward or backward in
time by one day. Pull down the Options menu to gain access to the Set Time
option, which allows arbitrarily large adjustments. The Options menu also
provides these other options:

            Option                            Function

      Save                Export the contents of the window to a PNG or
                          text file, as appropriate.
      Set Mark            See next section.
      Convert ft<->m      Convert units to the preferred system.
      Set Aspect          See next section.
      New Graph Window    Pop up a graph mode window for the location.
      New Text Window     Pop up a plain mode window for the location.
      New Clock Window    Pop up a clock mode window for the location.
      New Location
      Chooser             Pop up a new location chooser.
      Control Panel       See next section.

Without getting into the complicated options, you can navigate from the
location chooser to a graph window to other modes for the same location as
you see fit. Use the Dismiss buttons to get rid of windows that you are
through with.

                   Text windows provide Forward and Backward buttons for
                   scrolling forward and backward in time, and they also
provide the same Options menu that is available on graph windows.

                                              Clock windows first appear
                                              with no buttons whatsoever,
which is how you want them if you are going to leave them running on your
desktop. However, you can make the buttons appear and disappear by clicking
anywhere on the graph inside of the clock window.

The Options menu is again the same; Forward and Backward buttons are not
provided for the obvious reason.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Advanced usage

Mark level

The "mark level" is a specific tidal height or current velocity of your
choosing. When you set a mark level for a location, the times at which the
tide level crosses the mark level will be displayed at the bottom of graphs
and included in plain listings and calendars. This option is useful to
determine the times when the tide will be low enough to expose something
that is submerged at high tide, or high enough to provide a desired depth.
You can set a mark level by selecting the Set Mark option on the Options
menu.

[San Francisco graph with mark level]

Note that mark level crossings will not be displayed in the clock window due
to lack of space. Note also that some locations, namely subordinate stations
with complex offsets, will not support setting a mark level for technical
reasons.

Aspect

The "aspect" is a number that controls how stretched out or scrunched up a
graph is. If timestamps are overlapping one another on a tide graph and
becoming unreadable, you can increase the aspect to make them farther apart.
An aspect of 1.0 is "normal;" an aspect of 2.0 stretches the graph by a
factor of 2; an aspect of 0.5 does the opposite, compressing the graph. You
can change the aspect by selecting the Set Aspect option on the Options
menu.

                                       An indecisive low tide at Portland,
                                       England has obscured the timestamps
in this tide graph.

                                       Stretching the graph to aspect 4.0
                                       clears up the mystery.

                                      This tide clock has been compressed
                                      to aspect 0.5.

The control panel

The control panel is the easiest way to customize the many user-serviceable
settings of XTide. It's not pretty, but it gets the job done.

[XTide control panel]

Colors can be changed to any of the "standard" X-windows color names or to
24-bit RGB specifications of the form rgb:hh/hh/hh by typing the new colors
in the dialog boxes. Other settings have pull-down choice menus or counting
buttons to help you along. Least user-friendly, but most powerful, are the
timestamp formats. In return for reading the Unix man page for the strftime
library function, you are empowered to change the timestamp formats to
practically anything you could ever need.

You can choose Apply to see how the settings look in the current session
only, or Save to make the settings permanent. They will be saved in the file
~/.xtide.xml.

The following is one example of the sort of thing you can accomplish using
the control panel. "Draw tide graphs as line graphs" was selected, and the
timestamp formats were changed to use 24-hour time instead of AM/PM. (The
format strings for this are provided in the on-line help for the control
panel.)

[Line graph with 24-hour timestamps]

Command line options

The interactive client supports all of the command line switches related to
settings which are described in a later section. In addition, it supports
the following.

-b "YYYY-MM-DD HH:MM"
     With -l, specify the begin (start) time for predictions using the ISO
     8601 compliant format shown above. The timestamp is in the local time
     zone for the location, or in UTC if the -z setting is engaged. If no -b
     is supplied, the current time will be used.
-display "X display"
     Specify the X display, e.g. "quake:0.0". This overrides the DISPLAY
     environment variable.
-fn "font"
     Specify the font to use for text windows, buttons, and labels. This
     will not affect the font used in tide graphs and other cramped spaces,
     which is not a user-selectable parameter.
-l "Location Name"
     Specify a location for tide predictions. When given to the interactive
     client, this causes it to start a tide clock for the specified location
     instead of launching a location chooser on startup. This is useful for
     starting a tide clock automatically when you log on. Multiple uses of
     -l will result in multiple tide clocks. The -m switch can be used to
     choose graph or plain mode instead of clock mode, and the -b switch is
     effective in these cases. (Please read Important note about the -l
     switch.)
-m g|p
     With -l, specify mode to be graph or plain instead of clock.
-v
     Print version string and exit. Please note that versions marked as
     DEVELOPMENT versions are not really versioned; they are work in
     progress and will change without warning.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Using the command line interface

The command line interface, tide, supports a number of modes that cannot be
accessed with the interactive client. It can run without X-windows, and
unlike the interactive client, it can easily be invoked from shell scripts.

The minimal usage is simply to specify a location with -l. The default mode
is plain, and the default format is text:

     $ tide -l "anchorage, al"
     Anchorage, Alaska
     61.2383 N, 149.8883 W

     1998-05-31  6:42 PM AKDT   1.14 feet  Low Tide
     1998-05-31 11:18 PM AKDT   Sunset
     1998-06-01 12:54 AM AKDT  27.40 feet  High Tide
     1998-06-01  4:35 AM AKDT   Sunrise
     1998-06-01  7:17 AM AKDT   6.60 feet  Low Tide
     1998-06-01 12:49 PM AKDT  23.89 feet  High Tide
     1998-06-01  5:44 PM AKDT   First Quarter

The non-interactive client supports all of the command line switches related
to settings which are described in a later section. In addition, it supports
the following.

-b "YYYY-MM-DD HH:MM"
     Specify the begin (start) time for predictions using the ISO 8601
     compliant format shown above. The timestamp is in the local time zone
     for the location, or in UTC if the -z setting is engaged. If no -b is
     supplied, the current time will be used.
-e "YYYY-MM-DD HH:MM"
     Specify the end (stop) time for predictions using the ISO 8601
     compliant format shown above. The timestamp is in the local time zone
     for the location, or in UTC if the -z setting is engaged. If no -e is
     supplied, the end time will be set to four days after the begin time.
     NOTE: For graphs, the end time is determined by the TTY width and
     aspect, not by this switch.
-f h|p|t
     Specify the output format as HTML, PNG, or text. See the modes page for
     legal modes and formats. The default is text.
-l "Location Name"
     Specify a location for tide predictions. (Please read Important note
     about the -l switch.)
-m b|c|g|l|p|r|s
     Specify mode to be banner, calendar, graph, list, plain, raw, or stats.
     See the modes page for legal modes and formats. The default is plain.
-ml [-]N.NN(ft|m|kt)
     Specify the mark level to be used in predictions. The predictions will
     include the times when the tide level crosses the mark. Example usage:
     -ml -0.25ft Some subordinate stations won't take this option.
-o "filename"
     Redirect output to the specified file.
-s "HH:MM"
     Specify the step interval, in hours and minutes, for raw mode
     predictions. The default is one hour.
-v
     Print version string and exit. Please note that versions marked as
     DEVELOPMENT versions are not really versioned; they are work in
     progress and will change without warning.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Running the web server

xttpd is an XTide web server. It provides web-based access to XTide's tide
predictions by allowing a web browser to speak directly to the XTide program
in HTTP. xttpd can replace httpd or it can co-exist with one. Usage: xttpd
[port] [...other xtide settings switches...].

If you run xttpd with no command line arguments, it will assume that it is
replacing httpd and try to bind port 80. If you want it to co-exist with an
existing server, or if you do not have privilege to get port 80, give it the
port number as the first command line argument:

     % xttpd 8080

You will then need to link it up as http://www.wherever.org:8080/ instead of
just http://www.wherever.org/, but otherwise, no damage done. xttpd will try
to set its UID to 'nobody' once the port is established, but will issue a
warning and continue with the default user ID if this fails.

You can set the address for feedback either in config.hh or with the
environment variable XTTPD_FEEDBACK.

xttpd will produce a small number of zombie processes during normal
operation. They are cleaned up after each new connection, so there is no
cause for concern.

Hosts connecting to xttpd will be logged to standard output.

Since a web site is supposed to be self-explanatory, the process of using
xttpd will not be documented here. If there are problems with people of
normal intelligence not being able to figure out how to use it, these should
be reported to me as bugs, and the explanatory text in the web server will
be updated accordingly.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Customizing XTide

XTide is customized by changing its settings. The most convenient way to do
this is generally through the control panel that is documented in a previous
section. However, you can also change these settings in config.hh, in your X
resources database, or on the command line. The order of precedence, from
least significant to most significant, is:

  1. config.hh
  2. Xdefaults (X resources)
  3. ~/.xtide.xml (control panel)
  4. command line

Note that only xtide (not xttpd or tide) reads Xdefaults.

All command line settings take the form -xx value, with a space between the
switch and the supplied value. Even the yes-or-no settings require a value
of "y" or "n" to be supplied.

XTide*background
     Background color for text windows and location chooser.
     Default: white
     Command line: -bg
     config.hh: bgdefcolor
     .xtide.xml: <xtideoptions bg="white"/>
XTide*buttoncolor
     Background color of buttons.
     Default: gray80
     Command line: -bc
     config.hh: buttondefcolor
     .xtide.xml: <xtideoptions bc="gray80"/>
XTide*cwidth
     Default width for tide clocks. NOTE: Default clock height is the same
     as default graph height (XTide*gheight).
     Default: 84
     Command line: -cw
     config.hh: defcwidth
     .xtide.xml: <xtideoptions cw="84"/>
XTide*datefmt
     Strftime style format string for printing dates.
     Default: %Y-%m-%d
     Command line: -df
     config.hh: datefmt
     .xtide.xml: <xtideoptions df="%Y-%m-%d"/>
XTide*datumcolor
     Color of datum line in tide graphs.
     Default: white
     Command line: -Dc
     config.hh: datumdefcolor
     .xtide.xml: <xtideoptions Dc="white"/>
XTide*daycolor
     Daytime background color in tide graphs.
     Default: SkyBlue
     Command line: -dc
     config.hh: daydefcolor
     .xtide.xml: <xtideoptions dc="SkyBlue"/>
XTide*ebbcolor
     Foreground in tide graphs during outgoing tide.
     Default: SeaGreen
     Command line: -ec
     config.hh: ebbdefcolor
     .xtide.xml: <xtideoptions ec="SeaGreen"/>
XTide*extralines
     Draw datum and MSL lines in tide graphs? (y/n)
     Default: n
     Command line: -el
     config.hh: extralines
     .xtide.xml: <xtideoptions el="n"/>
XTide*floodcolor
     Foreground in tide graphs during incoming tide.
     Default: Blue
     Command line: -fc
     config.hh: flooddefcolor
     .xtide.xml: <xtideoptions fc="Blue"/>
XTide*foreground
     Color of text and other notations.
     Default: black
     Command line: -fg
     config.hh: fgdefcolor
     .xtide.xml: <xtideoptions fg="black"/>
XTide*gaspect
     Default aspect for tide graphs.
     Default: 1.0
     Command line: -ga
     config.hh: defgaspect
     .xtide.xml: <xtideoptions ga="1.0"/>
XTide*gheight
     Default height for tide graphs.
     Default: 312
     Command line: -gh
     config.hh: defgheight
     .xtide.xml: <xtideoptions gh="312"/>
XTide*globelongitude
     Default center longitude for globe.
     Valid values: -180 -150 -120 -90 -60 -30 0 30 60 90 120 150 360
     360 will pick the longitude with the most tide stations.
     Default: 360
     Command line: -gl
     config.hh: defgl
     .xtide.xml: <xtideoptions gl="360"/>
XTide*gwidth
     Default width for tide graphs.
     Default: 960
     Command line: -gw
     config.hh: defgwidth
     .xtide.xml: <xtideoptions gw="960"/>
XTide*hourfmt
     Strftime style format string for printing hour labels on time axis.
     Default: %I
     Command line: -hf
     config.hh: hourfmt
     .xtide.xml: <xtideoptions hf="%I"/>
XTide*lwidth
     Width for lines in tide graphs with nofill.
     Default: 2.5
     Command line: -lw
     config.hh: deflwidth
     .xtide.xml: <xtideoptions lw="2.5"/>
XTide*markcolor
     Color of mark line in graphs and of location dots on the spinning
     globe.
     Default: red
     Command line: -mc
     config.hh: markdefcolor
     .xtide.xml: <xtideoptions mc="red"/>
XTide*mslcolor
     Color of Mean Sea Level line in tide graphs.
     Default: yellow
     Command line: -Mc
     config.hh: msldefcolor
     .xtide.xml: <xtideoptions Mc="yellow"/>
XTide*nightcolor
     Nighttime background color in tide graphs.
     Default: DeepSkyBlue
     Command line: -nc
     config.hh: nightdefcolor
     .xtide.xml: <xtideoptions nc="DeepSkyBlue"/>
XTide*nofill
     Draw tide graphs as line graphs? (y/n)
     Default: n
     Command line: -nf
     config.hh: nofill
     .xtide.xml: <xtideoptions nf="n"/>
XTide*timefmt
     Strftime style format string for printing times.
     Default: %I:%M %p %Z
     Command line: -tf
     config.hh: timefmt
     .xtide.xml: <xtideoptions tf="%I:%M %p %Z"/>
XTide*toplines
     Draw depth lines on top of tide graph? (y/n)
     Default: n
     Command line: -tl
     config.hh: toplines
     .xtide.xml: <xtideoptions tl="n"/>
XTide*ttyheight
     Height of ASCII graphs (characters).
     Default: 24
     Command line: -th
     config.hh: defttyheight
     .xtide.xml: <xtideoptions th="24"/>
XTide*ttywidth
     Width of ASCII graphs, banners, and calendars (characters).
     Default: 79
     Command line: -tw
     config.hh: defttywidth
     .xtide.xml: <xtideoptions tw="79"/>
XTide*units
     Preferred units of length: ft, m, or x (no preference).
     Default: x
     Command line: -u
     config.hh: prefunits
     .xtide.xml: <xtideoptions u="x"/>
XTide*zulu
     Coerce all time zones to UTC? (y/n)
     Default: n
     Command line: -z
     config.hh: zulu
     .xtide.xml: <xtideoptions z="n"/>

Format of ~/.xtide.xml

If you have compiled the interactive client (xtide), then you do not need to
worry about ~/.xtide.xml at all, because the control panel will configure it
for you automatically.

In the event that you cannot use xtide but still need to make some settings
for the command line client, use the example below as the starting point for
your ~/.xtide.xml file. This example just sets the TTY geometry. You can add
more settings by adding more attributes (like the tw and th attributes shown
here) to the xtideoptions entity. The attributes that are recognized for
each setting are documented above.

     <?XML version="1.0" RMD="NONE"?>
     <xtideoptions tw="79" th="24"/>

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] What to do if your location isn't listed

As was explained in the Introduction, tide predictions for a given location
cannot be conjured out of the void -- you need to get some special data
(harmonic constants) for each and every location for which you want to
predict tides. XTide reads this data from harmonics files that you must
download along with the distribution.

A complete list of locations in the available harmonics files is at
http://www.cs.umbc.edu/~davidf/harmlist.html, kept there because it causes
me to exceed my disk quota in my regular account. Check to make sure that
your location does not appear anywhere in it by any alias. It is possible
that the data set is available, but due to lack of known coordinates it does
not show up in the location chooser unless you select List All.

If your location is not already on the list, you have two options:

  1. If you are in the U.S., you can pay NOAA between $10 and $40 for a data
     set. Other tide services in other countries may give out this data for
     free, or they may refuse to give it out "for security reasons."
     Nowadays it's getting harder and harder to get good data. I have
     removed the lengthy explanation of how to order data from NOAA and add
     it to the harmonics file as nobody has successfully done it in several
     years.
  2. Find out the tide offsets from a well-known reference station for which
     I already have data and create a new subordinate station in
     offsets.xml. You should be able to get offsets with relative ease from
     a local boating magazine, chartbook, yacht club, or marine authority.
     Also, NOAA now has a web page with offsets for thousands of places at
     http://www.opsd.nos.noaa.gov/tp4days.html.

Subordinate stations are not "real" tide stations -- their tides are figured
by applying corrections to a reference station, i.e., one for which we have
good harmonics data. However, XTide 2 happily lets you enter subordinate
stations into the database under their own names and forget the ugly truth.

Subordinate stations are added to offsets.xml (available from
http://www.universe.digex.net/~dave/files/). Someday I will have a valid DTD
for it and you will be able to edit it in Word Perfect in a user-friendly
way. For now, you must follow the examples.

There are many different flavors of offsets for subordinate stations. At
this time, XTide supports all known flavors. Below are some examples of what
you get versus what you need to enter. I would, of course, like you to send
me the data when you are finished so that I can distribute it to others.

If you get:

     Head Harbor, Isle au Haut    -0:20   (Portland)

Then you enter:

     <subordinatestation name="Head Harbor, Isle au Haut, Maine"
       pedigree="From NOAA http://www.opsd.nos.noaa.gov/tp4days.html"
       latitude="44.021666667"
       longitude="-68.62"
       timezone=":America/New_York"
       reference="Portland, Maine">
     <simpleoffsets> <timeadd value="-0:20"/> </simpleoffsets>
     </subordinatestation>

If you get:

               Time meridian, 150` E           on Ponape Harbor

     Marcus Island                           -0 19   -0 19    (*0.65+0.3)

Then you enter:

     <subordinatestation name="Marcus Island (Minami Tori Shima)"
       pedigree="From Alan Eugene Davis"
       latitude="24.2667"
       longitude="154.0000"
       timezone=":Pacific/Guam"
       reference="Ponape Harbor">
     <simpleoffsets>
       <timeadd value="-0:19"/>
       <levelmultiply value="0.65"/>
       <leveladd value="0.3" units="feet"/>
     </simpleoffsets>
     </subordinatestation>

If you get:

     Reagan National Airport   +0 16  -0 02  *1.07  *1.06  Washington DC

Then you enter:

     <subordinatestation name="Reagan National Airport, Washington, D.C."
       pedigree="From NOAA http://www.opsd.nos.noaa.gov/tp4days.html"
       latitude="38.8520867"
       longitude="-77.0377119"
       timezone=":America/New_York"
       reference="Washington, D.C.">
     <offsets>
       <max>
         <timeadd value="+0:16"/>
         <levelmultiply value="1.07"/>
       </max><min>
         <timeadd value="-0:02"/>
         <levelmultiply value="1.06"/>
       </min>
     </offsets>
     </subordinatestation>

If you get:

               Time meridian, 180` E           on Kwajalein Atoll

     Ailinglapalap Atoll                     +0 08   +0 07    +0.4    +0.3

Then you enter:

     <subordinatestation name="Ailinglapalap Atoll, Marshall Islands"
       pedigree="From Alan Eugene Davis"
       latitude="7.5"
       longitude="168"
       timezone=":Pacific/Kwajalein"
       reference="Kwajalein Atoll">
     <offsets>
       <max>
         <timeadd value="+0:08"/>
         <leveladd value="0.4" units="feet"/>
       </max><min>
         <timeadd value="+0:07"/>
         <leveladd value="0.3" units="feet"/>
       </min>
     </offsets>
     </subordinatestation>

If you get:

     For Oakland Inner Harbor Reach, depth 33m. below datum, 37d 47.67'N 122d
     17.15'W the time differences are:

     Min.     Flood    Min.     Ebb     Speed       Average Speed & Direction
     before            before           ratios      Min  Fld      Min  Ebb
     Flood             Ebb
     h  m     h  m     h  m     h  m    Flood Ebb

     -2 38    -0 48    -1 12    -1 40   0.1   0.1   - -  0.3 082  - -  0.2 255

Then you enter:

     <subordinatestation name="Oakland Inner Harbor Reach Current"
       pedigree="NOS data via Ed Wallner"
       latitude="37.8105"
       longitude="-122.5022"
       timezone=":America/Los_Angeles"
       reference="Golden Gate Bridge, California Current">
     <offsets>
       <max>
         <timeadd value="-0:48"/>
         <levelmultiply value="0.1"/>
       </max><min>
         <timeadd value="-1:40"/>
         <levelmultiply value="0.1"/>
       </min>
       <!-- Slack offsets are only of the timeadd variety. -->
       <floodbegins value="-2:38"/>
       <ebbbegins value="-1:12"/>
     </offsets>
     </subordinatestation>

In most cases you won't be given the latitude and longitude with the offsets
for a subordinate station. A 1-meg list of many NOS tide stations with
coordinates is available at
http://www.cs.umbc.edu/~davidf/nos_station_list.txt. If it's not in there
and you can't find it anywhere else, just estimate the coordinates as best
you can using an atlas.

The timezone attribute is only used to choose the time zone in which to
render output for the location. In the majority of cases this will be the
same as for the reference station, and you can just omit timezone to get
this behavior.

Please see the note in the next section about the need to unambiguously
specify the name of the reference station.

Getting harmonic constants from your front yard

[Image]
National Ocean Service tide station at Bar Harbor, Maine, 1997-06-24.  1997
David Flater.

If you are ambitious and have access to regular water level readings for
your locale over the course of a year or so, you can derive the harmonic
constants yourself. Unfortunately, I do not yet distribute a program for
deriving harmonic constants. See the news page for more information about
this.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Important note about the -l switch

If you run XTide with few locations specified on the command line, XTide
will skip the harmonics file indexing step and just load those few locations
as fast as possible. Because this process is substantially different from
indexed access, there are differences in the resolution of location names
that you must be aware of if there is more than one data set that could
match your location name.

When the harmonics files are indexed, the names of all of the locations in
all of the harmonics files are sorted into alphabetical order. A location
name that could possibly match more than one data set always matches the one
that is first in alphabetical order. (It is not case-sensitive.)

When fast loading is used, XTide checks each harmonics file in your
HFILE_PATH in order, and scans each file from top to bottom. The first
matching data set is immediately loaded. This MAY NOT be the one that is
first in alphabetical order in all of the harmonics files.

There are steps that you can take to avoid getting the wrong data set:

   * If your location appears in more than one harmonics file, choose the
     version that you think is the most accurate and remove the other
     harmonics file from your path.
   * Always use the full name of the data set. For example, use "Washington
     Canal, New Jersey" instead of just "Washington" to avoid getting
     "Washington, D.C." by mistake.

Note that the reference stations needed by subordinate stations are also
identified by name only, and therefore suffer from the same potential
ambiguities. When adding subordinate stations to offsets.xml, always use a
non-ambiguous name to specify the reference station.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Known limitations

  1. RGB color specs (rgb:N/N/N) in sizes other than 24 bits (rgb:hh/hh/hh)
     generally will not work.
  2. Time begins on January 1, 1970 and ends on December 31, 2037. Attempts
     to generate tide predictions at or near these boundaries will blow up.
  3. All timestamps have a precision of plus or minus one minute.
  4. All predictions are made to an accuracy of plus or minus one minute (in
     the mathematical sense, not in the sense of matching up with the real
     world).
  5. URLs assigned to specific locations by the xttpd web server are rather
     transient and will change whenever the harmonics files are updated. The
     xttpd web space will remain internally consistent, but hyperlinks from
     outside pages will be screwed.

Known bugs

  1. If two events (e.g., high tide and full moon) happen to coincide very
     closely, within 1 minute of each other, and you reverse the direction
     of the scrolling in the interactive plain mode window at a point where
     only one of the events is visible, you might be able to make the other
     one disappear. Cause of bug: accuracy of predictions, precision of
     timestamps. Workaround: don't do that.
  2. Some of the dialog windows cause harmless but annoying toolkit warnings
     when you dismiss them. Cause of bug: don't understand what the toolkit
     grabs are doing. Workaround: ignore warnings.
  3. In the interactive plain mode window only, tide events can be listed
     out of order for subordinate stations. Cause of bug: design conflict.
     Efficient scrolling is incompatible with keeping the list sorted.
     Workaround: save the predictions to a file and they will be sorted.
  4. Tide graphs and raw output for subordinate current stations won't mesh
     with the predicted times of slack water. Cause of bug: The
     interpolation algorithm used to produce tide graphs for subordinate
     stations doesn't do slack water. Workaround: none.
  5. Line width in line graphs isn't maintained when the slope of the graph
     becomes drastic. Cause of bug: need better algorithm for drawing line
     graphs. Workaround: set the aspect higher.
  6. Multiple data sets having the same name cannot be distinguished, and it
     is not deterministic which one you will get. Cause of bug: data sets
     are keyed by name. Workaround: If the same location appears in multiple
     harmonics files, choose which version you want to use and remove the
     other harmonics file from your HFILE_PATH.
  7. The fast loader can get confused if there are locations that start with
     non-alphabetic characters or if there are lines in the file that are
     longer than 1000 characters. Cause of bug: performance optimization of
     fast loader requires these compromises. Workaround: don't do that.
  8. Buttons will sometimes shift out from under the mouse pointer and get
     "stuck on." Cause of bug: (1) button moves due to changing geometry of
     other things in the box, leading to (2) button shifts out from under
     the pointer, which triggers (3) bug in Athena Widgets where the button
     release event gets lost. Workaround: As needed, click on the stuck
     button to un-stick it. This problem can be prevented in the control
     panel by specifying a fixed-width font with the -fn switch, which
     avoids (1). The bug is less likely in other windows.
  9. There are edge effects at the start and end of an interval chosen for
     subordinate station predictions. Some events that are inside of the
     interval may be excluded, and vice-versa. Cause of bug: While the
     interval is faithfully scanned for the reference station, tide events
     can jump in or out of the chosen interval after the offsets are
     applied. Workaround: Leave a margin around the interval of interest
     that is larger than the offsets of the subordinate station (a few hours
     should suffice).
 10. The analog tide clock icon flashes when it updates, and doesn't update
     at all under some window managers. Alternate symptom: tide clocks crash
     the window manager at random. Cause of bug: Window managers don't
     expect icons to keep changing and aren't designed to handle it
     properly. Workaround: Use a window manager that doesn't suck.
 11. Dialog boxes don't behave like you would expect when you hit the Enter
     key. Cause of bug: Athena widgets use multi-line buffers even for
     one-line fields. Workaround: Don't hit Enter.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Image]
Sunset over the bar, Bar Harbor, Maine, 1997-06-24.  1997 David Flater.

Frequently Asked Questions

Q: Can you please add predictions for Mumble Foo Bar?

A: Sorry, I can't. Please read the section entitled What to do if your
location isn't listed.

Q: Can you tell me where I can find a web page with predictions for Mumble
Foo Bar?

A: Sorry, I cannot keep track of all of such web pages. A search engine may
help you.

Q: I'm having a problem with a tide-predicting web page.

A: You are probably using a web page that somebody set up with a CGI
interface to XTide 1. If the predictions don't have a "100% Pure C++" logo
at the bottom, then it's not my web interface and I can't fix it. Please
contact the web site maintainer.

Q: No, really, I'm having a problem with your xttpd. None of the images
work, and the calendars are illegible.

A: You need to get a better web browser. Netscape 4 or Internet Explorer 4
should work.

Q: Please send me today's predictions for Mumble Foo Bar before 11:30.

A: Sorry, I do not have the time to provide this level of service.

Q: Can you tell me the offsets for Mumble Foo Bar?

A: Sorry, I can't. Your best bet is to check local sources as described in
the section entitled What to do if your location isn't listed.

Q: When compiling XTide, I get link errors related to the PNG library even
though I'm using the latest version.

A: Some Unix vendors (SGI) have stuck crappy old versions of libpng in
/usr/lib. If you can't get rid of it, then you need to add the -nostdlib
switch to your link line, and add -L/usr/lib at the end.

Q: I always get a warning about "using obsolete time zone database."

A: That will happen on many platforms, but it won't impact you if you are
only getting predictions for U.S. locations. Please see the System
requirements section for details of what this means and what you can do to
fix it, if you so choose.

Q: How do I switch from tide to current predictions or vice-versa for a
given location?

A: Alas, although the two are clearly connected in the physical world, they
are unrelated from the perspective of XTide. Even for the same location,
tide predictions and current predictions require two completely separate
data sets, and rarely will you get both. If current predictions are
available for a location, they will appear in the location list with the
word "Current" at the end of the name.

Q: You have multiple data sets with the same name or with just numbers to
distinguish them. What's the diff?

A: It often happens that I get more than one data set for the same location.
Sometimes they are from different sources; other times, one is just older
than the other. When I have enough information to know which one is best, I
will make it the first one (with no number). But if you are concerned about
matching predictions up with those from some particular source, you should
try each data set and see which one matches the best.

Q: What are bogo-knots?

A: Way back before I found out that hydraulic current stations generate
results that are actually in units of knots squared, I didn't know what
units they were, so I called them "bogo-knots." Since that time, I have (1)
changed the units in my source data to knots squared, and (2) added
functionality to XTide version 2 to convert these to regular knots.
Therefore, if you are still seeing bogo-knots, then you are definitely using
obsolete data and an obsolete version of XTide, or accessing a web site that
is using obsolete data and an obsolete version of XTide. I am not the
maintainer of any such web sites, and I recommend upgrading to XTide 2,
which will barf all over any harmonics files that still contain
"bogo-knots."

Q: First it says high tide is at 3:15 PM but then when I run it again it
says 3:14 PM.

A: XTide's accuracy is plus or minus one minute. The behavior that you
witnessed is normal.

Q: Has this been ported to Windows / OS/2 / anything but Unix?

A: Yes, to varying degrees. Please see the ports page.

Q: Why do the high and low tides have such different levels to them on any
given day? Does it actually coincide with the amount of pull exerted by the
phase or closeness of the moon?

A: The tides do not coincide too closely with the moon. While the moon
produces most of the force that drives them, the exact tide levels result
from the sloshing around of huge amounts of water, the effects of the shape
of the coastline, and things like that.

Q: Is there a set time advancement each day for the next high and low tide?
Does it always repeat 12 1/2 hours later, or are the calculations a little
more arcane than that?

A: The 12 hour 25 minute cycle is literally only a first order approximation
of semi-diurnal tides. Most tide predictions involve twenty to thirty terms,
and some require over a hundred. The 12:25 cycle is just the most dominant
term.

Q: If it's high tide here, is it low tide in [faraway place]?

A: It's hard to infer anything over large distances since localized effects
can have a huge influence on tides.

Q: What does the zero (0) on a tide chart represent?

A: Tide heights are given relative to the "datum" which in most cases is
Mean Lower Low Water. The zero therefore represents an "average" low tide.
You can find official definitions of "datum" and "mean lower low water" in
NOAA's tide glossary at http://www.opsd.nos.noaa.gov/tideglos.html.

Q: The tides for my location are totally wrong!

A: This seldom happens anymore with up-to-date harmonics files, but if it
does, let me know and I will delete the offending data set. (A
disproportionate number of Florida data sets have bit the dust this way.)

Q: The tides for Mumble Foo Bar are obviously bogus because they have four
high tides on this day / only one high tide on this day / tides that are
just a few minutes apart.

A: That is not necessarily a problem. Some places really do have four high
tides in one day, and other places only have one. Some will generate "extra"
tides once in a while when the tidal forces align in such a way as to
produce an "indecisive" high or low tide (see the Portland, England example
in a previous section). These extra tides can be arbitrarily close together.
Official predictions may omit them, but XTide faithfully reports all maxima
and minima that it finds.

Q: What does slack water mean?

A: This and many other terms are defined in the NOAA tide glossary at
http://www.opsd.nos.noaa.gov/tideglos.html.

Q: I have five constituents and some seasonal corrections for my location.
Can you get this to work?

A: Sorry, I can't. Somebody with more expertise might be able to derive a
full set of constituents from that, but the results would probably still
only be a rough approximation of your tides.

Q: Where's the Java?

A: Gone. I tried Java as an experiment with XTide 1, and it proved to be
unstable, unreliable, and not portable at all from one web browser to the
next, even between the same version of Netscape running on different
platforms. So I no longer use it.

Q: I want to write my own tide predicting program. Can you provide a SIMPLE
explanation of the tide-predicting function?

A:

     The tide prediction function is fairly simple, requiring only a
     cosine function. The piles of code surrounding it in XTide are to
     optimize the process of finding maxima and minima. This can be
     done less optimally with significantly less code and effort (as
     early versions of XTide did).

     Since it is hard to draw summation symbols in ASCII, here is the
     pseudocode instead:

          Height = Datum;
          for a = 1 to numconst
            Height = Height + amplitude * nodefactor * cos (speed * time + phase)
          next a

     The datum is provided at the top of the data set in the harmonics
     file.

     The amplitudes are the first column of numbers in the data set in
     the harmonics file.

     The node factors are tabulated for each year at the top of the
     harmonics file, or can be calculated from scratch using the code
     in the Congen program, available in
     http://www.universe.digex.net/~dave/files/. Most likely you will
     just want to tabulate them.

     The speeds of the numconst constituents are listed at the top of
     the harmonics file in degrees per hour.

     If speed is in degrees or radians per X, then time is in X since
     the beginning of the year. The specific time zone for the
     beginning of the year is chosen as described below.

     Phase includes a yearly adjustment called the equilibrium argument
     that is tabulated at the top of the harmonics file (or calculated
     from scratch like the node factors), minus the location-specific
     phases that are the second column of numbers in the data set
     (given in degrees). By default, you will get phases such that the
     time is measured from January 1 00:00 in the time zone specified
     by the meridian, but it is trivial to adjust the phases for any
     other time zone. What XTide does is adjust them all to UTC and
     then use the Unix time zone functions to render the output with
     Daylight Savings Time and everything.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Design notes

XTide 2 is written in portable C++. I have avoided using any of the fancier,
less portable features of C++ such as the "standard" C++ class library,
exceptions, templates, and namespaces. The only thing I am really using is
the core C++ language, i.e., classes and overloading. If there is any
problem compiling XTide with any C++ compiler, ANSI-compliant or otherwise,
I will attempt to address it. (Someday this C++ portability stuff will all
seem quaint.)

XTide 2 conforms to the honorable old tradition of having command line
switches be no more than two characters long, except where needed for
compatibility with X11.

The usage of XML for subordinate stations is because I have gotten burned
again and again by the inflexible format of the harmonics files. The
expensive extraction of coordinates from comments is a result of this
legacy. However, the cost of using XML is that it's harder to cut corners in
the fast loader. It could be done, but currently I'm just gambling that
Moore's Law will outpace the growth of offsets.xml.

The Right Solution[TM] is to quit doing database type things in XTide and
instead put all of the harmonics data into a Real Database[TM]. I'll be
first on the bandwagon whenever Postgres becomes a required feature of every
Unix installation.

Known design problems:

  1. Nine source files must be changed to add one new setting. I am aware of
     the grand unified setting management system provided by X, but did not
     use it because it would not do what I needed.
  2. I forgot to consider the startup process when adding dependencies
     between different classes, so hokey things are done to avoid getting
     into catch-22 situations. (This is a classic example of what happens
     when you get brainwashed by the OOA&D religion and forget how to
     program.)
  3. I probably should have taken the simple approach in the interactive
     text window, and used TideContext::textMode instead of optimizing the
     scrolling. This would fix bugs #1 and #3. However, the performance
     would be seriously impacted in the negative direction.
  4. The analog tide clock icon caused more problems (with buggy window
     managers) than it was worth.
  5. URLs assigned to prediction pages by the web server should probably be
     based on the harmonics file name and the location name rather than a
     transient "row ID."

The good news, anyway, is that the NOS system of tide prediction that XTide
implements is not totally obsolete yet. Tide agencies around the world are
moving to secretive systems with hundreds of constituents, jealously
guarding the data from public use, but the U.S. is still using the same old
system, and it still works great. Regardless, XTide 2 should expand to
handle Doodson data and whatever else becomes necessary. With the XML
parser, it's no big deal to add totally new kinds of tide stations that will
be handled by newer XTide versions and ignored by older ones.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Credits

Unlike XTide 1, which grew like a weed with code and ideas being contributed
by a small but industrious group of people, XTide 2 was mainly a
cathedral-building exercise on my part (see "The Cathedral and the Bazaar"
by Eric S. Raymond, http://www.ssc.com/linux/Eric/cathedral-paper.html). I
didn't want to make a bloated monster; I just wanted to correct the mistakes
that were made in XTide 1, and clean it up so that it would be more
maintainable. To that end, I switched from clone-and-hack C to
abstract-classes-and-virtual-functions C++. Nevertheless, much of XTide 2 is
just implementation or re-implementation of ideas and code that originated
with the XTide 1 contributors and the members of the beta test mailing list.
XTide 1 began as nothing but a tide clock with no other modes and very few
details, and it was from e-mail feedback and contributed code that I
eventually learned the features and modes that people wanted to see.

Significant chunks of code in XTide 2 came from the following people:

     John Thorstensen allowed me to re-use code from his skycal
     distribution (ftp://iraf.noao.edu/contrib/skycal.tar.Z) to get the
     sunrise, sunset, and phase of moon calculations.

     Geoffrey T. Dairiki's fast root-finding code survives in XTide 2
     with only a C++ veneer.

Other contributions:

     Alan Eugene Davis deserves special mention for being the world's
     best beta tester, offering timely and constructive feedback on
     practically every revision.

     Thanks to Edward P. Wallner for lots of valuable information and
     tide data, including the Anchorage predictions that are so cool.

     Beta testers: thanks to Dean Pentcheff for early beta testing and
     feedback; to Victor Bom for a 32/64-bit fix for the DEC Alpha; to
     Alan J. Wylie for AIX debugging; and to David Warren for an SGI
     portability patch.

     ...and a belated, very probably posthumous thanks to Paul
     Schureman, whose Special Publication No. 98 from the old U.S.
     Coast & Geodetic Survey in 1924 remains the canonical source for
     the tide prediction methodology implemented by XTide.

The XTide 1 contributions are summarized below. I have removed e-mail
addresses from this documentation because it was too big of a maintenance
hassle with people always moving around. If you need to contact someone,
e-mail me and I will supply the most recent address that I have.

(This list was copied from the XTide 1 documentation, and is in no
particular order.)

     Thanks to Greg Seidman for suggesting many of the features that
     appeared in version 1.

     Thanks to Frank Smith for supplying data and putting up with my
     confused e-mail during the stressful debugging of 1.0.1.

     Thanks to Karl Hahn, Tom Brown and "George" for supplying a huge
     number of harmonic constants.

     Thanks to Jean-Pierre Lapointe for supplying the Canadian
     harmonics file and lots of other harmonics, and also the unequal
     offsets interpolation algorithm.

     Thanks to Edward P. Wallner for the endless time, effort, and cash
     that he spent getting harmonic constants out of the dusty decks of
     the world's hydrographic bureaus and onto the Internet where they
     belong, and for mentoring on the calculation of node factors and
     equilibrium arguments.

     Thanks to Dale DePriest for suggesting many new features, beta
     testing, and porting to several flavorful operating systems.

     Thanks to Dean Pentcheff for beta testing, suggesting features,
     coding GIF support, supplying many data sets, and generally being
     very active in promoting XTide.

     Thanks to Jef Poskanzer for much coding, suggesting of features,
     and beta testing.

     Thanks to Jack Greenbaum for much coding, suggesting of features,
     beta testing, and doing the homework to get prediction of currents
     figured out.

     Thanks to Rob Miracle and Simon Burge for helping with Ultrix
     compatibility. Additional thanks to Simon for helping diagnose
     failures that only occurred in the southern hemisphere.

     Thanks to Scott Hemphill and Edward J. Corbett for equilibrium
     arguments, node factors, and some accuracy improvements in the
     harmonics file.

     Thanks to Toru Suzuki for providing and maintaining the
     harmonics.japan file.

     Thanks to Georg Vollmers, Tom Varga, Bob Kenney, Alan Eugene
     Davis, Bruce Bowler, Phil Hughes, and Graeme Rae for suggesting
     new features and/or beta testing.

     Thanks to Andrew Davidson for helping with Solaris compatibility.

     Thanks to Geoff Kuenning for the SunOS patch.

     Thanks to Jeff Small for suggesting features and writing the man
     page.

     Thanks to Mikhail Fridberg for doing the Mac port.

     Thanks to Paul C. Roberts and "Alex" for porting XTide to
     Microsoft Windows. Thanks to Mike Hopper for doing an updated port
     to Windows 95 and NT.

     Thanks to Walt Bilofsky for the Palm Pilot derivative (Tide Tool).

     Thanks to Stan Uno for Alpha and Macintosh patches.

     Thanks to Jeff Dairiki for the jumbo performance patch and
     excellent bug fixes.

     Thanks to Eric Rosen for the BSD/OS 2.1 patch.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Bibliography

Canonical sources on the NOS tide prediction methodology (including a
mathematical explanation from first principles in SP98):

     Manual of Harmonic Analysis and Prediction of Tides. Special
     Publication No. 98, Revised (1940) Edition (reprinted 1958 with
     corrections; reprinted again 1994). United States Government
     Printing Office, 1994.

     Computer Applications to Tides in the National Ocean Survey.
     Supplement to Manual of Harmonic Analysis and Prediction of Tides
     (Special Publication No. 98). National Ocean Service, National
     Oceanic and Atmospheric Administration, U.S. Department of
     Commerce, January 1982.

Those can be ordered from NOAA for $5 or $10, depending on the phase of the
moon.

My sources for X-windows programming reference:

     Kimball, Paul E. The X Toolkit Cookbook. Prentice Hall P T R, New
     Jersey, 1995.

     Nye, Adrian. Xlib Programming Manual. O'Reilly & Associates, Inc.,
     Volume 1, Third Edition, July 1993.

  ------------------------------------------------------------------------

   * Contents
[Icon] Differences from XTide 1

XTide 2 is a complete redesign of XTide 1. There are too many subtle
improvements to list them all, but here are the not so subtle ones:

   * New interactive user interface for X windows client
   * Integrated web server now provided in distribution
   * Simpler, better command line interface
   * Handles multiple harmonics files transparently
   * Subordinate stations are now stored in an external database, and are
     expanded to handle all known styles of offsets
   * Hydraulic currents are fixed
   * Removed useless options and modes
   * Added sunrise, sunset, phase of moon

These are the non-obvious things you must know in order to migrate:

  1. The environment variable HFILE is no longer used to specify the
     harmonics file; instead, HFILE_PATH is used:

          export HFILE_PATH=/etc/harmonics:/etc/offsets.xml:/etc/harmonics.anchorage

     If HFILE_PATH is not set, XTide looks for the file "harmonics" in the
     default directory.
  2. XTide now has its own built-in icon. Remove any icon settings that you
     made in your window manager init files.
  3. You may no longer use anonymous units in harmonics files. The units
     must be one of the recognized alternatives. These are: feet, meters,
     knots, knots^2 (for hydraulic currents). If you are still using an
     ancient harmonics file that contains no units or "bogo-knots," then
     shame on you. It's high time that you upgraded.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Quick install instructions

  1. XTide requires:
        o libXpm version 4.3 or later (a.k.a. xpm-3.4, go figure)
        o libpng version 0.96 or later
        o libz version 1.0.4 or later (a.k.a. zlib-1.0.4)
  2. You must download at least one harmonics file from
     http://www.universe.digex.net/~dave/files/.
  3. You must set the environment variable HFILE_PATH to point to the
     harmonics files that you downloaded. Example:

          export HFILE_PATH=/etc/harmonics:/etc/offsets.xml:/etc/harmonics.anchorage

  4. If your Imake is known to work, do this to compile:

          xmkmf; make depend; make

     Otherwise, copy Makefile.std to Makefile, edit as needed, and type
     make.
  5. You should now have three binaries:
        o xtide, the interactive X-windows client
        o tide, the non-interactive TTY client
        o xttpd, the web server
  6. The X-windows client is easy to use. Go for it.
  7. tide does a few things that xtide doesn't do. Run it with nothing on
     the command line and read the usage info.
  8. xttpd is a self-contained web server. Fire it up and browse away. If
     you don't have root or if you already have a web server running,
     provide a port number (e.g., 8080) on the command line when you start
     it, and find it at http://your.site.net:8080/ instead of
     http://your.site.net/. Set the environment variable XTTPD_FEEDBACK to
     change the feedback address. (You can also change the compiled-in
     default in config.hh.)

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] Change log

XTide 2.0 Beta.3 (1998-06-28)

Reversed order of location list latitude sort so that points north appear at
the top (sug. Dave Davey).

XTide 2.0 Beta.2 (1998-06-02)

SGI portability fix from David Warren: changed declarations of nested
structs in header files to use Classname::structname instead of struct
structname.

XTide 2.0 Beta.1 (1998-06-01)

First versioned release of XTide 2.

  ------------------------------------------------------------------------

   * Next
   * Contents
[Icon] News

The Creeping Feature List

This list is not a promise to implement, but only an acknowledgement that
the following features have been requested or thought about. Please let me
know if you intend to submit code for one of these so that I can try to keep
people from duplicating effort. As guardian of the architecture, I reserve
the right to reject code whose bloat and munge factors exceed the benefits.

If you want to register a vote for or against any of these features, just
send e-mail (dave@universe.digex.net). Please specify one of the following:
(1) I *NEED* this; (0) I don't *NEED* this, but it would be nice, whine
whine; or, (-1) this is useless bloat, kill it, kill it.

Bug fixes or features having scientific and technical merit

   * DWF: Add support for Doodson stations? (See "Help Wanted" below).

User interface improvements

   * DWF: Note moon phases in tide graphs somehow.
   * DWF: Add a real color chooser in control panel.
   * DWF: Make date/time format dialog more user-friendly.
   * DWF: Change mapping of locations to URLs so that links won't break when
     harmonics files are changed.
   * AED and Dean Pentcheff want outlines of continents on the globe. I'm
     fighting this because the performance of the location chooser seems too
     slow already.
   * Jef Poskanzer long ago asked for a global plot of tide levels to show
     how the tides move around. This could be done by color-coding the dots
     on the globe, but it would (1) require a true-color display and (2) be
     too slow to be the default behavior of the globe.
   * "Grant, Diane DC" <Grant.Diane.DC@bhp.com.au> wants to be able to
     execute a query like 'find all days in this year having a flood greater
     than 3.0 between 8 AM and 9 AM.'
   * AED: Want to be able to append with -o instead of overwrite.

Code cleanups

   * DWF: Clean up xxTimestamp using xxMultiChoice.

Data maintenance

(These don't require changes to XTide)

   * Action item for Alan Eugene Davis: Add subordinate stations in his
     local area to offsets.xml.
   * DWF: Con somebody into entering all of the subordinate stations that
     NOAA now provides at http://www.opsd.nos.noaa.gov/tp4days.html.
     Currently working on this: hal@peak.org
   * DWF: Figure out what's up with the constituents OP2, OQ2, MKS2, and NO1
     in harmonics.canadian and finish the Congen file. The purpose of this
     exercise is to expand harmonics.canadian to work with years before 1994
     and after 2025. N.B., harmonics.japan is nearly identical; only M1 is
     different.
   * Action item for Toru Suzuki: waiting on corrections to Japanese tide
     data that were submitted by Ed Wallner. (No contact since 1997-07-05)
   * DWF: Add remainder of NOS 37 stations to harmonics.
   * DWF: Create harmonics.aus for the remaining Australian data? (See
     below.)
   * DWF: Create harmonics.nz to approximate the New Zealand data? (See
     below.)

  ------------------------------------------------------------------------

                                Help Wanted

I say: "When the going gets tough, delegate." Please read 'Caveats' at the
bottom before volunteering for anything.

Implementing the Doodson System

There are two competing methods of tide prediction: the NOS method, which
XTide implements, and the Doodson method, which is used for lots of tide
predictions outside of the U.S.

The major incompatibility between them is that the Doodson method uses the
latitude of the tide station as an input, and the NOS method does not. In
the NOS method, all of the tricky astronomical calculations can be done once
and henceforth read from tables. With Doodson, either you do it from scratch
for every station, or else you approximate by choosing a mediocre latitude
and using that for all stations.

nickw03@ibm.net has provided a Fortran program and source data that does
most, but not all, of the constituents that appear in the troublesome
non-U.S. tide data that Ed Wallner sent me. With a lot of work, using this
program as a cookbook, XTide could be extended to support the Doodson
system. Doodson stations would be added as a new XML type to avoid
conflicting with the NOS data, and as a new subclass of ReferenceStation in
the program.

Math Is Hard

Once in a long while, someone will ask me if I have a program to convert raw
tide level readings into a set of harmonic constants. I still don't because
I lost the tutorial that someone sent me on how to do it. ("Lost" is a
euphemism for "my hard drive crashed and I hadn't backed up my e-mail
because it didn't seem that important at the time.")

This should be a Simple Matter of Programming for anyone whose math skills
are strong enough to know what "Solving for this in the least squares sense"
refers to in the NOS documentation. Inputs: (1) a harmonics file containing
the constituent speeds, equilibrium arguments and node factors for all
relevant years; (2) a long list of tide level readings in the format output
by XTide's raw mode. Outputs: (1) a set of harmonic constants using the
constituents in the selected harmonics file; (2) the residual statistics.

Reconciling Constituents from Canada, Mexico, Australia, New Zealand

In some cases, the same constituent names are used to mean different things
by different tide agencies around the world. Having already processed most
of the obviously NOS data that was on hand, I have now reached the point
where I don't have confidence that I'm making the right guesses about which
constituents are what. There are also constituents in use for which I have
absolutely no information.

I still have the following data remaining to be converted:

   * More Australian data that uses yet more constituents, all of which have
     some variation in either harmonics or harmonics.canadian now.
     Previously, all Australian data used the constituents in
     harmonics.admiralty, which I distilled from harmonics.canadian without
     knowing whether they are really the right versions of the constituents.
     Somebody who knows more than I do should really review the Congen file
     and make sure it's right.
   * New Zealand data that seems to be on the Doodson system. Most of the
     mysterious constituents are defined in the Fortran program from
     nickw03@ibm.net, but there is one location that has a few unknowns. The
     best I could do with this is try to approximate the Doodson
     constituents in a separate harmonics file and throw out the one data
     set that has undefined constituents, or wait until somebody adds direct
     Doodson support to XTide.
   * Mexico and British Columbia data with reams of random constituents.
     Most seem fairly obvious, but since Canada uses incompatible variations
     of NOS constituents, anything that I do with this data will be
     guesswork.

I have not yet even managed to make a Congen file to replicate what
Jean-Pierre Lapointe did with a few of the constituents in
harmonics.canadian. Almost, but not quite. I figured out that NO1 is N2 - O1
but with the node factors from the NOS version of M1. I figured out that the
arguments for OP2 and OQ2 are twisted around by 180 degrees for no obvious
reason. But for MKS2, I haven't managed to replicate anything but the speed
using Congen formulas. And if I ever succeed, how do I know that these are
the right definitions to use for the British Columbia data that I have
sitting around?

The bottom line is that somebody with more background knowledge needs to be
doing this.

Caveats

There are some reasons why you might not want to embark on one of these
quests.

  1. Relative to the amount of data that has already been converted, the
     amount of data that I'm stuck on is not really significant. Unless you
     live in New Zealand and really need those tide predictions, the work is
     more academic than practical.
  2. Australia has privatized its tide prediction service, and Canada no
     longer distributes tide data to the public. The data that I have,
     particularly in the case of Australia, is likely to be obsolete. This
     trend towards secrecy and privatization also means that not much new
     Doodson data is likely to surface.
  3. Not too many people have access to a year's worth of tide level
     readings to go deriving their own harmonic constants.

If you still want to tackle one of these tasks, e-mail me at
dave@universe.digex.net. Thanks.

  ------------------------------------------------------------------------

   * Contents
