Allgemeine Beschreibung
Allgemeine Beschreibung
ediarum ist eine seit 2012 entwickelte digitale Arbeits- und Publikationsumgebung, die aus mehreren Softwarekomponenten besteht und im Grunde ein Werkzeugkasten aus verschiedenen auf TEI-Standard basierenden Modulen ist. Damit bietet ediarum eine Schnittstelle zwischen Editionsumgebung, XML-Datenbank und Rechercheportal, wobei die Kernfähigkeit jedenfalls in der Aufbereitung von XML-Dateien besteht. Die digitale Arbeitsumgebung basiert auf einer eXist-db und ermöglicht nicht nur die Transkription von Manuskripten und Drucken, sondern vor allem auch die TEI-konforme Annotation und Erstellung von Text- und Sachapparaten sowie Registern.
ediarum ist als ein Add-On für Oxygen konzipiert und seit 2015 gibt es eine generalisierte Eingabeoberfläche. Zu beachten ist, dass ediarum keine Plug-and-Play-Software ist, da immer ein:e DH-Entwickler:in für die Implementierung und den Betrieb von ediarum nötig ist. In laufenden Projekten werden nicht immer alle Module, sondern mitunter auch nur Frameworks eingesetzt.
Hinweis: Die nachfolgenden Ausführungen beschränken sich auf die Module ediarum.DB, ediarum.BASE.edit und ediarum.REGISTER.edit.
Anwendungsbereiche
- Transkription von Manuskripten und Drucken
- Text-Mark-up
- TEI-konforme Annotation
- Indexierung
- Erstellung von Text- und Sachapparaten sowie Registern
- Publikation in Web und Druck
Funktionsübersicht
- Kollaborationsmöglichkeit
- Möglichkeiten der Qualitätssicherung
- Module innerhalb unterschiedlicher Umgebungen (hier nur auszugsweise):
- eXist-db:
- ediarum.DB zur Konfiguration einer eXist-Datenbank - die Daten, die von beliebigen Webtechnologien genutzt werden können, werden dabei über eine JSON-API geliefert
- ediarum.WEB als Library, die entsprechende Funktionalitäten für die Erstellung einer WebApp für ein Rechercheportal bereitstellt
- Oxygen XML-Editor:
- ediarum.BASE.edit beinhaltet nützliche Funktionen für die Bearbeitung von XML-Dateien wie zum Beispiel Stylesheets für den Autor-Modus, die eine benutzerfreundlichere Transkription (von Formatierungen wie Unterstreichungen, Hervorhebungen, Streichungen, Leserlichkeit etc. oder Markierung fremdsprachlicher Einträge) mit Schaltflächen im Oxygen-Editor ermöglichen
- ediarum.REGISTER.edit beinhaltet nützliche Funktionen für die erleichterte Auszeichnung von Personen, Orten etc.
- ediarum.PDF für das Herunterladen und Ausdrucken von TEI-XML-kodierten Texteditionen (in Entwicklung)
- ediarum.MEDIAEVUM für die Edition mittelalterlicher (Prosa-)Texte
- eXist-db:
- Diverse Ansichtsmöglichkeiten: Web-Ansicht und PDF-Vorschau
- Nutzung des DTA-Basisformats als Schema (ODD/RNG)
Voraussetzungen
Jedes Tool kann einerseits bestimmte Vorkenntnisse der Benutzer:innen voraussetzen und andererseits auch hinsichtlich der Software-Umgebung gewisse Anforderungen stellen.
Erforderliche Kenntnisse
- EDV-Grundkenntnisse
- TEI-XML
- XPath/XQuery
- HTML/CSS von Vorteil
- Grundverständnis von GitHub
Benötigte Software
- Oxygen XML Author (kommerziell)
- eXist-db (optional - nur bei kollaborativem Arbeiten und für Registerverknüpfungen; Workarounds sind grundsätzlich möglich)
- Docker Desktop (für eine weniger fehleranfällige Installation von eXist-db)
Tool-Kompatibilität
| IIIF | Transkribus | FromThePage | FairCopy | OpenRefine | ba[sic?] | TEI Publisher | ediarum.WEB | |
| ediarum | ❌ | ❌ | 🦄 | ❌ | 🦄 | ❌ | 🦄 | ✅ |
✅ Integrationen vorhanden und Entwickler:innen bewerben Übergänge
❌ Kein Entwicklung einer Transition im DigEdTnT-Projekt, keine Entwicklerintegration beschrieben
🦄 Transition im DigEdTnT-Projekt erstellt
</div>
## Kostenübersicht
* **ediarum & eXist-db:**
* kostenlos
* **Oxygen XML Author:**
* Halbjahres-Abo: $190 - 244
* Jahres-Abo: $335 - 432
[Detaillierte Preisübersicht (Oxygen)](https://www.oxygenxml.com/xml_author/buy_oxygen_xml_author.html#_new_ath)
# Möglichkeiten & Grenzen
Da jedes Projekt unterschiedliche Anforderungen mit sich bringt, sollen nachfolgend mögliche Vor- und Nachteile des Tools aufgelistet werden, die während der Durchführung des jeweiligen [Beispielprojekts](https://digedtnt.github.io/about/#rezeptsammlung-pipeline-1) festgestellt wurden.
## Stärken
* Nutzung von Oxygen als komfortable und stabile Arbeitsumgebung mit ergiebiger Dokumentation
* Projektmitarbeitende können die Edition in einer benutzerfreundlichen "Autoransicht" bearbeiten und über eine eigene Werkzeugleiste per Mausklick Auszeichnungen vornehmen
* Anpassungsmöglichkeit der Bearbeitungsansicht für den jeweiligen Arbeitsschritt
* Validierung von Dokumenten gegen das eingebundene Schema sowie Ausgabe von entsprechenden Fehlermeldungen direkt während Bearbeitung
* Ständige Weiterentwicklung durch [BBAW](https://www.bbaw.de/)
* Einfache Nachnutzbarkeit von Funktionalitäten und Designs
* Möglichkeit Daten-Backups einzustellen (dabei sind jedoch Speicherkapazitäten zu beachten)
* [Zotero](https://www.zotero.org/)-Integration möglich
## Herausforderungen & Probleme
* Implementierung und projektspezifische Konfiguration erfordert DH-Entwickler:in
* Abhängigkeit von eXist-db und Oxygen
* Datenbank-Technologie ist bei größeren Datenmengen noch suboptimal, da eXist-db viel Arbeitsspeicher benötigt - für eine stabile Funktion der Datenbank sollten zumindest 2 GB Arbeitsspeicher zur Verfügung stehen
* Metadaten-Anreicherung bzw. -Ergänzung nur teilweise im benutzerfreundlicheren Autormodus möglich
* Suche im Register während der Annotation bietet keine Suche nach alternativen Bezeichnungen eines Eintrags
# Einrichtung & Erste Schritte
Anhand eines [Beispielprojekts](https://digedtnt.github.io/about/#rezeptsammlung-pipeline-1), das zum Ziel hat, Kochrezepte aus dem Mittelalter computergestützt zu analysieren und später über eine Forschungsplattform zur Verfügung zu stellen, soll nachfolgend ein möglicher Arbeitsablauf für die Annotation mit _ediarum_ beschrieben werden. Die dafür verwendeten Daten wurden bereits mit dem Tool [FromThePage](https://digedtnt.github.io/fromthepage/) transkribiert und daraufhin für die weitere Bearbeitung vorbereitet (siehe [Transition](https://digedtnt.github.io/transition-fromthepage-ediarum/)). In dieser Kurzanleitung soll nun mit _ediarum_ die weitere Annotation und Indexierung der Kochrezepte des Beispielprojektes erfolgen und beschrieben werden.
## 1. Installation einzelner Komponenten
* **Installation von eXist-db:** Um die Abläufe für ein kollaborativ angelegtes Projekt genauer zu betrachten, soll nachfolgend zuerst das Einrichten einer XML-Datenbank beschrieben werden. Dies dient dazu, die bereits erstellten Transkriptionen für die weitere Annotation zu speichern und für die gemeinsame Bearbeitung bereitzustellen.
* Hier geht es zur detaillierten [Installationsanleitung für Docker Desktop und eXist-db](https://digedtnt.github.io/docker-exist/).
* **Installation von ediarum.DB in eXist-db:** Um später unser eigenes Projekt generieren zu können, müssen wir nun _ediarum_ in eXist einrichten.
* Dafür laden wir aus dem [ediarum-Github-Repository](https://github.com/ediarum/ediarum.DB/releases) die aktuellste Version von ediarum.DB als XAR-Datei herunter. Zum Zeitpunkt dieses Projekts ist dies die Version 4.0.2.
* Im eXist-Dashboard können wir nun über den Package Manager die XAR-Datei hochladen.
→ Nach erfolgreichem Upload finden wir nun eine eigene Kachel mit der _ediarum_-App, die ab sofort außerdem auch im Dashboard über einen Link verfügbar ist.
* **Installation des Oxygen XML-Editors:** Abschließend fehlt nur mehr der Download und die Installation des [Oxygen XML Author](https://www.oxygenxml.com/documentation.html) - und zwar mindestens in Version 20.1. Alternativ kann auch der Oxygen XML Editor installiert bzw. genutzt werden.
## 2. Einrichtung des Projekts
* Zuerst wollen wir in unserer eXist-Datenbank für unsere Edition ein Projekt mit standardisierter Ablagestruktur sowie bestimmten Settings einrichten. Damit diese Standards korrekt angelegt werden, nutzen wir die ediarum.DB-App.
* Wir klicken also zunächst auf "ediarum" in unserem eXist-Dashboard.
* Die _ediarum_-App öffnet sich nun in einem weiteren Fenster im Browser, wo wir im Menü zu **Verwaltung > Projekte** navigieren und dort im Feld "Neues Projekt" einen Projektnamen für unsere Edition eingeben und abschließend auf "Anlegen" klicken.
→ Es dürfen keine Umlaute, Leer- oder Sonderzeichen verwendet werden.
* Außerdem möchten wir für unser Projekt in der Datenbank noch ein _ediarum_-Register aktivieren. In der geöffneten _ediarum_-App wählen wir dafür wieder unser Projekt aus und gelangen so auf die Projekt-Übersichtsseite.
Dort legen wir ein neues Register an, indem wir neben **Neues Register** auf "Aktivieren" klicken. Für unser Beispielprojekt wählen wir hier "Sachbegriffe" aus dem Drop-Down-Menü des _ediarum_-Registers und wählen bei Registeraufbau die Option "Register in einer Datei".
* Wir können nun als Admin mit dem admin-Benutzernamen (ohne Passwort-Eingabe) eine Verbindung unseres Oxygen-Editors zur Datenbank herstellen. Für unsere Projektmitarbeitenden wollen wir aber noch weitere Benutzer:innen in der _ediarum_-App anlegen. Dafür gehen wir wieder auf die Übersichtsseite unseres Projekts und wählen in dem Menüpunkt **Projektkonfiguration > Benutzer** aus. Dort haben wir bereits *zim-digedtnt* als User angelegt und fügen jetzt noch *zim-student* als weiteres Projektmitglied hinzu.
→ Damit auch andere Benutzer:innen bzw. Projektmitarbeitende die Register nutzen können, müssen wir im User Manager der eXist-db entsprechende Zugriffsrechte vergeben. Dafür gehen wir zum eXist-db-Dashboard, wählen dort **User Manager** und klicken jenen Benutzernamen an, dem wir Zugriffsrechte einräumen wollen.
Am Ende der User-Ansicht gibt es ein Gruppenverwaltungssystem, wo wir unserem/unserer Benutzer:in auch Zugriff auf die Gruppe "oxygen" gewähren sollten, wenn wir unseren Projektmitarbeitenden Zugriff auf die erstellten Projekt-Register einräumen wollen.
Damit hat der/die ausgewählte Projektmitarbeitende nun ebenfalls Zugriff auf das zuvor angelegte Register und kann dieses bei der Annotation nutzen.
* Im nächsten Schritt stellen wir im Oxygen XML Author eine Verbindung zu unserem soeben eingerichteten Projekt her, um alle in _ediarum_ enthaltenen Funktionalitäten verfügbar zu machen. Wir öffnen dafür den Oxygen XML Author und wählen im Menü **Optionen > Einstellungen**, um anschließend in der linken Spalte "Datenquellen" anzuklicken und unter der Tabelle zu den Verbindungen auf das Plus zu klicken. Dort geben wir nun unsere Projektdaten an.
Ob unsere Datenbankverbindung erfolgreich war, können wir herausfinden, indem wir im Menü **Fenster > Ansicht zeigen > Datenquellen Explorer** auswählen. Dort scheint nun unser Projekt mit der darin angelegten Ordnerstruktur auf.
Den Ordner mit den Briefen und dem Briefbeispiel.xml können wir schließlich löschen. Für unser Projekt legen wir stattdessen einen neuen Ordner mit der Bezeichnung "Manusrikpte" an, indem wir nach einem Rechtsmausklick auf unser Projekt im Datenquellen-Explorer "Verzeichnis erstellen" wählen. In diesen Ordner importieren wir nun unsere transformierten und auf das [DTABf angepasste XML-Dokumente](https://github.com/DigEdTnT/digedtnt.github.io/tree/master/data/pipelines/pipeline_1/ediarum/data/import).
Wenn wir nun alle Verzeichnisse ausklappen, sieht die Ordnerstruktur und der Ordnerinhalt folgendermaßen aus:
* Als nächstes richten wir uns noch die grundlegenden _ediarum_-Frameworks in unserer Arbeitsumgebung ein. Dafür legen wir zuerst einen Ordner für diese Frameworks auf unserem lokalen Dateisystem an und legen dort die GitHub-Repositorien [ediarum.BASE.edit](https://github.com/ediarum/ediarum.BASE.edit/releases) und [ediarum.REGISTER.edit](https://github.com/ediarum/ediarum.REGISTER.edit/releases) ab, indem wir jeweils die ZIP-Dateien mit dem Source Code des letzten Releases herunterladen und diese dann entpacken. Da wir später auch ein editionsspezifisches Framework für unsere eigene Edition benötigen, legen wir zusätzlich noch einen projektspezifischen Ordner zur Erweiterung des Basis-Frameworks an.
In Oxygen müssen wir nun noch unter **Optionen > Einstellungen** in der linken Spalte zu **Dokumenttypen-Zuordnung > Orte** navigieren, dort "Benutzerdefiniert" aktivieren und dann den Dateipfad zu unserem Framework-Ordner angeben.
Nach einem Neustart des Oxygen XML Author sollten nun unter **Optionen > Einstellungen > Dokumenttypen-Zuordnung** die _ediarum_-Frameworks aufscheinen. Hier wählen wir "ediarum.BASE.edit" aus und klicken "Erweitern" an, um unser eigenes Erweiterungsframework für unsere Edition einzubinden. Wir geben hierfür den Namen für unser editionsspezifisches Framework an, aktivieren beim Speicherort die Option "Extern" und geben dann den Pfad zu unserem zuvor angelegten Framework-Ordner an.
* Abschließend richten wir uns im Oxygen XML Author ein Projekt ein. Dafür navigieren wir in Oxygen auf **Projekt > Neues Projekt** und wählen dort den Ordner unseres projektspezifischen Frameworks aus.
Damit die Editorvariablen im Projekt gespeichert werden, gehen wir außerdem auf **Optionen > Einstellungen** und wählen dort "Benutzerspezifische Editorvariablen", um im Weiteren diese Projekt-Optionen anzuwenden.
→ Am Ende sehen die Editorvariablen für unser spezifisches Projekt so aus:
## 3. Erweiterung des projektspezifischen Frameworks
### a. Erstellen eines neuen Buttons
* Im vorangegangenen Kapitel haben wir uns zusätzlich zu dem über GitHub heruntergeladenen BASE-framework (ediarum.BASE.edit) auch ein eigenes projektspezifisches Framework mit dem Namen *ediarum.MARezepte.edit* angelegt. Dieses wollen wir nun erweitern. Nachdem es in unserem zuvor genutzten Transkriptionstool ([FromThePage](https://digedtnt.github.io/fromthepage/)) nicht möglich war, Textstellen mit roter Schriftfarbe zu annotieren, legen wir uns nun einen Button für den Oxygen XML Author an, um Projektmitarbeitenden diese spezifische Annotation zu vereinfachen.
* Im Oxygen XML Author gehen wir unter **Optionen > Einstellungen** auf **Dokumenttypen-Zuordnung** und wählen dort das projektspezifische Framework ediarum.MARezepte.edit, um dieses zu bearbeiten.
* In dem neuen Dokumenttypen-Fenster wählen wir nun den Reiter **Autor** und in der linken Menüleiste **Aktionen**. Mit einem Klick auf das Plus-Zeichen öffnet sich schließlich ein weiteres Fenster, in dem wir eine neue Aktion bzw. einen neuen Button anlegen können.
* Für die Konfiguration eines Buttons, der die Annotation von Textstellen mit roter Schrift erleichtert, haben wir die Felder wie folgt befüllt.
→ Nach der Wahl einer ID, eines kurzen und verständlichen Namens sowie eines Menü-Tastenkürzels (a), haben wir einen kurzen Beschreibungstext gewählt (b), der im Oxygen XML Author als Tooltip angezeigt wird. Wir haben schließlich Icons für den Button in zwei unterschiedlichen Größen erstellt, innerhalb unseres projekteigenen Frameworks gespeichert und den Pfad zu den Icons referenziert, sowie außerdem ein Tastenkürzel gewählt (c), mit dem Projektmitarbeitende auch ohne Mausklick auf den Button Textstellen annotieren können. Im nächsten Feld (d) geben wir an, unter welcher Bedingung die Aktion überhaupt gesetzt werden darf. Da wir in unserem Fall eine Textpassage mit einem [``-Element](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-hi.html) umgeben wollen, geben wir bei der **XPath-Aktivierung** an, dass dieser Button bzw. diese Annotation nur dann möglich sein soll, wenn an dieser Stelle auch tatsächlich ein ` `-Element erlaubt ist. Für diese Art der Annotation haben wir uns im Übrigen auf Grundlage der Vorgabe für [Einfärbungen](https://www.deutschestextarchiv.de/doku/basisformat/einfaerbung.html) im DTABf entschieden. In dem Auswahlmenü zum Vorgang (e) wählen wir den gewünschten Prozess, den wir mit unserer Aktion ausführen wollen - in unserem Fall ist dies die "SurroundWithFragmentOperation", die bewirkt, dass die markierte Textstelle mit einem "Fragment" umgeben wird. Welches Element mit welchen Attributen dieses Fragment am Ende sein soll, legen wir schließlich etwas weiter unten fest, wo wir die Zeile **fragment** auswählen und schließlich auf das Konfigurationssymbol klicken.
* In dem Fenster zur Bearbeitung des Fragments können wir angeben, dass wir die markierte Stelle mit einem ``-Element umgeben wollen, das ein Attribut `@rendition` mit dem Wert "#red" beinhaltet.
* Damit der Button letztlich auch in unserer Menüleiste erscheint und den Projektmitarbeitenden bei der Annotation zur Verfügung steht, fügen wir in dem Dokumenttypen-Fenster im Reiter **Autor** unter **Symbolleiste** unsere neue verfügbare Aktion zu den Textaktionen hinzu.
* Um im Autormodus nach einem Klick auf den neu konfigurierten Button auch eine sichtbare Veränderung zu bewirken, muss im CSS noch eine entsprechende Änderung vorgenommen werden. Im Dokumenttypen-Fenster kann man einsehen, auf welches CSS zugegriffen wird.
Es wäre nun entweder möglich, ein eigenes projektspezifisches CSS anzulegen, oder aber das im ediarum.BASE.edit-Framework bereits vorhandene standard.css zu erweitern. Wir haben uns dazu entschlossen, die entsprechenden Erweiterungen im standard.css, das im Frameworks-Verzeichnis in dem Ordner ediarum.BASE.edit zu finden ist, vorzunehmen. Wir fügen also folgenden CSS-Code hinzu:
```css
quote hi[rendition="#red"],
text hi[rendition="#red"] {
color: red;
-oxy-display-tags: none;
}
```
* Wenn wir nun im Autormodus unseren neuen Button verwenden, wird unser markierter Text rot eingefärbt. Die Oxygen-Tags, die im Autormodus standardmäßig erscheinen, werden außerdem unterdrückt.
### b. Anpassung bereits bestehender Buttons
* Grundsätzlich besteht im ediarum.BASE.edit-Framework bereits ein Button für die Annotation mit Registereinträgen, der ein Dropdown-Menü mit einer Registerliste öffnet.
→ Um die Annotation der Zutaten zu erleichtern und die Klickzahl zu minimieren, haben wir entschieden, den Listenpunkt "Sachbegriffe" aus dem Dropdown als eigenen Button in der Menüleiste anzulegen.
* Dafür navigieren wir über **Optionen > Einstellungen > Dokumenttypen-Zuordnung** zu unserem projektspezifischen Framework (ediarum.MaRezepte.edit), klicken auf "Bearbeiten" und wählen anschließend im Dokumenttypen-Fenster im Reiter **Autor** den Menüpunkt **Aktionen**.
Hier wählen wir die Aktion mit dem Namen "Sachbegriff" und klicken auf das Werkzeugsymbol, um diese Aktion zu bearbeiten.
* Im Fenster zur Bearbeitung der Aktion ändern wir die ID von rs[term] auf term, fügen neue Icons hinzu, die wir lokal im Ordner für das projektspezifische Framework gespeichert haben, wählen ein Tastenkürzel (Strg + I) für jene Projektmitarbeiter:innen, die die Arbeit mit der Tastatur bevorzugen, und ändern die XPath-Aktivierung dahingehend, dass wir bei der Annotation die entsprechende Textstelle nun anstatt mit einem ``- und `