               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
   [1]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 [2]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:
    [3]http://www.flaterco.com/xtide/files.html
     _________________________________________________________________

   [4]Buoy in the mist

Contents

     * [5]License and disclaimer ("NOT FOR NAVIGATION," "ABSOLUTELY NO
       WARRANTY")
     * Verbose documentation
          + [6]Introduction
          + [7]System requirements
          + [8]Installation instructions for Unix, Cygwin, or Mac OS X
          + [9]Available ports for non-Unix platforms
          + [10]Modes and formats
          + [11]Using the interactive interface
          + [12]Advanced usage
          + [13]Using the command line interface
          + [14]Running the web server
          + [15]Customizing XTide
          + [16]What to do if your location isn't listed
          + [17]Known limitations and bugs
          + [18]FAQ
          + [19]Design notes
          + [20]Credits
          + [21]Bibliography
          + [22]Appendix A -- Historical predictions and Y2038 compliance
     * Short attention span documentation for experienced XTide users
          + [23]Differences from XTide 1
          + [24]Quick install instructions
          + [25]Change log
          + [26]News (current XTide developments)

   Hint:  If you have no idea what all this is about, try reading the
   [27]FAQ first.

   -- 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.

References

   1. http://www.flaterco.com/xtide/
   2. http://www.libpng.org/pub/png/png.html
   3. http://www.flaterco.com/xtide/files.html
   4. http://www.flaterco.com/
   5. http://www.flaterco.com/xtide/disclaimer.html
   6. http://www.flaterco.com/xtide/introduction.html
   7. http://www.flaterco.com/xtide/sysreq.html
   8. http://www.flaterco.com/xtide/installation.html
   9. http://www.flaterco.com/xtide/ports.html
  10. http://www.flaterco.com/xtide/modes.html
  11. http://www.flaterco.com/xtide/interactive.html
  12. http://www.flaterco.com/xtide/advanced.html
  13. http://www.flaterco.com/xtide/tty.html
  14. http://www.flaterco.com/xtide/xttpd.html
  15. http://www.flaterco.com/xtide/settings.html
  16. http://www.flaterco.com/xtide/harmonics.html
  17. http://www.flaterco.com/xtide/bugs.html
  18. http://www.flaterco.com/xtide/faq.html
  19. http://www.flaterco.com/xtide/design.html
  20. http://www.flaterco.com/xtide/credits.html
  21. http://www.flaterco.com/xtide/bibliography.html
  22. http://www.flaterco.com/xtide/time_t.html
  23. http://www.flaterco.com/xtide/xtide1diff.html
  24. http://www.flaterco.com/xtide/quickinst.html
  25. http://www.flaterco.com/xtide/changelog.html
  26. http://www.flaterco.com/xtide/news.html
  27. http://www.flaterco.com/xtide/faq.html

################################################################

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 maintained by Bob Kenney, [1]read the boilerplate (a copy is
   available at
   [2]http://harmonics.unh.edu/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.

   Although the package as a whole is GPL, some individual source files
   are public domain.  Consult their header comments for details.

                             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 any 'harmonics data' that might be 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 the
   maintainer of that data has of knowing when it is bad is when someone
   with access to authoritative tide predictions or observations reports
   a problem.  You should not use this program or any data files that
   might be distributed with it 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.
     _________________________________________________________________

     * [3]Contents

References

   1. http://harmonics.unh.edu/xtide/harmonics_boilerplate.txt
   2. http://harmonics.unh.edu/xtide/harmonics_boilerplate.txt
   3. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Bald Head Cliff, Ogunquit, Maine, 1998-06-15

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
   [2]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.  See
   [3]http://www.flaterco.com/xtide/files.html for details on where to
   get these.

   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.
     * 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.
     _________________________________________________________________

     * [4]Next
     * [5]Contents

References

   1. http://www.flaterco.com/
   2. http://www.nos.noaa.gov/
   3. http://www.flaterco.com/xtide/files.html
   4. http://www.flaterco.com/xtide/sysreq.html
   5. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Cutler in the fog

System requirements

   XTide is Unix software.  It is intended to compile and run correctly
   on any reasonably modern version of Unix.  However, testing on flavors
   other than Linux is becoming less and less frequent.  I make
   portability fixes whenever problems are reported.

   XTide has been ported to a variety of other operating systems with
   differing levels of success.  These ports will be discussed in a
   [2]later section.

   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 and a C++ compiler.  XTide
   was written in a very portable subset of C++ which has now been made
   less portable by the use of the 'long long int' data type.
   Nevertheless, if there is any problem compiling XTide with any C++
   compiler, ANSI-compliant or otherwise, I will attempt to address it.

   The C compiler is for libtcd, which is bundled with and used by XTide.

   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
   [3]ftp://ftp.x.org/contrib/libraries/ or from one of the many mirrors
   of the X11 directory tree.

   Pointers to the latest libpng and libz can be found under the PNG home
   page at [4]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 [5]ftp://elsie.nci.nih.gov/pub/ or by installing an
   operating system upgrade.
     _________________________________________________________________

     * [6]Next
     * [7]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/ports.html
   3. ftp://ftp.x.org/contrib/libraries/
   4. http://www.libpng.org/pub/png/libpng.html
   5. ftp://elsie.nci.nih.gov/pub/
   6. http://www.flaterco.com/xtide/installation.html
   7. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Prospect Harbor Pt. Light, Prospect Harbor, Maine, 1998-06-14

Installation instructions for Unix, Cygwin, or Mac OS X

   These installation instructions assume that you have provided the
   necessary libraries and C++ compiler discussed in the [2]previous
   section.  They also assume that you are building from sources obtained
   from [3]http://www.flaterco.com/xtide/files.html.  However, some Linux
   users may be able to shortcut this process using the RPMs at
   [4]http://erizo.ucdavis.edu/~dmk/software/RPMS/ (courtesy of David M.
   Kaplan).

  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 XTide distribution is
   available from [5]http://www.flaterco.com/xtide/files.html in gzipped
   tar format.  Information on harmonics files is also provided on that
   page.

   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 -

    XTide 2.6

   XTide 2.6 uses a compressed binary format (TCD) for harmonics files.
   However, it compresses a bit more with gzip, so it's distributed
   gzipped.  First you need to un-gzip it:

gzip -d harmonics.tcd.gz

   Then move it to a permanent location, e.g., /usr/local/share/xtide,
   and make it world readable:

mkdir /usr/local/share/xtide
chmod 755 /usr/local/share/xtide
chmod 644 harmonics.tcd
mv harmonics.tcd /usr/local/share/xtide

    XTide 2.0 through 2.5

   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.
       XTide 2.6

export HFILE_PATH=/usr/local/share/xtide/harmonics.tcd

    XTide 2.0 through 2.5
       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

    All versions
       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.
       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
       harmonics and offsets files!)
       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.  If a configuration file is used,
       the first line should consist of the value that would be assigned
       to HFILE_PATH:
/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

   Type the following at the shell prompt to compile:

