Merge branch 'cli-pretty'v1.2.0

--pretty, and the --month/--date/--today flags that make it usable: a box
spans seven lines, so the flag that improved reading had removed grepping.

1 files changed, 130 insertions, 1 deletions

diff --git a/man/colitur.1 b/man/colitur.1
index 1a330d8..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
@@ -476,6 +480,131 @@ Print a usage summary to standard output and exit 0.
 .TP
 .BR \-V ", " \-\-version
 Print the version and exit 0.
+.SH PRETTY OUTPUT
+.B \-\-pretty
+draws each day as its own box rather than as a row for
+.BR awk (1):
+a heading with the date and the liturgical colour, then the celebration, its
+rank and season, and any commemorations \-\- each on its own line inside the
+box.
+.PP
+The box art is
+.B pure ASCII
+\-\- only
+.BR + ", " \- " and " | ,
+never Unicode box-drawing. That is deliberate: this format exists to be pasted
+or piped into a document, a mail or a plain-text ordo, and U+2500 and its
+relatives survive that only when every stage agrees about encoding and font.
+.B +\-\-\-+
+has never failed to render anywhere. Column alignment counts UTF\-8 code
+points rather than bytes, so a name carrying
+.RB \(lq \(ha \(rq
+or a ligature still lines the right edge up.
+.PP
+Accepted by
+.BR day ", " readings ", " rubrics " and " temporal .
+Every other command refuses it rather than accepting it and doing nothing:
+.BR emit ", " table ", " render " and " publish
+already choose their shape through
+.B \-\-format
+or
+.BR \-\-template ,
+and
+.B easter
+prints six key/value lines rather than a day grid.
+.PP
+Colour is written only when standard output is a terminal, so redirecting or
+piping yields plain aligned text \-\- the alignment survives, the escape
+sequences do not, and the colour column degrades to its initial
+.RB ( w ", " r ", " g ", " v ", " o ", " k )
+so the information is not simply lost. The
+.B NO_COLOR
+environment variable is honoured on presence, whatever its value, per the
+convention at https://no-color.org.
+.PP
+The default output is unchanged by this flag and remains the parseable one.
+Nothing should be written to parse
+.BR \-\-pretty :
+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