From d727d07472172e3308ebd1706476a6bbf7ec1306 Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Tue, 18 Aug 2026 13:23:23 +0200
Subject: docs: point --help and the man page at the new overlay workflow

Both listed check and new-overlay among the commands but neither told a
reader how they fit together, which is the part that makes them useful. The
overlay sections now carry the four-step loop -- new-overlay, edit, check,
run -- and state what check does not do, since its name invites a stronger
reading than it earns.

Also documents what the format now permits: citations and layer optional, the
signed Easter_offset, the negative nth counting from the end of the month,
and the legal values of each of the six required fields, which previously
appeared only in the shipped example.
---
 man/colitur.1 | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

(limited to 'man/colitur.1')

diff --git a/man/colitur.1 b/man/colitur.1
index a637f19..6e380ce 100644
--- a/man/colitur.1
+++ b/man/colitur.1
@@ -169,6 +169,17 @@ Barbara and Rogation Wednesday \(em are applied first, then each
 in the order given. Last writer wins, so a later file may deliberately override
 an earlier one, or a universal entry, by naming its slug.
 .PP
+The workflow:
+.RS
+.nf
+
+.B colitur new\-overlay > my\-parish.sexp
+.B $EDITOR my\-parish.sexp
+.B colitur check my\-parish.sexp
+.B colitur day 2026 \-\-overlay my\-parish.sexp
+.fi
+.RE
+.PP
 An overlay is an S\-expression file with an
 .I id
 and a list of directives:
@@ -177,10 +188,38 @@ An added entry carries its own date specification, which may be a fixed
 .RI ( month ", " day )
 pair, an
 .I Easter_offset
-in days, or an
+in days (signed; Easter itself is 0), or an
 .I Nth_weekday
-of a month \(em so a patronal feast on "the first Sunday of October" or a
-dedication anniversary reckoned from Easter are both expressible. See
+of a month \(em the
+.I nth
+may be negative to count from the end, so
+.B \-1
+is the last \(em so a patronal feast on "the first Sunday of October" or a
+dedication anniversary reckoned from Easter are both expressible.
+.PP
+In an added celebration the
+.I citations
+and
+.I layer
+fields may be omitted: they default to empty and to the overlay's own
+.IR id .
+The remaining six are required, and each is a closed set \(em
+.I rank
+is
+.BR Class1 ", " Class2 ", " Class3 " or " Class4 ,
+.I status
+is
+.B Feast
+or
+.BR Commemoration_only ,
+.I colour
+is
+.BR White ", " Red ", " Violet ", " Green ", " Black " or " Rose ,
+and
+.I subject
+is
+.BR Lord ", " Bvm ", " Saint " or " Temporal .
+See
 .I <prefix>/share/colitur/examples/diocesan\-example.sexp
 for a worked, runnable example of all four directives and all three date
 shapes:
-- 
cgit v1.3