                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.flaterco.com/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.flaterco.com/xtide/files.html

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

[Tide closes in]

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)

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

-- David Flater (software@flaterco.com)

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

NOTE.  The license and disclaimer appearing below applies to the XTide
program itself.  For information about permissions on the harmonic constants
in harmonics.txt, read the boilerplate (a copy is available at
http://www.flaterco.com/xtide/harmonics_boilerplate.txt).

                    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
[Perkins Cove, Maine, 1998-06-09]

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.  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
[Nobska Light, Cape Cod, MA, 1998-06-17]

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.

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 from
ftp://ftp.cdrom.com/pub/X11/contrib/libraries/ 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.libpng.org/pub/png/libpng.html.  These, too, are available
with most up-to-date Linux distributions.  Some commercial Unixes 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
[Lobster boat and the big ocean, Ogunquit, Maine, 1998-06-08.]

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.flaterco.com/xtide/files.html 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.xyz.tar.gz | tar xvf -

To uncompress a harmonics file:

     gzip -d harmonics.txt.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., /usr/local/share/xtide, and make them world readable:

     mkdir /usr/local/share/xtide
     chmod 755 /usr/local/share/xtide
     chmod 644 harmonics.txt offsets.xml
     mv harmonics.txt offsets.xml /usr/local/share/xtide

Configuring

  1. You need to set the environment variable HFILE_PATH to point to your
     harmonics files.  If you are using offsets.xml, it is advisable to put
     it at the end of the list to ensure that reference stations will
     resolve properly.  Example:

          export HFILE_PATH=/usr/local/share/xtide/harmonics.txt:\
          /usr/local/share/xtide/offsets.xml

     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.

     NEW with version 2.4:  If an element of HFILE_PATH is a directory,
     XTide will attempt to load every file in that directory (so be sure
     that they are all XTide files!)

     NEW with version 2.2:  To facilitate packaging for Linux distributions,
     the file /etc/xtide.conf may be used in lieu of HFILE_PATH to supply
     the harmonics path.  The environment variable, if set, takes precedence
     over the config file.  /etc/xtide.conf should contain the value that
     would be assigned to HFILE_PATH, on one line:

     /usr/local/share/xtide/harmonics.txt:/usr/local/share/xtide/offsets.xml

  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

Version 2.2 or later

Type the following at the shell prompt to compile:

     ./configure; make

Do 'make install' as root to install the binaries and man pages under
/usr/local.

./configure understands the basic GNU Autoconf flags; to install under /usr
instead of /usr/local you would do './configure --prefix=/usr'.

If you need to wedge in some extra flags for compiling and linking, set the
variables extracxxflags and extraldflags before running configure.  For
example, to search /mumble/foo/include for include files, you could do

     extracxxflags="-I/mumble/foo/include" ./configure

under the Bourne shell.  You can also preselect the C++ compiler to use by
setting the variable CXX.  HP-UX users may need to do this, since autoconf
does not look for aCC:

     CXX="aCC" ./configure

If you need to reconfigure after changing any settings, remove the
config.cache file to ensure that your changes will take effect.

HP-UX

If CXX is set to aCC, configure will add compile and link switches copied
from the old Imakefile.hp.  If you are not using aCC, you may need to set
some flags yourself:

     extracxxflags="-I/opt/aCC/include/iostream" extraldflags="-lPW" ./configure

Machines without X11

If you don't have any version of X11 installed and just want to compile
xttpd or tide, generate a Makefile using ./configure and then type 'make
xttpd' or 'make tide'.  You will probably need to install the binaries by
hand.

Older versions

Versions of XTide before 2.2 used Imake instead of Autoconf to generate
makefiles.  A hacked Imakefile was provided to work around problems under
Solaris, but it never worked all that well.  Another hacked Imakefile was
provided for HP-UX.

Replace Imakefile with the hacked version of your choice, then type the
following at the shell prompt to compile:

      xmkmf; make depend; make

If your Imake is properly configured, that should do it.  ('make depend' is
usually broken under Solaris; you may need to skip that step.)  When the
compilation is complete, install the binaries and man pages by hand -- 'make
install' does not work.

If all else fails

Copy Makefile.in (version 2.2 or later) or Makefile.std (older versions) to
Makefile and edit as needed.

Troubleshooting

Q: When compiling XTide, I get many errors like:

In file included from xtide.hh:5,
                 from xtide.cc:21:
/usr/openwin/include/X11/Xlib.h:2099: ANSI C++ forbids declaration `XSetTransientForHint' with no type

A: The combination of newish GCC versions and archaic X11 header files that
leads to this error routinely occurs under Solaris.  If you add -fpermissive
to your extracxxflags as described above, the errors will become warnings
and compilation should succeed.

Q: When compiling XTide, I get:

xxContext.o: In function `xxContext::makePixmap(char **, Visual *, unsigned long, unsigned int)':
xxContext.o(.text+0xc51): undefined reference to `XpmCreatePixmapFromData'
RGBGraph.o: In function `RGBGraph::writeAsPNG(void (*)(png_struct_def *, unsigned char *, unsigned int))':
RGBGraph.o(.text+0x3c3): undefined reference to `png_set_IHDR'
make: *** [xtide] Error 1

A: This relates to the old, Imake way of compiling.  The
XpmCreatePixmapFromData error is because for some reason your Imake didn't
put -lxpm on the link line.  Use makefile.std instead.  The png_set_IHDR
error is answered in the next FAQ (see below).

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 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
[The tide cometh, Provincetown, MA]

Available ports (and non-ports) for non-Unix platforms

If a program is derived from XTide source code, I call it a port.  If a
program contains no XTide source code but uses XTide data files, I call it a
non-port.  These are only listed if there is no good port to a given
platform.  This is not an attempt to track all tide-predicting software,
only that with some connection to XTide.  Better software having nothing to
do with XTide may be available, but is not listed here.

These programs are all maintained by different people.  They may be
significantly different from XTide 2 as documented here.  If you have
problems with a port or non-port, please contact the correct maintainer.  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.wxtide32.com/.
   * 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.

Macintosh

There are no good ports of XTide to the Mac at this time.  There is a GPL'd
non-port called Mr. Tides that you can find at
http://www.exmsft.com/~augusth/Tides/Tides.html.

There were several bad ports of XTide to the Mac.  The first was a port of
just the text client from XTide 1.3 that is reported to have succumbed to
software rot.  The others were ports of the graphical client made by
[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 for the Palm
                  Pilot or any other compatible device running PalmOS.
Judging from the picture it does produce output comparable to that of
XTide.  The URL for Tide Tool is
http://www.toolworks.com/bilofsky/tidetool.htm.

Bilofsky writes: "Tide Tool used to qualify as a port, and still has a
modest amount of code from XTide 1.5.  But since Jeff Dairiki redid the
algorithm to use integer math, I'm not sure how much of it is XTide any
more.  I guess I'd call it the descendant of a port."

HP Calculator

                     David MacCuish has done a similar-in-spirit non-port
                     for HP48 series calculators.  As of 2000-09-20, HpTide
is still in development.  MacCuish writes: "I have a new release out.  This
one has many improvements, and 30 locations.  Locations are now much easier
for me to convert and if anyone wants a specific one from v1.10 of the
harmonics file they can simply e-mail me requesting that I post it on my
site."

HpTide can be found at http://www.northcoast.com/~heygus/hptide.html.

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.

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

   * Next
   * Contents
[Pemaquid bell]

Modes

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.

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 arranges most of the information available in text mode into a
commonly used tabular layout.

 Day   High             High             High     Moon    Sunrise   Sunset
                Low              Low

 Sun 1:30 AM  8:36 AM 1:56 PM 8:44 PM          First      6:13 AM  8:13 PM
 6   EDT /    EDT /   EDT /   EDT /            Quarter    EDT      EDT
     3.10 ft  0.19 ft 2.86 ft 0.05 ft

 Mon 2:27 AM  9:33 AM 2:57 PM 9:33 PM                     6:14 AM  8:12 PM
 7   EDT /    EDT /   EDT /   EDT /                       EDT      EDT
     3.01 ft  0.30 ft 2.70 ft 0.18 ft
              10:31           10:23
 Tue 3:24 AM  AM EDT  3:58 PM PM EDT                      6:15 AM  8:11 PM
 8   EDT /    / 0.38  EDT /   / 0.30                      EDT      EDT
     2.96 ft          2.61 ft
              ft              ft
              11:29           11:16
 Wed 4:21 AM  AM EDT  4:57 PM PM EDT                      6:16 AM  8:09 PM
 9   EDT /    / 0.42  EDT /   / 0.39                      EDT      EDT
     2.94 ft          2.58 ft
              ft              ft
              12:25
 Thu 5:16 AM  PM EDT  5:52 PM                             6:17 AM  8:08 PM
 10  EDT /    / 0.43  EDT /                               EDT      EDT
     2.98 ft          2.61 ft
              ft
              12:09
 Fri          AM EDT  6:07 AM 1:17 PM  6:43 PM            6:18 AM  8:07 PM
 11           / 0.46  EDT /   EDT /    EDT /              EDT      EDT
              ft      3.04 ft 0.42 ft  2.68 ft

 Sat          1:01 AM 6:53 AM 2:04 PM  7:30 PM            6:19 AM  8:06 PM
 12           EDT /   EDT /   EDT /    EDT /              EDT      EDT
              0.50 ft 3.13 ft 0.40 ft  2.77 ft

"Alt" calendar mode arranges the information into a traditional weekly
calendar layout.

    Sun 6      Mon 7     Tue 8      Wed 9     Thu 10    Fri 11     Sat 12
 High Tide
 3.10 ft
 1:30 AM    High Tide  High Tide High Tide            Low Tide   Low Tide
 EDT        3.01 ft    2.96 ft   2.94 ft              0.46 ft    0.50 ft
 Sunrise    2:27 AM    3:24 AM   4:21 AM    High Tide 12:09 AM   1:01 AM
 6:13 AM    EDT        EDT       EDT        2.98 ft   EDT        EDT
 EDT        Sunrise    Sunrise   Sunrise    5:16 AM   High Tide  Sunrise
 Low Tide   6:14 AM    6:15 AM   6:16 AM    EDT       3.04 ft    6:19 AM
 0.19 ft    EDT        EDT       EDT        Sunrise   6:07 AM    EDT
 8:36 AM    Low Tide   Low Tide  Low Tide   6:17 AM   EDT        High Tide
 EDT        0.30 ft    0.38 ft   0.42 ft    EDT       Sunrise    3.13 ft
 High Tide  9:33 AM    10:31 AM  11:29 AM   Low Tide  6:18 AM    6:53 AM
 2.86 ft    EDT        EDT       EDT        0.43 ft   EDT        EDT
 1:56 PM    High Tide  High Tide High Tide  12:25 PM  Low Tide   Low Tide
 EDT        2.70 ft    2.61 ft   2.58 ft    EDT       0.42 ft    0.40 ft
 Sunset     2:57 PM    3:58 PM   4:57 PM    High Tide 1:17 PM    2:04 PM
 8:13 PM    EDT        EDT       EDT        2.61 ft   EDT        EDT
 EDT        Sunset     Sunset    Sunset     5:52 PM   High Tide  High Tide
 Low Tide   8:12 PM    8:11 PM   8:09 PM    EDT       2.68 ft    2.77 ft
 0.05 ft    EDT        EDT       EDT        Sunset    6:43 PM    7:30 PM
 8:44 PM    Low Tide   Low Tide  Low Tide   8:08 PM   EDT        EDT
 EDT        0.18 ft    0.30 ft   0.39 ft    EDT       Sunset     Sunset
 First      9:33 PM    10:23 PM  11:16 PM             8:07 PM    8:06 PM
 Quarter    EDT        EDT       EDT                  EDT        EDT
 9:02 PM
 EDT

Calendar mode is not available from the interactive client.

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):

Day     High            High            High    Moon    Sunrise Sunset
                Low             Low

Sun  6  1:30 AM 8:36 AM 1:56 PM 8:44 PM         First Q 6:13 AM 8:13 PM
Mon  7  2:27 AM 9:33 AM 2:57 PM 9:33 PM                 6:14 AM 8:12 PM
Tue  8  3:24 AM 10:31 A 3:58 PM 10:23 P                 6:15 AM 8:11 PM
Wed  9  4:21 AM 11:29 A 4:57 PM 11:16 P                 6:16 AM 8:09 PM
Thu 10  5:16 AM 12:25 P 5:52 PM                         6:17 AM 8:08 PM
Fri 11          12:09 A 6:07 AM 1:17 PM 6:43 PM         6:18 AM 8:07 PM
Sat 12          1:01 AM 6:53 AM 2:04 PM 7:30 PM         6:19 AM 8:06 PM

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

   * Next
   * Contents
[Cutler in the fog]

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
[Perkins Cove, Maine, 1998-06-09]

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.

If you use the same location a lot, you can set the environment variable
XTIDE_DEFAULT_LOCATION to its name instead of using -l every time.

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

   * Next
   * Contents
[Moonrise over Marginal Way]

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

If you use the same location a lot, you can set the environment variable
XTIDE_DEFAULT_LOCATION to its name instead of using -l every time.

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|C|g|l|p|r|s
     Specify mode to be banner, calendar, alt. 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 (appends).
-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
[Prospect Harbor Pt. Light, Prospect Harbor, Maine, 1998-06-14]

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.

Starting with XTide version 2.2, xttpd forks itself into the background and
uses the syslog facility for all logging.  Hosts connecting to xttpd are
logged with priority INFO.

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
[Sunset over the bar, Bar Harbor, Maine, 1997-06-24]

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: %l
     Command line: -hf
     config.hh: hourfmt
     .xtide.xml: <xtideoptions hf="%l"/>
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*nosunmoon
     Suppress sunrise, sunset, moon phases? (y/n)
     Default: n
     Command line: -ns
     config.hh: nosunmoon
     .xtide.xml: <xtideoptions ns="n"/>
XTide*timefmt
     Strftime style format string for printing times.
     Default: %l:%M %p %Z
     Command line: -tf
     config.hh: timefmt
     .xtide.xml: <xtideoptions tf="%l:%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"?>
     <xtideoptions tw="79" th="24"/>

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

   * Next
   * Contents
[National Ocean Service tide station at Bar Harbor, Maine, 1997-06-24]

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 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.flaterco.com/xtide/harmlist.html.  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 need to obtain either a set
of harmonic constants or a set of corrections.  These are explained in more
detail below.

Harmonic constants

Harmonic constants of the first kind, the kind worth having, are created by
analysis of regular water level readings taken by automated tide stations
like the one pictured above.  Harmonic constants of the second kind, the
kind not worth having, are created by mangling the first kind to approximate
the results of applying corrections.  We are only interested in the first
kind.  XTide can do corrections properly, so mangled data just junks up the
database.

As far as I know, all published reference stations for the U.S. are already
supported.  If one has been missed, you might be able to obtain it from NOAA
for between $10 and $40.  A tolerable facsimile might be available for free
from
http://co-ops.nos.noaa.gov/data_retrieve.shtml?input_code=100201001har.  If
so, let me know it's there and I'll snag it.

In countries other than the U.S., you might have a really hard time getting
the resident tide-predicting authority to release data.  Usually it is
because they want to retain a lucrative monopoly on tide predictions, though
some may be afraid that the data will be used to time an invasion by sea.
Regardless, if you do manage to obtain harmonic constants, please obtain and
forward to me a statement from the authority either granting permission for
non-commercial use with XTide or explaining that such permission is not
required.

I actually still have a collection of old harmonic constants for ports world
wide that had to be withdrawn because of the permissions issue (for the full
sob story, see the FAQ).  If you have contact with your local marine
authorities and could obtain and forward a statement that use of this tide
data is not restricted in your region, it could be reinstated.  However, it
would be better if they just sent me the newest data.

If you have access to a year's worth of regular water level readings for
some locale, you can derive the harmonic constants yourself using the
Harmgen program available from http://www.flaterco.com/xtide/files.html.

Corrections

A subordinate station is a tide station whose predictions are obtained by
applying corrections to a reference station, i.e., one for which we have
good harmonic constants.  The words 'corrections,' 'differences,' and
'offsets' are used interchangeably.

You should be able to get offsets with relative ease from a local boating
magazine, chartbook, yacht club, or marine authority.  Another source is
NOAA's web page at http://co-ops.nos.noaa.gov/tp4days.html.  The file at
http://www.flaterco.com/xtide/lots_of_offsets.txt contains similar data, but
has already been imported.  If you find suitable offsets, you can add them
to the file offsets.xml (available from
http://www.flaterco.com/xtide/files.html).

There are many different flavors of offsets for subordinate stations.  At
this time, XTide supports all known flavors except for the Admiralty one
that has different height differences depending on the time of month.

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.

BEWARE:  If your reference station is in a different time zone, you may need
to alter the time offsets to REMOVE compensation for the time zone
difference.  In XTide, offsets are independent of the time zone.

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"
       note="This is just an example of how to add a note.">
     <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 33 ft. 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, 33 ft. below datum Current"
       pedigree="NOS data via Ed Wallner"
       latitude="37.7945"
       longitude="-122.28583333"
       timezone=":America/Los_Angeles"
       reference="San Francisco Bay Entrance (Golden Gate), California Current">
     <offsets>
       <max>
         <timeadd value="-0:48"/>
         <levelmultiply value="0.1"/>
         <avglevel value="0.3" units="knots"/>
         <direction value="082" units="degrees true"/>
       </max><min>
         <timeadd value="-1:40"/>
         <levelmultiply value="0.1"/>
         <avglevel value="0.2" units="knots"/>
         <direction value="255" units="degrees true"/>
       </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.flaterco.com/xtide/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.

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

   * Next
   * Contents
[Bald Head Cliff, Ogunquit, Maine, 1998-06-15]

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
[Morning in OC]

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.
  6. The raw tide levels for subordinate current locations whose reference
     stations are hydraulic will do bogus things for a few minutes around
     the time of slack water.  Hydraulic currents exacerbate a minor
     inaccuracy that exists for all subordinate stations, producing a major
     inaccuracy.

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
[Buoy in the mist]

Frequently Asked Questions

   * Can you please add predictions for Mumble Foo Bar?
   * Can you tell me where I can find a web page with predictions for Mumble
     Foo Bar?
   * I'm having a problem with a tide-predicting web page.
   * Can you send me predictions for Mumble Foo Bar?
   * Can you tell me the offsets for Mumble Foo Bar?
   * I live outside of the U.S. and my location is no longer supported.
     What happened?
   * For Chesapeake and Delaware Canal Current, Flood and Ebb are not
     informative.  Which way is which?
   * For Cape Cod Canal Current, Flood and Ebb are not informative.  Which
     way is which?
   * When compiling XTide, I get errors like....
   * I always get a warning about "using obsolete time zone database."
   * How do I switch from tide to current predictions or vice-versa for a
     given location?
   * You have multiple data sets with the same name or with just numbers to
     distinguish them.  What's the diff?
   * What are bogo-knots?
   * First it says high tide is at 3:15 PM but then when I run it again it
     says 3:14 PM.
   * Has this been ported to Windows / OS/2 / anything but Unix?
   * Why do the high and low tides have such different levels to them on any
     given day?
   * Is there a set time advancement each day for the next high and low
     tide?  Does it always repeat 12 1/2 hours later?
   * If it's high tide here, is it low tide in [faraway place]?
   * What does the zero (0) on a tide chart represent?
   * Why is it that the tides two miles from here are an hour different than
     the tides here?
   * The tides for my location are totally wrong!
   * 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.
   * Why are there two high tides per day, anyway?  How is this possible?
   * What does "slack water" mean?
   * I have five constituents and some seasonal corrections for my
     location.  Can you get this to work?
   * I want to write my own tide predicting program.  Can you provide a
     SIMPLE explanation of the tide-predicting function?
   * Hey, man, like, what happened to the Java?

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

A: Probably not.  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: Dean Pentcheff's interface to XTide at
http://tbone.biol.sc.edu/tide/sitesel.html seems to be really popular.
However, there are lots of sites running xttpd (the supported XTide web
interface) and lots more that just serve predictions for specific localities
in their own special way.  I cannot keep track of all of such web pages, but
a search engine might help you.

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

A: I am not the right person.  Please contact the web site maintainer.

Q: Can you send me predictions for Mumble Foo Bar?

A: I cannot possibly provide this level of service to everyone who wants
it.  Please use a web site.

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

A: You can get them easier than I can by checking the sources described in
the section entitled What to do if your location isn't listed.

Q: I live outside of the U.S. and my location is no longer supported.  What
happened?

A: After a complaint from the U.K. Hydrographic Office and the subsequent
discovery that country-by-country permissions are now required to use
harmonic constants (data needed to predict tides), the distributions of data
that spanned many countries (all of the data originating with the
International Hydrographic Office or the Table des Mares des Grands Ports
du Monde) have been removed.

Back in the old days, the collection of hydrographic data was done almost
exclusively using public funds.  The resulting harmonic constants were
treated as scientific results, published, and distributed on request from an
international data bank.  But in the late 20th century, a wave of
privatizations occurred, and harmonic constants became the intellectual
property of the collecting agencies.

You wouldn't think it possible to "un-publish" data that was distributed
with considerable freedom at one time.  Nevertheless, at this time the
international data bank is no more, the Table des Mares des Grands Ports du
Monde has been withdrawn from publication, and I have been forced to remove
the associated data from the XTide database.

For my own part, I do not consider privatization to be inherently evil.  It
would have been reasonable to keep newly generated data secret while leaving
the old data in the public domain until it became useless from age.  But in
my opinion it was wrong to lay claim to the old data that was once shared in
the spirit of scientific openness.  It was a disservice and dishonor to all
of us who accepted and used that data on good faith, and donated our own
time to maintain it and add value to it, only to end up accused of copyright
infringement.

Although as of now only the U.K. has made an issue of it, the fact that they
did suffices to "poison" all of the IHO data, for every country.  We can no
longer assume that we have permission to use any of it.  In countries other
than the U.K., if you have contact with your local marine authorities and
could obtain and forward a statement that usage of the old data is not
restricted in your region, it could be reinstated.  However, if they have
newer data, it would be better if they just sent me that, with all necessary
permissions attached.  I regret that countries having no recognizable tide
authority have been effectively disenfranchised.

The U.S. is different because there is a law stating that government
publications are in the public domain, with few exceptions, and it happens
that the National Ocean Service is still in the government.

Q: For Chesapeake and Delaware Canal Current, Flood and Ebb are not
informative.  Which way is which?

A: Based on observations by Richard W. Reynolds and friends, it appears that
"Flood" for this data set indicates that water is flowing from the
Chesapeake to the Delaware bay.

Q: For Cape Cod Canal Current, Flood and Ebb are not informative.  Which way
is which?

A: According to Reinhard Schumann, "Flood" for this data set means "current
towards the east."  Woods Hole current is probably the same.

Q: When compiling XTide, I get errors like....

A: Please refer to the troubleshooting section of the installation
instructions.  If your error is not shown there, please email
software@flaterco.com for assistance.

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?

A: The 12 hour 25 minute cycle is literally only a first-order
approximation.  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 or some other Lower Low Water.  The zero therefore
usually coincides with the lower of the two low tides occurring in a day,
but whether it's the average case or an extreme case depends on exactly
which definition was used.  You can find official definitions of "datum,"
"mean lower low water," and the alternative lower low waters in NOAA's tide
glossary at http://www.opsd.nos.noaa.gov/tideglos.html.

Q: Why is it that the tides two miles from here are an hour different than
the tides here?  If the tidal bulge follows the moon at 1,000 miles per
hour, how can the difference be so great?

A: When the water tries to follow the moon, it runs up against a lot of
obstacles, including its own inertia, the shape of the coastline, and the
resonances that are set up by the continual tidal motion.  In some cases the
tides are fighting a permanent current, e.g., going up a river, and this
slows down the tidal crest.  The result is that the tides at any one place
at any given time don't have a whole lot to do with the moon any more.

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.  I used to be
aggressive about deleting data based on sketchy evidence like "I was out in
the bayou this afternoon and the tides were off by an hour" but I've since
learned that a lot of people get confused about Daylight Savings Time,
compare predictions from the wrong side of the island, fail to consider the
effects of local weather, etc.  So PLEASE, if possible, cite some
predictions from a local newspaper or something to corroborate the
complaint.  (Note:  The "seldom happens" part might change depending on how
reliable the new batch of offsets data is.  There were some data quality
issues with the meridians, which means that there might be a lot of
off-by-one-hour type of errors to sort out in the near term.  These are
fixable.)

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 might omit them, but XTide faithfully
reports all maxima and minima that it finds.

On the other hand, many subordinate station predictions are generated from
"corrected" versions of the data for their reference stations, and sometimes
when these "corrections" get too big, spurious maxima and minima can
result.  This situation can be corrected by replacing the offending data set
with a proper subordinate station definition in offsets.xml.

Q: Why are there two high tides per day, anyway?  How is this possible?

A: The standard simple answer to this question is that the water on the side
of the earth opposite the moon bulges out due to decreased lunar gravity in
the same way that the water on the side of the earth nearest the moon bulges
out due to increased lunar gravity.  This is counter-intuitive in that one
might expect all of the water to just rush over to the side where the moon
is.  To explain this, I quote from "Our Restless Tides," a NOAA tutorial at
http://www.opsd.nos.noaa.gov/restles1.html:

     To all outward appearances, the moon revolves around the earth,
     but in actuality, the moon and earth revolve together around their
     common center of mass, or gravity.  The two astronomical bodies
     are held together by gravitational attraction, but are
     simultaneously kept apart by an equal and opposite centrifugal
     force produced by their individual revolutions around the
     center-of-mass of the earth-moon system.  This balance of forces
     in orbital revolution applies to the center-of-mass of the
     individual bodies only.  At the earth's surface, an imbalance
     between these two forces results in the fact that there exists, on
     the hemisphere of the earth turned toward the moon, a net (or
     differential) tide-producing force which acts in the direction of
     the moon's gravitational attraction, or toward the center of the
     moon.  On the side of the earth directly opposite the moon, the
     net tide-producing force is in the direction of the greater
     centrifugal force, or away from the moon.

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: Why bother?  You'll never get accurate predictions like that.  Anyway, I
don't know how to translate seasonal corrections into something that XTide
can use.

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[a] * nodefactor[a] * cos (speed[a] * time + phase[a])
     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.flaterco.com/xtide/files.html.  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.

Q: Hey, man, like, what happened to the Java?  What's all this C++ stuff?
Haven't you heard that Java increases your productivity by a factor of four,
and is totally standard on every platform?  You could even ship out the tide
prediction to the client machines and take the load off of your web server.
Wouldn't that be great?

A: Yeah, well, I tried Java, but I didn't inhale.  It was unstable,
unreliable, and not portable at all, not even between the same version of
Netscape running on different platforms.  I spent all of my time dealing
with patches to this stupid little applet.  It didn't do anything but tide
graphs, and it did them badly; yet the code kept getting bigger from all the
workarounds people kept sending.  It was "write once, run nowhere, debug
forever."

So, when it was time to build XTide 2, I gave Java a righteous trashing.
Not just trashed, but trashed really hard, intentionally broken into several
jagged pieces, and stomped down into the trash can with both feet, shouting
"Good riddance to bad rubbish! Yaaaah! Yaaaah!"  Now when I get emails from
Java evangelists it is all I can do not to give their whole ancestry a good
Pythonesque taunting.

If you would like to obsolete XTide by doing everything better in Java, you
are welcome to try.  However, please be prepared to take over the
maintenance of the harmonics database as well, because I will not be too
keen on continuing that thankless task once XTide is obsolete.

[100% Pure C++.  Cute applet.  Now shut up and program.]

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

   * Next
   * Contents
[Perkins Cove, Maine, 1998-06-08]

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 (Settings.hh,
     Settings.cc in 3 places, config.hh, UserDefaults.cc,
     xxApplicationDefaults.cc, ConfigDefaults.cc, CommandLineSettings.cc,
     xxXTideRoot.cc in 4 places, and xxXTideRoot.hh), plus the
     documentation.  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."

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

   * Next
   * Contents
[Sunset over L.A. Dunton, Mystic, Connecticut, 1998-06-06]

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.tuxedo.org/~esr/writings/cathedral-bazaar/).
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 reuse 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 in no particular order:

     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.

     Thanks to Walt Bilofsky for converting lots of difficult data for
     offsets.xml.

     Thanks to Thomas Dean for the patch to display current directions,
     to John Holden for the location URL patch to xttpd, and to John
     Stanley for the robots.txt patch.

     Thanks to Peter S. Galbraith for a large number of miscellaneous
     patches, changes, and suggestions.

     Bug fixers: 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; to David Warren for an SGI
     portability patch; to Falk Hueffner for another 64-bit fix; to
     Giuseppe Cabras for a Digital Unix portability fix; to Christopher
     Caldwell for HP-UX portability; to Raphael Malyankar for a
     workaround for Sun WorkShop C++; and to Phil Thornton for a Dstr
     bugfix.

     ...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 originally removed e-mail
addresses from this documentation because it was too big of a maintenance
hassle, but now it's an anti-SPAM measure.  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
[Girl feeding gulls]

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.txt:/etc/offsets.xml

     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.flaterco.com/xtide/files.html.
  3. You must set the environment variable HFILE_PATH to point to the
     harmonics files that you downloaded.  Example:

          export HFILE_PATH=/usr/local/share/xtide/harmonics.txt:\
          /usr/local/share/xtide/offsets.xml

  4. ./configure; 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

Although it has become fashionable to use odd minor revision numbers to
indicate development versions and even minor revision numbers to indicate
stable versions, XTide does not follow that practice.  The development
version leading up to stable version X.Y would be labeled X.Y DEVELOPMENT,
and the beta versions would be labeled X.Y Beta Z.  DEVELOPMENT versions are
subject to frequent change without notice.  I do not assign different
numbers to all the micro-revisions.

XTide 2.4 (2001-05-09)

(Bug) Fixed an OLD memory management bug in Dstr.cc.  Thanks to Phil
Thornton.

XTide 2.4 BETA 2 (2001-04-15)

(Bug) xttpd did not supply a robots.txt page.  Added robots.txt patch from
John Stanley.

XTide 2.4 BETA 1 (2001-03-25)

(Feature) Enhanced HFILE_PATH to enable searching of directories.

(Bug) Removed, or at least improved, a kludge in Timestamp that was
preventing 24-hour time users from getting leading zeros on hours.  A
compensatory change to the default time and hour formats was also made.

(Nit) Updated example in NO_HFILE_PATH error message again.

(Tuning) Reduced fastload limit to 2.

(Feature) Xttpd now shows the versions of the harmonics files that it's
using on its main page.

(Feature) Added a note attribute to subordinate station XML.

(Optimization) Incorporated patch to squeeze out null constituents.

XTide 2.3 (2000-12-08)

No code changes; just promoted to final release status.

XTide 2.3 BETA 2 (2000-10-01)

(Code rot) Added :America/Belem, :America/Fortaleza, and :America/Maceio and
revised abbreviation for :America/Sao_Paulo in time zone compatibility
table.

(Compliance) Smashed case in all (I hope) HTML markup tags for XHTML
compatibility (sugg. Richard Kennedy).

(Nit) Typographical tweaks in xttpd.

XTide 2.3 BETA 1 (2000-09-03)

(Feature) Replaced calendar mode with a clone of the much more popular one
that Dean Pentcheff has been using on his web site.  The "old" calendar mode
is still available from tide as -m C.

(Feature) Added setting to suppress sunrise, sunset, moon phases.

(Code rot) Added :America/Goose_Bay to timezone compatibility table.

(Nit) Updated example in NO_HFILE_PATH error message.

XTide 2.2.2 (2000-07-30)

(Compliance) To comply with XML 1.0, the offsets.xml file was changed to
have a single "root" document element.  As a result, XTide 2.2.1 and earlier
cannot find the stations in it.  This patch enables XTide to read either old
or new offsets.xml files.  The prolog of .xtide.xml written by XTide is also
made compliant.

XTide 2.2.1 (2000-07-16)

(Code rot) Added :America/Hermosillo and :America/Iqaluit to the zoneinfo
compatibility table.

XTide 2.2 (2000-01-12)

No code changes; just promoted to final release status.

XTide 2.2 BETA 1 (1999-12-12)

(Compliance) Xttpd now backgrounds itself and logs to the syslog facility.

(Feature) Added /etc/xtide.conf as alternative to setting HFILE_PATH.  The
format of this should probably be XML to guard against future expansion, but
for now it is as contributed from Debian (Peter Galbraith).

(Feature) Ditched Imake for Autoconf, which simplifies installation.

(Feature) Installed a Unicode-esque collating sequence for Latin1.

(Feature) xttpd: applied location lookup patch from John Holden.  This
enables URLs of the form http://whatever/locations/name in addition to the
more reliable http://whatever/locations/nnn.html syntax.  The name-based
URLs are not promulgated by xttpd itself.  The new syntax is documented in a
new hints & tricks page served by xttpd.

(Feature) If you set the environment variable XTIDE_DEFAULT_LOCATION, it
works like the default location feature of XTide 1.

(Robustness) Improved resolution of reference stations for subordinate
stations to eliminate many SUB_SUBORDINATE errors.  Fast loading is still
sensitive to the ordering of HFILE_PATH.

(Code rot) Added an autoconf step to deal with mutually incompatible
requirements of different platforms on the signature of the accept()
function as used in xttpd.cc.

(Code rot) Added Antarctic time zones to the compatibility table in
Timestamp.cc.

(Compliance) Changed packaging from xtide2/* every time to xtide-X.Y.Z/*.
Changed suggested disposition of xttpd from bin to sbin.  Changed xttpd man
page section from 1 to 8.  Changed suggested disposition of harmonics files
from /etc to /usr/local/share/xtide.

(Compliance) Moved some static functions into externC.cc with appropriate
signature changes to placate the Sun compiler's anachronism checker.

(Portability) Added workaround for bug in Sun WorkShop Compiler C++ SPARC
Version 5.000.  Thanks to Raphael Malyankar.

(Nit) Applied patch from Peter Galbraith to set background color in xttpd to
white.

XTide 2.1.7 (1999-08-14)

(Bug) Fixed drawing of Latin1 characters.  This involved increasing the font
height by one row, which will cause minor but noticeable changes in the
placement of text.

(Portability) Changed backlog parameter for socket in xttpd.cc from 0 to 5.
Digital Unix would accept no connections if backlog was 0.  Thanks to
Giuseppe Cabras.

XTide 2.1.6 (1999-08-09)

(Bug) Fixed xttpd assertion failure when subordinate stations don't supply
time zones.

(Bug) Made RGBGraph stop crashing when it's asked to draw characters that it
doesn't know.  To do, teach RGBGraph to draw the entire Latin1 character
set.

(Portability) Messed with usage of select() in xttpd.cc to try to make it
more portable.  Giuseppe Cabras reported trouble with it under Digital Unix.

(Portability) Added Imakefile.hp from Christopher Caldwell.

XTide 2.1.5 (1999-07-22)

(Portability) Cleaned up overloading ambiguities and ANSI compliance
problems encountered with HP aC++ B3910B A.01.18 (HP-UX 10.20).  Thanks to
Christopher Caldwell.

XTide 2.1.4 (1999-05-17)

(Portability) Got rid of some dubious implicit conversions between
PredictionValue::Unit and its encapsulated enum.  Don't know if they were
strictly conforming or not, but they made the latest Sun compiler use the
wrong constructor.  This showed up as UNRECOGNIZED_UNITS errors when trying
to load a tide station.

XTide 2.1.3 (1999-05-16)

(Code rot) Stopped including stream.h in common.hh.  It was always redundant
with iostream.h, but now stream.h has vanished from Sun's latest compiler.

XTide 2.1.2 (1999-03-15)

Add support for color specifications having the deprecated #RRGGBB format,
which recently resurfaced on Debian.

Patch from Falk Hueffner for Timestamp::tm2utc.  On his Alpha (BSD?), time_t
is 64 bits but gmtime returns NULL if the time_t is out of a certain range,
which was leading to segfaults.

Fixed reporting of MKTIME_FAILED errors caused by bad timestamps on the -b
and -e switches.

XTide 2.1.1 (1999-01-24)

Patch to get rid of all of the references to universe.digex.net that
appeared in the sources and documentation.  No functional changes.

XTide 2.1 (1998-12-20)

Implemented something similar to a patch sent by Thomas Dean to enable the
direction of current that he provided in his XML offsets to be displayed in
the boilerplate of text output.  Making it work for reference stations is
deferred until whenever reference stations are migrated to XML and the new
attributes can conveniently be added.

Removed $(DEPXPMLIB) from xtide dependencies (DEPLIBS1 in manifest) to get
rid of this needless compilation failure:

     make: *** No rule to make target `/usr/X11R6/lib/libXpm.a', needed by `xtide'.  Stop.

The cause of this was that some Linux distributions only provide a shared
libXpm, while the dependencies generated by Imake check for the existence of
the static library.

Made -o switch append instead of overwrite files per request from AED.

XTide 2.0.1 (1998-10-04)

Fixed a bug reported by Alan Davis which caused access violations and other
problems when a default center longitude was set in the control panel.

XTide 2.0 (1998-07-28)

No code changes; just promoted to final release status.

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

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

Deleted data

After a complaint from the U.K. Hydrographic Office and the subsequent
discovery that country-by-country permissions are now required to use
harmonic constants (data needed to predict tides), the distributions of data
that spanned many countries (all of the data originating with the
International Hydrographic Office or the Table des Mares des Grands Ports
du Monde) have been removed.

For the full sob story, see the FAQ.

Netherlands update

Koos Doekes of the Rijkswaterstaat RIKZ/ITB generously supplied 40
authoritative data sets for the Netherlands that appear in the latest
harmonics.txt.

Take my job

If you want to take over maintenance of the database of harmonic constants,
it's yours.  I don't have it in me to fight the tsunami of red tape and
parochialism that, according to rumor, caused the death of the International
Hydrographic Office's data bank (the only officially sanctioned
international database of harmonic constants).