./configure; make

   libtcd, which is bundled in the libtcd subdirectory of the XTide
   distribution, will be automatically compiled and statically linked
   into the XTide executables.

   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 extracflags (for libtcd's C sources), extracxxflags
   (for XTide's C++ sources), and extraldflags (for linking) before
   running configure.  For example, to search /mumble/foo/include for
   include files, you could do

extracflags="-I/mumble/foo/include" extracxxflags="-I/mumble/foo/include" ./con
figure

   under the Bourne shell.  You can also preselect the C compiler to use
   by setting the variable CC and 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.

    IRIX

   Some SGI machines come with a broken make program.  Use GNU make.

    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

    Cygwin

    XTide can be compiled and run using [6]Cygwin, which is an emulated Unix
    environment for Windows that is free for typical non-commercial users.  The
    Cygwin distribution and its full license terms are available from
    [7]http://www.cygwin.com/.

    Users who know nothing about Unix should not attempt to compile XTide under
    Cygwin but should instead use one of the "native" ports of XTide to Windows
    listed in the [8]ports section.

    The following special notes apply only to Cygwin installations:
    1. As you would expect, emulating Unix/X11 under Windows exacerbates
       the performance bottlenecks already in X11 and creates some new
       ones.  Certain operations may become intolerably slow.
    2. Cygwin packages are all versioned separately, so there is no
       baseline "Cygwin version" against which to test XTide.  Testing
       was initially conducted using the collection of packages that was
       current as of 2002-05-20.  Less thorough testing was done as of
       2003-05-28.
    3. The web server (xttpd) did not work when tested 2002-05-20 and is
       not supported for Cygwin at this time.
    4. Ensure that /usr/X11R6/bin is in your PATH environment variable or
       you'll get an error saying that it can't find libICE.dll.
    5. In Cygwin, X runs as a Windows window that contains within it your
       X root window and the rest of your X environment.  Before using
       xtide, you need to fire up the X server by running startx just as
       you would under Unix.
    6. If XTide issues a CORRUPT_HARMONICS_FILE error, you may have
       unintentionally converted the harmonics file to Windows/DOS line
       discipline.  For harmonics.txt, try converting it back to Unix.
       For harmonics.tcd, re-download using binary mode FTP.
    7. Because of limitations in Cygwin's strftime implementation, the
       default format for time stamps is changed to include leading zeros
       in the "hours" field and to omit the time zone indicator.
    8. Cygwin appears to have a unique implementation of time zones.  As
       of 2002-05-20, it does not include the (de facto standard) time
       zone database available from [9]ftp://elsie.nci.nih.gov/pub/.
       Users are advised to be extra wary of possible time zone issues.
    9. Compiling XTide 2.6 with -DTIME_WORKAROUND failed under the
       2002-05-20 snapshot of Cygwin because of a missing declaration for
       EOVERFLOW.  Upgrading to the latest Cygwin as of 2003-05-28 fixed
       the problem.

    Mac OS X

    XTide was reported to compile cleanly under Mac OS X with XFree86 4.2 and
    the PNG package installed via Fink ([10]http://fink.sourceforge.net/).  Use
    extracxxflags="-I/sw/include" and extraldflags="-L/sw/lib" to find the
    Fink-installed PNG files.
    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.
    If all else fails

    Copy Makefile.in over Makefile and edit as needed.

  Troubleshooting

  Q: When I type 'make', it immediately tries to link xtide and forgets to
  compile the object files first.

  A: This problem has been reported with the make program distributed on some
  SGI machines.  Use GNU make.

  Q: When compiling XTide, I get an error involving xml_l.cc, xml_y.cc,
  xml_y.hh, or lex.xml.c.

  A: Run the script do_xml.sh to regenerate the offending XML parser sources
  and try again.

  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 `XSetTransie
ntForHint' 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 lon
g, unsigned int)':
xxContext.o(.text+0xc51): undefined reference to `XpmCreatePixmapFromData'
RGBGraph.o: In function `RGBGraph::writeAsPNG(void (*)(png_struct_def *, unsign
ed 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.

  Option:  World Vector Shoreline

  If you have gotten everything else working, you may then wish to consider if
  you want to install the World Vector Shoreline (WVS) files to enable XTide to
  draw coastlines on the map.  (This only works for XTide 2.5 or newer.)

  This step is optional because the data files are large, the functionality is
  very CPU-intensive, and the ability to predict tides is not affected.  It is
  not advisable to install the WVS files on a machine slower than a 500 MHz
  PC.  If you decide to install them:
    1. Download the gzipped tar file of WVS data from
       [11]http://www.flaterco.com/xtide/files.html.
    2. Create a directory to contain the WVS files.
    3. Change your current working directory to that directory.
    4. Unpack the tar file in that directory.
    5. Either set the environment variable WVS_DIR to the name of that
       directory or supply the directory name as the second line of the
       configuration file /etc/xtide.conf.
     _________________________________________________________________

     * [12]Next
     * [13]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/sysreq.html
   3. http://www.flaterco.com/xtide/files.html
   4. http://erizo.ucdavis.edu/~dmk/software/RPMS/
   5. http://www.flaterco.com/xtide/files.html
   6. http://www.cygwin.com/
   7. http://www.cygwin.com/
   8. http://www.flaterco.com/xtide/ports.html
   9. ftp://elsie.nci.nih.gov/pub/
  10. http://fink.sourceforge.net/
  11. http://www.flaterco.com/xtide/files.html
  12. http://www.flaterco.com/xtide/ports.html
  13. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Bridge Street

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 can use the same harmonics
   files that some version of XTide did, 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
   commonality with 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

   XTide can be compiled and run using [2]Cygwin, which is an emulated
   Unix environment for Windows that is free for typical non-commercial
   users.  The Cygwin distribution and its full license terms are
   available from [3]http://www.cygwin.com/.  Please refer to the
   [4]Installation section for special instructions about using XTide
   under Cygwin.

   Users who know nothing about Unix should not attempt to compile XTide
   under Cygwin but should instead use one of the following "native"
   ports of XTide to Windows.

   The latest "native" port to Windows, by Phil Thornton, is based on
   XTide 2.  It has so many changes and enhancements relative to the Unix
   source that it's now more a descendant of a port than a port.  A
   "nagware" binary is available at [5]http://www.mdr.co.nz/.  Sources
   are obtainable on CD for a distribution fee (as permitted by the GPL).

   There are two older "native" ports to Microsoft Windows, distributed
   with both sources and binary:
     * The newer older port, "WXTide32" by Mike Hopper, is based on XTide
       1.6.2 but includes its own location chooser.  It works under
       Windows 95 or Windows NT.  It has a web page at
       [6]http://www.wxtide32.com/.
     * The older older port, "WTide16" and "WTide32" by Paul C. Roberts,
       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 [7]ftp://ftp.demon.co.uk/pub/ibmpc/win3/apps/wtide.

  Macintosh

   XTide was reported to compile cleanly under Mac OS X with XFree86 4.2
   and the PNG package installed via Fink
   ([8]http://fink.sourceforge.net/).  Use extracxxflags="-I/sw/include"
   and extraldflags="-L/sw/lib" to find the Fink-installed PNG files.

   For some earlier versions of Mac OS, there is a GPL'd non-port called
   Mr. Tides that you can find at [9]http://www.exmsft.com/~augusth/.

  Palm Pilot

   Palm Pilot

   [10]Walt Bilofsky has implemented [11]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 [12]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."

  Pocket PC / Windows CE

   PocketPC

   Dave Buchholz has implemented [13]cTide for the PocketPC 2000 or
   PocketPC 2002.  It's a port of a port ([14]WXTide32), but the
   screenshots still look a lot like XTide.  You can find it at
   [15]http://airtaxi.net/ctide/.

  HP Calculator

   HP Calculator

   David MacCuish and Dennis Straley have done a similar-in-spirit
   non-port for HP48G and HP49G series calculators.  As of 2001-11-08,
   [16]HpTide is still in development, but it now supports a larger
   number of locations.  For current news and status, please see the
   HpTide web site, [17]http://heygus.2y.net/hptide.

  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 [18]os2/unix.  You must have an X
   environment to use xtide while tide will work in any environment.
   Also get [19]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.
     _________________________________________________________________

     * [20]Next
     * [21]Contents

References

   1. http://www.flaterco.com/
   2. http://www.cygwin.com/
   3. http://www.cygwin.com/
   4. http://www.flaterco.com/xtide/installation.html#cygwin
   5. http://www.mdr.co.nz/
   6. http://www.wxtide32.com/
   7. ftp://ftp.demon.co.uk/pub/ibmpc/win3/apps/wtide/
   8. http://fink.sourceforge.net/
   9. http://www.exmsft.com/~augusth/
  10. http://www.toolworks.com/bilofsky/
  11. http://www.toolworks.com/bilofsky/tidetool.htm
  12. http://www.toolworks.com/bilofsky/tidetool.htm
  13. http://airtaxi.net/ctide/
  14. http://www.wxtide32.com/
  15. http://airtaxi.net/ctide/
  16. http://heygus.2y.net/hptide
  17. http://heygus.2y.net/hptide
  18. ftp://hobbes.nmsu.edu/os2/unix
  19. ftp://hobbes.nmsu.edu/os2/unix/emx09c
  20. http://www.flaterco.com/xtide/modes.html
  21. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Morning in OC

Modes

   This page provides an overview of the kinds of things that XTide can
   do.  How to do them will be explained in the [2]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.  Sunrise and sunset
   are denoted with different background colors; moonrise, moonset, and
   moon phases are shown along the bottom.  A + mark on the graph
   indicates the conditions at the time that the graph was generated.

   For currents, the times of [3]slack water are also shown along the
   bottom.  This unfortunately competes with the lunar information for
   space.  The fix is to turn off sun and moon information using the
   [4]control panel described in a later section, or else use one of the
   other modes to decipher the timestamps when they overlap.

   San Francisco Current graph

  Clock mode

   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 text listing of events, no foo-foo.
San Francisco, California
37.8067 N, 122.4650 W

2003-02-13  2:17 PM PST   Moonrise
2003-02-13  3:25 PM PST  -0.32 feet  Low Tide
2003-02-13  5:46 PM PST   Sunset
2003-02-13 10:49 PM PST   4.64 feet  High Tide
2003-02-14  3:05 AM PST   3.16 feet  Low Tide
2003-02-14  5:44 AM PST   Moonset
2003-02-14  7:01 AM PST   Sunrise
2003-02-14  9:02 AM PST   6.27 feet  High Tide

  Calendar mode

   Calendar mode arranges most of the information available in text mode
   into a commonly used tabular layout.

   Day High
   Low High
   Low High Phase Sunrise Sunset Moonrise Moonset
   Sun 16 4:30 AM PST / 2.58 ft 10:35 AM PST / 6.61 ft 5:18 PM PST /
   -0.89 ft Full Moon 6:58 AM PST 5:49 PM PST 5:42 PM PST 7:11 AM PST
   Mon 17 12:22 AM PST / 5.24 ft 5:14 AM PST / 2.22 ft 11:22 AM PST /
   6.55 ft 5:55 PM PST / -0.76 ft 6:57 AM PST 5:50 PM PST 6:55 PM PST
   7:47 AM PST
   Tue 18 12:53 AM PST / 5.45 ft 6:01 AM PST / 1.83 ft 12:11 PM PST /
   6.29 ft 6:33 PM PST / -0.42 ft 6:56 AM PST 5:51 PM PST 8:08 PM PST
   8:18 AM PST
   Wed 19 1:26 AM PST / 5.67 ft 6:52 AM PST / 1.47 ft 1:03 PM PST / 5.84
   ft 7:11 PM PST / 0.10 ft 6:54 AM PST 5:52 PM PST 9:20 PM PST 8:48 AM
   PST
   Thu 20 2:02 AM PST / 5.86 ft 7:47 AM PST / 1.13 ft 2:02 PM PST / 5.25
   ft 7:52 PM PST / 0.76 ft 6:53 AM PST 5:53 PM PST 10:32 PM PST 9:18 AM
   PST
   Fri 21 2:40 AM PST / 6.01 ft 8:48 AM PST / 0.85 ft 3:10 PM PST / 4.63
   ft 8:38 PM PST / 1.49 ft 6:52 AM PST 5:54 PM PST 11:44 PM PST 9:48 AM
   PST
   Sat 22 3:24 AM PST / 6.09 ft 9:56 AM PST / 0.59 ft 4:36 PM PST / 4.14
   ft 9:31 PM PST / 2.21 ft 6:51 AM PST 5:56 PM PST 10:22 AM PST

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

              Sun 16      Mon 17 Tue 18 Wed 19 Thu 20 Fri 21 Sat 22
   Low Tide 2.58 ft
   4:30 AM PST
   Sunrise
   6:58 AM PST
   Moonset
   7:11 AM PST
   High Tide 6.61 ft
   10:35 AM PST
   Full Moon
   3:53 PM PST
   Low Tide -0.89 ft
   5:18 PM PST
   Moonrise
   5:42 PM PST
   Sunset
   5:49 PM PST
   High Tide 5.24 ft
   12:22 AM PST
   Low Tide 2.22 ft
   5:14 AM PST
   Sunrise
   6:57 AM PST
   Moonset
   7:47 AM PST
   High Tide 6.55 ft
   11:22 AM PST
   Sunset
   5:50 PM PST
   Low Tide -0.76 ft
   5:55 PM PST
   Moonrise
   6:55 PM PST
   High Tide 5.45 ft
   12:53 AM PST
   Low Tide 1.83 ft
   6:01 AM PST
   Sunrise
   6:56 AM PST
   Moonset
   8:18 AM PST
   High Tide 6.29 ft
   12:11 PM PST
   Sunset
   5:51 PM PST
   Low Tide -0.42 ft
   6:33 PM PST
   Moonrise
   8:08 PM PST
   High Tide 5.67 ft
   1:26 AM PST
   Low Tide 1.47 ft
   6:52 AM PST
   Sunrise
   6:54 AM PST
   Moonset
   8:48 AM PST
   High Tide 5.84 ft
   1:03 PM PST
   Sunset
   5:52 PM PST
   Low Tide 0.10 ft
   7:11 PM PST
   Moonrise
   9:20 PM PST
   High Tide 5.86 ft
   2:02 AM PST
   Sunrise
   6:53 AM PST
   Low Tide 1.13 ft
   7:47 AM PST
   Moonset
   9:18 AM PST
   High Tide 5.25 ft
   2:02 PM PST
   Sunset
   5:53 PM PST
   Low Tide 0.76 ft
   7:52 PM PST
   Moonrise
   10:32 PM PST
   High Tide 6.01 ft
   2:40 AM PST
   Sunrise
   6:52 AM PST
   Low Tide 0.85 ft
   8:48 AM PST
   Moonset
   9:48 AM PST
   High Tide 4.63 ft
   3:10 PM PST
   Sunset
   5:54 PM PST
   Low Tide 1.49 ft
   8:38 PM PST
   Moonrise
   11:44 PM PST
   High Tide 6.09 ft
   3:24 AM PST
   Sunrise
   6:51 AM PST
   Low Tide 0.59 ft
   9:56 AM PST
   Moonset
   10:22 AM PST
   High Tide 4.14 ft
   4:36 PM PST
   Sunset
   5:56 PM PST
   Low Tide 2.21 ft
   9:31 PM PST

   Calendar mode is not available from the interactive client.

  Banner mode

   Banner mode is a specialization of graph mode for output on old
   tractor feed dot matrix or line printers that use continuous reams of
   paper.  Also useful as a workaround if your printing application does
   stupid things with color graphs.  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

*******-****-****-****0*****1****2****3****4****5****6**  7     8    9
-10****3****2****1**** ***** **** **** **** **** **** ***
******* **** **** ****f*****f****f****f****f****f****f*** f     f    2003-02-16
*******f****f****f****t*****t****t****t****t****t****t*** t     t  10:35 AM PST
-11****t****t****t***************************************
********************************************************  |     |    |
*******************************************************   |     |    |
-12***************************************************    |     |    |
**************************************************** |    |     |    |
*************************************************    |    |     |    |
-1********************************************* |    |    |     |    |
********************************************    |    |    |     |    |
*****************************************  |    |    |    |     |    |
-2************************************|    |    |    |    |     |    |
***********************************   |    |    |    |    |     |    |
******************************** |    |    |    |    |    |     |    |
-3***************************    |    |    |    |    |    |     |    |
**************************  |    |    |    |    |    |    |     |    |
****Full Moon***********    |    |    |    |    |    |    |     |    |
-4**3:53 PM PST*******|     |    |    |    |    |    |    |     |    |
********************* |     |    |    |    |    |    |    |     |    |
********************  |     |    |    |    |    |    |    |     |    |
-5*****************   |     |    |    |    |    |    |    |     |    2003-02-16
****Moonrise*******   |     |    |    |    |    |    |    |     |   5:18 PM PST
-***5:42 PM PST****   |     |    |    |    |    |    |    |     |    |
-6*****************   |     |    |    |    |    |    |    |     |    |
********************  |     |    |    |    |    |    |    |     |    |

  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 Tide 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.
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

  Medium rare mode

   Medium rare mode is just like raw mode except that the timestamps are
   "cooked" according to the date and time format settings that are in
   effect.
2002-02-06  4:56 PM EST 2.054437
2002-02-06  5:56 PM EST 1.573781
2002-02-06  6:56 PM EST 1.086896
2002-02-06  7:56 PM EST 0.656111
2002-02-06  8:56 PM EST 0.224729
2002-02-06  9:56 PM EST -0.161049
2002-02-06 10:56 PM EST -0.265521
2002-02-06 11:56 PM EST 0.077530

  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.

   The 'Type' column shows Ref for reference stations and Sub for
   subordinate stations.  The meaning of this is explained in a [5]later
   section.

   Location Type Coordinates
   0.8 n.mi. above entrance, Alloway Creek, New Jersey Sub 39.4967 N,
   75.5167 W
   130th Street, Hudson River, New York Sub 40.8167 N, 73.9667 W
   2.5 miles above mouth, Little Satilla River, Georgia Sub 31.0583 N,
   81.4933 W
   2.5 n.mi. above entrance, Alloway Creek, New Jersey Sub 39.5050 N,
   75.4833 W
   3 miles above A1A highway bridge, Loxahatchee River, Florida Sub
   26.9700 N, 80.1267 W
   37th Avenue, Long Island City, East River, New York, New York Sub
   40.7617 N, 73.9467 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
     alt. calendar text, HTML
     clock         PNG, X-windows
     graph         text, PNG, X-windows
     list          text, HTML
     plain         text, X-windows
     raw           text, X-windows
     medium rare   text, X-windows
     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
       2003-02-13                   2003-02-13      2003-02-14             2003
       3:25 PM PST                 10:49 PM PST     3:05 AM PST            9:02

8 ft --------------------------------------------------------------------------

7 ft --------------------------------------------------------------------------
                                                                             **
6 ft --------------------------------------------------------------------******
5 ft -----------------------------------------------------------------*********
                                   *************                   ************
4 ft ---------------------------*********************----------****************
3 ft -------------------------*************************************************
*                           ***************************************************
2 ft --------------------******************************************************
1 ft*-----------------*********************************************************
*******            ************************************************************
0 ft***************************************************************************
-1 ft**************************************************************************
*******************************************************************************
****Moonrise*****************************************************Moonset*******
***2:17 PM PST*************************************************5:44 AM PST*****
2**1***2***3***4***5**6***7***8***9**10**11*12***1***2***3***4***5***6**7***8**
|**|***||**|***|***|**|***|***|***|***|***|*|||**|***|***|***|***|**||**|***|**

   You can also get the calendar and alt. calendar modes in text format.
   However, they don't fit very well into 79 columns:
Day    High          High          High   Phase  Sunris Sunset Moonri Moonse
              Low           Low

Sun 16        4:30 A 10:35  5:18 P        Full M 6:58 A 5:49 P 5:42 P 7:11 A
Mon 17 12:22  5:14 A 11:22  5:55 P               6:57 A 5:50 P 6:55 P 7:47 A
Tue 18 12:53  6:01 A 12:11  6:33 P               6:56 A 5:51 P 8:08 P 8:18 A
Wed 19 1:26 A 6:52 A 1:03 P 7:11 P               6:54 A 5:52 P 9:20 P 8:48 A
Thu 20 2:02 A 7:47 A 2:02 P 7:52 P               6:53 A 5:53 P 10:32  9:18 A
Fri 21 2:40 A 8:48 A 3:10 P 8:38 P               6:52 A 5:54 P 11:44  9:48 A
Sat 22 3:24 A 9:56 A 4:36 P 9:31 P               6:51 A 5:56 P        10:22

   To fix this, you could turn off sun and moon information:
Day          High                      High                      High
                          Low                       Low

Sun 16                    4:30 AM PST  10:35 AM PST 5:18 PM PST
Mon 17       12:22 AM PST 5:14 AM PST  11:22 AM PST 5:55 PM PST
Tue 18       12:53 AM PST 6:01 AM PST  12:11 PM PST 6:33 PM PST
Wed 19       1:26 AM PST  6:52 AM PST  1:03 PM PST  7:11 PM PST
Thu 20       2:02 AM PST  7:47 AM PST  2:02 PM PST  7:52 PM PST
Fri 21       2:40 AM PST  8:48 AM PST  3:10 PM PST  8:38 PM PST
Sat 22       3:24 AM PST  9:56 AM PST  4:36 PM PST  9:31 PM PST

   Or, you could change the time format to a more compact, 24-hour
   format:
Day    High          High          High   Phase  Sunris Sunset Moonri Moonse
              Low           Low

Sun 16        04:30  10:35  17:18         Full M 06:58  17:49  17:42  07:11
Mon 17 00:22  05:14  11:22  17:55                06:57  17:50  18:55  07:47
Tue 18 00:53  06:01  12:11  18:33                06:56  17:51  20:08  08:18
Wed 19 01:26  06:52  13:03  19:11                06:54  17:52  21:20  08:48
Thu 20 02:02  07:47  14:02  19:52                06:53  17:53  22:32  09:18
Fri 21 02:40  08:48  15:10  20:38                06:52  17:54  23:44  09:48
Sat 22 03:24  09:56  16:36  21:31                06:51  17:56         10:22

   Or, you could just set a wider width.  It's your choice, depending on
   what is most important to you.  All of these are [6]settings that you
   can change with the [7]control panel or [8]command-line switches.
     _________________________________________________________________

     * [9]Next
     * [10]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/interactive.html
   3. http://www.opsd.nos.noaa.gov/glossary/gloss_s.html#slack
   4. http://www.flaterco.com/xtide/advanced.html#cp
   5. http://www.flaterco.com/xtide/harmonics.html
   6. http://www.flaterco.com/xtide/settings.html
   7. http://www.flaterco.com/xtide/advanced.html#cp
   8. http://www.flaterco.com/xtide/settings.html
   9. http://www.flaterco.com/xtide/interactive.html
  10. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Pemaquid bell

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.

   When XTide is finished indexing the harmonics files you will get a
   location chooser.  The location chooser initially shows a hemisphere
   of the globe.  The location list enumerates every tide station that is
   plotted on the map.  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.

   (If you do not get outlines of coastlines, please refer to the
   Installation section, subsection [2]"Option:  World Vector
   Shoreline".)

   Globe window

   Location list window

   You can change to a flat map projection that shows the entire world at
   once by clicking on Flat.  You can make this your default location
   chooser if desired (see the later section [3]Customizing XTide).

   Map window

   You can zoom in on an area by clicking on the map with the left mouse
   button; zooming out is accomplished with the button at the bottom of
   the map window.  Your view can be shifted left, right, up, or down
   using the arrow keys on the keyboard.  The location list updates to
   contain only those tide stations that are visible.  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 map indicating the area selected:

   Map 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 map 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.  (In raw and medium rare modes, you are given the
   opportunity to adjust the start and end times for the output.)
   Set Mark See [4]next section.
   Convert ft<->m Convert units to the preferred system.
   Set Aspect See [5]next section.
   Set Step See [6]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 Raw Mode Window Pop up a raw mode window for the location.
   New Medium Rare Mode Window Pop up a medium rare 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 [7]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 window

   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 window Clock window with buttons

   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.
     _________________________________________________________________

     * [8]Next
     * [9]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/installation.html#WVS
   3. http://www.flaterco.com/xtide/settings.html
   4. http://www.flaterco.com/xtide/advanced.html
   5. http://www.flaterco.com/xtide/advanced.html
   6. http://www.flaterco.com/xtide/advanced.html
   7. http://www.flaterco.com/xtide/advanced.html
   8. http://www.flaterco.com/xtide/advanced.html
   9. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]The tide cometh, Provincetown, MA

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.  (The example shown
   has sun and moon output turned off to avoid overlapping timestamps.)

   San Francisco graph with mark level

   Mark level crossings are not displayed in clock mode windows due to
   lack of space.  Some locations, namely subordinate stations with
   complex offsets, do 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.
   Portland, England at aspect 1.0

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

   Stretching the graph to aspect 4.0 clears up the mystery.
   Washington, D.C. at aspect 0.5

   This tide clock has been compressed to aspect 0.5.

  Step

   In raw and medium rare modes, tide levels are normally listed with an
   increment of one hour for successive lines of output.  You can adjust
   this increment using the Set Step option.

  The control panel

  The control panel is the easiest way to customize the many user-serviceable
  [2]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; they are:  Hour format %H; Time format %H:%M %Z.

  Line graph with 24-hour timestamps
  Command line options

  The interactive client supports all of the command line switches related to
  [3]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 YYYY-MM-DD HH:MM, where hours
          range from 00 to 23.  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.  NOTE: Graphs
          actually start a little earlier so that the specified time is
          not obscured by the labels for the depth axis.

   -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.

   -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.

  Other switches that are supported by the [4]non-interactive interface are not
  supported by the interactive interface and will be ignored.
    ________________________________________________________________________

     * [5]Next
     * [6]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/settings.html
   3. http://www.flaterco.com/xtide/settings.html
   4. http://www.flaterco.com/xtide/tty.html
   5. http://www.flaterco.com/xtide/tty.html
   6. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Tide closes in

Using the command line interface

   The command line interface, tide, supports a number of [2]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

2003-02-12  7:27 AM AKST   Moonset
2003-02-12  8:50 AM AKST   Sunrise
2003-02-12 10:19 AM AKST  10.72 feet  Low Tide
2003-02-12 11:34 AM AKST   Moonrise
2003-02-12  3:42 PM AKST  24.41 feet  High Tide
2003-02-12  5:37 PM AKST   Sunset
2003-02-12 11:00 PM AKST   1.95 feet  Low Tide
2003-02-13  5:31 AM AKST  25.51 feet  High Tide
2003-02-13  8:29 AM AKST   Moonset

   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 [3]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 YYYY-MM-DD HH:MM, where hours range from
          00 to 23.  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.  NOTE: Graphs actually
          start a little earlier so that the specified time is not
          obscured by the labels for the depth axis.

   -e "YYYY-MM-DD HH:MM"
          Specify the end (stop) time for predictions using the ISO 8601
          compliant format YYYY-MM-DD HH:MM, where hours range from 00 to
          23.  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
          [4]modes page for legal modes and formats.  The default is
          text.

   -l "Location Name"
          Specify a location for tide predictions.  You can use the -l
          switch more than once if you want to specify multiple
          locations.

   -m b|c|C|g|l|m|p|r|s
          Specify mode to be banner, calendar, alt. calendar, graph,
          list, medium rare, plain, raw, or stats.  See the [5]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.

   The interactive interface does not support all of these switches and
   options.  For example, you can't pop up a graph with a mark line on it
   by saying xtide -m g -ml 1ft.  Refer to the [6]previous page for a
   list of the options supported by the interactive interface.

   Starting with version 2.6, XTide understands the following syntactic
   shortcuts:
     * Arguments can be concatenated with their switches.
     * A yes/no switch that omits its argument implies "y".
     * Using +xx instead of -xx for a yes/no switch inverts the argument
       (so if the argument is omitted, "n" is implied).

   Some shorthand forms are ambiguous.  For example, -lw5 could mean "set
   the line width to 5" (-lw 5) or it could mean "load the location named
   w5" (-l w5).  If this happens, you will get an error and will need to
   spell out what you meant.
     _________________________________________________________________

     * [7]Next
     * [8]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/modes.html
   3. http://www.flaterco.com/xtide/settings.html
   4. http://www.flaterco.com/xtide/modes.html
   5. http://www.flaterco.com/xtide/modes.html
   6. http://www.flaterco.com/xtide/advanced.html#intopts
   7. http://www.flaterco.com/xtide/xttpd.html
   8. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Nobska Light, Cape Cod, MA, 1998-06-17

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 [2]settings
   switches...].

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

   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.

   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 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.

  Troubleshooting

  Q: When I run xttpd, it exits immediately with no errors to tell me what went
  wrong.

  A: When executed, xttpd immediately disassociates itself from your terminal
  and starts logging all diagnostics to syslog.  So look in your system logs.
  You will find these someplace like /var/log or /var/adm/log.
    ________________________________________________________________________

     * [3]Next
     * [4]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/settings.html
   3. http://www.flaterco.com/xtide/settings.html
   4. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Girl feeding gulls

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 [2]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.

   Canonically, all command line settings take the form -xx value, with a
   space between the switch and the supplied value.  The yes-or-no
   settings get a value of "y" or "n".  However, starting with version
   2.6, XTide understands the following syntactic shortcuts:
     * Arguments can be concatenated with their switches.
     * A yes/no switch that omits its argument implies "y".
     * Using +xx instead of -xx for a yes/no switch inverts the argument
       (so if the argument is omitted, "n" is implied).

   Some shorthand forms are ambiguous.  For example, -lw5 could mean "set
   the line width to 5" (-lw 5) or it could mean "load the location named
   w5" (-l w5).  If this happens, you will get an error and will need to
   spell out what you meant.

   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 Mean Tide Level lines in tide graphs? (y/n)
          Default: n
          Command line: -el
          config.hh: extralines
          .xtide.xml: <xtideoptions el="n"/>

   XTide*flatearth
          Prefer flat map to round globe location chooser? (y/n)
          Default: n
          Command line: -fe
          config.hh: flatearth
          .xtide.xml: <xtideoptions fe="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 location chooser.
          Valid values: -180 -150 -120 -90 -60 -30 0 30 60 90 120 150 360
          360 will pick the longitude with the most tide stations.
          Default: 360
          Command line: -gl
          config.hh: defgl
          .xtide.xml: <xtideoptions gl="360"/>

   XTide*gwidth
          Default width for tide graphs.
          Default: 960
          Command line: -gw
          config.hh: defgwidth
          .xtide.xml: <xtideoptions gw="960"/>

   XTide*hourfmt
          Strftime style format string for printing hour labels on time
          axis.
          Default: %I (Cygwin and Irix); %l (all others)
          Command line: -hf
          config.hh: hourfmt
          .xtide.xml: <xtideoptions hf="%l"/>

   XTide*infer
          Use inferred values for some constituents.  For expert use
          only.
          Default: n
          Command line: -in
          config.hh: infer
          .xtide.xml: <xtideoptions in="n"/>

   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 Tide 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 sun and moon events in output? (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: %I:%M %p (Cygwin only); %I:%M %p %Z (Irix only); %l:%M
          %p %Z (all others)
          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"/>
     _________________________________________________________________

     * [3]Next
     * [4]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/advanced.html#cp
   3. http://www.flaterco.com/xtide/harmonics.html
   4. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]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 [2]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.  Information on
   obtaining harmonics files is at
   [3]http://www.flaterco.com/xtide/files.html.

   Several ways to obtain a complete list of locations in the available
   harmonics files are linked from
   [4]http://harmonics.unh.edu/xtide/files.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 and send this
   information to the current maintainer of the harmonics files, Bob
   Kenney (see linkage at [5]http://www.flaterco.com/xtide/files.html).
   You could do it yourself using the tools available at
   [6]http://www.flaterco.com/xtide/files.html, but please forward the
   data to Mr. Kenney anyway so that others may benefit.

  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
   [7]http://co-ops.nos.noaa.gov/data_retrieve.shtml?input_code=100201001
   har.  If so, just let Mr. Kenney know it's there.

   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 Mr. Kenney a
   statement from the authority either granting permission for
   non-commercial use or explaining that such permission is not required.

   There is 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 [8]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 Mr. Kenney
   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
   [9]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
   [10]http://co-ops.nos.noaa.gov/tp4days.html.  The file at
   [11]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 harmonics.tcd using
   the tideEditor program in the tcd-utils package (available from
   [12]http://www.flaterco.com/xtide/files.html).  Alternately, you can
   add your offsets to offsets.xml (available from
   [13]http://harmonics.unh.edu/xtide/files.html) and then regenerate
   harmonics.tcd using the build_tide_db program in the tcd-utils
   package.  Please refer to the README file in tcd-utils for more
   information on using build_tide_db.

    General notes and warnings

     * 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.
     * 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
       [14]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.  However, 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 don't get slack offsets (floodbegins, ebbbegins) for a
       current station, OMIT those fields!  When slack offsets are
       omitted, XTide will interpolate a reasonable value.  But if you
       specify zero, you get zero -- even if that's unreasonable given
       the skew of max and min.

    Adding corrections using tideEditor

   First set the environment variable HFILE_PATH to point at the TCD file
   that you want to modify.  (This would be a good time to make a back-up
   copy.)

   When you start tideEditor, you get a map of the world.  Point at the
   location where you want to add a subordinate station and right click.

   You will get a prompt asking "Will the new station be a reference
   station or a subordinate station?"  Choose Subordinate.

   You will get a prompt saying "Please select the new reference
   station."  Use the pull-down list to select the reference station and
   click OK.

   You will then get a window with the tabs General and Offsets,
   initially showing General.  General has the following fields.
     * Record Number.  Ignore this.
     * Reference Station.  Already filled in to what you selected.
     * Station Name.  Enter the name of the new subordinate station.
     * Latitude.  Already filled in to the location you clicked, but you
       can change it.  Unlike XTide, which uses degrees out to four
       decimals, tideEditor expresses the latitude in degrees, minutes,
       and seconds.
     * Longitude.  Already filled in to the location you clicked, but you
       can change it.  Unlike XTide, which uses degrees out to four
       decimals, tideEditor expresses the longitude in degrees, minutes,
       and seconds.
     * Source.  Enter a description of where you got the data.
     * Time Zone.  Use the pull-down to set the time zone.
     * Country.  Optional.  Use the pull-down to set the country.
     * Pedigree.  Pedigree is a numerical measure of the
       authoritativeness of the data.  "Hearsay" is always a safe choice.
     * Restriction.  Everybody except DoD personnel can ignore this.
     * Comments.  Optional.

   Offsets has the following fields.
     * Level Units.  Select feet or meters for tides, knots or knots^2
       for currents.  knots^2 occur only rarely, so if you are unsure,
       choose knots.
     * Direction Units.  Optional.  If you use directions, choose degrees
       true or degrees.
     * Minimum Time Add.  The time adjustment for low tide / max ebb.  It
       is expressed as an integer that is hours times 100 plus minutes,
       so for -0:20 (negative 0 hours, 20 minutes) you would write -20,
       and for 1:40 (positive 1 hour, 40 minutes) you would write 140.
       If you don't have this, leave it blank.
     * Minimum Level Add.  A value, in the units identified by Level
       Units, that is added to the tide level or current velocity
       predicted at low tide or max ebb.  If you don't have this, leave
       it blank.
     * Minimum Level Multiply.  A multiplier for the tide level or
       current velocity predicted at low tide or max ebb.  If you don't
       have this, leave it blank.
     * Minimum Average Level.  Optional.  Not used by XTide.
     * Minimum Direction.  Optional.  If desired, specify the direction
       of max ebb in degrees or degrees true as indicated by Direction
       Units.
     * Maximum Time Add, Level Add, Level Multiply, Average Level, and
       Direction are analogous, but correspond to high tide / max flood.
     * Flood Begins.  Another kind of "Time Add" used only by currents to
       adjust the time of the slack preceding a flood.  If you don't have
       this, leave it blank.  If it got initialized to zero, make it
       blank.
     * Ebb Begins.  Analogous to Flood Begins.

   When finished, click OK.  When you quit tideEditor, your new station
   will be saved in the updated harmonics.tcd.

   Notations used to describe corrections will vary:

    Notation              Translation
   -0:20       Time Add -20
   1 23        Time Add 123
   *1.07       Level Multiply 1.07
   +0.4        Level Add 0.4
   (*0.65+0.3) Level Multiply 0.65, Level Add 0.3

   If you were not given separate corrections for max and min, set both
   the max and min values to whatever you got.  For example, if you get

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

   then you should set both Minimum Tide Add and Maximum Time Add to -20.

    Adding corrections in XML format

   Following are examples to illustrate the XML format for offsets.

   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 Curren
t"
  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>
     _________________________________________________________________

     * [15]Next
     * [16]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/introduction.html
   3. http://www.flaterco.com/xtide/files.html
   4. http://harmonics.unh.edu/xtide/files.html
   5. http://www.flaterco.com/xtide/files.html
   6. http://www.flaterco.com/xtide/files.html
   7. http://co-ops.nos.noaa.gov/data_retrieve.shtml?input_code=100201001har
   8. http://www.flaterco.com/xtide/faq.html#60
   9. http://www.flaterco.com/xtide/files.html
  10. http://co-ops.nos.noaa.gov/tp4days.html
  11. http://www.flaterco.com/xtide/lots_of_offsets.txt
  12. http://www.flaterco.com/xtide/files.html
  13. http://harmonics.unh.edu/xtide/files.html
  14. http://www.flaterco.com/xtide/nos_station_list.txt
  15. http://www.flaterco.com/xtide/bugs.html
  16. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Lobster boat and the big ocean, Ogunquit, Maine, 1998-06-08.

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. All timestamps have a precision of plus or minus one minute.
    3. 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).
    4. 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.
    5. 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.
    6. Moonrise and moonset don't work before 1900 or after 2099.
    7. The time scale used by TIME_WORKAROUND is not strictly speaking
       UTC since it does not implement [2]leap seconds.  The maximum
       discrepancy as of 2003 is 22 seconds, which is still "below the
       noise."

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. 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.
    8. 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).
    9. 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.
   10. 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.
     _________________________________________________________________

     * [3]Next
     * [4]Contents

References

   1. http://www.flaterco.com/
   2. http://www.boulder.nist.gov/timefreq/pubs/bulletin/leapsecond.htm
   3. http://www.flaterco.com/xtide/faq.html
   4. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Perkins Cove, Maine, 1998-06-09

Frequently Asked Questions

     * [2]Can you please add predictions for Mumble Foo Bar?
     * [3]Can you tell me where I can find a web page with predictions
       for Mumble Foo Bar?
     * [4]I asked you about a particular location and you sent me to the
       FAQ, but I don't see anything in the FAQ about it.
     * [5]I'm having a problem with a tide-predicting web page.
     * [6]Can you send me predictions for Mumble Foo Bar?
     * [7]Can you tell me the offsets for Mumble Foo Bar?
     * [8]Can you predict the tide and/or current if I give you the
       latitude and longitude?
     * [9]I have a tide watch that only goes through the year 1999.  What
       year could I set it to that would be the same as this year?
     * [10]I am doing some historical research and need to project what
       the tides would have been a long long time ago.
     * [11]I live outside of the U.S. and my location is no longer
       supported.  What happened?
     * [12]The predictions for somewhere in Mexico or Nunavut are off by
       one hour or six hours.
     * [13]For Chesapeake and Delaware Canal Current, Flood and Ebb are
       not informative.  Which way is which?
     * [14]For Cape Cod Canal Current, Flood and Ebb are not
       informative.  Which way is which?
     * [15]When compiling XTide, I get errors like....
     * [16]I want to change the end time of a tide graph but the settings
       that I make have no effect.
     * [17]When I run xttpd, it exits immediately with no errors to tell
       me what went wrong.
     * [18]I always get a warning about "using obsolete time zone
       database."
     * [19]How do I switch from tide to current predictions or vice-versa
       for a given location?
     * [20]You have multiple data sets with the same name or with just
       numbers to distinguish them.  What's the diff?
     * [21]What are bogo-knots?
     * [22]First it says high tide is at 3:15 PM but then when I run it
       again it says 3:14 PM.
     * [23]Has this been ported to Windows / OS/2 / anything but Unix?
     * [24]Why do the high and low tides have such different levels to
       them on any given day?
     * [25]Is there a set time advancement each day for the next high and
       low tide?  Does it always repeat 12 1/2 hours later?
     * [26]If it's high tide here, is it low tide in [faraway place]?
     * [27]What does the zero (0) on a tide chart represent?
     * [28]Why is it that the tides two miles from here are an hour
       different than the tides here?
     * [29]The tides for my location are totally wrong!
     * [30]The tides for Mumble Foo Bar are obviously bogus because they
       have too many high tides on this day / only one high tide on this
       day / tides that are just a few minutes apart.
     * [31]Why are there two high tides per day, anyway?  How is this
       possible?
     * [32]What does "slack water" mean?
     * [33]I have five constituents and some seasonal corrections for my
       location.  Can you get this to work?
     * [34]I have a theory that [random phenomenon] is related to tidal
       forces, but I am landlocked.  Can you, like, predict the "tides"
       for [landlocked location]?
     * [35]I want to write my own tide predicting program.  Can you
       provide a SIMPLE explanation of the tide-predicting function?
     * [36]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 [37]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
   [38]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 asked you about a particular location and you sent me to the FAQ,
   but I don't see anything in the FAQ about it.

   A: "Mumble Foo Bar" is a made-up place that is meant to represent
   whatever place you are looking for.  Whatever is said in this FAQ
   about Mumble Foo Bar applies to your location as well.

   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 [39]What to do if your location
   isn't listed.

   Q: Can you predict the tide and/or current if I give you the latitude
   and longitude?

   A: The short answer is no.  XTide cannot predict tides unless you
   provide harmonic constants (see [40]What to do if your location isn't
   listed).

   From what I'm told, the tide models that were built from
   [41]TOPEX/Poseidon data work on a global scale, but they are
   inaccurate on continental shelves.  Some organizations have
   constructed models that function in coastal waters in localized
   regions.  For example, NIWA has a [42]model for New Zealand's coastal
   waters, and NOAA has a [43]model of currents in San Francisco Bay.
   Although XTide could make use of harmonic constants generated from
   these models, XTide does not implement any such models.

   Q: I have a tide watch that only goes through the year 1999.  What
   year could I set it to that would be the same as this year?

   A: Sorry.  It just doesn't work like that.

   Q: I am doing some historical research and need to project what the
   tides at Mumble Foo Bar would have been a long long time ago.

   A: This is generally ill-advised.

   It is technically possible to get XTide to make projections back to 1
   AD (see [44]http://www.flaterco.com/xtide/time_t.html for details).
   However, such projections are usually unverifiable and are likely to
   be wildly inaccurate.  If you work from these projections with no
   means of independent verification, you deserve what you get.

   The perishability of tide data for a given location varies depending
   on how quickly the local topography changes.  Some places go rotten in
   less than a decade.  All locations are impacted by global sea level
   change, which becomes significant in less than a century.  Needless to
   say, the credibility of projections for anywhere reaches zero well
   before you get back to 1 AD.  So please don't ask for BC support.

   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) were removed from the harmonics
   files in January 2001.

   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 we
   have been forced to remove the associated data from the harmonics
   files.

   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 to Mr.
   Kenney a statement that usage of the old data is not restricted in
   your region, it could be reinstated.  (Bob Kenney is the maintainer of
   the harmonics files that are used by XTide and other programs.  You
   can find them on his web site at
   [45]http://harmonics.unh.edu/xtide/files.html.)  However, if they have
   newer data, it would be better if they just sent that to Mr. Kenney
   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: The predictions for somewhere in Mexico or Nunavut are off by one
   hour or six hours.

   A: The referenced nations have recently made changes to their time
   zones or daylight savings time rules.  In order for XTide to give
   predictions in local time correctly, a recent version of the Zoneinfo
   library must be installed.  You can obtain this library from
   [46]ftp://elsie.nci.nih.gov/pub/.

   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 [47]troubleshooting section of the installation
   instructions.  If your error is not shown there, please email
   [48]software@flaterco.com for assistance.

   Q: I want to change the end time of a tide graph but the settings that
   I make have no effect.

   A: In graph mode, the end time is determined by the applicable width
   and aspect, not the other way around.  Thus, neither the -e switch nor
   the compiled-in defpredictinterval constant have any effect in this
   case.  In the interactive client, you can resize the window as you
   would any window and change the aspect from the Options menu.  The
   applicable command-line switches are -gw for X-windows or PNG formats,
   -tw for text format, and -ga.  For more details, refer to
   "[49]Customizing XTide."

   Q: When I run xttpd, it exits immediately with no errors to tell me
   what went wrong.

   A: When executed, xttpd immediately disassociates itself from your
   terminal and starts logging all diagnostics to syslog.  So look in
   your system logs.  You will find these someplace like /var/log or
   /var/adm/log.

   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
   [50]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: There multiple data sets with the same name or with just numbers to
   distinguish them.  What's the diff?

   A: It often happens that there are 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 there is enough information to
   know which one is best, it is listed first (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: 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 [51]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
   [52]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 Mr. Kenney know and he will delete the offending data
   set.  PLEASE, if possible, cite some predictions from a local
   newspaper or something to corroborate the complaint.

   Q: The tides for Mumble Foo Bar are obviously bogus because they have
   too many 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 only
   one tide cycle per day.  Others generate "extra" tides 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 [53]previous section) or
   a temporary reversal near mid-tide.  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 in the harmonics file with a proper subordinate
   station definition.

   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
   [54]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
   [55]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: XTide is not presently enabled to handle seasonal corrections
   directly.  To my knowledge, seasonal corrections are only used in
   publications by the British Admiralty that do not allow redistribution
   of data, so the value of providing better support for them in XTide
   would be marginal at best.  However, if you have legal access to such
   data and are determined to use it with XTide, it may be possible to
   synthesize values for long-term constituents to "approximate the
   approximation."  A speadsheet for doing this is available from
   [56]http://www.flaterco.com/xtide/files.html.

   Q: I have a theory that [random phenomenon] is related to tidal
   forces, but I am landlocked.  Can you, like, predict the "tides" for
   [landlocked location]?

   A: There is no support for this in XTide (ocean tides have only the
   vaguest connection to latitude, longitude, and the position of the
   moon), but you can find relevant information by searching the web for
   "land tide."

   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.txt
   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
   [57]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.  Customarily, the meridian is chosen to be the standard time
   of the location in question to make life easier on simple tide
   prediction programs that don't mess with time zones or summer time
   adjustments.  In the harmonics.txt file, you will find the meridian of
   each data set right before the time zone identifier, in hours and
   minutes:  e.g., -05:00 :America/Montreal.  It is trivial to adjust the
   phases of the constituents for any desired meridian.  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.  At that time, for
   the purpose that I tried to use it, 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.

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

     * [58]Next
     * [59]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/faq.html#10
   3. http://www.flaterco.com/xtide/faq.html#20
   4. http://www.flaterco.com/xtide/faq.html#25
   5. http://www.flaterco.com/xtide/faq.html#30
   6. http://www.flaterco.com/xtide/faq.html#40
   7. http://www.flaterco.com/xtide/faq.html#50
   8. http://www.flaterco.com/xtide/faq.html#51
   9. http://www.flaterco.com/xtide/faq.html#52
  10. http://www.flaterco.com/xtide/faq.html#57
  11. http://www.flaterco.com/xtide/faq.html#60
  12. http://www.flaterco.com/xtide/faq.html#65
  13. http://www.flaterco.com/xtide/faq.html#70
  14. http://www.flaterco.com/xtide/faq.html#80
  15. http://www.flaterco.com/xtide/faq.html#90
  16. http://www.flaterco.com/xtide/faq.html#92
  17. http://www.flaterco.com/xtide/faq.html#95
  18. http://www.flaterco.com/xtide/faq.html#100
  19. http://www.flaterco.com/xtide/faq.html#110
  20. http://www.flaterco.com/xtide/faq.html#120
  21. http://www.flaterco.com/xtide/faq.html#130
  22. http://www.flaterco.com/xtide/faq.html#140
  23. http://www.flaterco.com/xtide/faq.html#150
  24. http://www.flaterco.com/xtide/faq.html#160
  25. http://www.flaterco.com/xtide/faq.html#170
  26. http://www.flaterco.com/xtide/faq.html#180
  27. http://www.flaterco.com/xtide/faq.html#190
  28. http://www.flaterco.com/xtide/faq.html#200
  29. http://www.flaterco.com/xtide/faq.html#210
  30. http://www.flaterco.com/xtide/faq.html#220
  31. http://www.flaterco.com/xtide/faq.html#230
  32. http://www.flaterco.com/xtide/faq.html#240
  33. http://www.flaterco.com/xtide/faq.html#250
  34. http://www.flaterco.com/xtide/faq.html#255
  35. http://www.flaterco.com/xtide/faq.html#260
  36. http://www.flaterco.com/xtide/faq.html#270
  37. http://www.flaterco.com/xtide/harmonics.html
  38. http://tbone.biol.sc.edu/tide/sitesel.html
  39. http://www.flaterco.com/xtide/harmonics.html
  40. http://www.flaterco.com/xtide/harmonics.html
  41. http://topex-www.jpl.nasa.gov/mission/topex.html
  42. http://www.niwa.co.nz/services/tides
  43. http://sfports.wr.usgs.gov/SFPORTS/vec_map/vec_map.html
  44. http://www.flaterco.com/xtide/time_t.html
  45. http://harmonics.unh.edu/xtide/files.html
  46. ftp://elsie.nci.nih.gov/pub/
  47. http://www.flaterco.com/xtide/installation.html#trouble
  48. mailto:software@flaterco.com
  49. http://www.flaterco.com/xtide/settings.html
  50. http://www.flaterco.com/xtide/sysreq.html
  51. http://www.flaterco.com/xtide/ports.html
  52. http://www.opsd.nos.noaa.gov/tideglos.html
  53. http://www.flaterco.com/xtide/advanced.html#indecisive
  54. http://www.opsd.nos.noaa.gov/restles1.html
  55. http://www.opsd.nos.noaa.gov/tideglos.html
  56. http://www.flaterco.com/xtide/files.html
  57. http://www.flaterco.com/xtide/files.html
  58. http://www.flaterco.com/xtide/design.html
  59. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Sunset over the bar, Bar Harbor, Maine, 1997-06-24

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 template
   library, exceptions, 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." -- DWF, 1998.  I'm still
   waiting! -- DWF, 2002.)

   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 migration from text and XML to the binary TCD format in XTide 2.6
   laid to rest a lot of issues:  the urge to make everything XML; the
   urge to bind everything to Postgres; the urge to add an explicit index
   to improve performance; the urge to support compressed input.  I
   discussed requirements with Mr. Depner to try to ensure that the TCD
   format would be extensible while compromising where necessary so that
   he could deliver the efficiency that everyone wanted.  Let's hope the
   compromise was a good one.

   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 in 2 places, 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."
    6. Constituent inference was patched in via libtcd and maybe could
       have been integrated better.  In theory, you might want to control
       it on a station-by-station basis like preferred units, and it
       probably should not require a station reload to turn it on or off.
     _________________________________________________________________

     * [2]Next
     * [3]Contents

References

   1. http://www.flaterco.com/
   2. http://www.flaterco.com/xtide/credits.html
   3. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Sunset over L.A. Dunton, Mystic, Connecticut, 1998-06-06

Credits

   XTide 1 began as nothing but a tide clock with no other modes and very
   few details.  It grew like a weed with code and ideas being
   contributed by a small but industrious group of people.  XTide 2, on
   the other hand, began as a cathedral-building exercise on my part (see
   "The Cathedral and the Bazaar" by Eric S. Raymond,
   [2]http://www.tuxedo.org/~esr/writings/cathedral-bazaar/).  The
   purpose was to correct the mistakes that were made in XTide 1, most
   importantly to impose a coherent architecture so that the thing would
   become maintainable again.  Nevertheless, it is important to recognize
   that very few of the ideas and very little of the know-how implemented
   in XTide originated with me.  I just took the ideas and knowledge of
   others and turned them into software.

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

     John Thorstensen allowed me to reuse code from his skycal
     distribution ([3]ftp://iraf.noao.edu/contrib/skycal.tar.Z) to get
     the sun and moon calculations.

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

     Jan C. Depner was prolific in delivering the flat map, the World
     Vector Shoreline code, libtcd, tcd-utils, and inferred
     constituents.  Most of his work was paid for by the U.S. Naval
     Oceanographic Office, making them the first (and so far only)
     organizational sponsor of XTide development.  Thanks!

   Other contributions in no particular order:

     A huge thank you to Bob Kenney for taking over maintenance of the
     harmonics files.

     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 a number of xttpd enhancements, 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 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.
     _________________________________________________________________

     * [4]Next
     * [5]Contents

References

   1. http://www.flaterco.com/
   2. http://www.tuxedo.org/~esr/writings/cathedral-bazaar/
   3. ftp://iraf.noao.edu/contrib/skycal.tar.Z
   4. http://www.flaterco.com/xtide/bibliography.html
   5. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

   [1]Moonrise over Marginal Way

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.

   A catalog of information on the ISO 8601 standard date and time
   notation can be found at
   [2]http://dmoz.org/Science/Reference/Standards/Individual_Standards/IS
   O_8601/.

   An article about a model-based approach to tide prediction, which is
   completely different from what XTide does, is

     Derek Goring, "Computer Models Define Tide Variability," The
     Industrial Physicist, v. 7, n. 5, October/November 2001, pp.
     14-17.  Available at
     [3]http://www.niwa.co.nz/rc/prog/chaz/news/tidalmodel.pdf or
     [4]http://www.aip.org/tip/INPHFA/vol-7/iss-5/p14.pdf.
     _________________________________________________________________

     * [5]Next
     * [6]Contents

References

   1. http://www.flaterco.com/
   2. http://dmoz.org/Science/Reference/Standards/Individual_Standards/ISO_8601/
   3. http://www.niwa.co.nz/rc/prog/chaz/news/tidalmodel.pdf
   4. http://www.aip.org/tip/INPHFA/vol-7/iss-5/p14.pdf
   5. http://www.flaterco.com/xtide/time_t.html
   6. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

Appendix A -- Historical predictions and Y2038 compliance

   As of 2002, the average Unix uses a signed 32-bit integer to represent
   time as a count of seconds since 1970-01-01 00:00:00Z.  The limits of
   that representation are 1901-12-13 20:45:52Z and 2038-01-19
   03:14:07Z.  Some platforms instead use an unsigned 32-bit integer
   while others already use 64-bit integers.

   XTide originally limited itself to the range 1970 to 2037.  This
   provided portability and reliable results regardless of the time_t
   representation and allowed Interval (the difference between two
   timestamps) to be represented using a signed 32-bit integer.  However,
   an increasing number of requests for historical "past predictions"
   combined with slow progress in migrating the average Unix platform to
   a time representation capable of surviving year 2038 finally motivated
   the incorporation of a workaround.

   If XTide is compiled with TIME_WORKAROUND defined (see config.hh),
   time_t is redefined as a signed 64-bit integer and the platform's time
   functions are bypassed.  Years from 1 to 4000 are allowed.  However,
   time zones and daylight savings time are sacrificed.  Everything
   becomes UTC. [1]*

   If you want to be able to select the expanded range of dates from
   within the interactive client, you will also need to adjust the range
   of dates offered by the timestamp dialog by changing the values of
   dialogfirstyear and dialoglastyear in config.hh.

   In order to obtain predictions for past and future years, it is also
   necessary to use a harmonics file that supports those years.  You can
   create such a file using the following procedure.
    1. Obtain and build the congen package from
       [2]http://www.flaterco.com/xtide/files.html.
    2. Generate the needed years as explained in the README in the congen
       distribution.  E.g., congen -a1 -b 1800 -e 2200 < congen_input.txt
       > out.txt.
    3. Obtain the ASCII formatted harmonics files harmonics.txt and
       offsets.xml from the site indicated at
       [3]http://www.flaterco.com/xtide/files.html.
    4. Using a text editor, edit harmonics.txt and replace the segment
       between "Begin congen output" and "End congen output" with the
       data that you generated earlier.
    5. Obtain the tcd-utils package from
       [4]http://www.flaterco.com/xtide/files.html and build the
       build_tide_db converter.
    6. Convert the data to TCD format as explained in the README of the
       tcd-utils distribution.

   Please be aware that extrapolating predictions over large spans of
   time may give extremely inaccurate results.  The perishability of tide
   data for a given location varies depending on how quickly the local
   topography changes.  Some places go rotten in less than a decade.  All
   locations are impacted by global sea level change, which becomes
   significant in less than a century.  Needless to say, the credibility
   of projections for anywhere reaches zero well before you get back to 1
   AD.

   * The time scale used by TIME_WORKAROUND is not strictly speaking UTC
   since it does not implement [5]leap seconds.  The maximum discrepancy
   as of 2003 is 22 seconds, which is still "below the noise."
     _________________________________________________________________

     * [6]Contents

References

   1. http://www.flaterco.com/xtide/time_t.html#leap
   2. http://www.flaterco.com/xtide/files.html
   3. http://www.flaterco.com/xtide/files.html
   4. http://www.flaterco.com/xtide/files.html
   5. http://www.boulder.nist.gov/timefreq/pubs/bulletin/leapsecond.htm
   6. http://www.flaterco.com/xtide/xtide.html#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 sun and moon information (by popular demand...)
     * Fast, efficient binary format for harmonics data

   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=/usr/local/share/xtide/harmonics.tcd

       If HFILE_PATH is not set, XTide looks for the file "harmonics.tcd"
       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.
     _________________________________________________________________

     * [1]Next
     * [2]Contents

References

   1. http://www.flaterco.com/xtide/quickinst.html
   2. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

Icon Quick install instructions

    1. XTide requires:
          + 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)
    2. You must download at least one harmonics file.  See
       [1]http://www.flaterco.com/xtide/files.html for details on where
       to get these.
    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.tcd

    4. ./configure; make
    5. You should now have three binaries:
          + xtide, the interactive X-windows client
          + tide, the non-interactive TTY client
          + 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.)
     _________________________________________________________________

     * [2]Next
     * [3]Contents

References

   1. http://www.flaterco.com/xtide/files.html
   2. http://www.flaterco.com/xtide/changelog.html
   3. http://www.flaterco.com/xtide/xtide.html#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.6.4 (2003-11-16)

   (Bugs) Incorporated libtcd patch:

     Version 1.11
     David Flater
     2003-11-16

     (create_tide_db)  Fixed horrible bug:  offsets for speeds,
     equilibrium args, and node factors were sign-reversed with respect
     to their usage in read_tide_db_header and write_tide_db_header,
     resulting in possible overflows.

     (read_tide_db_header)  Added handling for zero tide records, which
     happens on new database create.

     (open_tide_db)  Added check of modified flag to 2003-10-14 code.

     (close_tide_db)  Deleted repeat free of tindex introduced
     2003-10-14.  Cleared modified flag on close.

  XTide 2.6.3 (2003-10-14)

   (Bug) Incorporated libtcd patch:

     Version 1.10
     David Flater
     2003-10-14

     Incorporated patch from Phil Thornton that closes a memory leak and
     improves performance on repeat calls to open_tide_db.  See
     [1]http://www.flaterco.com/xtide/tcd_notes.html

   (Nit) Added a precompiler directive to prevent code inside of assert
   statements from being disabled by over-ambitious optimization.

  XTide 2.6.2 (2003-09-05)

   (Bug) Incorporated libtcd patch:
    Version 1.09
    Jan C. Depner
    2003-09-04

    Bug fix - modifying last record in file and changing size of record caused
    a big problem.

  XTide 2.6.1 (2003-07-23)

   (Bug) Incorporated libtcd patch:
    Version 1.08
    Jan C. Depner
    2003-07-23

    Bug fix - deleting last record in file caused a big problem.

  XTide 2.6 (2003-05-28)

   No code changes; just promoted to final release status.

  XTide 2.6 BETA 4 (2003-03-27)

   (Nit) Updated version string in libtcd.

  XTide 2.6 BETA 3 (2003-03-27)

   (Bug) There was another problem with the encoding of subordinate
   stations in TCD files.  The only stations materially affected this
   time were Gnat Cove, Carroll Inlet, Alaska, and Olga Point, Olga
   Strait, Sitka Sound, Alaska.  However, the fix required another
   incompatible change to the encoding of subordinate stations and
   updates to affected code in libtcd and XTide.  TCD files produced with
   tcd-utils dated earlier than 2003-03-27 and previous development or
   beta versions of XTide 2.6 should be replaced to avoid getting
   incorrect results.

  XTide 2.6 BETA 2 (2003-03-18)

   (Bugs!) tcd-utils was building some subordinate current stations
   incorrectly.  The fix required an incompatible change to the encoding
   of slack offsets and updates to affected code in libtcd and XTide.
   TCD files produced with tcd-utils dated earlier than 2003-03-18 and
   previous development or beta versions of XTide 2.6 should be replaced
   to avoid getting incorrect results on subordinate current stations.
   Except... ironically, it appears that some of the subordinate current
   stations presently in the database are broken in precisely the same
   way as one of the TCD bugs, with the result that in those cases, you
   get the right answer only with the broken code.  The issue with those
   is the bogus assumption that the right thing to do if you don't get
   slack offsets is set them to zero.  If you don't get slack offsets
   (floodbegins, ebbbegins), OMIT those fields!  When slack offsets are
   omitted, XTide will interpolate a reasonable value.  But if you
   specify zero, you get zero -- even if that's unreasonable given the
   skew of max and min.  (This note has been added to the relevant
   portion of the documentation.)

  XTide 2.6 BETA 1 (2003-02-20)

   (Optimization) Changed from ASCII format harmonics files
   (harmonics.txt and offsets.xml) to binary TCD format (harmonics.tcd);
   retired the problematic fast loader since all loading now occurs at
   ludicrous speed.  Thanks again to Jan Depner.

   (Feature) Added setting to enable inferred constituents (Jan Depner).

   (Code rot) Expunged all uses of deprecated C++ streams from the code
   except for the verbose debugging code that hasn't been used in ages.

   (Feature) Added support for the following command line syntactic
   shortcuts:
     * Arguments can be concatenated with their switches.
     * A yes/no switch that omits its argument implies "y".
     * Using +xx instead of -xx for a yes/no switch inverts the argument
       (so if the argument is omitted, "n" is implied).

   (Feature) Overhauled usage of time_t to allow timestamps to range
   before 1970 and after 2037.  Added TIME_WORKAROUND to enable access to
   the past and future years on platforms where time_t is 32 bits.

   (Portability) Changed default time formats when compiling under Irix
   to work around lack of support for %l in SGI's strftime
   implementation.  C.f., similar Cygwin bug fixed in XTide 2.5 BETA 1
   (2002-05-21) and the "fix" that started it all in XTide 2.4 BETA 1
   (2001-03-25).  What a pain.

   (Nits) Gave the control panel a scrollbar.  Stabilized the layouts of
   the control panel, text, raw, and medium rare modes.  Merged
   xxRareModes into xxTextMode.

   (Feature) Replaced the now mostly useless filename field in location
   lists with a type field (reference or subordinate).

   (Feature) The zone at the bottom of tide graphs previously used to
   note slack and mark crossing events is now shared by moon events.  The
   date was replaced with a description that is abbreviated when things
   get crowded.

   (Feature) Added moonrise, moonset.

  XTide 2.5 (2002-07-14)

   (Nit) Tweaked some verbiage in the control panel.

  XTide 2.5 BETA 1 (2002-05-21)

   (Portability) Tweaked autoconfig files to allow clean compilation
   under OS X.  Thanks to Martin Hofmann.

   (Portability) Changed default time formats when compiling under Cygwin
   to work around lack of support for %l and %Z formats by Cygwin's
   strftime implementation.

   (Feature) Added medium rare mode.

   (Feature) Made raw and medium rare modes accessible from the GUI.

   (Feature) Incorporated new globe code, which added coastlines and a
   new flat map projection, from Jan C. Depner.

   (Feature) Allowed switching between Cylindrical Equidistant and
   Orthographic Projections.  Added setting to specify user's preference
   (flatearth).

   (Feature) Globe now rotates on two axes, and both globe and map
   include latitude and longitude readouts.

   (Feature/Portability) Incorporated patch from John Holden to improve
   xttpd user interface for requesting tide calendars and to work around
   an Alpha-specific bug in timestamp rendering.

   (Code rot) Updated :America/Iqaluit, :America/Mexico_City, and
   :Mexico/General in time zone compatibility table.

   (Bug) "Mean Sea Level" verbiage corrected to say "Mean Tide Level."
   Identifiers containing msl were not renamed.

   (Nit) Updated disclaimer text.

   (Nit) Cleaned up xxTimestamp.  N.B., newer versions of Athena Widgets
   now show two columns of choices where pull-down buttons used to run
   off the screen, so the "tiny font" previously used for some of the
   choices is no longer used here.  It is still used in the clock icon.

   (Nit) Added a line to the 'install' target of Makefile.in to create
   the target directories if they do not exist.

  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.
     _________________________________________________________________

     * [2]Next
     * [3]Contents

References

   1. http://www.flaterco.com/xtide/tcd_notes.html
   2. http://www.flaterco.com/xtide/news.html
   3. http://www.flaterco.com/xtide/xtide.html#contents

################################################################

Icon News
     _________________________________________________________________

Hire me

   Experienced programmer, seasoned standards worker, published
   researcher and shameless self-promoter seeks elite frequent flier
   status and a chance at world domination.  However, I'll work for money
   if that's all you've got.  Email [1]dave@flaterco.com for a rsum or
   just make an offer.  (What, don't you trust me?)

   Please hurry.  The weasels are closing in.

XTide 2.6

   New!  Improved!  With Perfect File Magic^TM by Jan Depner, XTide 2.6
   starts up an order of magnitude faster.  harmonics.txt and offsets.xml
   are replaced by harmonics.tcd, which has a compact and efficient
   binary format.  Also by popular demand, moonrise and moonset times are
   now provided.

Obituary:  Edward P. Wallner

   Ed Wallner, author of TIDES4 and a long-time mentor, passed away on
   2002-11-01.

   His son, Mark Wallner, turned over the software saying "do as you
   wish."  I have sorted through everything and distilled it down to the
   collection that you can find at [2]ftp://ftp.flaterco.com/wallner/.
   Please refer to the Readme in that directory for additional
   information.

Data files

   (2002-07-26)  Bob Kenney reports that there was a truncation problem
   with the data files he was distributing.  It is unclear how long this
   problem went undetected.  You may wish to re-download to ensure that
   you have the whole thing.
     _________________________________________________________________

Roadmap to future development

  Things that need fixing

     * Nothing known broken at this time.

  Changes that would not affect tide prediction

   This list is not a promise to implement, but only an acknowledgement
   that the following changes 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.

   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.
     * xttpd: Change mapping of locations to URLs so that links won't
       break when harmonics files are changed.
     * xttpd: Allow selection of IP address on machines with multiple
       addresses.
     * Simon Bridger requested the -b and -e dates to recognize some
       relative and special date specifications, like yesterday, today,
       tomorrow, mon-sun, sat+7 for next saturday.  For example,
       "tomorrow 23:59" or "sat 00:00".  Look for applicable standards.
     * Simon Bridger requested support for multiple -b and -e
       specifications.
     * Tim Cera notes that Options might be more user-friendly if it was
       split into separate menus for "Create new windows" versus "Change
       settings."
     * Add a real color chooser in control panel.  This would come free
       with Qt or similar if we ever migrated from Athena widgets.
     * Graeme Rae suggested a line for the current time in text listings,
       like "2001-03-19 11:50 AM PST 0.10 feet Falling"
     * Constituent inference was patched in via libtcd and maybe could
       have been integrated better.  In theory, you might want to control
       it on a station-by-station basis like preferred units.  But, maybe
       it's a non-issue.  Nobody has complained yet.
     * Simon Bridger requested a "weekend warrior" option that lists
       today, tomorrow, Saturday, Sunday, and next Saturday.
     * 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.
     * David Mendez suggests plotting the derivative of the tide as well
       as the tide -- this is useful for predicting swells.
     * 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.'

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

  Changes that would affect tide prediction

   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
            [3]http://www.pac.dfo-mpo.gc.ca/sci/osap/projects/tidpack/tid
            pack_e.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.
     _________________________________________________________________

     * [4]Contents

References

   1. mailto:dave@flaterco.com
   2. ftp://ftp.flaterco.com/wallner/
   3. http://www.pac.dfo-mpo.gc.ca/sci/osap/projects/tidpack/tidpack_e.htm
   4. http://www.flaterco.com/xtide/xtide.html#contents
