In diesem Verzeichnis resources
befinden sich Dateien, die für die
technische Realisierung der Edition nötig sind.
catalog.xml
: ein XML-Katalog zur Umleitung von Dateipfaden und URLs. Wird ausgewertet von oXygen und Maven.ci_settings.xml
: Einstellungen für die CI/CD-Pipeline von gitlabexist-db
: Dateien, die für die Erstellung eines XAR-Pakets für eXist-db/TEI-publisher benötigt werden. In der CI/CD-Pipleline wird per Maven (vgl. pom.xml) ein TEI-Publisher-Datenpaket erzeugt.schema
: Schema zur Validierung der TEI-Dateienxsl
: XSL-Transformationen für die CI/CD-Pipelinexql
: XQuery-Scripts für die CI/CD-PipelineREADME.md
: dieser Text hier
Maven wird verwendet, um
- Tests gegen die TEI-Dokumente zu fahren (continuous quality control)
- Test-Reports auf Gitlab-Pages zu erzeugen
- bei erfolgreich absolvierten Tests ein Expath-Package für die eXist-db/TEI-Publisher zu bauen und in der Gitlab-registry zu speichern
Dieses Package wird dann durch die CI/CD-Pipeline in der eXist-db bzw. TEI-Publisher ausgebracht (deploy).
Die Datei pom.xml
ist die Maven-Datei des
Projekts. Sie sollte im Wurzelverzeichnis des Repository
liegen. Andernfalls verkompliziert sich das Setup erheblich. Das
Projekt wird mit dem Befehl
mvn PHASE
im Wurzelverzeichnis des Repository getestet, gebaut etc. Die
Build-Artefakte liegen anschließend im Verzeichnis target
. Werte von
PHASE
siehe unten. Um Test-Reports in HTML zu erzeugen, ist der
komplexere, zweistufige Befehl (siehe unten) auszuführen.
Die wichtigsten Anpassungen an ein Projekt erfolgen in der Datei
pom.xml
. Die Datei ist kommentiert, so dass eine Anpassung keine
Schwierigkeit bereiten sollte.
Insbeondere sind folgende <properties>
anzupassen:
-
tei.suffix
: Datei-Endung der TEI Dokumente -
schema.basename
: Dateiname des Schemas ohne Datei-Endung -
transformation.stylesheet
: Pfad zum XSL-Stylesheet für die Transformation vor der Paketierung -
transformation.xincludeAware
: ob XInclude's bei der Transformation vor der Paketierung expandiert werden sollen. -
exist.db.permission
: Hier sollten Sie nicht das Passwort für die Produktivumgebung hineinschreiben. Dieses sollte als UmgebungsvariableEXIST_DB_PERMISSIONS
an der Kommandozeile bzw. als CI/CD-Variable gesetzt werden. -
repo.slotname
: the path segment that represents the root folder of the project. The HTML error report will be empty, if this is not set up correctly.
Zu testen sind die syntaktische Wohlgeformtheit, die Konformität gegenüber dem TEI-Schema sowie einige Schematron-Tests.
Für das Feedback der Tests an die Herausgeber der Edition sind zugängliche Test-Reports erforderlich.
Die Herausforderung besteht nicht im Testen, sondern in der
Generierung von Reports. Das maven-xml-plugin
generiert beim
Validieren leider nicht direkt Reports. Dasselbe gilt für das
ph-schematron-maven-plugin
. Die Lösung besteht darin,
- a) für schematron-Tests zunächst svrl-Reports zu erzeugen,
- b) die Maven-Logs, die das
maven-xml-plugin
generiert, zu parsen und - c) beides in einer HTML-Summary gemeinsam darzustellen, die auf Gitlab-Pages ausgebracht wird.
Der Punkt b) ist ein bisschen 'hacky', jedoch ist die Alternative,
nämlich ein Umwandeln aller verwendeter Schema-Sprachen nach
Schematron (per
XSLT
oder per dtdschematron) und die
anschließende Gewinnung von svrl-Reports technisch nicht
ausgereift. Zur Realisation wird zweimal ausgeführt, wobei das erste
Mal in eine Datei geloggt werden muss, die beim zweiten Mal gelesen
wird. Die Reports werden bei der zweiten Ausführung bis zur Phase
compile
generiert. Mit den folgenden Befehlen werden die Reports
erzeugt in target/index.html
erzeugt:
mkdir target
mvn test -l target/mvn.log || mvn compile
In der Phase test
werden noch Tests mit dem maven-xml-plugin
und
dem ph-schematron-maven-plugin
gefahren. Maven wird mit einem
Exit-Code ungleich 0 beendet, wenn ein Test fehlschlägt, so dass das
Package in diesem Fall nicht gebaut und ausgebracht (deploy) wird.
Die Abfolge der Phasen von Maven folgt einem festgelegten Schema. Sie werden folgendermaßen verwendet:
generate-sources
: Touchtarget/mvn.log
, um Vorhandensein dieser Datei sicherzustellen. Plugin:maven-antrun-plugin
; ID:mvn.log
generate-sources
: Erzeugen von Kopien der TEI-Dokumente, bei denen XInclude aufgelöst ist. Außerdem werden Metadaten-Dateien des Expath-Packages mit Secrets aus den Umgebungsvariablen erzeugt. Plugin:xml-maven-plugin
; ID:transform
generate-resources
: Erzeugen von XSLT aus den Schematron-Dateien inresources/schema
. Plugin:ph-schematron-maven-plugin
; ID:sch2xslt
generate-resources
: Erzeugen vontarget/mvnlog.xml
austarget/mvn.log
per XSLT. Plugin:exec-maven-plugin
; ID:mvnlog.xml
compile
: Erzeugen von SVRL-Reports. Plugin:xml-maven-plugin
; ID:svrl-tei_all
undsvrl-witness
compile
: Erzeugen von HTML-Reports aus den SVRL-Reports:xml-maven-plugin
; IDsvrl2html
compile
: Erzeugen des HTML-Überblick-Reportstarget/index.html
aus den SVRL-Reports und austarget/mvnlog.xml
:exec-maven-plugin
; IDerrors.html
test
: Schematron-Test inresources/schema/witness.sch
. Plugin:ph-schematron-maven-plugin
; IDwitness
test
: Syntaktiche Wohlgeformtheit und Schema-Validität gegenresources/schema/tei_all.rng
. Plugin:xml-maven-plugin
; ID:validate
package
: Erzeugen des Expath-Package. Plugin:maven-assembly-plugin
package
: Umbenennen der vom Assembly-Plugin erzeugten zip-Datei in eine xar-Datei. Pluginmaven-antrun-plugin
; ID:copy
Edition (Daten) und App sind getrennt. Aus dem vorliegenden git-Archiv wird eine Daten-Kollektion für die eXist-db bzw. TEI-publisher erzeugt, d.h. ein XAR-Archiv.
mvn package
erzeugt das Paket, das anschließend unter
target/edition-data-template-cx-<VERSION>.xar
zu finden ist. Die Version
kann in der Datei pom.xml
eingestellt werden.
Welche TEI-Dateien in dieser Kollektion enthalten sind und welche
nicht, kann in der Datei
resources/exist-db/assembly.xml
festgelegt
werden.