This is the readme file for Tide Tool 2.1a for the Palm Pilot.  For 
changes from earlier versions (and we have some nice ones), see "What's New."

Of course you will want to read this entire file before skipping to the
"INSTALLATION" section below.  

IF YOU HAVE QUESTIONS, FIRST SEE THE FAQ:
http://www.toolworks.com/bilofsky/tidefaq.htm.

THIS MAY NOT BE THE MOST RECENT VERSION OF TIDE TOOL.  Check the Tide
Tool web page at http://www.toolworks.com/bilofsky/tidetool.htm.  To be
notified of new releases, see http://www.toolworks.com/bilofsky/tideemail.htm.

Tide Tool is copyrighted, licensed freeware.  It is not public domain.  See 
"License" below.

If Tide Tool doesn't work for you, please let me know so I can fix it.
And if you have an unusual or interesting use for Tide Tool, please tell me.

Walt Bilofsky
bilofsky@toolworks.com

*** U.K. USERS - READ "NOTE TO USERS IN THE BRITISH ISLES" BELOW. ***

******************************************************
**   WARNING: Tide Tool uses unverified tide and    **
**   current data which comes from many sources     **
**   and has not been thoroughly tested.            **
**                                                  **
**  CHECK TIDE TOOL AGAINST YOUR LOCAL TIDE TABLES  **
**       TO VERIFY THE DATA FOR YOUR LOCATION.      **
**                                                  **
**   DO NOT RELY EXCLUSIVELY ON TIDE TOOL WHERE     **
**     SAFETY OF LIFE OR PROPERTY IS AT RISK!       **
******************************************************

Agencies like NOAA exist because there is a need for certifiably correct 
tide predictions.  Do not rely on these predictions if you need guaranteed 
results.  There is NO WAY we can get certified data on a zero budget. We 
rely on users like you to tell us when something is wrong. Please continue 
to do so.

NOTE: Tide Tool uses algorithms best suited to North America.
Tide computations should generally agree with local tables in North
America to within a few minutes, unless the specific locations for 
Tide Tool and the tables are different.  In other parts of the world,
the difference from local tables may be greater.  In some locations in 
Australia, the difference can be up to an hour or two.  Also note that
the sunrise and sunset computation is approximate.

Predictions for offset locations (indicated by a little circle at the 
end of the location name) are approximations derived using a time and magnitude 
offset from a known "reference station".  This can give strange results in some
cases.  In particular, the graphs for offset locations are drawn using simple 
interpolations and should be regarded as rough approximations.


REQUIREMENTS:
-------------

To run Tide Tool, you need a Pilot handheld computer, or other handheld (such
as the Handspring Visor) running the Palm OS (Operating System).  If you don't 
have these, see the FAQ (http://www.toolworks.com/bilofsky/tidefaq.htm).


INSTALLATION:
-------------

	To install Tide Tool on your Palm, use the Palm Install Tool on your PC 
	to install three files:

		tidetool.prc
		TideArgs.pdb
		and one (or more) regional database file (See list of files at the
			end of this document).

	IF YOU ARE UPGRADING FROM AN EARLIER VERSION OF TIDE TOOL, DELETE THE OLD
	VERSION FROM YOUR PALM BEFORE INSTALLING THE NEW ONE.

	Because the regional database files make the location selection process 
	run more slowly, and take up considerable RAM, only install the files for the 
	regions you're interested in.  (Or disable some of the installed regions.
	See "About the Regional Databases" below.)

	To add another set of locations, install the additional regional
	database file.  To delete or disable a region, use the Edit menu.

	If conserving memory is important, you can install SmallArgs.pdb instead
	of TideArgs.pdb.  This saves about 24k of memory, but will only allow
	tide computation from 1998 to 2014, instead of to 2031.


TIDE AND CURRENT DISPLAY:
-------------------------

The first time you run Tide Tool, it will (after a one-time initial message)
compute today's tides at the default tide location for the region you loaded.

You will also see the present time and tide displayed right under the date.
This will not appear when you change to a date other than today.

You can switch to a graphical display by tapping the Graph button.

If you want a prediction for a specific time, use the graphical display, and
tap the graph at the time you want.  The time and tide line will show the
prediction.  If displaying today's predictions, tapping the prediction text
will return to the "now" status.

The phase of the moon and the state of the sun (up, down or near the horizon)
are also shown.  Tap the sun or moon for more details.  

The Prev button goes to the last previous location you displayed.

