From b39c8187ef1b87eea084e3c3d2226be5cf320dca Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Fri, 28 Aug 2026 10:03:27 +0200 Subject: feat(cli): --month, --date and --today narrow a report --pretty made a report readable and, in the same stroke, ungreppable: a box spans seven lines, so `grep 2026-03-` returns fragments of March rather than March. The nearest working equivalent is a paragraph-mode awk incantation that depends on the boxes happening to be blank-line separated -- knowledge no reader should need to select a month. The three flags are ALTERNATIVES, not a stack. Naming two exits 2 rather than letting one quietly win, the same discipline the positional year and --year already follow, and the same reason this program refuses a flag it cannot honour instead of accepting and ignoring it. --date and --today CARRY a year, so the year becomes optional on those two and required only after the window has had its say: `colitur day --today` is a complete command while `colitur day` still is not. A year named alongside them must agree. The disagreement message names the flag rather than printing two bare numbers, because with --today the second year appears nowhere on the command line for the reader to trace. temporal refuses --year yet accepts --date/--today including as its year source. That is not a back door to the refused spelling: --year is a second spelling of the positional year, which temporal deliberately does not offer, whereas --date selects a DAY and merely happens to determine which year contains it. The window is a predicate over an ISO date STRING rather than over a Date.t, because the two report shapes reach it differently -- resolved days carry a Date.t, temporal_report carries a flat Record whose date is already text -- and one shared test is one implementation rather than two that can drift. Accepted by day, readings, rubrics and temporal; refused by easter, emit, table, render, publish, check, convert, lang, config and new-overlay. --pretty had shipped undocumented in both --help and colitur(1). Both now carry it, alongside the new narrowing section; the man page's awk example is shown precisely so the flag that replaces it is justified. Default output is byte-identical to 1.1.0 across seven years, five commands and both rites, and across all five emit formats and the shipped templates. --- man/colitur.1 | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) (limited to 'man') diff --git a/man/colitur.1 b/man/colitur.1 index 33b66a5..4d639f8 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -8,8 +8,10 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .br .B colitur .B temporal -.I YEAR +.RI [ YEAR ] .RB [ \-\-rite " ef\(brof" ] +.RB [ \-\-pretty ] +.RB [ \-\-month " N" " | " \-\-date " YYYY\-MM\-DD | " \-\-today ] .br .B colitur .BR day | readings | rubrics @@ -22,6 +24,8 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .RB [ \-\-sigla\-book " full\(brabbr" ] .RB [ \-\-sigla\-tradition " NAME" ] .RB [ \-\-raw ] +.RB [ \-\-pretty ] +.RB [ \-\-month " N" " | " \-\-date " YYYY\-MM\-DD | " \-\-today ] .br .B colitur .B emit @@ -524,6 +528,83 @@ Nothing should be written to parse its layout is free to change, which is precisely what the default format is not. .PP +.SH NARROWING A REPORT +.B \-\-month +.IR N , +.B \-\-date +.I YYYY\-MM\-DD +and +.B \-\-today +print part of a year instead of all of it: one month, one day, or the day this +program is run. They are accepted by the same four commands +.RB ( day ", " readings ", " rubrics ", " temporal ) +and refused by every other, on the same reasoning as +.BR \-\-pretty . +.PP +They are +.B alternatives, +not a stack. Naming two is an error rather than a silent win for one: +.PP +.RS 4 +.EX +$ colitur day \-\-month 3 \-\-today 2026 +colitur: day: \-\-month and \-\-today are alternatives; name one +.EE +.RE +.PP +They are independent of +.BR \-\-pretty , +and useful in the default format too. Under +.B \-\-pretty +they are close to necessary: a box spans seven lines, so +.BR grep (1) +selects only fragments of one. The nearest equivalent is a paragraph-mode +.BR awk (1) +incantation, which works only because the boxes are blank-line separated, and +which the reader should not have to know: +.PP +.RS 4 +.EX +$ colitur day \-\-pretty 2026 | awk 'BEGIN{RS="";ORS="\en\en"} /2026\-03\-/' +$ colitur day \-\-pretty \-\-month 3 2026 # the same 31 boxes +.EE +.RE +.PP +.B \-\-date +and +.B \-\-today +NAME a year, so on those two the year may be omitted \-\- +.B colitur day \-\-today +is a complete command. A year given as well must agree, the same rule a +positional year and +.B \-\-year +already follow: +.PP +.RS 4 +.EX +$ colitur day \-\-today 2027 +colitur: day: year 2027 and \-\-today (2026) disagree +.EE +.RE +.PP +.B \-\-month +names no year and so still needs one. +.PP +.B temporal +refuses +.B \-\-year +but accepts +.B \-\-date +and +.BR \-\-today , +including as its source of a year. That is not an inconsistency: +.B \-\-year +is a second spelling of the positional year, which +.B temporal +deliberately does not offer, whereas +.B \-\-date +selects a day and merely happens to determine which year contains it. +.PP .SH OUTPUT FORMAT .SS day .RS -- cgit v1.3