docs(naming): the config man page, and the field reference

colitur-config.5 documents the file's location, the flag > config >
default precedence, every setting, and that an unknown key is warned
about rather than fatal. Its worked example is a real run against the
shipped example overlay, pasted rather than hand-typed -- including one
genuine gotcha found while verifying it: overlay/template values are not
shell-expanded, so a bare "~/..." written into the config file fails to
load; the full path must be written out instead.

colitur-templates.5's field reference is updated for the view change --
every field checked against lib/render/view.ml and schema/day-v1.json,
not transcribed from memory or an earlier version of this page -- and its
worked example is pasted from a real `colitur table` run. Its
scope-shadowing warning about {{name.la}} is REMOVED and replaced with a
short note that the hazard is now unrepresentable, because name is a
plain resolved string with no dotted path left to fall back through. The
num collision between a month and a week (both carry num, and a bare
{{num}} read from inside a day silently climbs to the week's own value,
not the month's) still exists and is demonstrated with a real render, not
merely asserted. A man page describing a hazard that was fixed is as
wrong as one that omits a real hazard.

Two further stale mentions of the removed {{name.la}} hazard, and two
places describing the schema as "Latin and English names" rather than one
resolved display name, were found in colitur.1 while cross-checking and
fixed alongside the primary rewrite; its own CSV example in EMIT was also
still the pre-Task-5 column list (name_la/name_en, no *_name columns) and
is now the real, verified header.

lang/ already installs beside templates/ and schema/ (a prior hotfix);
colitur-config.5 is added to install/uninstall/man/doc in the Makefile so
`make install`/`make doc` cover it too.

1 files changed, 308 insertions, 0 deletions

diff --git a/man/colitur-config.5 b/man/colitur-config.5
new file mode 100644
index 0000000..8f21028
--- /dev/null
+++ b/man/colitur-config.5
@@ -0,0 +1,308 @@
+.TH COLITUR\-CONFIG 5 "2026" "colitur" "File Formats"
+.SH NAME
+colitur\-config \- default settings file for colitur(1)
+.SH SYNOPSIS
+.I ~/.config/colitur/config.ini
+.SH DESCRIPTION
+A
+.B colitur
+config file supplies DEFAULTS for four settings \(em
+.IR lang ", " overlay ", " template " and " format
+\(em so a command line does not have to repeat
+.B \-\-lang
+.IR en ,
+.B \-\-overlay
+.I ~/calendars/diocese.sexp
+or
+.B \-\-template
+.I booklet.tex
+on every invocation.
+.PP
+A config file is entirely
+.BR OPTIONAL .
+With none present, every command behaves exactly as it does without this
+feature, except that display names still resolve through the built\-in
+default language
+.RI ( la ).
+.SH LOCATION
+.RS
+.nf
+$XDG_CONFIG_HOME/colitur/config.ini   if $XDG_CONFIG_HOME is set and non\-blank
+$HOME/.config/colitur/config.ini      otherwise
+.fi
+.RE
+.PP
+If neither variable is usable (no
+.BR HOME ),
+there is no config path at all, and colitur behaves exactly as if no config
+file existed \(em this is not an error.
+.SH PRECEDENCE
+For every one of the four settings, in order:
+.RS
+.nf
+1. the command\-line flag        (\-\-lang, \-\-overlay, \-\-template, \-\-format)
+2. the config file's own value
+3. the built\-in default
+.fi
+.RE
+.PP
+.BR "colitur config \-\-show" ,
+described below, reports EXACTLY this resolution for the flags given on
+that same command line \(em it is not a separate calculation that could
+disagree with what a real command actually does; both go through the same
+resolver.
+.PP
+.IR lang ", " template " and " format
+are each a single scalar value: config supplies one only when the
+corresponding flag is
+.B entirely absent
+from the command line, never merged or overridden field\-by\-field with a
+partial flag value.
+.I overlay
+is a
+.B list
+(it is repeatable on the command line, and overlays apply in order, last
+writer wins) and follows the identical rule at the list level: config's
+.I overlay
+lines are used only when
+.B zero
+.B \-\-overlay
+flags were given; a single
+.B \-\-overlay
+on the command line replaces the config list entirely rather than adding to
+it. This keeps the direction of precedence uniform across all four settings
+\(em flag beats config beats default \(em rather than inventing a merge
+order nothing else in this file documents.
+.SH FORMAT
+An INI file, read by the same section reader
+.BR colitur\-overlay (5)'s
+flat INI form and colitur's own language files use: section names in
+.RB \(lq [ name ] \(rq ,
+.RB \(lq key " = " value \(rq
+lines,
+.B ;
+and
+.B #
+comments, blank lines ignored. No continuations, no quoting.
+.PP
+Every setting lives in a section named
+.BR defaults .
+A section named anything else is
+.B unrecognised
+\(em including a plain typo such as
+.B [deafults]
+\(em and is warned about, not silently dropped (see
+.B UNKNOWN KEYS AND SECTIONS
+below).
+.PP
+If
+.B [defaults]
+appears more than once, every occurrence is merged, not only the first: a
+hand\-edited config file will naturally grow a second
+.B [defaults]
+block as a user appends a line later, and only reading the first would
+silently ignore it. Within one key, or across two blocks, the
+.B LAST
+occurrence wins \(em the natural reading of "the bottom line is the one
+that took effect" for a file edited by hand over time. A repeated
+.B overlay
+key is the one exception: it
+.B accumulates
+(one entry per line), because a user legitimately has more than one local
+overlay.
+.SH SETTINGS
+.TP
+.B lang
+A language CODE (e.g.
+.BR la ", " en )
+or a file path, exactly as
+.B \-\-lang
+accepts it. Default
+.BR la .
+See
+.BR colitur (1)'s
+own
+.B NAMING
+section for how a CODE resolves to a file, and what an unknown language
+does (a hard error, on every command, never a silent fallback).
+.TP
+.B overlay
+A local calendar file, applied on top of the shipped universal one, exactly
+as
+.B \-\-overlay
+accepts it. Repeatable \(em one
+.B overlay
+.B =
+line per file, applied in the order they appear in the config file. No
+default (an empty list).
+.TP
+.B template
+A template file path, exactly as
+.B \-\-template
+accepts it. Relevant only to
+.BR table " and " render ,
+which require a template either from this setting or from
+.BR \-\-template ;
+no default.
+.PP
+.B Neither
+.I overlay
+.B nor
+.I template
+.B is shell\-expanded.
+A value is read as a literal string and handed straight to the filesystem
+\(em there is no shell here to turn a leading
+.B ~
+into
+.IR $HOME .
+.RS
+.nf
+
+$ printf '[defaults]\enoverlay = ~/calendars/diocese.sexp\en' > config.ini
+$ XDG_CONFIG_HOME=. colitur day 2026
+colitur: failed to load ~/calendars/diocese.sexp: ~/calendars/diocese.sexp: No such file or directory
+.fi
+.RE
+.PP
+Write the full path instead
+.RI ( $HOME /calendars/diocese.sexp,
+which the SHELL expands when the config file is CREATED, e.g. via
+.BR "echo \(dqoverlay = $HOME/calendars/diocese.sexp\(dq >> config.ini" ,
+not a bare
+.BR ~ / ... " written literally into the file)."
+.TP
+.B format
+One of
+.BR csv ", " json ", " sexp ", " xml " or " ics ,
+exactly as
+.B \-\-format
+accepts it. Relevant only to
+.BR emit ,
+which requires a format either from this setting or from
+.BR \-\-format ;
+no default.
+.SH UNKNOWN KEYS AND SECTIONS
+A key inside
+.B [defaults]
+that is none of the four settings above, and a section that is not named
+.BR defaults ,
+are each reported \(em on standard error, prefixed with the config file's
+own path \(em and then
+.BR ignored .
+Neither is fatal on its own. This is deliberate: a config file written for
+a newer
+.B colitur
+must still work on an older one that does not yet recognise every setting,
+but silently discarding a line the user wrote is exactly how a setting they
+believe is active quietly does nothing. The two are reported separately,
+worded differently, so a misspelled
+.B SECTION
+(the whole block silently doing nothing) reads differently from a
+misspelled
+.B KEY
+inside an otherwise\-recognised one:
+.RS
+.nf
+
+colitur: ~/.config/colitur/config.ini: unknown setting "langauge" (ignored)
+colitur: ~/.config/colitur/config.ini: unknown section [deafults] (ignored)
+.fi
+.RE
+.PP
+A config file that
+.B EXISTS
+but fails to
+.B parse
+at all \(em an unterminated
+.RB \(lq [ \(rq ,
+a
+.B key = value
+line before any section header \(em is a different case and is
+.BR FATAL :
+exit
+.BR 2 ,
+naming the file and the reason, on
+.B every
+command, not only ones that read
+.IR lang / overlay / template / format .
+The config file is loaded once, unconditionally, before any command
+dispatches \(em a config the user wrote and colitur cannot honour at all is
+not something to silently carry on past, even for a command
+(
+.B \-\-help
+included) that would not otherwise have consulted it.
+.SH SHOWING THE RESOLVED CONFIGURATION
+.BI "colitur config " \-\-show
+prints the config file's own path and whether it exists, then every one of
+the four settings with its resolved value and where that value came from:
+.BR flag ", " config " or " default .
+There is deliberately no separate "provenance" function elsewhere in the
+program \(em the same resolver that decides what
+.B colitur day
+actually uses is what
+.B \-\-show
+reports, so the two cannot disagree.
+.PP
+Flags given on the SAME
+.B config \-\-show
+command line preview exactly what they would resolve to on any other
+command \(em
+.B config
+is the one command that does NOT refuse
+.BR \-\-lang / \-\-overlay / \-\-template / \-\-format
+as having no effect on it, because previewing their resolution
+.I is
+its effect.
+.I overlay
+has no single scalar value, so it is listed one line per effective entry
+instead of one line total.
+.SH WORKED EXAMPLE
+Reproducible against the shipped example overlay \(em every literal below is
+a real run, not a transcription. The full, absolute path is written into the
+file (see the shell\-expansion note above \(em a bare
+.B ~
+would fail to load):
+.RS
+.nf
+$ mkdir \-p ~/.config/colitur
+$ cat > ~/.config/colitur/config.ini <<EOF
+[defaults]
+lang = en
+overlay = $HOME/.local/share/colitur/examples/diocesan\-example.sexp
+EOF
+$ colitur config \-\-show
+config file: /home/user/.config/colitur/config.ini (exists)
+lang       en                       (config)
+template   (none)                   (default)
+format     (none)                   (default)
+overlay    /home/user/.local/share/colitur/examples/diocesan\-example.sexp (config)
+$ colitur day 2026 | head \-1
+2026\-01\-01 thursday christmastide \- ef\-circumcision class\-1 white The Octave Day of the Nativity
+.fi
+.RE
+.PP
+.B day
+above used
+.I en
+and the diocesan example overlay with no flags at all, because neither was
+given on the command line; a real run with
+.B \-\-lang la
+or
+.B \-\-overlay
+would override each independently, per\-invocation, without editing the
+file.
+.SH SEE ALSO
+.BR colitur (1)
+for
+.BR \-\-lang / \-\-raw ,
+.BR "colitur lang" ,
+and the
+.B NAMING
+section in full.
+.PP
+.BR colitur\-overlay (5)
+for the overlay file format
+.I overlay
+names.
+.SH LICENSE
+AGPL\-3.0\-or\-later.