To see a tide or current for a different location, use the Place button (see
next section).

If portions of the tide graph or the background shadings are too light to read, 
adjust the contrast, or use the Edit/Preferences menu command to turn off 
grayscale display.



HOW TO FIND AND CHANGE LOCATIONS:
---------------------------------

The only locations for which Tide Tool can compute tides or currents are
the ones in its database (see "About the Regional Databases").  

To see a list of the locations in the database, hit the Place button on the
main screen.  This shows you a list of all the locations, in order of their
approximate distance from the location that was just displayed on the main
screen.

To see currents instead of tides, or vice versa, use the checkboxes.  This
is an easy way to get the closest current to your displayed tide location,
or vice versa.  (For example, if you are looking at the tide display, and want 
to see the nearest current location to the tide location you're looking at, hit 
Place, then the Currents checkbox, then OK.)

(There is usually not both tide and current data available for the same 
location.  In many parts of the world there are few or no current locations 
available.  See "About the Regional Databases" for more information.)

To view a list of the places you have viewed recently, check Previous.  Up to
32 locations are remembered.  Tide and current locations are mixed in this list.

To pick another location, tap it and hit OK.

The locations that have a tiny superscript 'o' at the end of the name are offset
locations.  They are computed by taking fixed differences from the tides or
currents at a reference station some distance away.

If you only want to see the reference stations, not the offset stations, press
Menu, select Edit/Preferences, and select "Ignore secondary stations".

To pick a location near another location you see, tap it, hit FIND, go
to the Find screen, and use Set Position To.  Or tap the location, hit OK to 
view that location, hit Place to return to the Place screen, and select Tides 
or Currents if necessary.

Also use the Find button:
	- To search for a location by name or substring
	- To find any locations near a known latitude /longitude


OTHER CONTROLS:
---------------

To see tides or currents for a date other than today:

	- Presss the scroll buttons to move back or forward one day.
	- Press any day of the week on the bar at the top of the screen.
	- Press the arrows on the week bar to move back or forward one week.
	- Use the Date button on the tides/currents screen.
	- The weekend days on the week bar, when highlighted, go to the other
		weekend day.

Tide Tool displays tides for dates from January 1, 1998 through December 30, 
2031.

To change the units displayed on the screen, press Menu and select
Edit/Units.  The Default setting will use the default units for each location.

To see the time zone information for the location you are viewing, press Menu
and select Info/Time Zone.

To see which regional databases are loaded, and some information about them,
and to disable or delete unwanted databases, press Menu and select Edit/Regions.
(See "About the Regional Databases").

For information about the location you are viewing, press Menu and select
Info/Location.  This will tell you the latitude and longitude of the location,
which regional database it is in, whether it is computed as an offset from
a reference station, and how many harmonic factors are used in the computation.
Offset locations and locations with many harmonic factors take longer to compute.

To turn color or grayscale display on or off, press Menu and select Edit/
Preferences.  If no color or grayscale option is shown, your device does
not support them.

To beam Tide Tool to another Palm device, press Menu and select Edit/
Beam Tide Tool.  Beaming from the Applications screen just sends tidetool.prc.
This function will send both tidetool.prc and all the database files (except
any that you have marked Disabled on the Edit/Regions menu).


SUN AND MOON FUNCTIONS
----------------------

To see the sunrise and sunset times for the day being displayed, tap on the
sun (or use the Info/Sun menu item).  Also, if the graph is displayed in color 
or shades of gray, the graph background indicates day and night times.  Sunrise 
and sunset times are generally accurate to within a few minutes in most latitudes, 
but can be off by as much as an hour or two at high latitudes when the sun is 
travelling nearly parallel to the horizon.  

To see the moon phases for the current month, and time of moonrise and moonset,
tap on the moon (or use the Info/Moon menu item).  Moon phases computed by Tide 
Tool are generally accurate to within one day.  Moonrise and moonset times are
good to within a minute or so.  The moon icon shows the current moon phase (one 
of 8 possibilities).

The sun icon shows whether the sun is up, down or on the horizon at the 
location being displayed, at today's date and local time.  If you're displaying
a location in the same time zone you're in, that's no problem.

But if you're in California and displaying Japan at 10:00 am California time, 
the sun icon will show the state of the sun in Japan at 10:00 am Japan time.  
Some day Palm OS will let you say where you really are, and this will all make 
more sense.

