Shareware Distance Functions v1.0 for Russ Webb's RPN Calculator
(Free Distance Functions v1.0, Registered Distance Functions v1.1)
Copyright (c) 1997 by Marvin E. Wilborne III

Overview
--------
This function set allows you to calculate the distance between two points on
the surface of the Earth.  There are two versions of the function sets, both
with identical user interfaces.

The principle difference is accuracy.  The free version is semi-accurate,
and the shareware version is highly accurate.  The registered version works
in both angle modes, Rad or Degree, and the Freeware and Shareware distance
functions only work in Degree mode.  

This text file is the same for both with examples that show the differences
in accuracy.

This function set is an extension to Russ Webb's RPN calculator which is
separately registered shareware and is available at this web site:

        http://kale.ee.cornell.edu/pilot/


Operation
---------
Once you install the PDB file included with the distribution, 7 functions
will be added to Russ Webb's RPN calculator next time you hotsync.

The functions and their discriptions follow:

Function        Description
========        ===========
dec             This function converts a number on the stack in degrees
                minutes and seconds format to decimal degress.  The number
                should be in dd.mmss format.

                For example, to convert 46 degrees 36 minutes 15 seconds to
                decimal format:

                Enter 46.3615 on the stack
                Press "dec"
                Answer on the top of the stack should be:  46.604167

                This function is necessary because all of the calculations
                are done with decimal degrees and the calculator needs to
                be in DEGREE mode when performing distance calculations.
                (You can work in RAD mode with the Registered version 1.1.)

hlon            Use this button to store the longitude of your favorite
                or home location.  The value should be in decimal degrees
                so you'll need to use the "dec" function to convert it before
                storing it with this function.  The value stored here is
                used by the "xh" function described below.

                Example:

                Your home longitude is 79 degrees 26 minutes West.
                Enter 79.26
                Press "dec"     stack value:  79.433333
                Press "hlon" 

hlat            Use this button to store the latitude of your favorite or
                home location.  The value should be in decimal degrees so
                you'll need to use the "dec" function to convert it before
                storing it with this function.  The value stored here is used
                by the "xh" function described below.

                Example:

                Your home latitude is 36 degrees 34 minutes North.
                Enter 36.34
                Press "dec"     stack value:  36.566667
                Press "hlat"

x               Calculate the distance between two locations who's decimal 
                longitude and latitude are the top 4 elements on the stack
                and return the answer in kilometers.

                Decimal degrees are required for each of the items, they
                should be in longitude-latitude-longitude-latitude order and
                East and South are NEGATIVE.

                Example:

                How far is it from Danville, Virginia USA to Tokyo, Japan?
                (Danville is 79 degrees 26 minutes West, 36 degrees 34
                minutes North, and Tokyo is 139 degrees 46 minutes East, 35
                degrees 42 minutes North)

                Enter:  -139.46
                Press "dec"     stack value:  -139.766667
                Enter:  35.42
                Press "dec"     stack value:  35.7
                Enter:  79.26
                Press "dec"     stack value:  79.433333
                Enter:  36.34
                Press "dec"     stack value:  36.566667
                Press "x"       stack value:  11040.323390
                        
                        which is the answer in kilometers
                
                Press "k2m"     stack value:  6860.138907
                        
                        which is the answer in miles

                The FREE distance functions return:
                11017.093060 kilometers or 6845.704250 miles.

                Another Example, this one taken from Jean Meeus' book
                "Astronomical Algorithyms" published by Willman-Bell, Inc.

                How far is it between the U.S. Naval Observatory at
                Washington DC and the Observatoire de Paris (France) using
                these coordinates?

                Paris:  2 degrees 20'14" East
                        48 degrees 50'11" North

                Washington:  77 degrees 03'56" West
                             38 degrees 55'17" North

                Enter:  -2.2014
                Press "dec"     stack value:  -2.337222
                Enter: 48.5011
                Press "dec"     stack value:  48.836389
                Enter: 77.0356
                Press "dec"     stack value:  77.065556
                Enter: 38.5517
                Press "dec"     stack value:  38.921389
                Press "x"       stack value:  6181.628543
                        
                        which is the answer in kilometers and in the
                        book is listed as 6181.63km with an accuracy of
                        50 meters.

                Press "k2m"     stack value:  3841.085897

                        which is the answer in miles.

                The FREE distance functions returns the following answer
                6165.584439 kilometers.  So, it's off by approximately
                16.04 kilometers which may be or may not be critical for
                your needs.

xh              Calculate the distance between the decimal longitude and
                latitude on the stack and the location stored using "hlon"
                and "hlat" described above and return the answer in
                kilometers.

                Use this function if you frequently calculate the distance
                between your home or favorite location, stored using "hlon"
                and "hlat" described above and some other point if you know
                the longitude and latitude.

                Example:  Let's say I've previously stored the coordinates
                of Danville, VA using "hlon" and "hlat" (which I did, above).

                Now I want to know how far from "home" Washington DC is using
                the coordinates listed above:

                Enter: 77.0356
                Press "dec"     stack value:  77.065556
                Enter: 38.5517
                Press "dec"     stack value:  38.921389
                Press "xh"      stack value:  334.422515

                which is answer in kilometers, get miles by pressing "k2m"
                                stack value:  207.800517

                The free functions return:

                        km:     334.490277
                        miles:  207.842622

k2m             Convert a value in kilometers to a value in miles.

                See examples above.

?               Display the "About" information for the function set.


Registration
------------
The DistanceFN v1.0 function set is Shareware.  You can download it and use
it for 30 days without registering.  If you continue to use it after 30 days,
please register by sending $5.00 to:

        Marvin E. Wilborne III
        124 Matthew Circle
        Danville, VA 24540

Or you can register on-line at http://www.pilotgear.com/

If you've already registered a RPN function set that I've developed, then
you're already registered for these.  I call it cross registering.

Address comments or questions by e-mail to:

        wilborne@gamewood.net


Release History
---------------
25 Sept 1997    Registered distance functions now work in both Radians or
                Degrees angle mode.

                This documentation was updated to support all versions.

22 Sept 1997    initial release of version 1.0 of both shareware DistanceFN
                and freeware Free DistanceFN

Legal Notice
------------
This software is copyrighted (c) 1997 by Marvin E. Wilborne III. Furthermore,
I make  no warranty with respect to the quality of this software, nor do I
warrant that its operation will be error-free. The author claims no liability
for data loss or any other problems caused directly or indirectly by use of
this application.

This software may be distributed freely as long as this file is included with
PDB file in it's original unmodified form.
