diff --git a/Makefile.am b/Makefile.am index 16399d5..06ea1f9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,4 +2,4 @@ SUBDIRS = src dist_doc_DATA = README -man_MANS = doc/sun.1 +man_MANS = doc/calcelestial.1 diff --git a/Makefile.in b/Makefile.in index 5c88286..1b96808 100644 --- a/Makefile.in +++ b/Makefile.in @@ -249,7 +249,7 @@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ SUBDIRS = src dist_doc_DATA = README -man_MANS = doc/sun.1 +man_MANS = doc/calcelestial.1 all: config.h $(MAKE) $(AM_MAKEFLAGS) all-recursive diff --git a/doc/calcelestial.1 b/doc/calcelestial.1 new file mode 100644 index 0000000..3a4776a --- /dev/null +++ b/doc/calcelestial.1 @@ -0,0 +1,139 @@ +.TH CALCELESTIAL "1" "May 2013" "calcelestial 0.1" "User Commands" +.SH NAME +calcelestial - calculates positions, rise, set and transit times of celestial bodies +.SH DESCRIPTION +Together with tools like 'at', 'cron' and 'date' it can be used to schedule arbitrary tasks at planet and moon rise, set or transit times. +.SH SYNOPSIS +.B calcelestial -p [object] -q [location] -m [moment] -f [format] +.SH OPTIONS +.TP +.B -p, --object +available objects are: +.IP +.RS +.RS +sun +.br +moon +.br +mars +.br +neptune +.br +jupiter +.br +mercury +.br +uranus +.br +saturn +.br +venus +.br +pluto +.RE +.RE +.TP +.B -H, --horizon +calc rise/set time with twilight: nautic, civil or astronomical +.TP +.B -t, --time +calc at given time: YYYY-MM-DD [HH:MM:SS] +.TP +.B -m, --moment +calc position at moment of: rise, set, transit +.TP +.B -n, --next +use rise, set, transit time of tomorrow +.TP +.B -f, --format +output format: see \fBstrftime\fR(3) and FORMAT section below for more details +.TP +.B -a, --lat +geographical latitude of observer: -90 to 90deg +.TP +.B -o, --lon +geographical longitude of oberserver: -180 to 180deg +.TP +.B -q, --query +query geonames.org for geographical coordinates +.TP +.B -z, --timezone +override system timezone +.TP +.B -u, --universal +use universial time for parsing and formatting +.TP +.B -h, --help +show this help +.TP +.B -v, --version +show version +.PP +.SH FORMAT +calcelestial supports all conversion specifications as documented in \fBstrftime\fR(3). +.br +additionally these special specifiers have been added: +.TP +.B %J +Julian Date +.TP +.B §r +equatorial right ascension in degrees +.TP +.B §d +equatorial declination in degrees +.TP +.B §a +azimut in degrees from north +.TP +.B §h +altitude in degrees +.TP +.B §d +diameter in arcseconds +.TP +.B §e +distance in kilometer +.TP +.B §t +observer timezone in hours west +.TP +.B §A +observer latitude in degrees north +.TP +.B §O +observer longitude in degrees east +.TP +.B §s +azimuth direction as letter, +.TP +.B §§ +A literal '§' character +.SH NOTES +.P +A combination of \fB--lat\fR & \fB--lon\fR or \fB--query\fR is required. +.P +The argument \fB-q, --query\fR fetches coordinates from the geonames.org database. Fetched coordinates will be cached locally. So an active internet connection is only required for the first time. +Please be aware of possible privacy issues! +.P +When symlinking the calcelestial binary to 'sun', 'moon' etc., the argument \fB-p, --object\fR is negligible: +.IP +.B sun -m rise -q Aachen +.SH EXAMPLES +.TP +\fBecho "~/bin/enable-lightning" | at $(calcelestial -p sun -m set -q Frankfurt -H civil)\fR +enable lightning at sunset in Frankfurt +.TP +\fBshutdown $(date -d "+10min $(calcelestial -m transit -a 50.55 -o -6.2)" +%H:%M)\fR +shutdown system 10 minutes after solar noon in Berlin +.TP +\fBnvram-wakeup -s $(date -d "-10min $(calcelestial -m rise -q Aachen)" +%s)\fR +start system 10 minutes before sunrise in Aachen +.SH FILES +geonames.org queries will be cached in \fI~/.geonames.cache\fR +.SH AUTHOR +calcelestial is written by Steffen Vogel +.SH BUGS +.TP +\fB%s\fR formatstring has buggy timezone offset in conjunction with daylight savings diff --git a/doc/sun.1 b/doc/sun.1 deleted file mode 100644 index e64dba6..0000000 --- a/doc/sun.1 +++ /dev/null @@ -1,83 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.40.10. -.TH SUN "1" "December 2012" "sun 0.1" "User Commands" -.SH NAME -sun \- calculate sun's rise/set times, the solar noon and the daylight time duration -.SH SYNOPSIS -\fBsun\fP \fImode\fP [options] -.SH DESCRIPTION -\fBsun\fP is designed to be used with tools like \fBcron\fP, \fBat\fP etc.. -Take a look at the EXAMPLE section for some useful usecases. -.TP -\fImode\fR is one of: -.IP -\fBrise\fP calculate sunrise -.IP -\fBset\fP calculate sunset -.IP -\fBnoon\fP calculate solar noon -.IP -\fBdaytime\fP calculate daylight time duration -.IP -\fBnighttime\fP calculate 24h - daytime - -.P -Please note that a combination of \fB\-\-lat\fR, \fB\-\-lon\fR or \fB\-\-query\fR is required! - -.SH OPTIONS -.TP -\fB\-t\fR, \fB\-\-twilight\fR=\fITWILIGHT\fP -use special twilight. - -\fBcivil\fR: \-6 degrees - -\fBnautic\fR: \-12 degrees - -\fBastro\fR: \-18 degrees - -.TP -\fB\-d\fR, \fB\-\-date\fR=\f%Y-%m-%d\fP -calculcate for specified date (eg. 2011\-12\-25) -.TP -\fB\-f\fR, \fB\-\-format\fR=\fIFORMAT\fP -output format (eg. %H:%M:%S). For valid formatstrings look at \fBstrftime\fP(3). -.TP -\fB\-a\fR, \fB\-\-lat\fR=\fI\-90..90\fP -geographical latitude in degrees -.TP -\fB\-o\fR, \fB\-\-lon\fR=\fI\-180..180\fP -geographical longitude in degrees -.TP -\fB\-q\fR, \fB\-\-query\fR=\fINAME\fP -query geonames.org for geographical position -.TP -\fB\-z\fR, \fB\-\-zone\fR=\fIINTEGER\fP -use timezone for output. Defaults to system-wide timezone defined in \fI/etc/timezone\fP or in environment variable TZ. -.TP -\fB\-h\fR, \fB\-\-help\fR -show this help -.TP -\fB\-v\fR, \fB\-\-version\fR -show version - -.SH EXAMPLES -.TP -.B echo "~/bin/enable-lightning" | at $(sun set -q Frankfurt -t civil) -enable lightning at sunset in Frankfurt - -.TP -.B shutdown $(date -d "+10min $(src/sun noon --lat=50.55 --lon=-6.2)" +%H:%M) -shutdown system 10 minutes after solar noon in Berlin - -.TP -.B nvram-wakeup -s $(date -d "-10min $(sun rise -q Aachen)" +%s) -start system 10 minutes before sunrise in Aachen - - -.SH "SEE ALSO" -.BR at (1) -.BR cron (1) -.BR nvram-wakeup (1) -.SH AUTHOR -Steffen Vogel -.SH BUGS -Please report bugs to: post@steffenvogel.de