From 0eae32f67145065b0e4960650ae06c293fd9f272 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Fri, 21 Aug 2026 12:33:30 +0200 Subject: docs(config): document the flavour key colitur.1 documented the flag and colitur-config(5) documented every [defaults] key except this one, which the previous commit added. Says what a flavour IS rather than only listing the values: the set of characters that must be neutered so a value cannot corrupt its target. A semicolon is ordinary text in LaTeX and a field separator in iCalendar; an unescaped & or _ does not look wrong in LaTeX, it aborts the build. Also why unset means INFER rather than 'no escaping', and why there is no silent fallback. --- man/colitur-config.5 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/man/colitur-config.5 b/man/colitur-config.5 index 0e242bf..15ca92b 100644 --- a/man/colitur-config.5 +++ b/man/colitur-config.5 @@ -182,6 +182,46 @@ 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 -- cgit v1.3