Word validieren mit Schematron?

Wie kann eine Worddatei validiert werden, sodass daraus erfolgreich projektspezifisches TEI-XML transformierbar ist?

von Dr. Jennifer Bunselmeier

Abstract: Um aus einer Worddatei per XSL-Transformation saubere TEI-XML generieren zu können, müssen die Dateien vorgegebene Formatierungsregeln genau einhalten. Wie kann dies sichergestellt und eine kontextabhängige Qualitätskontrolle durchgeführt werden? Ich teste zwei Möglichkeiten: das Onlinetool Data2Check und ein projektspezifisches Schematron, das auf der Word-XML aufsetzt. Hier ein Zwischenbericht.

Die Frage der Nutzer(un)freundlichkeit von digitalen Tools ist ein Dauerthema in der DH-Community. Die editorische Arbeit in unserem Projekt startete 2012 unmittelbar in den XML-Dateien. Diesen Arbeitsmodus empfanden die EditorInnen jedoch auch nach mehrjähriger Einarbeitungszeit als aufwändig, unkomfortabel und vor allem als extrem störend für den geisteswissenschaftlichen Denk- und Arbeitsfluss. Sie fühlten sich in ihrer editorischen Arbeit mehr behindert als unterstützt.

Als Zugeständnis an die Kodierenden, die sich bei der Arbeit ein etwas wohlgefälligeres Layout wünschen, bei dem der Lesefluss nicht durch XML-Tags im Text gestört wird, hätte sich ein Wechsel zum Oxygen-Autormodus mit einem projektspezifischen Framework (oder angelehnt an Ediarum). Diese Option wurde jedoch seinerzeit aus verschiedenen insbesondere strukturellen Gründen nicht gewählt.

Stattdessen arbeiten die EditorInnen jetzt in Word. Da eine docx-Worddatei im Hintergrund auf XML basiert, kann sie durch eine Transformation, z. B. per XSL oder XQuery (Word2TEI-Transformation), in das gewünschte Zielformat TEI-XML übersetzt werden.1 Dieses TEI-XML wird dann über weitere Skripte in HTML transformiert und in der Onlineedition angezeigt. Auf diese Weise können die EditorInnen in der vertrauten graphischen Wordoberfläche arbeiten und das Ergebnis direkt in der Onlineedition veröffentlicht sehen, ohne selber mit den XML-Dateien arbeiten zu müssen.

Unabdingbare Voraussetzung für eine erfolgreiche Transformation von Word-XML zu TEI-XML sind allerdings klare 1:1 Übersetzungsregeln. Das bedeutet, für jedes Phänomen und jede Formatierung in Word muss festgelegt sein, in welches TEI-Element es übersetzt werden muss. Umgekehrt muss jedes TEI-Element des Projekt-Datenmodells eine eindeutige, identifizierbare Entsprechung in der Worddatei haben. 

Inzwischen hat sich dieser Word2TEI-Workflow im Projekt etabliert, weist allerdings drei große Schwachstellen auf, für die in naher Zukunft eine Lösung gefunden werden muss.


1. Viele Transformationsschritte  – viele Fehlerquellen


Abb. 1   Der Word2TEI-Worfklow im Projekt. Die EditorInnen sehen nur das Eingangsformat Word und das Endergebnis in der Onlineedition, nicht die Schritte dazwischen. Das erschwert die Fehlersuche.

Zwischen dem Ausgangsmaterial (formatierte Worddatei) und dem Endprodukt (HTML-Seite in der Onlineedition) stehen viele komplexe Arbeitsschritte und Skripte, was die Fehlersuche sehr aufwändig macht, falls das Resultat nicht den Erwartungen entspricht.

Ein typisches Beispiel: Die EditorInnen edieren in Word, starten die Transformation und bekommen eine HTML-Seite in der Onlineedition angezeigt. Dort fehlt der erwartete Titel des edierten Textes. Wieso erscheint er nicht in der Ausgabe, obwohl er in der Worddatei steht? Liegt der Fehler in den Anzeigeskripten? In den Transformationsskripten? Oder in der Worddatei?

Die häufigste Ursache: Der Titel wurde in Word versehentlich falsch formatiert, z. B. mit der Formatvorlage „Titel“ und nicht mit der Formatvorlage „Überschrift1“. Die Transformationsskripte übersetzen aber nur Text in der Formatvorlage „Überschrift1“ (nicht „Titel“) in das dafür vorgesehene TEI-Element <title>. Für die Onlineanzeige laufen anschließend weitere XSL-Skripte. Diese übersetzen normalerweise <title> in das HTML-Element <h1>. Da aber <title> im TEI-XML aufgrund der falschen Formatvorlage gar nicht erst kodiert wurde, wird es auch in der HTML-Version nicht als <h1> angezeigt. Im besten Fall wird es in der Onlineanzeige als „normaler“ Text innerhalb von <p> übernommen, im schlechtesten Fall gar nicht visualisiert.

 


Abb. 2       Eine falsche Formatierung in Word führt zu einer fehlerhaften HTML-Anzeige. Für die EditorInnen ist dieser Fehler in Word oft nur schwer zu erkennen, er offenbart sich erst ganz am Ende des Workflows in der fehlerhaften Onlineanzeige.

