Changes

5 changed files (+176/-80)

• USAGE.txt (deleted)
  • @@ -1,71 +0,0 @@
    - 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 [date] Generate a report about the days sunrise and sunset timings. Default: the current day - - 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. - - Example 5: sunwait report y 20 m 3 d 15 10.49S 105.55E - Produce a report of the different sunrises and sunsets on an arbitrary day (2022/03/15) for an arbitrary location (Christmas Island) - - Note that program uses C library functions to determine time and localtime. - Error for timings are estimated at: +/- 4 minutes. -
• build.zig
  • @@ -20,6 +20,7 @@
    pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); + const man_opt = b.option(bool, "man", "Builds and installs man pages") orelse false; const exe = exe: { const exe = b.addExecutable(.{
  • @@ -43,9 +44,6 @@
    break :exe exe; }; - // Default step - b.installArtifact(exe); - // "zig build run" { const step = b.step("run", "Build and run sunwait");
  • @@ -56,5 +54,31 @@ run.addArgs(args);
    } step.dependOn(&run.step); + } + + const man = man: { + const cmd = b.addSystemCommand(&.{"asciidoctor"}); + + cmd.addArgs(&.{ "-b", "manpage" }); + cmd.addFileArg(b.path("docs/sunwait.adoc")); + cmd.addArg("--out-file"); + const out = cmd.addOutputFileArg("sunwait.1"); + + break :man b.addInstallFile(out, "share/man/man1/sunwait.1"); + }; + + // "zig build man" + { + const step = b.step("man", "Build man pages"); + step.dependOn(&man.step); + } + + // "zig build" + { + b.installArtifact(exe); + + if (man_opt) { + b.getInstallStep().dependOn(&man.step); + } } }
• docs/sunwait.adoc (new)
  • @@ -0,0 +1,143 @@
    + // Copyright (C) 2025 Shota FUJI + // + // This program is free software: you can redistribute it and/or modify + // it under the terms of the GNU General Public License as published by + // the Free Software Foundation, either version 3 of the License, or + // (at your option) any later version. + // + // This program is distributed in the hope that it will be useful, + // but WITHOUT ANY WARRANTY; without even the implied warranty of + // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + // GNU General Public License for more details. + // + // You should have received a copy of the GNU General Public License + // along with this program. If not, see <https://www.gnu.org/licenses/>. + // + // SPDX-License-Identifier: GPL-3.0-only + + = sunwait(1) + :docdate: 2025-07-09 + :doctype: manpage + :mansource: sunwait + + == Name + + sunwait - Calculates sunrise or sunset times + + == Synposis + + // TODO: Split these into dedicated pages + + *sunwait* *poll* [_general options_] [_calculation options_] + + *sunwait* *wait* [_general options_] [_calculation options_] + + *sunwait* *list* [_DAYS_] [_general options_] [_calculation options_] + + *sunwait* *report* [*d* _<DAY>_] [*m* _<MONTH>_] [*y* _<YEAR>_] [_general options_] [_calculation options_] + + *sunwait* *report* *today* [_options_] [_calculation options_] + + == Description + + Sunwait calculates, displays, or waits for sunrise or sunset times at the given location. + + *poll* will be called if no command is specified. + + == Options + + === General options + + ++[++*no*]*debug*:: + Prints debug logs. *wait* command exits in one minute if this option is set. + + ++[++*no*]*version*:: + Print the version number. + + ++[++*no*]*help*:: + Print help message. + + ++[++*no*]*gmt*:: + Print times in GMT. + + === Calculation options + + _TWILIGHT TYPE_:: + *sunwait* considers it's day when twilight starts and night when twilight ends. + This option sets a twilight type, which defines an angle of the Sun to consider twilight. + Possible values are: + + * *daylight* Top of the Sun just below (0 degrees) the horizon. + * *civil* Civil twilight, top of the Sun 6 degrees below the horizon. + * *nautical* Nautical twilight, top of the Sun 12 degrees below the horizon. + * *astronomical* Astronomical twilight, top of the Sun 18 degrees below the horizon. + + + + The default value is *daylight*. + You can also set arbitrary angle with "*angle* _<degree>_". + + _SUNRISE OR SUNSET_:: + Targets sunrise or sunset when set. + If this option is not set, *sunwait* targets both. + + * *rise* Sunrise, the Sun rose and the twilight starts. + * *set* Sunset, the Sun set past the twilight. + + _OFFSET_:: + Time offset to add to sunrise time and subtract from sunset time. + This offset value shifts sunrise and sunset time towards noon by the specified amount. + The value can be either of _MM_ (minutes) or _HH:MM_, and can have minus sign to represent negative amount. + + _LATITUDE_:: + Degrees in positive floating point without a unit, suffixed with *N* or *S*. + When unspecified, this will be the latitude of Bingham, England. + + _LONGITUDE_:: + Degrees in positive floating point without a unit, suffixed with *E* or *W*. + When unspecified, this will be the longitude of Bingham, England. + + _DAYS_:: + Prints report for next _N_ days, where _N_ is the specified value. + Defaults to *1*. + + *d* _<DAY>_:: + Day of the month. 1 to 31. + + *m* _<MONTH>_:: + Month. 1 to 12. + + *y* _<YEAR>_:: + Years since 2000. 0 to 99. + + == Exit status + + *0* Command successfully ended. + + *1* Error, uncategorized or generic. + + *2* It's day or twilight. Only *poll* exits with this status. + + *3* It' night (after twilight). Only *poll* exits with this status. + + == Examples + + Prints it's DAY or NIGHT at Giza Necropolis. + + [,shell] + ---- + sunwait poll 29.977435N 31.132484E + ---- + + Waits for 10 minutes before sunset at Giza Necropolis. + + [,shell] + ---- + sunwait wait set offset 10 29.977435N 31.132484E + ---- + + Wait until 1 hour 15 minutes 10 seconds before the Sun rises in Greenwich, London. + + [,shell] + ---- + sunwait wait rise offset -1:15:10 51.477932N 0.000000E + ----
• examples.txt (deleted)
  • @@ -1,5 +0,0 @@
    - # Return DAY or NIGHT - sunwait poll 43.641488N 71.534851W - - # Wait for 10 minutes before sunset - sunwait wait set offset 10 43.641488N 71.534851W
• flake.nix
  • @@ -36,7 +36,10 @@ system:
    let pkgs = nixpkgs.legacyPackages.${system}; - nativeBuildInputs = with pkgs; [ zig ]; + nativeBuildInputs = with pkgs; [ + zig + asciidoctor + ]; in { packages.default = pkgs.stdenvNoCC.mkDerivation {
  • @@ -49,6 +52,8 @@ mainProgram = "sunwait";
    }; nativeBuildInputs = nativeBuildInputs ++ [ pkgs.zig.hook ]; + + zigBuildFlags = [ "-Dman" ]; }; devShell = pkgs.mkShell {