I do not mind maintaining the database when the relevant data are "pushed"
in my direction (supplied in machine-ready form, with all necessary
permissions attached, as was the case with the Netherlands data described
above), but I don't have time to "pull" the data from an arbitrary number of
sources, in arbitrary formats, with arbitrary paperwork and restrictions on
usage.

Time zone trouble

Sonora and Nunavut have made recent (since 1999) changes to their time zones
and/or Daylight Savings Time.  Sorry, but these locations are just going to
be broken if you don't have fairly recent zoneinfo (see System
Requirements).

Congen 1.3

Congen 1.3 includes enhancements to generate the constituents needed by the
new Dutch data.  The format of the input file has changed.

Old news: The Disk Crash

Email received the weekend of 1999-11-07 was lost unread.

Old news: The Sudden Move

        The XTide web page moved to http://www.flaterco.com/xtide/.

                    The XTide software directory moved to
                 http://www.flaterco.com/xtide/files.html.

           Please send all XTide e-mail to software@flaterco.com.

Much to my surprise, on 1999-01-19 my venerable Digex shell account,
dave@universe.digex.net, was disabled forever.  Digex was bought out by
Intermedia, and Intermedia elected to do away with us old Unix shell users.

Unfortunately, the only warning that I received was a garbled e-mail
indicating that dial-up service was going to be discontinued.  Since
Universe accounts never came with dial-up -- they were accessible by telnet
only -- I concluded that they were not talking about me.

