Update man pages to the new CLI Previous CLI don't fit well to man page format, especially due to its hyphen-less semi-positional sometimes-ignored options.

Changes

6 changed files (+319/-95)

• build.zig
  • @@ -43,29 +43,42 @@
    step.dependOn(&run.step); } + // "zig build man" const man = man: { - const cmd = b.addSystemCommand(&.{"asciidoctor"}); + const step = b.step("man", "Build man pages"); + + const ManPage = struct { + source: std.Build.LazyPath, + outname: []const u8, + }; + + for ([_]ManPage{ + .{ .source = b.path("docs/sunwait.adoc"), .outname = "sunwait.1" }, + .{ .source = b.path("docs/sunwait-poll.adoc"), .outname = "sunwait-poll.1" }, + .{ .source = b.path("docs/sunwait-wait.adoc"), .outname = "sunwait-wait.1" }, + .{ .source = b.path("docs/sunwait-list.adoc"), .outname = "sunwait-list.1" }, + .{ .source = b.path("docs/sunwait-report.adoc"), .outname = "sunwait-report.1" }, + }) |page| { + const cmd = b.addSystemCommand(&.{"asciidoctor"}); + + cmd.addArgs(&.{ "-b", "manpage" }); + cmd.addFileArg(page.source); + cmd.addArg("--out-file"); + const out = cmd.addOutputFileArg(page.outname); - cmd.addArgs(&.{ "-b", "manpage" }); - cmd.addFileArg(b.path("docs/sunwait.adoc")); - cmd.addArg("--out-file"); - const out = cmd.addOutputFileArg("sunwait.1"); + const install = b.addInstallFile(out, b.fmt("share/man/man1/{s}", .{page.outname})); + step.dependOn(&install.step); + } - break :man b.addInstallFile(out, "share/man/man1/sunwait.1"); + break :man step; }; - // "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); + b.getInstallStep().dependOn(man); } }
• docs/sunwait-list.adoc (new)
  • @@ -0,0 +1,69 @@
    + // 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-list(1) + :docdate: 2025-07-21 + :doctype: manpage + :mansource: sunwait + + == Name + + sunwait-list - Lists sunset and sunrise time + + == Synposis + + *sunwait* *list* [_DAYS_] ++[++[-e | --event _<event>_]...] + + == Description + + This command prints a list of clock time when sunset and/or sunrise happens to stdout. + + == Options + + _DAYS_:: + Prints report for _DAYS_ days, including today. + Defaults to *1* (only today). + + *-e* _<event>_, *--event* _<event>_:: + Prints sunrise or sunset only when set. + If this option is not set, *sunwait* prints clock time of both, which is equivalent of, + + + + [,shell] + ---- + sunwait list -e sunrise -e sunset + ---- + + + + which means "list sunrise time and sunset time". + Valid values are: + + * *sunrise* Prints sunrise time, when the Sun rose and the twilight starts. + * *sunset* Prints sunset time, when the Sun set past the twilight. + + == Examples + + List civil sunrise and sunset times for today and next 6 days in Moscow, Russia. + + [,shell] + ---- + sunwait list 7 --twilight civil --lat 55.752163N --lon 37.617524E + ---- + + == See also + + *sunwait*(1)
• docs/sunwait-poll.adoc (new)
  • @@ -0,0 +1,55 @@
    + // 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-poll(1) + :docdate: 2025-07-20 + :doctype: manpage + :mansource: sunwait + + == Name + + sunwait-poll - Prints whether it's day or night + + == Synposis + + *sunwait* *poll* + + == Description + + This command prints *DAY* or *NIGHT* depends on the current time and location, then exits with corresponding status. + Unlike normal program, this program never exits with status *0*. + + == Exit status + + See *sunwait*(1) for error statuses. + + *2* It's day or twilight. + + *3* It' night (after twilight). + + == Examples + + Prints it's DAY or NIGHT at Giza Necropolis. + + [,shell] + ---- + sunwait poll --lat 29.977435N --lon 31.132484E + ---- + + == See also + + *sunwait*(1)
