From 7055723f8b79240ab2df1353eaaf3761f65414a9 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Mon, 17 Aug 2026 16:11:25 +0200 Subject: 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. --- test/cli.t | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'test/cli.t') diff --git a/test/cli.t b/test/cli.t index 288356c..d7e86f7 100644 --- a/test/cli.t +++ b/test/cli.t @@ -17,7 +17,7 @@ A year outside the supported domain is rejected (exit 2): No/garbage arguments give a usage error (exit 2): $ colitur - colitur: usage: colitur easter | colitur temporal | colitur day | colitur readings + colitur: usage: colitur easter | colitur temporal | colitur day | colitur readings (try: colitur --help) [2] The EF temporal cycle for a year, one line per day: @@ -211,3 +211,33 @@ with a confusing per-file error. (Exercised directly in the task, by creating _build/default/share/colitur/ef and confirming the year still resolves; not reproduced here because the cram sandbox's own exe path makes the layout awkward to stage without asserting on dune internals.) + +Help and usage are different things, and the difference is the Unix +convention rather than a preference. Asking for help is a request that +SUCCEEDED: it goes to standard output and exits 0, so it can be piped into a +pager or grepped. Being invoked wrongly is an error: a one-liner to standard +error, exit 2, leaving stdout clean for whatever the caller was really trying +to capture. + + $ colitur --help | head -1 + colitur -- deterministic liturgical calendar engine (Roman rite, 1962) + + $ colitur -h | head -1 + colitur -- deterministic liturgical calendar engine (Roman rite, 1962) + + $ colitur --help > /dev/null + $ colitur -h > /dev/null + +Nothing on stderr, and exit 0 (an exit other than 0 would print a [N] line): + + $ colitur --help 2>&1 >/dev/null + +The error path is the mirror image -- nothing on stdout, exit 2: + + $ colitur bogus 2>/dev/null + [2] + +Every command the help lists is a command the binary actually accepts. This +is the check that catches help text drifting away from the dispatch: + + $ for c in easter temporal day readings; do colitur $c 2026 > /dev/null || echo "$c FAILED"; done -- cgit v1.3