"On the horizon" means from 20 minutes before sunset to 40 minutes after.  Yes,
I know that there are algorithms for better computation of twilight, but I 
don't have one yet.


ABOUT THE REGIONAL DATABASES:
-----------------------------

Tide Tool comes with about 25 regional database files covering the entire
world (except for the British Isles; see note below).  Use the Edit/Regions 
menu command and tap an information icon to see what is in the databases 
you have loaded.

It is possible to load many or all the databases into your Palm, if you don't 
mind using up over a megabyte of memory.  You can also load the Tide Tool 
program and databases into flash memory or a ROM cartridge, if you have the 
necessary software and hardware.

However, Tide Tool is not capable of using all or even most of the locations 
at one time, so you may get an error when trying to go to the Place screen.  
Also, the more locations that are available, the slower the sort process when 
selecting locations.

To deal with this, you can temporarily disable some of the databases.  Go to
the Edit / Regions menu command, and use the pulldowns to set some of the
databases to "Disabled".  They will remain in memory, but you will not 
see them when searching or selecting locations until you enable them again.

The locations that you have viewed recently will still be available in the
"Locations Viewed Recently" list on the Places screen (the "Previous" checkbox), 
even if they are in a disabled database.

The databases are based on the harmonics files distributed with XTide 2.3,
using the latest data sets as of 4/7/01.  See http://www.flaterco.com/xtide.
The full location list as of 4/7/01 is on the web site at
http://www.toolworks.com/bilofsky/tidetool.htm.

I DO NOT ADD LOCATIONS TO TIDE TOOL.  I ONLY INCORPORATE LOCATIONS THAT
ARE IN, OR HAVE BEEN ADDED TO, THE XTIDE DATABASE.

IF YOU WANT YOUR LOCATION ADDED:  DO NOT ASK ME.  You must submit tide data
for your location to the XTide database.  See http://www.flaterco.com/xtide
/harmonics.html.  For most locations, this would mean submitting a set of 
offsets from a known reference location.  In some cases you would need to 
find or generate a set of harmonic constants.

Once the location has been added to the XTide database, I will incorporate it
into the next release of Tide Tool.

For information about your installed regional databases use the Edit menu.


ABOUT DAYLIGHT SAVINGS TIME:
----------------------------

Tide Tool tries to take into account the effects of local daylight savings
time.  On the tide/current display, next to the date, you will see the
time zone(s) that apply to the day being displayed.  You can check whether 
daylight savings is being applied correctly (and I hope you do) by hitting
the [Date] button and using the calendar to go to the day on which DST 
switches over.  If the program is doing this correctly, you'll see
something like:

	Oct 27, 1997 - EDT/EST

to indicate that both times apply at some part of the day.

If you find an error, please email me: bilofsky@toolworks.com.

To see the details for the location being displayed, hit the Menu button and
select Info/Time Zone.  DST can be suspended using the Edit/Units menu item.

Most areas that do not observe daylight savings time have their time zone
given relative to GMT (or Greenwich Mean Time, which is now usually called 
UTC, but GMT has a better flavour).  

NOTE: SPRING FORWARD, STUMBLE BACK:  Because the PalmPilot clock keeps
local time, it is impossible to know the real (GMT) time during the hour 
when DST "falls back".  For example, if it is 2:30 a.m. on the fourth 
Sunday in October in North America, there is no way for the program to 
know if it is 2:30 DST or 2:30 standard time.  Therefore, event times 
that fall within that hour may be off by one hour.

NOTE ON HISTORICAL DATES:  Tide Tool incorporates the DST calculations 
available as of September, 1997, as best I can figure them out.  Some time
zone information has been updated in response to user reports or other more
recent information.  Many countries have changed their DST policy in the 
past, but Tide Tool just assumes that the rules for dates earlier than 1997 
(or later, for that matter) use the same rules.

NOTE ON IRAN:  Iran, alone among the countries in the Tide Tool database,
uses the Persian calendar rather than the standard calendar of the Great
Satan.  This makes it difficult to calculate the correct switchover date
for DST.  The program should be correct for 1997 through 1999, and off by
no more than one day thereafter.  BTW, the only country with worse 
calculations is Israel, but Tide Tool fortunately has no Israel location
data.


ACCURACY OF PREDICTIONS:
------------------------

Tide Tool's accuracy varies.  It is pretty good in North America 
(usually within a few minutes) but not so good elsewhere. In some parts 
of Australia it can be off by an hour or more.  This is a limitation of 
the prediction method it uses, and the data sets available.

