1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
(** The config file: what the user wants by default, and where each value came
from.
Owns precedence and provenance and nothing else. Never reads the filesystem
-- callers hand it text -- so it is as testable as the language table.
A config file is OPTIONAL. With none, colitur behaves exactly as it does
without this feature, except that names resolve through the default
language. *)
type t
val empty : t
val of_string : string -> (t, string) result
(** [lang], [template] and [format] are each set from a single field. A
repeated key is LAST-WINS -- the opposite direction from
{!Colitur_kernel.Overlay_ini.get}'s first-wins over the same [section]
type -- because the natural reading of a config file a user edited by
hand and appended to is "the bottom line is the one that took effect".
This holds whether the repeat is within one [\[defaults\]] block or
across two of them: every section named [defaults] is merged, not only
the first, the same duplicate-section policy {!Lang.of_string} documents
for its own sections -- the two modules read the same underlying format
and must not disagree about what a repeated header means. *)
val lang : t -> string option
val overlays : t -> string list
val template : t -> string option
val format : t -> string option
(** The template ESCAPING flavour ([latex] | [typst] | [groff] | [html] |
[xml] | [ics] | [none]).
Only consulted when the flavour cannot be inferred from the template's
own extension, which is the usual case -- a template named [.tex] needs
no setting. It exists for the template whose extension says nothing,
and getting it wrong produces output that is malformed rather than
merely ugly, so there is deliberately no silent fallback. *)
val flavour : t -> string option
(** Which citation style to render a reference in: a language CODE, looked
up the same way {!lang} is, or a path -- but a DIFFERENT axis from
{!lang}: a language file's own [\[sigla\]] section IS a style
({!Colitur_citation.Render.style_of_fields}), and this key SELECTS
which file's [\[sigla\]] section supplies it, independently of which
file's other sections supply names elsewhere (a booklet may want
Polish names but Latin-convention citations). Same last-wins duplicate
policy as {!lang}. *)
val sigla_style : t -> string option
(** [full] or [abbr] -- overrides the style's own [book] setting rather than
replacing the style outright, so a chosen style's punctuation survives
even when the book form is overridden ({!Colitur_citation.Render.with_book}).
Same last-wins duplicate policy as {!lang}. *)
val sigla_book : t -> string option
(** The name of a section in [lang/traditions.ini] -- which BOOK a reference
DENOTES (Vulgate numbering by default), a different question again from
both {!sigla_style} (how a reference is WRITTEN) and {!lang} (what
everything else is CALLED): naming and numbering both vary by
convention, but not together. Same last-wins duplicate policy as
{!lang}. *)
val sigla_tradition : t -> string option
(** Keys present in the [\[defaults\]] section that this build does not
understand. Reported, never fatal: a config written for a newer colitur
must still work on an older one, but silently ignoring a line the user
wrote is how a typo becomes invisible. *)
val unknown_keys : t -> string list
(** Section names other than [\[defaults\]], reported separately from
{!unknown_keys} so the CLI can word the two warnings differently (a
misspelled section, e.g. [\[deafults\]], versus a misspelled key inside a
recognised one). Also never fatal, and never silent: a section this build
does not recognise is exactly the highest-value typo this feature exists
to catch, because it silently discards the whole section -- [lang] and
everything else in it -- with no other way for the user to notice. *)
val unknown_sections : t -> string list
(** [resolve ~flag ~config ~default] returns [(value, source)] with source one of
["flag"], ["config"], ["default"]. Precedence is flag > config > default. *)
val resolve : flag:string option -> config:string option -> default:string -> string * string
|
