merge: overlay authoring ergonomics

Two mandatory fields made optional, parse errors that stop naming kernel
source files, and a feedback loop -- colitur check and colitur new-overlay --
for a file the test layers deliberately cannot vouch for.

1 files changed, 21 insertions, 0 deletions

diff --git a/man/colitur.1 b/man/colitur.1
index 8a52858..a637f19 100644
--- a/man/colitur.1
+++ b/man/colitur.1
@@ -65,6 +65,27 @@ occurrence, commemoration and transfer.
 .BI readings " YEAR"
 The Mass reading citations, one line per day.
 .TP
+.B new\-overlay
+Print a starter overlay file to standard output, for redirection. Every value
+in it is a placeholder that will appear in
+.B day
+output if left unedited, so a half\-finished overlay is visible rather than
+silently inert.
+.TP
+.BI check " FILE" ...
+Load each overlay, apply it to the shipped calendar, and report what it does:
+the directive counts, the slug each targets, and any directive that matched
+nothing. Exits
+.B 2
+if a file fails to load or a directive found no target, so it composes into a
+Makefile or a pre\-commit hook. It answers three narrow questions \(em does
+the file parse, does every directive find its target, and what does the merged
+result contain. It does
+.I not
+validate a calendar against the rubrics, and cannot: see
+.B OVERLAYS
+below.
+.TP
 .BI \-\-overlay " FILE"
 Apply a user calendar on top of the shipped one. Repeatable and ordered;
 .B day