File	Date	Author	Commit
INSTALL	2022-12-23	ojkeenan	[25080e] small updates
LICENSE	2013-06-18	ojkeenan	[593731] v1.7 rc
Makefile	2013-06-18	ojkeenan	[593731] v1.7 rc
README	2022-12-23	ojkeenan	[25080e] small updates
algs.c	2015-08-20	ojkeenan	[74d845] added 2015
help.c	2015-08-21	ojkeenan	[e30210] correct an error in help.c
jdconv.c	2015-08-20	ojkeenan	[74d845] added 2015
main.c	2022-12-23	ojkeenan	[25080e] small updates
tick.c	2015-08-20	ojkeenan	[eecb10] reacquaintance update
voids.c	2022-12-23	ojkeenan	[25080e] small updates

Read Me

 ____  _     _  ____ _            _            _  _____ 
/ ___|(_) __| |/ ___| | ___   ___| | __ __   _/ ||___  |
\___ \| |/ _` | |   | |/ _ \ / __| |/ / \ \ / / |   / / 
 ___) | | (_| | |___| | (_) | (__|   <   \ V /| |_ / /  
|____/|_|\__,_|\____|_|\___/ \___|_|\_\   \_/ |_(_)_/   
(c) Oliver Keenan      

1) What is it?
2) Who maintains it (and why)?
3) Installation.
4) Usage.
5) Licensing details.
6) Documentation.
7) Bug Reporting.                       

	  _ 
	 / | +-------------+
 	 | | | What is it? | 
	 |_| +-------------+

SidClock is an open source Sidereal Time calculator for UNIX 
and UNIX-like systems. SidClock has been developed since 2012,
but is based on SolarClock, the .NET Windows utility by the same
author, which was developed from 2005 until 2010, before falling
dormant.

SidClock Features include:

* Greenwich and Local Sidereal Time Calculation (longitude mode)
* Present, Past and Future Calculations
* Julian Date Conversion
* Formatted or Pure Output Modes
* Adjustment for Nutation of Earth's Axis 
  (Apparent Sidereal Time Calculation)
* Logfile Generation Mode
* Silent Mode
* Quality Control File Generation
* Accurate to 0.02 seconds in the five centuries either side of Y2k. 

	  ___ 
	 |_  ) +---------------------------+
	  / /  | Who maintains it and why? |
	 /___| +---------------------------+

SidClock is developed and maintained by Oliver Keenan, an
amateur astronomist whose academic training is mainly in theology 
rather than in computing or the sciences. In 2005 I was undertaking a
part-time course at Joddrell Bank Observatory (part of the University
of Manchester), where I was involved in the analysis of data from
the 7m u/g teaching telescope and the Mark II elliptical 'scope. 
In particular, SidClock was developed in order to facilitate accurate
analysis of the Lunar Occultation of the Crab Nebula that took place
on 11/09/2001 (a day sadly remembered for other reasons), and was deployed
in 2005 and 2006 to automate solar radio observations taken from my own
garden-based radio observatory. Since then, SidClock, and its predecessor 
SolarClock, has been used to extensively, and has found users throughout
the amateur, university and professional sectors.  

	  ____ 
	 |__ /  +--------------+
	  |_ \  | Installation |
	 |___/  +--------------+

SEE ALSO: 'INSTALL' file.
     
Installation is by simple compile. Having downloaded and extracted the latest source code,
issuing the command 'make' will build the application most systems. Two binaries will be
generated: 'SidClock' containing the main programme, and 'jdconv', the included Julian
date conversion utility. The command 'make clean' will remove the generated binaries.

If you intend to use local sidereal time mode (-l), you will need to create a file in
the directory from which you execute SidClock called '.longitude' that contains the
Longitude of your location in degrees. Western Longitudes are negative numbers; Eastern
Longitudes are positive numbers: Oxford is -1.2558, Moscow is 37.6178, Valladolid is 
-4.7400, etc. By default, .longitude exists and is set to -122.3331 (Seattle, WA). 

Windows Users shoudn't have considerable difficulty in compiling SidClock under Cygwin,
although this is unsupported. Those seeking to use SidClock should note that it is 
installed for use on the SDF Public Access Unix System at "/sys/sdf/bin/sidclock",
see http://sdf.lonestar.org for more on obtaining an SDF user account.

	  _ _  
	 | | |   +-------+
	 |_  _|  | Usage |
	   |_|   +-------+

To calculate current Sidereal Time:          SidClock <options>
To calculate past or future Sidereal Times:  SidClock <options> <juliandate>

Available Options:
 -a      Calculate adjustment for nutation of Earth's axis (GAST +/- LAST turned on).
 -f      Generate report file (useful for Bug Reporting).
 -h      Display help.
 -l      Enable Local Sidereal Time Calculation (LMST turned on).
 -n	 Used with tick-mode to display each result on a new line.
 -r      Report into the SidClock.Log LogFile.
 -s      Used with logmode and file mode, displays no output displayed in terminal.
 -t      Enables 'tick' mode.
 -u      Display version details.
 -x      Return times in 'pure' decimal format.

Examples:
* sidclock -la                 Display current greenwich & local Sidereal time with adjustments
* sidclock -laro               Silently deposit the above into logfile
* sidclock -la 2446458.312616  Calculate local/apparent sidereal time for 27th Jan 1986 at 19:30:10 UTC.
* sidclock -x                  Calculate GMST in decimal form (e.g for use by another process).

For conversions between Julian Date and modern calendar, and vice versa:  
 * jdconv <year> <month> <day> <hour> <minute> <second>		Reports Julian Date
 * jdconv <julian date>						Reports modern calendar date.
Examples:
 * jdconv 2446516.118692    	[returns: Wed Mar 26 14:50:54 1986]
 * jdconv 2003 9 3 09 00 00	[returns: 2452885.875000]
The Julian Date results can then be fed into SidClock for Sidereal time generation:
 * sidclock -a 2452885.875000   [returns: GMST: 07:48:21.727, GAST: 07:48:21.806]
 * sidclock -xa 2452885.875000  [returns: 117.090531167, 117.090819472]

Note that due to the 32-bit 2038 problem, conversions from JD to Calendar date display are only
valid between 1901 and 2038. jdconv will alert you if you attempt to convert a date outside range.
Calendar date to JD conversion is valid for every era. This restriction is caused by limitations 
inherent in the time.h library: given the JD -> UTC feature is peripheral to SidClock's purpose,
it is unlikely I will find time to code an entirely new time/date library, although this would
represent a worthy project in its own right.

	  ___ 
	 | __|  +-----------+
	 |__ \  | Licensing |
	 |___/  +-----------+


SidClock is free open-source software, released under the terms of the New BSD License, see 
the file 'LICENSE' for more details.

SidClock is part of two microcosms of the free software movement: the TWENEX project hosted
out of Dallas TX <http://twenex.net/>, and the Landgraviate coder community, based in the
wilds of Oxford, UK <http://landgraviate.org/>.

	   __ 
	  / /   +---------------+
	 / _ \  | Bug Reporting |
	 \___/  +---------------+

If you noticed any bugs, glitches, or erroneous calculations, please report them. Wherever 
possible, please generate a report file using -f to <sidclock@landgraviate.org>. 

We don't have a huge user base, so you can be pretty sure I will respond. Please also let 
me know if there is an alternative output format or feature that you would like to see generated.

For quality control purposes, you can find copy of logfiles generated automatically by SidClock 
being run every 8 minutes on a BSD system at: http://keenan.gomen.org/sidclocklogs

You can find out SourceForge page at https://sourceforge.net/projects/sidclock/ where tickets 
are logged and recorded, the latest source code made available, etc.