
README information for jday and j2d		VERSION 2.4 2005-10-10

	$Id: README,v 1.12 2005/10/07 00:07:11 hiram Exp $

Astronomical Julian Date calculator

See also:  http://jday.sourceforge.net/

To unpack the source archive:
	with gnu tar:  tar -xvzf jday-2.4.tar.gz
	or an ordinary tar:
	gunzip -c jday-2.4.tar.gz | tar -xvf -

This creates a ./jday-2.4 directory.

To build jday:

	cd jday-2.4
	./configure		(the usual configure arguments are honored)
	make
	make check

The default build creates a static library, use --enable-shared
to also create shared libraries.  Since the static library is so
tiny, the extra effort to make a shared library is somewhat
unnecessary.  However, the dynamic library will work OK.

To install the jday, j2d and dbd binaries into /usr/local

	make install

Installs three binaries in /usr/local/bin:
	/usr/local/bin/jday
	/usr/local/bin/j2d
	/usr/local/bin/dbd
the include file:
	/usr/local/include/jday.h
the library:
	/usr/local/lib/libjday.a
and a man page:
	/usr/local/man/man1/jday.

To override the default /usr/local prefix,
use the --prefix=<some other prefix>
argument to the ./configure
(configure will honor the usual arguments)

TESTING:
	Run 'make check' to run these three tests:

	After the jday and j2d binaries are built, run the
	shell script: RunTest to test both of those binaries.

	The PERL examples can be tested with JdayTest.pl

	The dbd - days between dates example can be tested with Testdbd

To use:		(see also: jday.html in the source directory)

jday - with no arguments will print out the current Julian date
	based on your system clock and timezone.  If your
	timezone or system clock are inaccurate, the output of
	jday will also be inaccurate

To compute the Julian Date of a particular date/time,
any of the following invocations are allowed::

	jday year
	jday year month
	jday year month day
	jday year month day hour
	jday year month day hour minute
	jday year month day hour minute second

For those items not specified, the current system date/time is used.
And for symmetry with j2d output, the format of the output
of j2d can be used:

	jday -d year-month-day hour:minute:second

and in this case all items must be specified.

j2d only operates in one mode.

j2d - must have an argument, which is a julian date.
Output will be in the form: year-month-day hour:minute:second

For example, the following is possible::

	j2d `jday`

There is a RunTest script which will run through the following
set of dates.  Watch for any FAIL indications.

Examples:		(note: there is a year zero in julian dates)

	$ jday -4712 1 1 12 0 0
	0.000000         
	$ j2d 0.0
	-4712/01/01 12:00:00
	$ jday -1 12 31 12 0 0
	1721057.000000   
	$ j2d 1721057.000000
	-1/12/31 12:00:00
	$ j2d 1721058.000000
	0/01/01 12:00:00
	$ jday -d 0/01/01 12:00:00
	1721058.000000
	$ jday 0 12 31 12 0 0
	1721423.000000   
	$ jday 1 1 1 12 0 0
	1721424.000000   

	$ jday 1970 1 1 0 0 0
	2440587.500000   
	$ j2d 2440587.500000
	1970/01/01 00:00:00

	$ j2d 2451774.726007
	2000/08/18 05:25:27
	$ jday -d 2000/08/18 05:25:27
	2451774.726007

NEW TO VERSION 2.4:

Updated configure system to new versions of everything.
Changed output format to read: YYYY-MM-DD instead of
the version 1.3 output of: YYYY/MM/DD
There is a new option '-v1' to j2d to make it output
the version 1.3 type of output for backwards compatibility.

NEW TO VERSION 1.3:

There are now versions written in AWK, PHP and PERL.
They are not installed from the source directory.
PERL source:  CalDate.pm  J2D.pl  Jday.pl  JdayTest.pl
PHP source: CalDate.inc  Jday.php
AWK source: dbd.awk jday.awk
	(these AWK sources are shell scripts with the awk code
		in them.)

A demonstration program is included:  dbd.c (and dbd.awk)
	which will calculate days between dates.
	Testdbd script will exercise this example.

JAVA BUILD:

The Java is bare bones.  But I do believe it works.  To build it:
cd javaDate
javac Jdate.java
cd ..
javac J2D.java
javac Jday.java

KNOWN BUGS:

I haven't tested the awk version very much and it is not complete
with a j2d.awk function.  Also since awk isn't uniform on all systems,
it may not function.

Leap seconds are not accounted for, see below.

I couldn't get it to compile on the Sourceforge Compile
Farm machine x86-solaris1 (Solaris 9 on x86).  It wouldn't
make a static library.  And when asked for a shared library,
it made it, but it wouldn't link the binaries with it.

DEVELOPMENT ENVIRONMENT:

GNU Tools version used to generate the configure files:

automake (GNU automake) 1.9.2
aclocal (GNU automake) 1.9.2
autoconf (GNU Autoconf) 2.59
libtoolize (GNU libtool) 1.5.6

SEE ALSO:

Time Standard: http://tycho.usno.navy.mil
Systems of time:  http://tycho.usno.navy.mil/systime.html
Time Services: http://tf.nist.gov/timefreq/index.html
Network Time Protocol: http://www.ntp.org/
Leap Seconds: http://tf.nist.gov/timefreq/pubs/bulletin/leapsecond.htm

LEAP SECONDS:

The jday programs do NOT take into account the leap seconds that
have been added since 1972.  There is a planned leap second
for 2005-12-31 (MJD 53736)

From the NIST leapsecond.htm file:

Date 	MJD
1998-12-31 	51179
1997-06-30 	50630
1995-12-31 	50083
1994-06-30 	49534
1993-06-30 	49169
1992-06-30 	48804
1990-12-31 	48257
	
Date 	MJD
1989-12-31 	47892
1987-12-31 	47161
1985-06-30 	46247
1983-06-30 	45516
1982-06-30 	45151
1981-06-30 	44786
	
Date 	MJD
1979-12-31 	44239
1978-12-31 	43874
1977-12-31 	43509
1976-12-31 	43144
1975-12-31 	42778
1974-12-31 	42413
1973-12-31 	42048
1972-12-31 	41683
1972-06-30 	41499

	jday at hiram.ws - 2005-10-10 10:10:10 UTC - JD 2453653.923727
