add USAGE.txt

Changes

1 changed files (+68/-0)

• USAGE.txt (new)
  • @@ -0,0 +1,68 @@
    + Calculate sunrise and sunset times for the current or targetted day. + The times can be adjusted either for twilight or fixed durations. + + The program can either: wait for sunrise or sunset (function: wait), + or return the time (GMT or local) the event occurs (function: list), + or report the day length and twilight timings (function: report), + or simply report if it is DAY or NIGHT (function: poll). + + You should specify the latitude and longitude of your target location. + + + Usage: sunwait [major options] [minor options] [twilight type] [rise|set] [offset] [latitude] [longitude] + + Major options, either: + poll Returns immediately indicating DAY or NIGHT. See 'program exit codes'. Default. + wait Sleep until specified event occurs. Else exit immediate. + list [X] Report twilight times for next 'X' days (inclusive). Default: 1. + report Generate a report about the days sunrise and sunset timings. + + Minor options, any of: + [no]debug Print extra info and returns in one minute. Default: nodebug. + [no]version Print the version number. Default: noversion. + [no]help Print this help. Default: nohelp. + [no]gmt Print times in GMT or local-time. Default: nogmt. + + Twilight types, either: + daylight Top of sun just below the horizon. Default. + civil Civil Twilight. -6 degrees below horizon. + nautical Nautical twilight. -12 degrees below horizon. + astronomical Astronomical twilight. -18 degrees below horizon. + angle [X.XX] User-specified twilight-angle (degrees). Default: 0. + + Sunrise/sunset. Only useful with major-options: 'wait' and 'list'. Any of: (default: both) + rise Wait for the sun to rise past specified twilight & offset. + set Wait for the sun to set past specified twilight & offset. + + Offset: + offset [MM|HH:MM] Time interval (+ve towards noon) to adjust twilight calculation. + + Target date. Only useful with major-options: 'report' or 'list'. Default: today + d [DD] Set the target Day-of-Month to calculate for. 1 to 31. + m [MM] Set the target Month to calculate for. 1 to 12. + y [YYYY] Set the target Year to calculate for. 2000 to 2099. + + latitude/longitude coordinates: floating-point degrees, with [NESW] appended. Default: Bingham, England. + + Exit (return) codes: + 0 OK: exit from 'wait' or 'list' only. + 1 Error. + 2 Exit from 'poll': it is DAY or twilight. + 3 Exit from 'poll': it is NIGHT (after twilight). + + Example 1: sunwait wait rise offset -1:15:10 51.477932N 0.000000E + Wait until 1 hour 15 minutes 10 secs before the sun rises in Greenwich, London. + + Example 2: sunwait list 7 civil 55.752163N 37.617524E + List civil sunrise and sunset times for today and next 6 days. Moscow. + + Example 3: sunwait poll exit angle 10 54.897786N -1.517536E + Indicate by program exit-code if is Day or Night using a custom twilight angle of 10 degrees above horizon. Washington, UK. + + Example 4: sunwait list 7 gmt sunrise angle 3 + List next 7 days sunrise times, custom +3 degree twilight angle, default location. + Uses GMT; as any change in daylight saving over the specified period is not considered. + + Note that program uses C library functions to determine time and localtime. + Error for timings are estimated at: +/- 4 minutes. +