Catalogus en koormappen

Wat je nu doet: het model kennen waarmee de bibliotheek-site werkt, zodat publicatie, ids en navigatie niet door elkaar lopen.

Drie invalshoeken

Wie	Vraag	Ingang
Beheerder	Wat hebben we? Welk id gebruik ik?	Bibliotheek , Id-register , special pages
Koor (in situ)	Wat zingen we in welke volgorde?	Koormap, nu vooral liturgie zondag / weekdagen
Individueel koorlid	Wat moet / wil ik oefenen?	Koormap of bibliotheek (ook stukken die nog in geen map zitten)

Kernregel

De bibliotheek is de bron van waarheid. Koormappen zijn views: ze bevatten geen tweede kopie van de basispartituur-bestanden, maar verwijzen met bieb naar zangstuk/variant/uitvoeringsvorm.

Een uitvoeringsvorm mag publiek in de catalogus staan terwijl geen enkele koormap ernaar wijst. Dat is bewust: ontdekking en latere opname in een map (feest, collectie, parochiekeuze) komen daarna.

Bouwstenen in een koormap

Een koormap is geen platte lijst “één zangstuk = één pagina”. De liturgiemappen Hemelum (zondag / weekdagen) zijn een inhoudsopgave van liturgische plekken. Een titel in die inhoudsopgave kan naar één zangstuk wijzen, of naar een hoofdstuk met meerdere keuzes (bijvoorbeeld eerste antifoon: weekdagen, zondag, later feestdagen).

Bouwsteen	Bestand	Rol
Koormap-root	`koormappen/hemelum/liturgie-zondag\_index.md` (of `liturgie-weekdagen`)	Handmatige inhoudsopgave van die map
Koormap-sectie	map met `_index.md`	Liturgische plek / hoofdstuk; tekst plus kindlijst, of eigen TOC
Slot-pagina	map met `index.md`	Lees- of oefenblad: markdown plus `bieb` (geen catalogus/`lokaal/`-include)

Sectie (_index.md): zet automatische_inhoud: true als de layout de kindpagina’s mag tonen (voorbeeld: koormappen/hemelum/liturgie-zondag\eerste-antifoon\). Zet false als je zelf de inhoudsopgave van dat hoofdstuk schrijft (zoals de root van een liturgiemap). Gebruik in sectie-_index.md geen #-titel in de body; die titel komt uit de layout.

Slot-pagina (index.md): gewone markdown. Daartussen kun je één of meer shortcodes bieb zetten. Elke shortcode zet eerst de knoppen Oefenen / Beluisteren / Downloaden / Printen voor die uitvoeringsvorm, en daarna de PDF of VSA-SVG. De partituur blijft in de catalogus; de slot-pagina is alleen de view. Navigatie naar Bibliotheek of Koormap loopt via de sticky broodkruimelregel bovenaan de pagina.

Boom of compositieblad?

Twee manieren om meerdere uitvoeringsvormen op één liturgische plek te tonen —zelfde mechaniek, andere leeservaring:

Patroon	Wanneer	Voorbeeld
Boom	De zanger kiest één variant (of bladert per kind)	Cherubijnenhymne: sectie → 15b, 15c, …; antifoon: weekdagen / zondag
Compositieblad	Eén pagina bundelt een set (proza + scores)	Prokimens voor de hele week op één `index.md`, met shortcode per weekdag

Voorbeeld compositieblad (schets):

# Prokimen weekdagen (Kiev, Groningen)

## Maandag
{{< bieb id="prokimen/9a-maandag/groningen" >}}

## Dinsdag
{{< bieb id="prokimen/9a-dinsdag/groningen" >}}

Let op: elke bieb op dezelfde pagina heeft een eigen knoppenrij direct boven de partituur van die uitvoeringsvorm. Je hoeft geen aparte kindpagina’s te maken alleen om knoppen te scheiden.

Alias-varianten

Soms heeft dezelfde variant meerdere namen. Voorbeeld: de tropaar-variant maandag-toon-4 is dezelfde variant als heilige-engelen-toon-4 (de tropaar van de Heilige Engelen, gezongen op maandag). Dat is een alias op variant-niveau, niet een tweede uitvoeringsvorm.

Dan:

partituren (.vsa, PDF, …) staan alleen bij de canonieke variant, hier de uitvoeringsvorm tropaar/maandag-toon-4/hemelum;
de alias-variant heeft alleen een _index.md met frontmatter alias_van: tropaar/maandag-toon-4 — geen map hemelum/, geen index.md, geen partituur;
de bibliotheek-index van het zangstuk (tropaar/, kondak/, …) noemt beide varianten; achter de alias-naam staat dat het een alias is.