Before using Tide Tool's predictions, you should compare it with your 
local published tide tables to get a feel for how close it comes.

Predictions at offset locations (indicated by a little 'o' at the end
of the location name) are inherently approximate.  The event times (high
tide, max ebb, etc.) should be pretty good.  Predictions between events
on the graph display are really nothing more than intelligent guesses and 
should not be considered reliable.


OTHER LIMITATIONS:
------------------

Currently, the program assumes that the local date and time in your PalmPilot 
is the same as the local time and date of the tide location.  So if you're
displaying a location in a different time zone and it's 3:45 pm where you are,
the display will say it is now 3:45 pm at the tide location, but it isn't.
Of course, if you're not there, you probably don't care.


WHAT'S NEW:
-----------

Changes in v. 2.1:
	Displays in color or grayscale on devices that support it under PalmOS
		3.0 or later.
	Tide Tool can be beamed, and moved into flash memory.
	Any number of databases can be loaded; regions menu item allows them
		to be disabled individually.
	In Place screen, controls are active during sort.  In other words, you
		don't have to wait for the sort to finish before doing anything.
	All database files renamed (again); now Palm and Windows filenames agree.
	Locations in the British Isles have been removed; see note below.

Changes in v. 2.0:
	Graphical display of tides and currents.
	Tap the graph to get a prediction for a specific time and date.
	Major speed improvements (implemented by Jeff Dairiki).
	Over 6100 locations worldwide are included.  Many new places have been
		added, particularly in Japan, Canada and Australia.  Some database
		files have therefore gotten larger, even though they are better
		compressed.
	Secondary, or offset, locations added (relative to reference stations).
	The geography of the database files has been rearranged.
	The database files have gotten even larger.  Sorry - this is the price
		of progress.  Have you considered a new handheld with more RAM?
	Time of moonrise and moonset.
	Added progress thermometer to location chooser screen.
	Date format follows preference set in Palm OS

Changes in v. 1.2:
	Compatibility with Palm OS 3.1 (Euro character display bug).

Changes in v. 1.1c:
	Bug fix: Crashed if run without tideargs database file loaded.
	Bug fix: Fixed read from low memory error under Palm emulator.

Changes in v. 1.1b:
	Eastern Canada database: Four tide (including Halifax) and one
		current location added.
	South central Australia time is now correct (GMT+9:30).

Changes in v. 1.1:
	Return to recently displayed places (on the Places screen).
	Added sunrise/sunset times and moon phase.
	Bug fix: DST fixes for Australia and New Zealand from Betas 3 and 4
	Bug fix: Event times earlier than 0000 GMT redisplayed incorrectly.
	Bug fix: Deleting the database containing the location you're looking
		at now works properly.
	Three missing places added to the Carribean database (in v1.1a).
	
Changes in v. 1.01: 
	Added databases for the rest of the world.
	In tide/current display, the scroll buttons change the date.
	Edit menu (was Preferences) now allows deleting regional databases.
	Place form header now indicates Tide or Current.
	Bug fix: Event times on DST fall-back day were off by 1 hr.
	If displaying today and turned off and later on, or midnight passes, 
		keeps on displaying today.


FUTURE FEATURES:
----------------

My current wish list includes:

	A scroll bar for the locations list.

Additions are welcome; doubly so if you want to help implement them. :-)


NOTE TO USERS IN THE BRITISH ISLES:
-----------------------------------

The U.K. Hydrographic Office has taken the position that, in their opinion, our use 
of their tidal information "infringes the intellectual property of the Crown". 
Hence all sites within the British Isles have been removed, as well as a number of
other locations worldwide.  I regret the inconvenience to users, especially in the U.K.,
caused by this position of your government.

For more information and hints on where to complain, see 
http://www.toolworks.com/bilofsky/bloodypain.htm.


LICENSE:
--------

Tide Tool - A tide and current prediction program for Palm OS
Copyright (c) 1997-2001 Walt Bilofsky
Tide algorithms modified from XTide 1.5 (c) 1995, 1996 David Flater
Tide database from XTide 2.3 (c) 2001 David Flater

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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.


CREDITS:
--------

