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

Catalogus bladeren (referentie)

De catalogus is bedoeld als repertorium, niet alleen als inhoudsopgave van één liturgie. Via het menu Catalogus (startpagina Catalogus ):

• Zoeken — op titel, id of gezongen tekst
• Alfabetisch — boom op zangstuk (A–Z)
• Per herkomst — boom op herkomst (Hemelum, Groningen, …); taalsuffix (-ksl e.d.) is géén aparte herkomst — NL en Ksl van dezelfde stam staan onder elkaar
• Per soort — boom in liturgische volgorde (ektinia, tropaar, …)

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

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:

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:

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

Variant-id default

Als er nog maar één variant is, heet de map vaak default. Op de variant-pagina in de catalogus is de getoonde naam dan Standaard. Zodra er een tweede variant komt, geef je de map een echte id (hernoemen); default mag niet naast andere variant-ids onder hetzelfde zangstuk blijven staan.

Overzichtsbomen (Alfabetisch, Per herkomst, Per soort) slaan enkelvoudige tussenlagen over: heeft een tak precies één kind (één sub-tak of één blad), dan zie je meteen de inhoud van dat kind — en dat herhaalt zich tot er meerdere kinderen zijn of je bij een blad bent. Het bovenste niveau van het overzicht blijft wél altijd staan (herkomst-stam zoals Groningen, of het zangstuk op Alfabetisch / Per soort). Voorbeeld: onder Rode Gebedenboek met alleen één tropaar zie je Rode Gebedenboek → blad, niet eerst nog een tak «Tropaar». Onder Groningen verdwijnen zangstuk-takken met maar één blad (zoals soms Communievers); het blad staat dan direct onder Groningen. Ook de variant-laag verdwijnt bij elke enige variant (niet alleen bij default).

Extra bij (enige) default/standaard:

1. De bladtitel in de boom is Zangstuk (uitvoeringsvorm) — zonder het woord «Standaard» (het id …/default/… blijft in de code zichtbaar).
2. De sitebuild (catalogus-referentie) faalt als iemand default/standaard combineert met een andere variant onder hetzelfde zangstuk.

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:

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):

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

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

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):

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)

1. Nieuwe zangstuk-ids krijgen geen sorteerprefix (tropaar, niet tropaar). Liturgienummers horen in de koormap-titel en in Hugo- weight.
2. Spelling voor nieuwe ids: johannes, alleluia; liever voluit dan mg of zo-wk-mg.
3. Genummerde top-level zangstuk-ids zijn hernoemd (zie Zangstuk-soorten ). Nieuwe hernoemingen: werktraject Zangstuk hernoemen (bieb hernoem ).
4. Echte naamsynoniemen van dezelfde variant: alias_van. Spelling- en woordvolgorde-varianten: zoekindex + data/zoek-synoniemen.yaml .
5. 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).