Eigene Texte beitragen

Technischer Leitfaden zur Konversion bestehender TEI-Daten (MHD/FNHD) in das MHDBDB-Schema: spezifische Konventionen, Authority-File-Verknüpfungen und halbautomatische Annotations-Pipeline.

Weg A — Selbst-Ingest

Sie haben TEI-Kompetenz und richten die Pipeline selbst ein. Dieser Leitfaden führt Sie Schritt für Schritt durch das MHDBDB-Schema, die Authority-File-Verknüpfung und die halbautomatische Annotations-Pipeline.

→ Lesen Sie die Abschnitte 1–9 unten.

Weg B — DHCraft-Konvertierungsservice

DHCraft OG übernimmt Konvertierung, Lemmatisierung und Ingest als externen, kostenpflichtigen Service. Geeignet für Projekte ohne eigene TEI-Pipeline-Kapazität. Konditionen und Projektfinanzierungsoptionen auf Anfrage.

mhdbdb@plus.ac.at kontaktieren.

Vorab-Checkliste (vor dem ersten Schritt)

  • Sigle vereinbart (3–5 Großbuchstaben, eindeutig im Gesamtkorpus → per Mail abklären)
  • Eintrag in works.xml angelegt (Sigle, Titel, Genre, Autor)
  • Eintrag in persons.xml vorhanden oder person_anonym gesetzt
  • Genre-Klassifikation in genres.xml existiert (oder neuen Eintrag anfragen)
  • TEI-Quelldatei liegt in ingest/<sigle>/ (nicht direkt in tei/)
  • Stage-1-Validierung (TEI P5) läuft durch oder Abweichungen sind als GAP dokumentiert
  • Stage-2-Validierung (MHDBDB-Schema) ergibt 0 Fehler
  • @lemmaRef-Coverage ≥ 85 % (oder begründete Abweichung dokumentiert)
  • Index-Rebuild durchgeführt (build-corpus-index.py + build-authority-index.py) und Versionsbumps synchronisiert

1. Schema-Spezifika gegenüber Standard-TEI

Das MHDBDB-Schema (schema/mhdbdb.rnc) erweitert TEI P5 in zwei Richtungen: einige Strukturen werden strenger modelliert, andere bewusst gelockert (GAPs 1–11, dokumentiert im Schema).

Strenger als Standard-TEI

Element/Attribut MHDBDB-Anforderung
<w>/@xml:id Pflicht, eindeutig pro Datei
<pc>/@join Pflicht: "left" oder "right"
<div>/@type Enum: chapter | section | number | song | parallel | colophon | recipe plus Domain-Erweiterungen (siehe TEI-MODEL.md §6.0)
<msIdentifier>/@corresp Pflicht: works.xml#work_N
<persName>/@type Enum: "preferred" | "alternative"
<idno>/@type Kontextspezifisch (siehe §4.2)
POS-Tagset 19 Tags, Werte aus anderen Tagsets wie ART (STTS) oder GRA sind ungültig

Attribute, die im MHDBDB-Modell nicht (mehr) verwendet werden

  • @meaningRef auf <w>  → stattdessen @ana mit Pfad lexicon.xml#lemma_N_sense_M
  • @wordRef auf <w>  → stattdessen @corresp mit Pfad variants.xml#type_M
  • <seg type="pc">  → stattdessen <pc join="left|right">

TEI-P5-Standardelemente, optional erlaubt (seit 2026-05-08)

Diese TEI-P5-Elemente waren bisher nicht im MHDBDB-Schema und wurden mit der ARITHMETIC-Aufnahme als optional zugelassen (Beschluss PD-001, siehe auch §5.4). Sie müssen für kein Korpus genutzt werden:

Kategorie Elemente Verwendung
Editorisch <unclear>, <add>, <gap>, <abbr>, <expan>, <am>, <g> Unsicherheit, Hinzufügung, Lücke, Abbreviatur und ihre Auflösung
Onomastik <roleName>, <occupation>, <placeName>, <persName> (Inline), <person> (Inline) Personen-, Rollen-, Berufs- und Ortsannotation im Body
Domain Arithmetik <unit> (@type: weight/length/volume/distance/measurement), <rs> (@type: currency/goods), <figure> Maßeinheiten, Währungen, Diagramme/Rechen-Layouts

Plus 24 zusätzliche <div>/@type-Werte für Rechenbuch-Strukturklassifikation und 5 zusätzliche <hi>/@rend-Tokens (superscript, subscript, line-through, heading, underline). Vollständige Spec: TEI-MODEL.md §6.0.