Shortcode bieb krijgt een uitvoeringsvorm-id (drie lagen). Wie de alias-variant in dat id zet, bijvoorbeeld tropaar/heilige-engelen-toon-4/hemelum, wordt herschreven naar de canonieke uitvoeringsvorm. Product-tools (vsa-products, basispartituur-producten) slaan alias-varianten over: daar is niets te genereren.

check weigert een alias-variant die toch een uitvoeringsvorm-map of partituur bevat. Dat patroon mag voor elk zangstuk waarvan een variant onder meerdere namen bekend is.

Titels en frontmatter in de catalogus

Getoonde namen in de catalogus (paginatitel, navigatie, zoeken) worden afgeleid bij de bouw uit het pad/id, en bij een leaf optioneel uit de bron (VSA/mvsa-titel:). Handmatige redactionele titels horen in koormappen, niet in de catalogus. Agent-contract in de repo: docs/catalogus-titels.md.

Elke catalogus-pagina (_index.md of leaf-index.md) heeft minstens:

Veld	Rol
`publicatiestatus`	Wat koorleden mogen verwachten (`voorzien` / `concept` / `reviewable` / `productie`)
`automatische_inhoud`	Sectie: meestal `true` (kindlijst). Leaf: altijd `false` (score via `bieb`)

Ids komen uit het pad (zangstuk/variant/uitvoeringsvorm). Tooling en shortcode bieb gebruiken het pad. Frontmatter title / linkTitle zijn geen bron van waarheid (Hugo negeert ze op id-pagina’s); bieb accepteer mag ze nog als afgeleid artefact zetten.

Afleiding per laag

Laag	Korte naam (navigatie)	Paginatitel / zoek
Zangstuk	Uit mapnaam (streepjes → spaties)	Zelfde
Variant	Uit mapnaam (`default` → Standaard)	Zelfde
Uitvoeringsvorm (leaf)	Label uit uitvoeringsvorm-id (`Hemelum`, `Groningen`, …)	Uit bron-titel als die er is, anders uit id: `Zangstuk Variant (Label)`

Variant-id `default`

Als er nog maar één variant is, heet de map vaak default. De getoonde naam wordt dan Standaard. Zodra er een tweede variant komt, geef je de map een echte id (hernoemen).

Wat `check` wel en niet doet aan titels

scripts\check.cmd (met --strict: hard) controleert via check_catalogus_leaf_titles dat data/uitvoeringsvorm-link-titles.yaml gelijk blijft aan de labels in scripts/catalogus.py (Hugo en Python dezelfde namen). Geen eis meer op handmatige leaf-title.

Nog niet door check: een volledig frontmatter-schema of verplichte publicatiestatus. Mis je publicatiestatus op een leaf, dan ontbreekt de ? naast de titel; de build faalt daar niet op.

Soorten koormap (classificatie)

Zelfde mechaniek, andere bedoeling — geen nieuwe id-laag:

Type	Ordening	Voorbeeld
Liturgisch	Volgorde in de dienst	Liturgiemap Hemelum
Feest / kalender	Orde van die dag of cyclus	Pasen, 15 augustus
Collectie	Thematisch	Alle cherubijnen, troparen toon 1–8
Parochiekeuze	Wat dit koor deze periode zingt	“Hemelum najaar”, “Zwolle-cherubijn”

Optioneel later: frontmatter type: op de koormap-_index (liturgie, feest, collectie, parochie).

«Collectie» hier is dus een view in de koormap, geen extra maplaag boven zangstukken in de catalogus. Zie besluit 5 in Zangstuk-soorten .

Wat de catalogus-root toont

De root van de catalogus is geen sitemap van alle stubs. Koorleden zien daar vooral oefenbare zangstukken (nette titel, liturgienummer-volgorde). Voorzien-items en technische registers staan onder Speciaal en het Id-register .

Special pages

Automatisch bijgehouden (bij elke sitebuild):

Pagina	Inhoud
Voorzien	Zangstukken zonder oefenbare inhoud
Ongerefereerd	In de catalogus, nog niet in een koormap
Oefenbaar	Platte lijst van linkbare uitvoeringsvormen + id
Handmatig	Uitvoeringsvormen met `artefacten_handmatig: true`

Taalvarianten op de uitvoeringsvorm

Nederlands en kerkslavisch zijn aparte uitvoeringsvormen. De taal hoort in het derde padsegment (de leaf-map), niet in een vierde maplaag en niet als aparte map per bestandsformaat.

Regel: geen taalsuffix op de uitvoeringsvorm-id betekent Nederlands. Andere talen krijgen een suffix achter de leaf-naam (-ksl, later -en, -fr, …). Gebruik geen losse -nl-uitgang.

Wanneer wel, wanneer niet

