summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorLukasz Kasprzak <lukas@labunix.xyz>2026-08-28 10:03:27 +0200
committerLukasz Kasprzak <lukas@labunix.xyz>2026-08-28 10:03:27 +0200
commitb39c8187ef1b87eea084e3c3d2226be5cf320dca (patch)
treea12a09c8c4dfd8e69442e616b162d9dcc2dfc6a5 /man
parentf1d562a3a4d53a707385334ab553b8a6cad36b1b (diff)
downloadcolitur-b39c8187ef1b87eea084e3c3d2226be5cf320dca.tar.gz
colitur-b39c8187ef1b87eea084e3c3d2226be5cf320dca.zip
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.
Diffstat (limited to 'man')
-rw-r--r--man/colitur.183
1 files changed, 82 insertions, 1 deletions
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