GAPs (bewusst gelockert)

Das Schema toleriert elf strukturelle Abweichungen von TEI P5, weil eine Migration der Bestandsdaten unverhältnismäßig wäre. Wenn Ihre Daten dieselben Muster zeigen, müssen sie nicht angepasst werden. Beispiele:

  • <div>/@type kann fehlen (154 Bestandsfiles ohne)
  • <body> und <div> direkt mit Inline-Children (137+ Files)
  • Mehrere <title> in <monogr> (291 Files)
  • <p> mit eingebettetem <div> (7 Files)

Volle Liste in schema/mhdbdb.rnc, gekennzeichnet als # GAP N.

3. Wort- und Punctuation-Annotation

3.1 <w>

<w xml:id="SIGLE_1ra_6_5"
   lemmaRef="lexicon.xml#lemma_879"
   pos="NOM"
   ana="lexicon.xml#lemma_879_sense_1449">
  brôt
</w>

Beim Schreiben Ihrer TEI-Daten setzen Sie nur @xml:id; @lemmaRef, @pos, @ana und @corresp werden über die halbautomatische Pipeline (§6) gefüllt; die Spalte „Setzt" gibt an, in welcher Phase das passiert.

Attribut Setzt Beschreibung
@xml:id Beitragende:r (Pflicht) Eindeutig pro Datei. Konvention: {SIGLE}_{folio}_{line}_{pos} oder {SIGLE}_{seite}_{zeile}
@lemmaRef Pipeline Phase 1 lexicon.xml#lemma_N
@pos Pipeline Phase 2 Einer der 19 MHDBDB-POS-Tags (siehe §3.4)
@ana Pipeline Phase 3 (optional) lexicon.xml#lemma_N_sense_M: semantische Auflösung
@corresp Pipeline Phase 3 (optional) variants.xml#type_M: Wortform-Type
@reason Beitragende:r oder Pipeline (optional) Kommentar zur Auszeichnung (z. B. no-lemma für residuale Lücken)

3.2 <pc>

<pc join="left">,</pc>                  <!-- linkangebunden, nach Wort -->
<pc join="right">•</pc>                 <!-- rechtsangebunden, z.B. Cäsur -->
<pc xml:id="SIGLE_1ra_6_6" join="left">.</pc>  <!-- xml:id ist optional -->

Skribale Marker (ł, ̃, =, einzelne Initial-Buchstaben) gehören als <pc>, nicht als <w>. Wenn der Initial-Buchstabe Teil eines Wortes ist (Pattern aus älteren GAMS-Daten: <seg type="token"><hi rend="initial">A</hi>in</seg>), wird er nach Konversion zu <w><hi rend="initial">A</hi>in</w>: der <w>-Container darf seit 2026-05-08 <hi>-Children enthalten.

3.3 Strukturelle Konventionen

  • Kapitel-<head> als erstes Kind des <div type="chapter">, nicht inline. <milestone unit="chapter"/> markiert die ursprüngliche Position im Textfluss.
  • Dekorative Elemente (<hi rend="initial_historisiert">, <fw type="header">) tragen kein @lemmaRef oder @pos.
  • <hi> erlaubt seit 2026-05-08 wieder Rekursion (kontrollierte Ausnahme für genuine semantische Schachtelung wie durchgestrichene Brüche <hi rend="line-through"><hi rend="superscript">...</hi>...</hi>). Bei rein optischer Schachtelung gilt weiter: flach machen.

3.4 POS-Tagset (19 Tags)

Tag Kategorie MHG-Beispiele
NOMNomenacker, zît, minne
NAMEigennameUolrîch, Wiene, Rhîn; sant vor Namen
ADJAdjektivgrôz, schoene, guot
ADVAdverbschone, vil, sêre
DETDeterminativ (Artikel + Demonstrativ)der, diu, daz, ein, diser
POSPossessiv-Pronomenmîn, dîn, unser, ir (attributiv)
PROPronomenich, ez, wir; Relativ- und Indefinitpronomen
PRPPräpositionûf, zuo, under, durch
NEGNegationniht, nit, nie, ne, en; nie als PRO
NUMNumeralezwô, drî, zweinzegest
CCNJKoordinierende Konjunktionund, oder, aber, ouch, noch
SCNJSubordinierende Konjunktiondaz (clause-opening), ob, swenne, sît
CNJKonjunktion (Fallback)Nur, wenn SCNJ/CCNJ nicht entscheidbar
IPAInterrogativpartikelwie, war
VRBVollverbliuhten, varn, machen; haben/sîn/werden lexikalisch
VEXHilfsverbhaben/sîn/werden in Perfekt/Passiv
VEMModalverbmüezen, suln, kunnen
INJInterjektionahî, owê
DIGRömische ZifferIX, XVII; mediäval auch UIII=VIII