• docs/sunwait-report.adoc (new)
  • @@ -0,0 +1,68 @@
    + // 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-report(1) + :docdate: 2025-07-21 + :doctype: manpage + :mansource: sunwait + + == Name + + sunwait-report - Prints detailed report of sunrise and sunset times for the date + + == Synposis + + *sunwait* *report* [*y* _<years-since-2000>_] [*m* _<month>_] [*d* _<day-of-month>_] + + == Description + + This command prints detailed report on sunrise, sunset and other sun-related times for the date. + It by default targets current date, but you can override year, month, and/or day of month individually. + + == Options + + *y* _<years-since-2000>_:: + Years since 2000. 0 to 99. + Defaults to the current year - 2000. + + *m* _<month>_:: + Month. 1 to 12. + Defaults to the current month. + + *d* _<day-of-month>_:: + Day of the month. 1 to 31. + Defaults to the current date's day of the month. + + == Environment + + *TZ*:: + Generated report contains current timezone get by *localtime*(3) function, which refers to *TZ*. + If this variable is set, its value takes precedence over the system configured timezone. + See *tzset*(3) for timezone choosing algorithm. + + == Examples + + Produce a report of the different sunrises and sunsets on 2022/03/15 for Christmas Island, Australia. + + [,shell] + ---- + sunwait report y 20 m 3 d 15 --lat 10.49S --lon 105.55E + ---- + + == See also + + *sunwait*(1)
• docs/sunwait-wait.adoc (new)
  • @@ -0,0 +1,72 @@
    + // 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-wait(1) + :docdate: 2025-07-20 + :doctype: manpage + :mansource: sunwait + + == Name + + sunwait-wait - Waits for sunrise and/or sunset + + == Synposis + + *sunwait* *wait* ++[++[-e | --event _<event>_]...] + + == Description + + This command sleeps until the next _event_ happens. + + == Options + + *-e* _<event>_, *--event* _<event>_:: + Targets sunrise or sunset when set. + If this option is not set, *sunwait* targets both, which is equivalent of, + + + + [,shell] + ---- + sunwait wait -e sunrise -e sunset + ---- + + + + which means "waits for next sunset or sunrise". + Valid values are: + + * *sunrise* Waits for sunrise, when the Sun rose and the twilight starts. + * *sunset* Waits for sunset, when the Sun set past the twilight. + + == Examples + + Waits for 10 minutes before sunset at Giza Necropolis. + + [,shell] + ---- + sunwait wait -e sunset -o 10 --lat 29.977435N --lon 31.132484E + ---- + + Waits until 1 hour 15 minutes before the Sun rises in Greenwich, London. + + [,shell] + ---- + sunwait wait -e sunrise -o -1:15 --lat 51.477932N --lon 0.000000E + ---- + + == See also + + *sunwait*(1)
• docs/sunwait.adoc
  • @@ -16,7 +16,7 @@ //
    // SPDX-License-Identifier: GPL-3.0-only = sunwait(1) - :docdate: 2025-07-09 + :docdate: 2025-07-20 :doctype: manpage :mansource: sunwait
  • @@ -26,88 +26,50 @@ 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_] + *sunwait* [_options_] _<command>_ [_args_] == Description Sunwait calculates, displays, or waits for sunrise or sunset times at the given location. - *poll* will be called if no command is specified. + See *sunwait-poll*(1), *sunwait-wait*(1), *sunwait-list*(1) and *sunwait-report*(1) for command specific document. == Options - === General options - - ++[++*no*]*debug*:: + *--debug*:: Prints debug logs. *wait* command exits in one minute if this option is set. - ++[++*no*]*version*:: - Print the version number. + *--version*:: + Prints version number and exits. - ++[++*no*]*help*:: - Print help message. + *--help*:: + Prints help message to stdout and exits. - ++[++*no*]*gmt*:: - Print times in GMT. + *--utc*:: + Prints and parses times in UTC timezone instead of local timzone. - === Calculation options + *--lat* _<degree>_, *--latitude* _<degree>_:: + _degree_ is a signed floating point number or a positive floating point number with N or S suffix. + Defaults to the latitude of Bingham, England. - _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: + *--lon* _<degree>_, *--longitude* _<degree>_:: + _degree_ is a signed floating point number or a positive floating point number with E or W suffix. + Defaults to the longitude of Bingham, England. + + *--twilight* _<type>_:: + Sets a twilight type, which defines an angle of the Sun to consider twilight. + Valid 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>_". + * _<degree>_ Custom angle as a floating point number. Can be negative. - _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* _OFFSET_:: + *-o* _<duration>_, *--offset* _<duration>_:: 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. + The value can be either of *MM* (minutes) or *HH:MM*, and can have hyphen to represent negative offset. == Exit status
  • @@ -115,29 +77,14 @@ *0* Command successfully ended.
    *1* Error, uncategorized or generic. - *2* It's day or twilight. Only *poll* exits with this status. + *10* Out of memory. - *3* It' night (after twilight). Only *poll* exits with this status. + *11* Error during writing to stdout. - == Examples + *12* Error during writing to stderr. - Prints it's DAY or NIGHT at Giza Necropolis. + *15* Incorrect CLI usage, such as unknown option and invalid option value. - [,shell] - ---- - sunwait poll 29.977435N 31.132484E - ---- + == See also - 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 - ---- + *sunwait-poll*(1), *sunwait-wait*(1), *sunwait-report*(1), *sunwait-list*(1)