feat(cli): a Makefile, a man page, and --help

Three things the project had no answer for: how to install it without
knowing dune, where to read about it, and what it does when asked.

Makefile, same shape as lectio's -- PREFIX ?= $(HOME)/.local, BINDIR,
MANDIR, and the '## '-comment help target -- so the two siblings are
driven the same way. Every recipe wraps dune in `opam exec --`, which is
the actual point of having one here: `make build` works from a plain
shell with no `eval $(opam env)` first. install goes through `dune
install` rather than a hand-rolled copy, because the binary finds its
calendar data relative to its own path; the man page is installed
separately to share/man/man1, matching lectio. install and uninstall
were both run against a scratch prefix and checked: uninstall leaves
zero files behind.

PREFIX defaults to ~/.local because that is where lectio installs and
where it actually lives on this machine, so colitur lands on an existing
PATH with no shell change. An earlier install this session went to
~/opt/colitur, which was me over-applying a rule meant for third-party
tools to one of the author's own projects; it has been removed rather
than left as a second, staler binary competing on PATH.

man/colitur.1 documents the four commands, both output formats and why
they differ, COLITUR_DATA_DIR and its refusal to fall back, the data
resolution order, exit statuses, and -- deliberately -- the limitations:
EF only, Epistle and Gospel only with the chants unbuilt and rejected
rather than guessed, and the BVM Saturday Mass-selection gap. A man page
that only lists what works is half a man page. Renders clean under
`groff -ww -z`, no warnings.

--help prints to stdout and exits 0; a usage error prints one line to
stderr and exits 2. That is the Unix convention rather than a
preference: asking for help succeeded and should be pipeable, being
invoked wrongly did not and must not pollute stdout. Both directions are
asserted in cli.t, along with a loop confirming every command the help
text advertises is one the dispatch actually accepts -- the check that
catches help drifting away from the code.

1 files changed, 49 insertions, 1 deletions

diff --git a/bin/main.ml b/bin/main.ml
index ca89a12..573f190 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -330,10 +330,57 @@ let resolved_year_report ~line y =
 let day_report y = resolved_year_report ~line:day_line y
 let readings_report y = resolved_year_report ~line:readings_line y
 
+(* Help and usage are deliberately DIFFERENT things, and the difference is the
+   Unix convention rather than a preference: asking for help is a request that
+   SUCCEEDED, so [--help] prints to stdout and exits 0 (it can be piped into a
+   pager or grepped); being invoked wrongly is an error, so [usage] prints a
+   one-liner to stderr and exits 2, keeping stdout clean for whatever the
+   caller was really trying to capture. *)
+let help_text =
+  {|colitur -- deterministic liturgical calendar engine (Roman rite, 1962)
+
+usage:
+  colitur easter <year>      Easter, and the movable feasts anchored to it
+  colitur temporal <year>    the temporal cycle, one line per day
+  colitur day <year>         the resolved day identity, one line per day
+  colitur readings <year>    the Mass reading citations, one line per day
+  colitur -h, --help         this help
+
+<year> is a civil year, 1583..9999 inclusive. Each report covers 1 January to
+31 December of that year, not a liturgical year.
+
+output formats:
+  day       date weekday season week slug rank colour [+commemoration ...]
+            2026-04-05 sunday paschaltide 1 ef-easter-sunday class-1 white
+  readings  date slug | Epistle | Gospel
+            2026-12-25 ef-nativity | Heb 1:1-12 | John 1:1-14
+
+  A citation contains spaces, so readings uses " | " between its fields while
+  day stays space-separated; that is why they are separate commands rather
+  than extra columns.
+
+environment:
+  COLITUR_DATA_DIR
+            Read the calendar data from this directory instead of the
+            installed (<prefix>/share/colitur/ef) or build-tree location.
+            If it is set and holds no sanctoral.sexp, colitur exits 2 rather
+            than silently falling back to a different copy of the data.
+
+exit status:
+  0  success
+  2  bad usage, year out of range, or the calendar data could not be read
+
+Reading references only (e.g. "Jn 3:16"); never scripture text.
+See colitur(1) for the full description and the sources it computes against.|}
+
+let print_help () =
+  print_endline help_text;
+  exit 0
+
 let usage () =
   prerr_endline
     "colitur: usage: colitur easter <year> | colitur temporal <year> | colitur day <year> | colitur \
-     readings <year>";
+     readings <year>  (try: colitur --help)";
   exit 2
 
 let with_year ys f =
@@ -346,6 +393,7 @@ let with_year ys f =
 
 let () =
   match Sys.argv with
+  | [| _; ("-h" | "--help" | "help") |] -> print_help ()
   | [| _; "easter"; ys |] -> with_year ys easter_report
   | [| _; "temporal"; ys |] -> with_year ys temporal_report
   | [| _; "day"; ys |] -> with_year ys day_report