path: root/man/colitur-config.5

.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.
.TP
.B flavour
Which ESCAPING flavour a template's output is written in: one of
.BR latex ", " typst ", " groff ", " html ", " xml ", " ics " or " none ,
exactly as
.B \-\-flavour
accepts it. Relevant to
.BR table " and " render .
.IP
A flavour is the set of characters that must be neutered so a value cannot
corrupt the format it lands in, and every target has different ones: a
citation carrying a semicolon is ordinary text in LaTeX but a FIELD
SEPARATOR in iCalendar, so
.B "Ecclus 51:1\-8; 51:12"
must be written
.B "Ecclus 51:1\-8\e; 51:12"
there or one calendar field silently becomes two. In LaTeX a saint's name containing
.B &
or
.B _
does not merely look wrong \(em it aborts the build.
.IP
Normally there is nothing to set: the flavour is inferred from the
template's own file extension, so
.I ordo.tex
gets
.BR latex " and " ordo.ics " gets " ics .
This setting exists for the template whose extension says nothing. Leaving
it unset therefore means INFER, not "no escaping", which is why
.B colitur config \-\-show
reports it as
.BR (infer) " rather than " (none) .
There is deliberately no silent fallback: when the flavour can neither be
inferred nor found here, colitur refuses rather than guessing, because
guessing wrong yields output that is malformed rather than ugly, and
malformed output is usually silent.
.IP
.B none
is a real choice rather than a failure mode \(em correct when a template
targets plain text and the value should pass through byte for byte.
.TP
.B sigla_style
Which citation STYLE to render book names and punctuation with: a language
code, or a path to a file carrying a
.B [sigla]
section. Defaults to the resolved
.IR lang ,
so a booklet's citations follow its own language unless told otherwise.
See
.BR colitur (1)'s
.B SIGLA
section for the five style settings.
.TP
.B sigla_book
.BR full " or " abbr .
Overrides the selected style's own
.B book
setting. Default
.BR abbr ,
giving
.B "Luc 5:12\-14"
rather than
.BR "Evangelium secundum Lucam 5:12\-14" .
An unrecognised value is a hard error, the same discipline as an unknown
.BR \-\-lang .
.TP
.B sigla_tradition
A section name in
.IR lang/traditions.ini ,
deciding which book a reference DENOTES rather than what it is called.
Default
.BR vulgate ,
the identity \(em colitur never renumbers unless asked. With
.B modern
the Vulgate's own
.B "3 Kings 19:3\-8"
renders as
.B "1 Reg 19:3\-8"
in Latin, or
.B "1 Kgs 19:3\-8"
under
.BR "\-\-lang en" .
In Latin the modern tradition only really moves Kings and Esdras: Osee,
Ionas, Ecclesiasticus and the Apocalypse keep their Vulgate names either
way, because modern numbering is a vernacular convention.
Unlike
.IR sigla_book ,
an unrecognised value is NOT fatal: it warns on stderr and falls back to
.BR vulgate ,
because asking for a renumbering is optional the way asking for a language
is not.
.PP
Naming and renumbering are deliberately separate mechanisms.
.I sigla_style
selects what a book is CALLED, which varies by language;
.I sigla_tradition
selects which book a reference DENOTES, which does not \(em "modern
numbering" is the same decision in Latin, Polish and English. Conflating
them is how a citation ends up naming the wrong book.
.PP
None of these affect
.BR \-\-raw ,
which emits every citation exactly as stored, byte for byte.
.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.