ART ist nicht gültig: Artikel werden als DET getaggt. Disambiguierungs-Regeln zu daz, ein, ûf, kein etc.: siehe SKILL.md des POS-Disambiguators.

4. Authority-Files vorbereiten

Bevor die TEI-Datei aufgenommen wird, müssen drei Authority-Files-Einträge existieren oder ergänzt werden. Die Sigle ist das MHDBDB-Kürzel für den Text (z. B. WZB für Wenzelsbibel): drei bis fünf Großbuchstaben, abgesprochen mit dem Kernteam, eindeutig im gesamten Korpus.

4.1 Pflicht-Einträge

File Was eintragen
works.xml Neuer <bibl xml:id="work_X"> mit Sigle, Titel(n), GND/Wikidata/Handschriftencensus-<idno>, Genre-Pointer (<ptr target="genres.xml#…"/>), Autor-Ref, Edition in <relatedItem>. Erlaubte Kindelemente: title+, idno*, ptr*, author*, relatedItem* — kein <note> auf bibl-Ebene.
persons.xml Neuer <person xml:id="person_X"> mit GND/Wikidata-IDs, oder Verwendung von person_anonym bei anonymer Überlieferung
genres.xml Genre-Klassifikation muss in der MHDBDB-Taxonomie existieren; falls nicht, wird ein neuer Eintrag vorgeschlagen

4.2 <idno>/@type kontextspezifisch

Die erlaubten @type-Werte hängen von der Position im Header ab:

Position Erlaubte @type
msIdentifier/idno sigle | handschriftencensus | GND | wikidata | mwb-sigle
monogr/idno (in biblStruct) callNumber | ISBN
person/idno (in profileDesc/listPerson) GND | wikidata

4.3 Lemma-Anlage in lexicon.xml

Wenn die Pipeline (§6) Wortformen findet, deren Lemma noch nicht in lexicon.xml existiert (~43.750 Einträge Stand 2026-05), werden neue Lemmata mit dem Skript scripts/wzb-add-lemma.py angelegt. Es vergibt automatisch die nächste freie ID (Konvention: max. vorhandene ID + 20) und führt danach den Pre-flight-Check durch:

python scripts/wzb-add-lemma.py \
  --orth weise --pos NOM \
  --concept concept_23112700   # concept_ID aus concepts.xml

Beispiel Wenzelsbibel: vier neue Lemmata (cs tschechische Glossen, herte Herde/Viehzucht, scot Schekel, weise Waise). Die Vergabe kann durch das Kernteam oder in Absprache durch Beitragende erfolgen.

5. Konversion bestehender TEI-Daten

Wenn Sie bereits annotiertes TEI haben, etwa aus einem älteren MHDBDB-Schema, einem GAMS- oder TextGrid-Repositorium oder einer eigenen TEI-Konvention, durchläuft die Aufnahme einen mechanischen Konversions-Schritt vor der Annotations-Pipeline (§6). Dieser Abschnitt fasst die wiederkehrenden Drift-Punkte zusammen, die das Pattern in scripts/ingest/wzb/ und scripts/ingest/ari/ konkret adressiert.

5.1 Konversions-Cheatsheet

Wiederkehrende Drifts, die sich rein mechanisch konvertieren lassen:

Quell-Konvention MHDBDB-Ziel Heuristik
tei:-Präfix + Default-NS doppelt deklariert nur Default-NS http://www.tei-c.org/ns/1.0 Tags in den Default-NS umsetzen, tei: entfernen
<seg type="token"> <w> @xml:id übernehmen, @type fallenlassen
<seg type="pc"> ohne @join <pc join="left|right"> Vorgänger-Heuristik: existiert ein nicht-Whitespace-Vorgänger im selben Parent (ignorierend <lb>/<cb>/<pb>) → "left"; sonst "right"
Minimaler Header (nur <title>) Voller Header gemäß §2 Template-Stub mit Defaults; offene Felder als TBD-Marker (Sigle, Autor, Genre, work_N)
Kein <?xml-model?> Zwei PIs: ../schema/mhdbdb.rng + tei_all.rng festes Pattern, vor dem <TEI>-Root einfügen
<TEI> ohne @xml:id <TEI xml:id="{SIGLE}"> Sigle als ID-Wert

