added usage examples (closes #10)

This commit is contained in:
Steffen Vogel 2017-03-03 11:01:20 -04:00 committed by GitHub
parent ce825f8d74
commit 2a32f11aa1

View file

@ -21,6 +21,81 @@ git clone git://git.code.sf.net/p/libnova/libnova libnova && pushd libnova && au
autoreconf -i && ./configure && make install
```
# Usage
```
Usage:
Calcelestial [options]
Options:
-p, --object calc for celestial object: sun, moon, mars, neptune,
jupiter, mercury, uranus, saturn, venus or pluto
-H, --horizon calc rise/set time with twilight: nautic, civil or astronomical
-t, --time calc at given time: YYYY-MM-DD[_HH:MM:SS]
-m, --moment calc position at moment of: rise, set, transit
-n, --next use rise, set, transit time of tomorrow
-f, --format output format: see strftime (3) and calcelestial (1) for more details
-a, --lat geographical latitude of observer: -90° to 90°
-o, --lon geographical longitude of oberserver: -180° to 180°
-q, --query query coordinates using the geonames.org geolocation service
-l, --local query local timezone using the geonames.org geolocation service
-z, --timezone override system timezone (TZ environment variable)
-u, --universal use universial time for parsing and formatting
-h, --help show usage help
-v, --version show version
Note: A combination of --lat & --lon or --query is required.
The following special tokens are supported in the --format parameter:
§J Julian date of observation
§d Diameter in arc seconds
§e Distance to object in astronomical units
§r Equatorial Coordinates: Right Ascension in degrees
§d Equatorial Coordinates: Declincation in degrees
§a Horizontal Coordinates: Azimuth in degrees
§h Horizontal Coordinates: Altitude in degrees
§A Latitude in degrees
§O Longitude in degrees
§s Azimuth direction (N, E, S, W, NE, ...)
Calcelestial is written by Steffen Vogel <post@steffenvogel.de>
Please report bugs to: https://github.com/stv0g/calcelestial/issues
```
## Examples
The simplest variant uses the Unix tool [at(1)](https://linux.die.net/man/1/at) to schedule a command at a specific event:
```
echo ~/bin/turn-lights-on | at $(calcelestial -p sun -m set -q Frankfurt -H civil)
```
The following cronjobs automate this task everyday with updated times:
```
0 0 * * * echo 'fnctl stop && fnctl fade -c 000000' | at $(calcelestial -m rise -p sun -q Aachen)
0 0 * * * echo 'fnctl start' | at $(calcelestial -m set -p sun -q Frankfurt)
```
The tool [nvram-wakeup](http://www.vdr-wiki.de/wiki/index.php/NVRAM_WakeUp), can be used to turn on the system everyday 10 minutes before sunrise in Berlin:
```
nvram-wakeup -s $(date -d "$(calcelestial -m rise -p sun -q Berlin --format %+)" -10 minutes" +%s)
```
Or alternatively, the system can be shut down 10 minutes after sunset:
```
shutdown $(date -d "$(calcelestial -m rise -p sun --lat=50.55 --lon=-6.2 --format %+) +10 minutes" +%H:%M)
```
The current position of the moon can be estimated with:
```
calcelestial -p moon -q Aachen -f "az: §a alt: §h"
```
# License
calcelestial is licensed under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html).