Boy, was I wrong.

After the fact, it was all I could do, with much unanswered e-mail and phone
calls forwarded to mysterious folks with no direct phone numbers and
sometimes no names, to get my e-mail forwarded and recover my files.  More
than once I was told "We don't offer shell accounts" in a suspicious voice
and treated as if I were mentally ill.  It was only after the second time
that I communicated, indirectly, with incognito former Digex employees that
I finally got someone to help.  The first such person botched the job, and
when I tried to call back, no one recognized his name and I could not get
back in touch.

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

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.

Bug fixes or features having scientific and technical merit

IMHO, the cost of doing either of these to XTide exceeds the benefits.  They
should probably be left for whoever and whatever come after me and XTide.

   * Add support for Doodson style tide prediction as used by Foreman's IOS
     package.  At this time there seems to be little benefit to be gained by
     doing this:
       1. Most Doodson constituents are approximated fairly well by Congen
          now.
       2. The ones that aren't approximated well are those that are
          drastically affected by latitude.  Casement opined that the
          latitude-dependent method is bogus because tides are generated
          some place in mid-ocean with a different latitude anyway.
       3. No new Doodson data appears to be forthcoming.
       4. If you want IOS, you can find it at
          http://www.ios.bc.ca/ios/iap/pages/tidpack.htm.
   * There are two issues relating to the handling of node factors and
     equilibrium arguments.  The first issue is whether doing them on a
     yearly basis, as XTide now does, is sufficent.  Most tide prediction
     software does it monthly or at least does it for the middle of your
     prediction interval.  But the legacy of SP98 is to do it yearly, and
     that's probably good enough.  The second issue is whether the values
     should be tabulated, as they are now, or generated internally to
     XTide.  To support Doodson-style predictions with latitude corrections,
     it would be necessary to generate them internally.  Most tide
     prediction software does it internally, but I have reaped great
     benefits by keeping it architecturally separate.