2. Formale vs. semantische Kodierung

Word kodiert nach Formateigenschaften, nicht semantisch. Das bedeutet, alle Textportionen, die exakt dieselben formalen Eigenschaften aufweisen, werden in einem Element zusammengehalten. Ob diese Textportionen auch semantisch zusammengehören, spielt dabei keine Rolle. Umgekehrt können Textportionen, die semantisch zusammengehören, aufgrund formal unterschiedlicher Eigenschaften getrennt voneinander kodiert werden. Formateigenschaften, die zu einer getrennten Kodierung führen, können z. B. sein:

  • Absatz
  • geschütztes (oder anderweitig wichtiges) Leerzeichen
  • Wechsel der Schriftschnitte/-arten/-größen
  • Wechsel der Sprache
  • einsetzende/endende Unterkringelung von Wort(-teilen) durch die Grammatik- oder Rechtschreibkorrektur

Einige dieser formalen Trennungen sind für die Weiterverarbeitung nützlich (z. B. können semantisch relevante Passagen gut durch unterschiedliche Schriftschnitte voneinander getrennt werden), andere sind irrelevant und müssen im Rahmen der Transformation bereinigt werden (z. B. Texttrennungen nur aufgrund von Rechtschreibfehlermarkierungen).

Um saubere, sinnvolle TEI-XML-Dateien zu generieren, muss die rein formale Kodierung der Word-XML also zunächst um irrelevante Informationen und Inhalte bereinigt und dann anhand der verbleibenden Formalia in eine semantische Kodierung übersetzt werden. Je komplexer die TEI-Zielkodierung ist, desto stärker ist die Transformation auf ein gut organisiertes Zusammenspiel von projektinternen Absatz- und Zeichenformatierungen, Positionierungen und Formulierungen innerhalb von Textstrings angewiesen.

Ein Beispiel: Eine typische kritische Fußnote wie „am Rand hinzugefügt lorem ipsum B“ soll übersetzt werden in eine TEI-Lesartenkodierung:

<app>
	<lem/>
	<rdg wit="#B">
		<add place="margin">lorem ipsum</add>
	</rdg>
</app>

Listing 1 Eine Lesartenkodierung nach TEI, generiert aus einer Word-Fußnote

Bei diesem Transformationsbeispiel werden verschiedene Formatinformationen ausgewertet:

  • Das Format „Fußnote“, beginnend mit kursiviertem Text, weist auf eine Kodierung zur Textkritik hin (anders z. B. Sachanmerkungen, die als Fußnote in recte gesetzt wären). Die gesamte Fußnote wird daher übersetzt in <app><lem/><rdg/></app> (und nicht z. B. in <note type=“footnote“/>).
  • Der kursivierte Textstring selbst entspricht einer von mehreren möglichen standardisierten textkritischen Wendungen. Eine Liste aller Wendungen und ihrer TEI-Entsprechungen ist bei der Transformation hinterlegt. So wird „am Rand hinzugefügt“ übersetzt in <add place=“margin“>, weitere Beispiele wären „im Korrekturverzeichnis hinzugefügt“ in <add type=“corrigenda“> oder „gestrichen“ in <del>.
  • Der Text „lorem ipsum“ in recte beinhaltet den eigentlichen Textinhalt, der innerhalb von <add place=“margin“> stehen soll.
  • Der Textinhalt endet, sobald nach einem Leerzeichen eine weitere kursivierte Passage folgt. Diese wird als Bezeichnung des Textzeugen interpretiert und dem umgebenden <rdg/>-Element als @wit-Attribut beigegeben.
  • Da es sich um eine Hinzufügung in einem anderen als dem Haupttextzeugen handelt, bleibt das <lem/> leer.
Abb. 3   Eine Fußnote kann anhand verschiedener Formatinformationen in eine TEI-Lesartenkodierung übersetzt werden

Dieses Beispiel verdeutlicht die Wichtigkeit exakt eingehaltener Vorgaben. Schon kleine Fehler wie das versehentliche Nicht-kursivieren des Textzeugen oder ein Tippfehler in der standardisierten Wendung können zu falschen Kodierungen führen.

3. Zu viele Freiheiten in Word

Ziel des Word2TEI-Workflows ist es, den EditorInnen zu ermöglichen, die beiden Schritte „freies, kreatives geisteswissenschaftliches Arbeiten“ und „Glätten und Einpassen in ein einheitliches, projektspezifisches Format“ nicht mehr gleichzeitig durchführen zu müssen. Stattdessen sollen sie diese nach eigenen Präferenzen in den Arbeitsablauf einbauen können. Das strukturelle Arbeitsumfeld von Word ist jedoch primär auf die Anforderungen des ersten Schrittes ausgelegt und bietet kaum Unterstützung für den zweiten Schritt.

Das Problem: In Word kann, anders als in XML, kein Schema eingebunden werden, das die Schreibenden direkt warnt, wenn sie etwas formulieren oder formatieren, was nicht den Projektregeln entspricht und in dieser Form entweder gar nicht oder auf eine nicht gewollte Weise transformiert würde.