5.2 Pflicht-Attribute, die leicht übersehen werden

  • <change>/@who ist Pflicht neben @when, z. B. who="#mhdbdb-team" oder who="#editor". Ein Versions-Attribut wie @n ist nicht erlaubt.
  • <msIdentifier>/@corresp Pflicht: Verweis auf works.xml#work_N.
  • <pc>/@join Pflicht: bei rein mechanischer Konversion via Heuristik (siehe 5.1).

5.3 RelaxNG-Cascade verstehen

Wenn die Stufe-2-Validierung (siehe §7) fehlschlägt, sind die Fehlermeldungen oft kaskadierend: ein einziges Schema-fremdes Element produziert eine Folge von „extra content"-Meldungen bis hoch in den umschließenden <body>. Beispiel aus dem ARITHMETIC-Dogfood:

L164: Did not expect element unit there      ← echte Ursache
L128: Element p has extra content: lb
L127: Element div has extra content: p
L126: Element div has extra content: div
L106: Element div has extra content: pb
L105: Element body has extra content: div    ← Cascade-Spitze

Praktische Konsequenz: beim Stage-2-Debug zuerst die innerste, konkreteste Meldung adressieren („Did not expect element X"). Die anderen lösen sich oft mit auf, sobald die Wurzel beseitigt ist.

5.4 Domänen-spezifische Inline-Elemente

Genre-Korpora (Predigten, Rezepte, Rechenbücher) bringen oft eigene Inline-Mark-up-Konventionen mit. Bei der ARITHMETIC-Aufnahme (2026-05) wurden zwölf TEI-P5-Standardelemente und 24 zusätzliche <div>/@type-Werte als optional ins Schema aufgenommen (siehe TEI-MODEL.md §6.0). Bei künftigen Genre-Konflikten gibt es drei Wege:

  1. Schema-Erweiterung mit optionaler Markierung (gewählt für ARITHMETIC): TEI-P5-konforme Elemente werden im Schema erlaubt, aber nirgends als Pflicht. Korpora ohne diese Annotation merken nichts davon.
  2. Wegtransformation: Wrapper entfernen (Inhalt bleibt), wenn die Annotation entbehrlich ist oder semantisch via @ana auf das MHDBDB-Begriffssystem verweisen kann.
  3. Hybrid: TEI-konforme Standard-Elemente nutzen (<measure> statt <unit>) und die Domänen-Klassifikation in @ana oder @type tragen.

Die Entscheidung gehört dem MHDBDB-Kernteam zusammen mit dem Beitragenden. Begründung der ARITHMETIC-Wahl (Mittelweg): siehe docs/DECISIONS.MD § PD-001. Folge-Task: Begriffssystem-Anbindung über @ana auf concepts.xml (damit Maßeinheiten und Währungen in der Suche auffindbar werden).

5.5 Worked Example: ARITHMETIC

Sechs frühneuhochdeutsche Rechenbuch-Handschriften (GAMS Graz, Carina, Mai 2026). Konversion implementiert in scripts/ingest/ari/. Stand 2026-05-08: Schema-Erweiterung umgesetzt, alle 6 HS validieren Stage-2-PASS. Konversions-Artefakte committet als Zwischenstand unter ingest/ari/; Umzug nach tei/ erfolgt mit finalen Carina-Metadaten (Sigle, Edition, Genre). Vollständige Befund-Tabelle: ingest/ari/README.md.

6. Annotations-Pipeline

Die Annotation läuft in drei Phasen nach dem gleichen Muster: Auto-Match gegen vorhandene Authority-Daten, Disambiguierungs-TSV für mehrdeutige Fälle, Anwendung der aufgelösten TSV auf das TEI. Die Wenzelsbibel-Pipeline (scripts/ingest/wzb/) implementiert dieses Muster konkret und wird pro neuem Text vom Kernteam an Sigle, Pfade und text-spezifische Eigenheiten angepasst; sie ist nicht plug-and-play.

Ingest-Konvention (seit 2026-05-08): Source-Daten und Pipeline-Artefakte pro Korpus liegen unter ingest/<sigle>/, die Pipeline-Skripte unter scripts/ingest/<sigle>/. tei/ enthält nur produktionsreife Korpus-Files mit finalen Authority-Cross-References.

Phase 1: Lemmatisierung

Auto-Match: Jede <w>-Wortform wird gegen variants.xml (~192.000 Formen) gematcht, nach MHG-Normalisierung (â→a, ê→e, î→i, ô→o, û→u, ä→ae, ö→oe, ü→ue). Eindeutige Treffer setzen @lemmaRef; mehrdeutige Formen wandern in eine Disambiguierungs-TSV.

Disambiguierung: Auflösung der TSV in Frequenz-Tranchen (hochfrequent → einheitlich; mittelfrequent → mit Kontext; Hapax → manuell oder akzeptierte Lücke). In der Praxis: ~85–92 % nach Auto-Match, ~91–95 % nach Disambiguierungs-Tranchen, je nach Sprachstufe und Edition.

Phase 2: Wortart-Tagging

Lemmata mit nur einem POS-Wert in lexicon.xml werden direkt zugeordnet. Mehrdeutige Lemmata (z. B. daz: DET oder SCNJ) gehen in eine Pending-TSV und werden über kontextbasierte Regeln (±4 Nachbarn) oder LLM-Batches aufgelöst. Erwartbar: ~93–96 % Coverage.

Phase 3: Bedeutungs-Auflösung (optional)

Auflösung von @ana auf lexicon.xml#lemma_N_sense_M. Lemmata mit nur einer Bedeutung werden direkt zugeordnet; polyseme Lemmata erfordern KI-gestützte oder manuelle Disambiguierung. Diese Phase ist nicht Pflicht für eine Erst-Aufnahme; sie kann nachgeholt werden.

Strukturelle Bereinigung

  • Kapitel-Header in <fw>: @lemmaRef/@pos entfernen (nicht lexikalisch)
  • <head type="chapter"> als erstes Kind des <div> ablegen, ggf. <milestone unit="chapter"/> für die Originalposition
  • Skribale Marker und einzelne Initialen: <w><pc>

7. Validierung

Zwei-Stufen-Modell: Stufe 1 gegen tei_all.rng (TEI-P5-Konformität), Stufe 2 gegen mhdbdb.rng (MHDBDB-Konventionen). Stufe 2 ist das harte Gate: 0 Fails sind erforderlich. Stufe 1 wird mit einer dokumentierten Baseline von 30 toleranten GAP-Files verglichen (Drift-Wache).

Lokal validieren

# Voraussetzung: schema/tei_all.rng heruntergeladen, lxml installiert
python -c "
from lxml import etree
tei_all = etree.RelaxNG(etree.parse('schema/tei_all.rng'))
mhdbdb  = etree.RelaxNG(etree.parse('schema/mhdbdb.rng'))
doc = etree.parse('tei/SIGLE.tei.xml')
print('Stage 1 (TEI P5):  ', 'PASS' if tei_all.validate(doc) else 'FAIL: toleriert (siehe GAP-Baseline)')
print('Stage 2 (MHDBDB):  ', 'PASS' if mhdbdb.validate(doc) else mhdbdb.error_log)
"

Volles Skript

python scripts/audit/validate-corpus.py --sample SIGLE

CI-Validierung

Der GitHub-Action-Workflow schema-validation.yml läuft auf jedem PR und auf direkten Pushes auf main. Er regeneriert die .rng-Files aus den .rnc-Quellen (Drift-Check), validiert das gesamte Korpus + Authority-Files und schlägt Stage-2-Fails als CI-Errors aus.

8. Worked Example: Wenzelsbibel

Die Wenzelsbibel (Wien, ÖNB Cod. 2759–2764, Sigle WZB) ist die erste vollständige Aufnahme nach diesem Workflow und dient als Referenz für neue Beiträge.

<w>-Tokens
149.148
Sprache
Mittelhochdeutsch mit böhmischen Schreibkonventionen
@lemmaRef Coverage
95,3 %
@pos Coverage
95,3 %
@ana Coverage
95,2 %
Lessons Learned
Böhmische Schreibungen (cz=z, v=u, ou=û), tschechische Interlinearglossen, Initial-Schmuck, Kapitel-Header-Position

9. Referenzen

Schemata und Spezifikationen

Werkzeuge

  • scripts/audit/validate-corpus.py: Voll-Validierung des Korpus + Authority-Files
  • scripts/audit/check-lexicon-senses.py: Pre-flight-Check — prüft, dass alle lexicon.xml-Einträge mindestens ein <sense> haben
  • scripts/wzb-add-lemma.py: Neues Lemma in lexicon.xml anlegen (auto-ID, auto-sense, Pre-flight-Check)
  • scripts/ingest/wzb/: Pipeline-Skripte (Auto-Match, Bulk-Resolve, POS-Apply); pro neuem Text adaptieren
  • SKILL.md: POS-Tagset-Reference + Disambiguierungs-Regeln

Kontakt

Inhaltliche Rückfragen oder Hängestellen im Workflow: mhdbdb@plus.ac.at. Issue-Tracker: GitHub Issues.