Situatie	Wat je doet
Nederlands (alleen of naast een andere taal)	Geen taalsuffix: leaf `hemelum`
Zelfde herkomst in beide talen	Twee leaves: `hemelum` en `hemelum-ksl`
Alleen kerkslavisch (Cyrillisch)	Suffix `-ksl` op de uitvoeringsvorm-id
Mengvorm NL + kerkslavisch in één partituur	Suffix `-nl-ksl` (zeldzaam)

Voorkeursconventie voor nieuw werk: Nederlands zonder suffix; andere talen via suffix op de uitvoeringsvorm-id. Zet de taal niet in de variant-id.

Legacy / alternatief: sommige oudere stukken houden taal in de variant, bijvoorbeeld trisagion/8a-nederlands/hemelum naast trisagion/8a-slav/hemelum. Die maps niet hernoemen tot een aparte migratie; voor nieuwe ids volg je de suffix-regel hierboven.

Getranslitereerde producten (Latijns schrift naast Cyrillisch) horen later; die conventie staat nog niet vast in dit padmodel.

Pad, catalogus-id en bestandsstam

Begrip	Vorm	Voorbeeld (schets)
Cataloguspad	`catalogus\<zangstuk>\<variant>\<uitvoeringsvorm>\`	`catalogus\prijslied\bisschop-gregorios\hemelum\`
Catalogus-id (`bieb`)	`zangstuk/variant/uitvoeringsvorm`	`prijslied/bisschop-gregorios/hemelum`
Publicatiestam	`{zangstuk}-{variant}-{uitvoeringsvorm}`	`prijslied-bisschop-gregorios-hemelum`

Voorbeeld-paar (nog niet per se in de catalogus; richting voor nieuw werk):

content-source\catalogus\prijslied\bisschop-gregorios\hemelum\
content-source\catalogus\prijslied\bisschop-gregorios\hemelum-ksl\

Catalogus-ids: prijslied/bisschop-gregorios/hemelum en prijslied/bisschop-gregorios/hemelum-ksl. Bestandsstam van de Nederlandse leaf: prijslied-bisschop-gregorios-hemelum (plus extensie van de bron).

Precedent in het Id-register : o.a. cherubijnenhymne/15c-kastorski/hemelum-ksl (stub) en bestaande -ksl-leaves zoals tropaar/uw-heilig-kruis/groningen-ksl.

Canonieke bron vs afgeleiden

In elke leaf-map liggen bron en afgeleiden naast elkaar (siblings):

Soort	Voorbeelden	Rol
Canonieke bron	`{stam}.vsa`, `{stam}.mscz`, `{stam}.mvsa`, `{stam}.tekstblad.md`	Hier bewerk je
Afgeleiden	`{stam}.vsa.mxl`, `{stam}.vsa.pdf`, `{stam}.mp3`, `{stam}.mscz.pdf`, …	Regenereren met productscripts

Formaat is geen id-laag: geen aparte map pdf/ of mxl/ onder de leaf. PDF, MusicXML en audio blijven siblings van de bron in dezelfde uitvoeringsvorm-map. Detail: Publicatiecontrole .

Koormap: alleen `bieb`

Koormap-slots bevatten geen kopie van de partituur. Ze verwijzen met shortcode bieb naar het catalogus-id, inclusief het taalsuffix wanneer dat in de leaf-naam zit:

{{< bieb id="prijslied/bisschop-gregorios/hemelum" >}}
{{< bieb id="prijslied/bisschop-gregorios/hemelum-ksl" >}}

Korte woordenlijst: Woorden (regel Taal-suffix). Concrete ids: Id-register .

Naamgevingsbeleid (nieuwe ids)

Nieuwe zangstuk-ids krijgen geen sorteerprefix (tropaar, niet tropaar). Liturgienummers horen in de koormap-titel en in Hugo- weight.
Spelling voor nieuwe ids: johannes, alleluia; liever voluit dan mg of zo-wk-mg.
Genummerde top-level zangstuk-ids zijn hernoemd (zie Zangstuk-soorten ). Nieuwe hernoemingen: werktraject Zangstuk hernoemen (bieb hernoem ).
Echte naamsynoniemen van dezelfde variant: alias_van. Spelling- en woordvolgorde-varianten: zoekindex + data/zoek-synoniemen.yaml .
Taal: geen suffix = Nederlands; andere talen als suffix op de uitvoeringsvorm (-ksl, …) — zie Taalvarianten .

Zie Zangstuk-soorten voor de inventaristabel en resterende vervolgstappen.

Klaar als

Je kunt uitleggen waarom een Zwolle-cherubijn eerst in de catalogus hoort; waarom de Hemelum-liturgiemap géén tweede opslag van PDF’s is; wanneer je een sectie (boom) kiest versus een compositieblad (meerdere shortcodes op één pagina); en hoe je een NL/kerkslavisch-paar als twee uitvoeringsvormen aanmaakt (hemelum + hemelum-ksl).

Waar ligt wat Zangstuk-soorten