.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 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 <