This is the readme file for Tide Tool 1.1 for the Palm Pilot.
For changes from earlier versions, see "What's New."

Of course you will want to read this entire file before skipping to the
"INSTALLATION" section 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, tell me.)

Tide Tool is copyrighted, licensed freeware.  See "License" below.

Walt Bilofsky
bilofsky@toolworks.com

******************************************************
**   WARNING: Tide Tool uses unverified tide and    **
**   current data which comes from many sources     **
**   and has not been exhaustively 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!       **
******************************************************

Note: The PalmPilot's ability to perform complex mathematical
calculations is limited.  Tide computations should generally agree
with local tables to within a minute or two, unless the specific
locations for Tide Tool and the tables are different.  Sun and
moon computations are approximate.

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

To run Tide Tool, you need a U.S. Robotics PalmPilot (or PalmPilot
Professional) and the PalmOS version 2 operating system.  If you don't
have these, see the FAQ (http://www.toolworks.com/bilofsky/tidefaq.htm).


FILES:
------

	The following files are included in this distribution (filenames may
	be truncated in the zip file but they aren't critical):

		README.TXT	This file
		tidetool.prc	The program file
		TideArgs.PDB	Data for the tide computation algorithm
		TideArgL.PDB	A larger version of the tide computation data
		GPL		The GNU public software license

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

		USWest.pdb        West Coast of the U.S.
		USNewEngland.pdb  Massachusetts to Maine
		USMidAtlantic.pdb Rhode Island to DelMarVa Penninsula
		USSoutheast.pdb   Chesapeake Bay to Georgia
		USFlorida.pdb     Florida
		USGulfCoast.pdb   Alabama to Texas (not many places)
		USAlaska.pdb      Alaska (but Anchorage doesn't work very well)
		CanadaE.pdb       East Coast of Canada and N. Atlantic ocean
		CanadaSW.pdb      West Coast of Canada (s. of 49.5 N)
		CanadaCW.pdb      West Coast of Canada (49.5 N to 51 N)
		CanadaNW.pdb      West Coast of Canada (n. of 51 N)
		Carribean.pdb     Carribean, Central and South America (n of 
						the equator)
		Mexico.pdb		Mexico
		SAmerica.pdb      South America (s of the equator)
		GreatBritain.pdb  British Isles
		EuropeN.pdb       Europe (n. of 46.5 N) including all of Russia
		Mediterranean.pdb Mediterranean, including Europe (s. of
                                  46.5 N) and Africa (n. of 31 N)
		AfricaW.pdb       Western Africa (w. of 40 E, s. of 31 N)
		AfricaE.pdb       Eastern Africa and Western Asia (w. of
                                  60 E; see DST note re: Iran)
		AsiaSE.pdb        Southeast Asia (s. of 21.1 N) including
                                  Indonesia and the Philippines
		AsiaNE.pdb        China (except s. of 21.1 N), Japan, Korea
		PacificIs.pdb     Islands of the Pacific west of 130 E 
                                  including New Zealand, Tasmania and Papua/NG
		Australia.pdb     Australia


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

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

		tidetool.prc
		TideArgs.pdb
		and one (or more) regional database file (see previous section).

	If you are updating from an earlier version, you should delete Tide Tool
	from your PalmPilot before installing the update.

	Because the regional database files take up so much RAM, you can 
	install just the files for the regions you're interested in.

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

	TideArgs.pdb allows tide computation for years 1995 through 2010.  
	If you enjoy raw power, or love being able to plan ahead, install 
	TideArgL.pdb instead of TideArgs - it is 8K larger and gives you the 
	years 1990 through 2032.  


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 line will not appear when you change to a date other than today.

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.

Tap the Current button to see the currents for today at the default current
location (or an error message if there is no current data for the region you 
loaded).

Note that the tide and current locations are not necessarily near each other.


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 next topic).  

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

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

To pick another location, tap it and hit OK.

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

To change the units displayed on the screen, press Menu and select
Edit/Units.

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 delete unwanted databases, press Menu and select Edit/Regions.

To see the sunrise and sunset times for the day being displayed, tap on the
sun (or use the Info/Sun menu item).  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, tap on the moon (or use the 
Info/Moon menu item).  Moon phases computed by Tide Tool are generally 
accurate to within one day.  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.  That is, if
you're in California and displaying Japan at 10:00 am California time, the sun
will show the state of the sun in Japan at 10:00 am Japan time.  Some day Tide
Tool 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:
-----------------------------

The databases are based on the harmonics files distributed with XTide 1.6.
See http://www.universe.digex.net/~dave/xtide.  

IF YOU WANT YOUR LOCATION ADDED:  You must find or generate a set of
harmonic constants for your location, and contribute them to the XTide
database.  See http://www.universe.digex.net/~dave/xtide.  (Eventually 
Tide Tool may accept user-entered locations which are offsets of known ones.)

The databases are tedious to generate, so they tend to be large in order
to reduce the manual labor involved.  I haven't done the whole world yet,
but if you want a particular region let me know.

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:  Bbecause 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.  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 as 1997.  

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


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

Here's an explanation of why it sometimes takes a while to display 
tides and currents, and sometimes they display instantly:

The Palm Pilot takes several seconds to perform all the calculations 
needed to compute a tide and current, due to its limited arithmetic 
capacity (no floating point processor).

Because computation is slow, Tide Tool remembers up to 16 computed
(or partially computed) pages, and can display them instantly when
you return to them.  It tries to favor pages you have looked at recently,
and data for today.

When you start Tide Tool, it takes a few seconds longer for the first
computation.  This is because it is generating a table of cosines.
Tide Tool speeds up its computations by using this table rather than 
computing cosines - each high or low tide computation needs about 400 
cosines, and it's slow.  It would take 4K of PalmPilot RAM to store the 
table, so Tide Tool computes the table each time it starts up.  This 
takes about three seconds.


LIMITATIONS:
------------

If two tide or current events are closer together than about an hour, the
program may not pick them up.  PLEASE LET ME KNOW if this is significant
in your area.

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. 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.
	
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.
	User-specified locations as offsets from known locations.
	Display in graph form.

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


LICENSE:
--------

Tide Tool - A tide and current prediction program for the USR PalmPilot
Copyright (c) 1997 Walt Bilofsky
Tide algorithms modified from XTide 1.5 (c) 1995, 1996 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.)

	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, 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 U.S. Robotics'
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.  For the 
moment, I am discouraging such distributions - Tide Tool is my first
PalmPilot program, and until I understand the UI system calls better,
it shouldn't serve as an example for anyone else.  However, if you
insist, send two dollars and a self-addressed, stamped envelope
(32 cents) to Walt Bilofsky, P.O. Box 111, Corte Madera, CA 94976,
and I'll mail you a disk.  You MUST include an email address with
your request.