Tide Tool is based on a number of programming projects by individuals who
made their work available at no charge, over the Internet.  Particular
thanks to:

	David Flater, author of XTide. (Also starring:  Jef Poskanzer; 
		Jack Greenbaum; Rob Miracle; Geoff Kuenning; Dale DePriest; 
		Stan Uno; Dean Pentcheff; Jeff Dairiki; Eric Rosen.)

	Jeff Dairiki, who was kind enough to insert his superfast tide 
		computation code into Tide Tool.

	The developers of the GNU C++ compiler and the programmers who
		ported it to the Palm Pilot

	Greg Hewgill for CoPilot, the PalmPilot emulator for Windows,
		without which TideTool would not have been completed until 2037.

	Wes Cherry for the Pilot Resource Compiler, PilRC.

Tide Tool is named in honor of The Software Toolworks (later called Mindscape), 
developer of many great software products including The Chessmaster, Mavis 
Beacon Teaches Typing, and The Miracle Piano Teaching System.  

I started The Software Toolworks in 1980 by writing and selling software 
for the Heathkit H-89 computer.  The H-89 featured an 8-bit Z-80 processor 
running at 2 MHz, 48k (not meg) of RAM, and one floppy disk drive with a 
capacity of 90K bytes.

Although the PalmPilot is considerably more powerful than the H-89, the
community of software developers which has coalesced around the Palm OS's
open software architecture is reminiscent of the cooperative energy that
infused the early days of personal computer software publishing.


SOURCE CODE:
------------

Under the terms of the GNU software license, you are entitled to a
machine-readable copy of the source code of this program.  As of
March 1998, the source code for version 1.1a is available on the Tide 
Tool web site at http://www.toolworks.com/bilofsky/tidesource.htm.  Please 
note the cautions, especially the one about the source code being
unsupported.  As of October 2000, the source for version 2.0 has not yet
been posted, but it will be in due course.  If you want the source,
email me at bilofsky@toolworks.com.

Please also note that the source code is subject to the terms of
the GNU public license, so if you're thinking of making your
fortune by selling something that uses it, please think again.
Sorry.


APPENDIX - FILES:
-----------------

The following files are included in this distribution:

		README.TXT		This file
		tidetool.prc	The program file
		TideArgs.pdb	Data for the tide computation algorithm
		SmallArgs.pdb	A smaller substitute for TideArgs 
					(covers years to 2014 instead of 2031)
		GPL			The GNU public software license

and the following regional databases containing tide data 
for different regions (and current data in North America).

	Maine to Massachusetts.pdb       Massachusetts to Maine
	Newport RI to Cape May NJ.pdb	   Newport, R.I. to Cape May, N.J.
	Cape May NJ to Virginia.pdb	   Cape May, N.J. to Virginia
	North Carolina to Georgia.pdb	   North Carolina to Georgia
	Florida East.pdb	               Florida (east of Sarasota)
	Gulf Coast & Florida West.pdb    Gulf Coast, and Florida (Sarasota west)
	Alaska.pdb                       Alaska
	U.S. West Coast.pdb              West Coast of the U.S.
	Canada (Southeast), N Atl.pdb    East Coast of Canada and N. Atlantic ocean
						     (s. of 47 N)	
	Canada (Central East), N Atl.pdb East Coast of Canada and N. Atlantic ocean
						     (47 N to 53 N)	
	Canada (Northeast), N Atl.pdb    East Coast of Canada and N. Atlantic ocean
						     (n. of 53 N)	
	Canada (Southwest).pdb           West Coast of Canada (s. of 49.5 N)
	Canada (Central West).pdb        West Coast of Canada (49.5 N to 51 N)
	Canada (Northwest).pdb           West Coast of Canada (n. of 51 N)
	Carribean.pdb                    Carribean, Central and South America (n of 
					           the equator)
	Mexico.pdb		               Mexico
	South America.pdb                South America (s of the equator)
	Northern Europe.pdb              Europe (n. of 46.5 N) including all of Russia,
							but excepting the British Isles (note above)
	Mediterranean.pdb                Mediterranean, including Europe (s. of
                                         46.5 N) and Africa (n. of 31 N)
	Africa, Asia Minor.pdb           Africa (including Asia Minor e. of 60 E)
	Asia.pdb                         Asia (w. of 60 E), excluding Japan.  Includes
                                         Indonesia and the Philippines
	Japan (Southwest).pdb		   Southwest half of Japan (west of 134 E)
	Japan (Northeast).pdb		   Northeast half of Japan (east of 134 E)
	Pacific Islands.pdb              Islands of the Pacific west of 131 E including
                                         New Zealand, Tasmania and Papua/New Guinea
	Australia.pdb                    Australia