User interface improvements

I have sorted these in order of what I perceive as decreasing importance.
You can lobby to increase the priority of something if you so choose.

   * XTide 3:  It's time to migrate the main harmonics file to XML.  Along
     the way, various old, bad design choices can be fixed:  (1) latitude,
     longitude, note, etc. can be added as proper attributes; (2) change
     from "sparse" listing of constants to tagged values; (3) retire the
     fast loader and other optimizations that depend on random access; (4)
     read compressed input.
   * DWF: Change mapping of locations to URLs so that links won't break when
     harmonics files are changed.
   * Robert Thorsby requests Moon Rise / Moon Set times.
   * Tim Cera wants interactive access to raw mode in xtide -- select a
     location, choose start and end times using xxTimestamp.
   * DWF: Note moon phases in tide graphs somehow.
   * Graeme Rae suggested a line for the current time in text listings, like
     "2001-03-19 11:50 AM PST 0.10 feet Falling"
   * AED and Dean Pentcheff want outlines of continents on the globe.
   * DWF: Make date/time format dialog more user-friendly.
   * DWF: Add a real color chooser in control panel.
   * 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.  Hans Bot has
     seconded this request.
   * Diane Grant 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.'

Code cleanups

   * DWF: Clean up xxTimestamp using xxMultiChoice.

If you want to tackle one of these tasks, e-mail me at
software@flaterco.com.  Thanks.

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

   * Contents