Erschwerend kommt bei unserer Hybridedition hinzu, dass die Worddateien nicht nur die Grundlage für die XML-Dateien bilden, sondern auch als Basis für die Erstellung einer Printedition durch eine Setzerei verwendet werden. Das bedeutet, die Worddateien müssen gleich zwei formalen Ansprüchen genügen: 1. Die Formatierung muss in einer Art und Weise vorliegen, dass die Dateien problemlos in ein fehlerfreies TEI-XML-basiertes Datenmodell transformiert werden können. 2. Die Dateien aller BearbeiterInnen müssen ein einheitliches Format aufweisen und den Anforderungen an ein Druckmanuskript entsprechen, sodass beim Satz keine arbeitsaufwendige und kostenintensive Nachbearbeitung erfolgen muss.

Die Lösung für alle drei genannten Schwachstellen ist eine möglichst frühzeitige Qualitätskontrolle der Ausgangsdokumente. Ich habe zu diesem Zweck zwei Möglichkeiten getestet.

Möglichkeit A – Das Wordvalidierungstool Data2Check

Abb. 4 Data2Check – ein leicht zu bedienendes, individuell konfigurierbares Onlinetool. [Quelle: https://www.data2check.de/documentation/doku-word.html#regeln]

Vielversprechend ist das Tool Data2Check.

Data2Check ist ein komfortables, leicht bedienbares und individuell konfigurierbares frei zugängliches Onlinetool, mit dessen Hilfe man u. a. prüfen kann, ob Worddateien einer festgelegten Struktur folgen oder eine vorgegebene Terminologie verwenden. Ein Vorteil für EditorInnen: Erkannte Fehler können unmittelbar als Kommentar in der Worddatei zurückgegeben werden.

Das Tool kann Formatvorlagenabfolgen (Absatz und Zeichen) prüfen, z. B.:

  • Nach jeder Formatvorlage „Überschrift1“ muss genau einmal die Formatvorlage „Absatz ohne Einzug“ folgen.
  • Jedes Dokument muss (genau) eine Formatvorlage „Überschrift1“ und (mindestens) eine Formatvorlage „BearbeiterIn“ enthalten.
  • In der Formatvorlage „Zitat“ sind keine Zeichenformatvorlagen (Kursivierung etc.) erlaubt.
  • Bilder und/oder Tabellen sind nie erlaubt usw.

Spezielle Formulierungen sind per String oder Regular Expression (RegEx) suchbar, anzeigbar oder sogar direkt ersetzbar, z. B.:

  • Alle Dokumente sollen die Schreibweise „Onlineedition“ verwenden. Andere (explizit anzugebende) Schreibungen wie „online Edition“, „Online Edition“ oder „Online-Edition“ werden „angewarnt“ oder direkt ersetzt.
  • Datumsangaben müssen einem bestimmten Format entsprechen usw.

Ein absolut empfehlenswertes Tool!

Leider ist es für unsere Zwecke nicht weitreichend genug, denn: String-/RegEx-Abfragen und Formatvorlagen können nicht kombiniert geprüft werden. Genau das führt bei unserer Transformation aber oftmals zu Fehlern, denn die TEI-Elemente werden oft auf Basis von standardisierten Formulierungen innerhalb bestimmter Formatvorlagen generiert. So sind Wörter wie „gestrichen“ in einer Fußnote explizite Marker für eine ganz bestimmte Kodierung und ähnliche, aber falsche Formulierungen wie „durchgestrichen“ sind an dieser Stelle nicht erlaubt – an anderen Stellen im Text sind jedoch natürlich beide Wörter zugelassen, weil sie dort keine (oder eine andere) Funktion haben.

Möglichkeit B – Schematron für Word-XML

Da Word-XML auf XML basiert, ist es möglich, die Datei außerhalb des Wordprogamms zu validieren, noch bevor sie transformiert wird. Dabei soll sichergestellt werden, dass…

  1. alle Konstellationen, Formulierungen und Formatvorlagen, auf die die Transformationsskripte zugreifen, korrekt verwendet wurden,
  2. die EditorInnen so früh wie möglich eine Rückmeldung erhalten, wenn und wo(!) Fehler auftreten, die die Transformation stören oder verhindern.

Um XML-Dateien nicht nur rein syntaktisch, sondern auch kontextabhängig zu prüfen, bietet sich Schematron an. Dazu wird die Worddatei direkt im Oxygen-Editor geöffnet und mit einer Schematron-Schemadatei validiert.

Die ersten Versuche sind sehr vielversprechend.

Beispiel Titelei – Struktur gut prüfbar

Was mit Schematron sofort gut funktioniert, sind strukturelle Abfragen auf Formatvorlagenebene ohne (oder mit nur minimaler) Textbeteiligung.

Das obige Beispiel mit der fälschlich verwendeten Formatvorlage „Titel“ statt „Überschrift1“ lässt sich z. B. gut abbilden. Wenn an bestimmten Stellen im Dokument nur bestimmte Formatvorlagen erlaubt sind, kann für die Word-Kodierung der Formatvorlagen (<w:pStyle w:val=“…“>) in einem Schematron-<assert>-Test einfach eine feste Liste an Attributwerten für @w:val vorgegeben und jede Abweichung angewarnt werden.

Ein anderes Beispiel: alle unsere Worddateien müssen mit vier Absätzen in einer bestimmten Formatvorlage und mit standardisierten Angaben beginnen (Titel, BearbeiterIn, Datum und projektinterne Textnummer). Aus diesen werden wichtige Angaben für den <teiHeader> generiert. Danach folgt eine Leerzeile ohne Formatvorlage. Die ersten vier Absätze sind aufgrund der festgelegten Reihenfolge und des standardisierten Inhalts (u. a. ein festes Zahlenformat) gut prüfbar. Für die Leerzeile greift ein einfacher <report>-Test der sicherstellt, dass der fünfte Absatz im Dokument keinerlei Formatvorlagen-Styleinformationen und keinen Text enthält. Fehlt diese Leerzeile, scheitert die Transformation komplett, da die unmittelbar nachfolgende Struktur darüber entscheidet, welche Transformationsskripte angewendet werden und welche nicht, weshalb diese Prüfung besonders wichtig ist.

Beispiel Spracheinstellung und Sonderzeichen – Transformationsskripte entlasten

Da die Wordprogramme der EditorInnen in sehr unterschiedlichen Sprachen eingestellt sind, weisen die Dateien mitunter unterschiedlich benannte Word-Formatvorlagen auf (Überschrift1, Heading1, Titolo1,…) oder verschiedene per Autokorrektur ersetzte Anführungszeichen (typographische, französische,…). Diese Details sind für die EditorInnen nur schwer zu bemerken, führen jedoch zu großen Transformationsproblemen.

Aktuell müssen die Transformationsskripte deshalb per <choice>-Test vieles abfangen, was bei einer einheitlichen Formatierung in Word nicht nötig wäre.

Wird diese Art der Qualitätskontrolle aus den XSL-Transformationsskripten ins Schematron verlagert, ist das nicht nur methodisch sauberer, sondern entlastet zusätzlich die XSL-Skripte, macht sie weniger fehleranfällig und steigert dafür deren Performanz. Darüber hinaus sind Kleinigkeiten wie eine einheitliche Verwendung der Anführungszeichen für ein sauberes Druckmanuskript ebenfalls wichtig.

Beispiel Stringabfragen – Schematron um individuelle Funktionen erweiterbar

Die oben erwähnte Zerstückelung des Textes aufgrund formaler Kriterien führt dazu, dass String- oder RegEx-Abfragen beim Prüfen der Word-XML nicht ohne Weiteres funktionieren.

Glücklicherweise sah sich der Kollege, der seinerzeit die XSL-Skripte für die Word2TEI-Transformation geschrieben hat, mit demselben Problem konfrontiert. Seine Lösung: er hat XSL-Funktionen geschrieben, mit denen sich das Word-XML leichter parsen lässt.2 Darunter auch eine Funktion, die die Textblöcke wieder zusammensetzt, sodass Stringabfragen möglich sind. Auf diese Funktionen kann auch Schematron aufbauen, sodass eine Kombination von Formatvorlage und String abfragbar ist.


<xsl:function name="wt:string" as="xs:string">
	<xsl:param name="context" as="item()*"/>
	<xsl:value-of select="string-join($context//w:t, '')"/>
</xsl:function>
<pattern id="standardisierte_Wendungen">
	<rule context="w:footnote/w:p[w:r/w:t]">
		<let name="string" value="wt:string(.)"/>
		<report test="not(starts-with($string,'am Rand hinzugefügt') or starts-with($string,'gestrichen'))" role="warning">Bitte standardisierte Formulierung in der krit. Anm. prüfen.</report>
	</rule>
</pattern>

Listing 2 Eine XSL-Funktion wt:string() setzt die Word-Textblöcke aus w:t per string-join() zusammen. Die Funktion kann in einer Variablen oder direkt im <report>-Test aufgerufen werden.

Ein bislang ungelöster Schönheitsfehler ist die Genauigkeit in der Fehlermarkierung. Da derartige Abfragen den gesamten Inhalt von w:p (also einem Absatz) als String ansetzen und nur ein boolesches „String-enthält“ / „String-enthält-nicht“ zurückgeben, wird bei einer Fehlermeldung folglich der gesamte Absatz als fehlerhaft markiert, nicht eine konkrete Tippfehler-Stelle. Insbesondere bei längeren Abschnitten wäre eine präzisere Lokalisierung wünschenswert.

Ein Problem bleibt – zurück zum Oxygen

Für die EditorInnen dürfte der Anblick von Word-XML eine noch abschreckendere Wirkung haben als die Code-Ansicht von TEI-XML. Wie sollen Schematronwarnungen in Word-XML dabei helfen, in Word das eine Spatium zu finden, das versehentlich in der falschen Formatvorlage formatiert ist?

Lösung: Doch der Autormodus

Die erste und einfachste Möglichkeit ist die Anzeige der Word-XML in einem sehr einfachen Autormodus ohne komplizierte CSS-Stilanweisungen, in dem die fehlerhafte Stelle vom Schema möglichst präzise markiert wird. Die EditorInnen können die markierte Textstelle dann in ihrer Worddatei suchen und dort die Formatierung überprüfen. Diese Option nutzen wir aktuell und sie wird als durchaus zumutbar empfunden. Da kein projektspezifisches Framework verwendet wird, werden jedoch Auszeichnungen wie Kursivierung nicht wiedergegeben.

Abb. 5 Die Anzeige von Word-Fußnoten im Oxygen-Autormodus. Das Schematron warnt die falsche Formulierung „durchgestrichen“ an (richtig wäre „gestrichen“).

Vision: Schematronfehlermeldungen in Word zurückspielen

Eine elegante Lösung wäre ein Zurückspielen der Schematronfehlermeldungen in die Worddatei in Form eines Kommentars, wie es bei Data2Check möglich ist. Einen solchen Weg hat Colin Mackenzie auf der XML Prag (Februar 2020) vorgestellt3: Mithilfe einer XProc Pipeline4 können alle notwendigen Schritte automatisch nacheinander ablaufen: „Word.zip entpacken à Word-XML validieren à Schematronfehlermeldungen über XSL in Worddatei einfügen“. Ob sich diese Vorgehensweise auch für unser Projekt als effizient und praktikabel erweist, muss noch getestet werden.

Zwischenfazit zu Wordvalidierungstools

  Pro Contra
Data2Check
  • sehr einfach zu konfigurieren
  • grobe Struktur gut prüfbar
  • globale String- und RegEx-Abfragen möglich
  • Fehlermeldung direkt in Word möglich
  • Kombination von Stringabfrage und Formatvorlage nicht möglich
  • Regeln für komplexe Schachtelungen von Formatvorlagen nur bedingt möglich
Schematron
  • deutlich komplexere Abfragen und Konfigurationen möglich als bei Data2Check
  • erweiterbar um QuickFixes (Tauglichkeit noch zu prüfen)
  • Typisierung der Fehler in Error und Warnung möglich
  • alle Regeln in den Transformationsskripten können einzeln schon vorab geprüft werden, da mit XPath und den Funktionen dieselbe Sprache verwendet wird
  • Qualitätskontrolle (i.S.v. typische Fehler abfangen) muss nicht mehr in den XSL-Skripten während der W2T-Transformation stattfinden
  • Stringabfragen nur durch Erweiterung um eigene Funktionen möglich (dann aber Kombination von Stringabfrage und Formatvorlage möglich)
  • Fehlermeldung (erstmal) nur im Word-XML (=Oxygen-Autormodus) möglich
  • Word-XML (erstmal) nicht im Ganzen validierbar (da Text, Fußnoten, Endnoten und Kommentare jew. als einzelne XML gespeichert werden)

 

  1. Die Transformation muss nicht zwangsläufig selbst geschrieben werden, der TEI-Onlineservice OxGarage bietet automatische Transformationen für eine Vielzahl an Ausgangs- und Zielformaten an, darunter Word zu XML, TEI-XML oder Verbatim-XML. Die individuellen Projektanforderungen, insbesondere hinsichtlich der Transformation der Apparate, erforderten jedoch komplexere Eingriffe, als dies mit OxGarage möglich ist, daher wurde dieser Service nicht gewählt. []
  2. Zur Dokumentation siehe Dario Kampkaspars GitHub-Repository; Zusammenstellung aller Funktionen hier. []
  3. Mackenzie, Colin: Use cases and examination of XMLtechnologies to process MS Worddocuments in a corporate environmentToolset to test and improve the quality and consistency of styling in MS Word. (Vortragsmaterialien hier) []
  4. XProc ist eine XML-Sprache, die die Stapelverarbeitung beliebig vieler Eingangsdokumente (z.B. XML-Dateien) durch beliebig viele automatisch nacheinander ablaufende Verarbeitungsschritte (z.B. XSL-Transformationen oder Schematron-Validierungen) ermöglicht. []

Docker für die Digital Humanities

von Stephan Makowski

Manchmal möchte ich schnell mal etwas testen. Da ich regelmäßig mit Softwarelösungen arbeite, die hauptsächlich unter Linux laufen, setze ich mir für Testzwecke eine virtuelle Maschine auf. Das geht, ist aber recht ressourcenhungrig. Egal, ob unter Hyper-V oder Virtual Box. Möchte ich mehr als zwei Maschinen gleichzeitig laufen lassen, hat mein Rechner irgendwann eben keinen Speicher mehr. Also muss ich mir etwas anderes einfallen lassen.

Die beste Lösung hierfür ist ohne Zweifel ein Docker-Setup. Bei Docker handelt es sich um eine Containerlösung. Vereinfacht gesagt bedeutet das, dass auf dem Host ein Dockerservice installiert wird. Nach der Installation können beliebig viele (je nachdem, was der Rechner/Server so hergibt) Web-/Mailserver, Datenbanken, WordPressinstanzen, etc. gestartet und gemanaged werden. Eine Übersicht über die möglichen Container, die unter Docker laufen, ist auf Docker Hubs zu finden.

Das Schöne daran ist: Die meiste Software, z. B. Apache, MySQL oder Neo4J, ist direkt ohne weitere Programmierkenntnisse einsetzbar. Die Container werden runtergeladen, individuell konfiguriert und in der Dockerumgebung gestartet. Klingt einfach? Ist es auch. Wer mir nicht glaubt, kann das hier direkt mal nachlesen.

Docker compose – dein Freund und Helfer

Inwiefern ist das also auch für die Digital Humanities interessant? In etlichen Bereichen werden NoSQL Datenbanken wie eXist-db oder BaseX eingesetzt. Auch diese Datenbanken sind bereits als vorbereitete Dockerimages zu haben. 

Möchte man solch eine Konfiguration öfter mal testen, tut man gut daran, eine sogenannte docker-compose-Datei zu schreiben. Hierbei handelt es sich um eine Art Beschreibung, welches Image Docker laden soll und wie dieses zu konfigurieren und zu starten ist. 

Im Juni 2021 wurde eine neue NoSQL-Datenbank mit dem Namen FusionDB veröffentlicht. Zu Testzwecken habe ich hierfür eine docker-compose-Datei erstellt, die ich im Folgenden präsentieren möchte:

version "3"
services:
  fusiondb:
    image: fusiondb
    build:
      context: ./conf
      dockerfile: ./Dockerfile
      args:
        PASSWORD: ${PASSWORD}
        INIT_MEMORY: ${INIT_MEMORY:-256}
        MAX_MEMORY: ${MAX_MEMORY:-2048}
        CACHE_SIZE: ${CACHE_SIZE:-256}
        COLLECTION_CACHE: ${COLLECTION_CACHE:-256}
        LUCENE_BUFFER: ${LUCENE_BUFFER:-256}
        HTTP_PORT: ${HTTP_PORT:-4059}
        HTTPS_PORT: ${HTTPS_PORT:-5059}
        SERVER_NAME: ${SERVER_NAME:-localhost}
    volumes:
      - data:/opt/fusiondb/fusiondb-server-1.0.0-ALPHA1/data
    ports:
      - 4059:4059
      - 5059:5059  
    container_name: fusiondb
    restart: always
    networks:
      - www
    labels:
      - "traefik.backend=fusiondb-backend"
      - "traefik.docker.network=www"
      - "traefik.frontend.rule=Host:fusiondb.stephan-makowski.de"

volumes:
  data: {}

networks:
  www:
    external:
      name: ${TRAEFIK_NETWORK:-www}

docker-compose.yml

In dieser Datei soll ein Dienst mit dem Namen fusiondb erstellt werden. Hierfür gibt es (noch) kein fertiges Image, sodass dieses vorab erstellt werden muss. Die Anweisungen, welche und wie eine Erstellung vorgenommen werden soll, befinden sich in der Datei „Dockerfile“ (s. unten). 

Ein wichtiger Vorteil von Docker ist die EInrichtung sogenannter Volumes. Hierbei handelt es sich um (permanente) Verzeichnisse, die zur Laufzeit innerhalb des Containers gemounted werden. Es sind sozusagen Ordner, die an einer bestimmten Stelle eingehangen werden. An dieser Stelle soll das Volume data an das Verzeichnis /opt/fusiondb/fusiondb-server-1.0.0-ALPHA1/data angehangen werden. Wozu? Die Volumes können vom Host gesichert werden. Außerdem wird so sichergestellt, dass die Daten persistent vorgehalten werden. Ohne solch ein Volume würde bei jedem Start der Ursprungszustand des Images wiederhergestellt werden. Das ist bei Datenbanken etwas unpraktisch.

Die meisten Dienste im Internet sind über Portangaben zu erreichen. Für die Internetseiten ist es meist der Port 80, der als Standard für alle eingehenden Http-Anfragen genutzt wird. Der Service fusiondb soll allerdings auf eingehende Anfragen auf den Port 4059 (http) sowie 5059 (https) lauschen. Die Angaben können hier ganz leicht gesetzt werden. Oft kommt es aber vor, dass zwei unterschiedliche Dienste denselben Port nutzen. In diesem Fall kann in der Datei eine Zuweisung vorgenommen werden, welcher Port alternativ abgehört werden soll. Die Notation hierfür ist:

-ports:
     – externer Port: interner Port


Damit wird eine Art Weiterleitung eingerichtet, die für jeden Dockercontainer genutzt werden kann.

Die folgenden Definitionen geben an, wie der Service heißt, welches interne Routingnetzwerk genutzt werden soll und ob ergänzende Informationen benötigt werden. In meinem Fall habe ich noch Angaben für den Routerservice Traefik gemacht. Abschließend folgen die Definitionen der Netzwerke sowie der Volumes. An dieser Stelle sei auf die gute Dokumentation von Docker verwiesen.

Wenn man kein Image hat, baut man sich halt eines

Wie bereits erwähnt, gibt es derzeit für fusiondb noch kein Dockerimage. Da ich dieses aber gern testen wollte und für zukünftige Updates bereits vorbereitet sein möchte, erstelle ich mir das Image selbst. 

Im Grunde folgt die Datei dem Aufbau:

    • Welche Basis soll benutzt werden?
    • Was soll innerhalb der Basis gemacht werden?
    • Wie ist das Image ansprechbar und wie soll Docker die Inhalte ansprechen?
ARG BASE_CONTAINER=ubuntu:latest
FROM $BASE_CONTAINER

LABEL maintainer="Stephan Makowski <stephan.makowski@rub.de>"

USER root

ENV JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"

ARG PASSWORD
ARG INIT_MEMORY=256
ARG MAX_MEMORY=2048
ARG CACHE_SIZE=256
ARG COLLECTION_CACHE=256
ARG LUCENE_BUFFER=256
ARG HTTP_PORT=8080
ARG HTTPS_PORT=8443
ARG SERVER_NAME='localhost'

RUN apt-get update && apt-get -yq dist-upgrade &&\
  apt-get install -yq --no-install-recommends \
  sudo \
  curl \
  htop \
  default-jdk \
  unzip \
  vim \
  wget &&\
  rm -rf /var/lib/apt/lists/*

WORKDIR /opt/fusiondb

RUN wget http://www.fusiondb.com/download/fusiondb-server-1.0.0-ALPHA1-unix.tar.bz2

RUN tar xjf ./fusiondb-server-1.0.0-ALPHA1-unix.tar.bz2

WORKDIR /opt/fusiondb/fusiondb-server-1.0.0-ALPHA1

VOLUME /opt/fusiondb/fusiondb-server-1.0.0-ALPHA1/data

RUN echo '#!/bin/bash' >> /usr/local/bin/docker-entrypoint.sh &&\
  echo 'set -e' >> /usr/local/bin/docker-entrypoint.sh &&\
  echo 'cd /opt/fusiondb/fusiondb-server-1.0.0-ALPHA1' >> /usr/local/bin/docker-entrypoint.sh &&\
  echo 'sudo bin/startup.sh' >> /usr/local/bin/docker-entrypoint.sh &&\
  chmod +x /usr/local/bin/docker-entrypoint.sh

EXPOSE ${HTTP_PORT} ${HTTPS_PORT}

HEALTHCHECK --interval=1m --timeout=3s \
  CMD curl -f http://localhost:4059/ || exit 1

ENTRYPOINT ["docker-entrypoint.sh"]

Dockerfile

Kurz zusammengefasst soll das Image für die Datenbank das letzte verfügbare Ubuntu als Ursprungsbetriebssystem nutzen. Anschließend erfolgt eine Aktualisierung und die Installation benötigter Komponenten wie z. B. Java. Im nächsten Arbeitsschritt lädt Docker dann die Datenbank herunter, entpackt diese und kopiert das Startskript, damit dieses von Docker ausgeführt werden kann. 

Mir war bewusst, dass es sicherlich nicht die eleganteste Lösung ist, und wollte noch weitere Verarbeitungsschritte einarbeiten. Deshalb sind noch einige etwas kryptische Argumente enthalten. Und: Es funktioniert. Das erlaubt mir schon mal vorab, fleißig zu testen. Sollte in naher Zukunft eine aktualisierte Version der fusiondb herauskommen, bin ich vorbereitet. 

Die Skripts können vollständig aus meinem Gitlab heruntergeladen werden.

Routing mit Traefik

Egal, ob Datenbank, Webpages oder andere Tools: selten werden die Dienste über nur einen Domainnamen angesprochen. So macht es Sinn, explizite Namen bzw. Subdomains für die unterschiedlichen Dienste zu verwenden. Während eine x-beliebige API unter api.meine-domain.de erreichbar ist, kann das obere Beispiel unter fusion.meine-domain.de laufen. Diese sinnstiftende syntaktische Unterscheidung vereinfacht die Nutzung wesentlich. Eine Möglichkeit, dies zu erreichen, ist die Verwendung des Dienstes traefik. Hierbei handelt es sich um einen Routingdienst, der sowohl per Docker als auch nativ auf dem Server betrieben werden kann. Die Nutzung ist denkbar einfach. Die jeweiligen Subdomains (www, api, db, etc.) werden im Domain Name Server (DNS) der Domain angelegt und verweisen dort zentral auf den Server (per IP). Wie ein jeweiliger Dienst angesprochen werden kann, muss separat in der docker-compose Datei hinterlegt werden.

labels:

– „traefik.backend=fusiondb-backend“

– „traefik.docker.network=www“

– „traefik.frontend.rule=Host:fusiondb.stephan-makowski.de“

Der Dienst wäre in diesem Beispiel nun unter fusiondb.stephan-makowski.de zu erreichen. Die Notation unterscheidet sich aber je nach verwendeter Traefik-Version. Mit dem Upgrade auf Traefik V2.0 ist die Auszeichnung zwar etwas umfangreicher geworden, erlaubt im Gegenzug aber eine vielfältigere Konfiguration. Eine Übersicht über sämtliche Funktionalitäten kann hier schwerlich geleistet werden. Vielmehr dient diese Übersicht lediglich als erster Eindruck.

labels:

    – traefik.enable=true

    – traefik.http.routers.hp.entrypoints=http

    – traefik.http.routers.hp.rule=Host(`fusiondb.stephan-makowski.de`)

    – traefik.http.middlewares.hp-https

   -redirect.redirectscheme.scheme=https

   – traefik.http.routers.hp.middlewares=hp-https-redirect

   – traefik.http.routers.hp-secure.entrypoints=https

   – traefik.http.routers.hp-secure.rule=Host(`fusiondb.stephan-makowski.de`)

   – traefik.http.routers.hp-secure.tls=true

   – traefik.http.routers.hp-secure.tls.certresolver=http

 

Die Notation ist teilweise variabel. So ist die grundlegende Syntax:

   – traefik.http.[middlewares/routers].[Abkürzung des Dienstes].etc

 

Es muss beachtet werden, dass jeder Dienst sein eigenes Namenschema enthält. Ansonsten kann eine Auflösung des Dienstes nicht erfolgen.

Beispiel:

   – traefik.http.routers.hp.rule=Host(`www.stephan-makowski.de`)

   – traefik.http.routers.api.rule=Host(`api.stephan-makowski.de`)

   -traefik.http.routers.fusion.rule=Host(`fusiondb.stephan-makowski.de`)

Ausblick

Ob eine kleine NoSQL-Datenbank zum Testen, eine WordPressinstanz als Projektseite oder ein Cluster, der über mehrere Server Ausfallsicherheit bietet: All das kann Docker und noch mehr. Und das Wichtigste: Das System ist kostenfrei erhältlich und nutzbar. Die Zeiten, in denen in langwierigen Verfahren an Rechenzentren Server beantragt werden mussten, sind vorbei. Denn Docker ist ein wunderbares Werkzeug und erleichtert einem massiv die Arbeit. Außerdem ersparen Dienste wie Traefik eine tiefgründige Beschäftigung mit Apache oder Nginx und macht Docker sowohl für IT-Expert*innen als auch für Laien interessant.

Für einen Austausch zu dem Thema stehe ich gern zur Verfügung.

Weiterführende Links

Überarbeitete Fassung des Blogbeitrags vom 17. Juni 2019 auf https://blog.stephan-makowski.de

Webinar „eXist-db und XQuery“

Am kommenden Mittwoch und Donnerstag findet per Zoom eine interne Fortbildung zu dem Thema „eXist-db und XQuery“ statt. Der Schwerpunkt am Mittwoch wird vor allem im Bereich der nativen XML-Datenbanken liegen. Primär soll erläutert werden, was Datenbanken sind und welchen Mehrwert diese bieten. Hierzu werden verschiedene einschlägige Datenbanken vorgestellt und deren Vor-/Nachteile erläutert. Der Fokus wird aber bei der eXist-db liegen. Im zweiten Teil des Mittwochs erfolgt dann eine kurze Einführung in XQuery sowie XPath.
Der Donnerstag wird dann vollumfänglich dazu genutzt die explizite Verwendung von XQuery anhand eines Beispiels exemplarisch durchzugehen. Hierzu wurde eine authentische Test-App erstellt, um praktisch die Verwendung von XQuery zu üben und nachvollziehen zu können. Der Nachmittag soll der Umsetzung und Beantwortung von speziellen Wünschen der Teilnehmer dienen.

Mittwoch

9:00 – 10:30h Einführung in native XML-Datenbanken
10:30 – 11:00h Pause
11:00 – 12:30h Einführung in XQuery & XPath

Donnerstag

9:00 – 10:30h Exemplarisches Beispiel für die Verwendung von XQuery
10:30 – 11:00h Pause
11:00 – Open End Benutzerspezifische Fragen (Facettierung, Github-Workflow, etc)


Vortragende: Lena Stahn, Stephan Makowski

Kontakt: Stephan.Makowski@uni-wuppertal.de

Das DH-Blog @ BUW

Das Blog „DHBUW“ hat zum Ziel, die Entwicklung und Tätigkeiten des seit Mai 2019 am historischen Seminar der Bergischen Universität Wuppertal [BUW] neu etablierten Lehrstuhls für „Digital Humanities“ zu präsentieren und zu diskutieren. Die Professur ist am Fachbereich Geschichte angesiedelt und setzt Schwerpunkte in den Bereichen Quellenerschließung, Digitale Editionen, Informationsvisualisierung und Digital History. Sie wird unterstützt durch uns, ein engagiertes, breit aufgestelltes und vielseitig interessiertes Lehrstuhlteam, das es sich zur Aufgabe gemacht hat, die DH nicht nur an der BUW, sondern einem breiten Publikum bekannt und schmackhaft zu machen.

Wir beschäftigen uns mit Daten, Datenmodellen, Formaten und Standards in den digitalen Geisteswissenschaften. Auch die Theoriebildung ist ein zentraler Aspekt. Daneben wird die Lehre ein zentrales Thema sein. Durch „Werbung“ für unsere Veranstaltungen in Form von uns selbst verfassten Berichten hoffen wir, Interesse wecken und Hemmungen bei der Beschäftigung mit „digitalen“ Themen beseitigen zu können. Gleichzeitig wollen wir die Studierenden ermutigen, von ihren selbst erarbeiteten Projekten und Ergebnissen, die im Rahmen von Seminaren und praktischen Übungen entstehen, zu berichten. Als Teil des Lehrstuhl-Betriebs sollen sie ein fester Bestandteil des Lehrstuhl-Blogs sein. Mit diesem Konzept möchten wir eine partizipative und interaktive Komponente in unseren Blog integrieren. Darüber hinaus berichten wir von Workshops und Schools, die sich thematisch mit diversen X-Technologien befassen und an deren Ausrichtung die BUW als Institution beteiligt ist. Weitere wichtige Inhalte werden unsere eigenen Forschungsprojekte sein. Dadurch soll das Profil der DH am Standort Wuppertal zum Vorschein kommen.