Dateienstruktur bei der AGSBS

Einer der Grundpfeiler der Arbeitsgruppe Studium für Blinde und Sehbehinderte ist die Übertragung von Literatur und Vorlesungsmaterialien wie Präsentationsfolien oder Übungsblättern in ein digitales, barrierefreies Format. Aus diesem Grunde nutzt die AGSBS die Auszeichnungssprache Markdown und (La)TeX sowie das Konvertierungsprogramm Matuc oder das PowerPoint-Plugin, um daraus barrierefreies HTML zu gewinnen. Das Zusammenspiel dieser Absichten, Formate und Programme entwickelte über die Jahre bei der AGSBS eine komplexe Ordnerstruktur, die Übersichtlichkeit für den Bearbeiter und erleichterte Navigation für die Leserschaft sowohl für Bücher, als auch andere Studienmaterialien, erleichtern sollen.

Ordnerhierarchie der AGSBS

Die Hierarchie der Ordner und Dateien bei der Übertragung von einem Format in das von der AGSBS genutzte Format verläuft insgesamt über vier bis sechs Ebenen. Deren Anzahl ist von den jeweiligen Voraussetzungen der Quelle abhängig.

Ordner und Dateien folgen dabei mehr oder weniger zwingenden Namenskonventionen, die von den notwendigen Programmen gelesen und für die Konvertierung benötigt werden.

Erste Ebene - Oberordner

Screenshot des Projektordners in Atom

Der oberste Ordner dient der Zuordnung der jeweiligen Inhalte. Dabei wird aktuell unterschieden zwischen Büchern und Lehrveranstaltungen (Paper bzw. Essays sollen folgen), denen im Verwaltungssystem der AGSBS bei korrekter Einordnung ein spezieller Wert zugeordnet wird.

• Buchprojekt
  • Die Namenskonvention eines Oberordners für Fachliteratur folgt dabei der ID, die das Redmine einem Bucheintrag zuweist, dem Nachnamen des Autors bzw. Herausgebers sowie dem Titel des Buches. Die ID besteht dabei aus der Ziffer für das jeweilige Buch im Gesamtkatalog der AGSBS seit Einführung des Verwaltungssystems (z.B. B-255) sowie dem Veröffentlichungsjahr der jeweils vorliegenden Auflage.
• Lehrveranstaltungsprojekt
  • Die Namenskonvention eines Oberordners für Lehrveranstaltungen folgt dabei der ID, die das Redmine den Lehrmitteln zuweist, sowie dem Namen der jeweiligen Veranstaltung. Eine Unterscheidung zwischen Vorlesung, Seminar und Übung erfolgt erst später bzw. nicht. Die ID besteht dabei aus der Ziffer für die jeweilige Lehrveranstaltung im Gesamtkatalog der AGSBS seit Einführung des Verwaltungssystems (z.B. L-122) sowie dem Jahr des jeweiligen Semesters.

Zweite Ebene - Bearbeitung und Quellen

Screenshot des Projektordners in Atom

In der zweiten Ebene gibt es lediglich zwei Ordner. Der Ordner bearbeitet beinhaltet das gesamte übertragene Dokument sowie alle Medien- und sonstigen Dateien, die für das barrierefreie Dokument notwendig sind. Im Ordner quellen wiederum befinden sich alle Dateien, die der Übertragung vorangehen bzw. aus der Quellmaterialvorbereitung stammen.

Dritte Ebene - Vorlesung und Übung

Screenshot des Projektordners in Atom

Die dritte Ebene ist ein Sonderfall innerhalb des Bearbeitungsordners, der vorwiegend bei Lehrveranstaltungen Verwendung findet. Die Ordner in dieser Ebene weisen die Dokumente der jeweiligen Lehrveranstaltung den unterschiedlichen Einheiten der Veranstaltung zu. Dies trifft in den meisten Fällen auf Vorlesungen (hier werden auch Seminare mit Dauerpräsentationen dazu gezählt) sowie Übungen zu. Die gesamte Bearbeitung der jeweiligen Dokumente findet in diesen einzelnen Ordnern statt. Es bietet sich in einem solchen Fall an, dass der Quellordner dieselbe Unterteilung aufweist, um auf diese Weise die Übersicht und Zuordnung zu verbessern.

Vierte Ebene - Bearbeitungsstruktur

Screenshot des Projektordners in Atom

Innerhalb der vierten Ebene findet die eigentliche Bearbeitung statt. Dabei spiegelt die Struktur dieser letzten Endes bearbeiteten Dokumente bei Büchern das Inhaltsverzeichnis und bei Lehrveranstaltungen den angedachten Semesterplan wieder. In den Ordnern Vorlesung und Übung befinden sich die jeweiligen Ordner der Kapitel bzw. Übungsblätter, eine Lecture-Meta-Datei sowie das von Matuc generierte Inhaltsverzeichnis dieser jeweiligen Bearbeitung.

Kapitelordner

Die Ordner für die einzelnen Abschnitte des vorliegenden Quellmaterials werden in Anlehnung an das Wort "Kapitel" mit k sowie der nachfolgenden, zweistelligen Rangfolgenziffer benannt. Dasselbe gilt für Anhänge (anh) eines Werkes sowie im Falle von Übungsblättern mit dem Präfix blatt. Letzteres wird allerdings seltener genutzt. Das Vorwort (v01) kann ebenfalls mehrere Abschnitte aufweisen, dies ist in der Regel allerdings nicht der Fall. Die Einschränkung auf einen Bereich von 100 maximal möglichen Kapiteln (oder Anhängen) ist aus der praxisorientierten Erfahrung der AGSBS erwachsen - sicherlich kann es Werke geben, die über weitaus mehr Kapitel verfügen.

• Kapitel: k00, k01, k02, ..., k{..}
• Vorwort: v01
• Anhang: anh00, anh01, anh02, ..., anh{..}
• Blatt: blatt01, blatt 02, ..., blatt{..}

Lecture Meta Data

Die Metadatei (.lecture_meta_data.dcxml) ist eine von Matuc generierte und für Matuc notwendige Datei, welche die Daten für die Bearbeitung und zur Quelle bereithält. Bei der Konvertierung werden diese Daten genutzt, um sie als Metadaten der HTML-Datei anzulegen oder aus ihr Bedingungen für die Art und Weise der Bearbeitung abzuleiten.

Die Datei kann dabei direkt über die Eingabeaufforderungen per Matuc, über Atom oder mit dem PowerPoint-Plugin erzeugt werden. Alle erforderlichen Daten können mit einem Editor jederzeit nachträglich manuell bearbeitet werden.

• MAGSBS:sourceAuthor: Angabe über Autoren der Quelle (z.b. Buchautor, Dozent der Lehrveranstaltung oder Herausgeber)
• dc:source: Angabe zur Art der Quelle (z.B. Präsentation des Lehrstuhls für Mensch-Computer-Interaktion, Handbuch)
• dc:publisher: Angabe zum Verlag bzw. zur Institution, bei der die Quelle veröffentlicht wurde (z.B. Springer, TU Dresden)
• dc:format: Angabe zum Format der vorliegenden Quelldatei
• dc:contributor: Angabe zum Bereitsteller des barrierefreien Dokuments (Voreinstellung: AGSBS)
• MAGSBS:tocDepth: Angabe zur Tiefe des von Matuc generierten Inhaltsverzeichnis; wird aus den Überschriften innerhalb der Kapiteldokumente heraus gelesen (Voreinstellung: 5)
• MAGSBS:pageNumberingGap: Angabe zum Abstand der Seitenlinks an der Ober- und Unterseite jedes Kapiteldokuments, die durch Matuc generiert werden (Voreinstellung: 5)
• dc:rights: Angabe zur Lizenz der Benutzung (Voreinstellung: Access limited to members)
• dc:creator: Angabe zum Bearbeiter; Name wird automatisch vom Benutzernamen des Computers ausgelesen
• MAGSBS:generateToc: (Voreinstellung: 1)
• dc:date: Angabe zum Jahr der Veröffentlichung der Quelle (z.b. 1990, WS 2017/18)
• dc:title: Angabe zum Titel der Literatur bzw. zur Veranstaltung
• dc:language: Angabe zur Sprache der Quelle (de für Deutsch, eng für Englisch)
• MAGSBS:appendixPrefix: (Voreinstellung: 0)
• MAGSBS:version: Angabe zur gegenwärtigen Matuc-Version, während der Bearbeitung (Stand März 2018: Matuc 0.7)

Inhaltsdateien

Die inhalt.md und inhalt.html ist eine von Matuc generierte Datei, die zur besseren Navigation innerhalb des gesamten Dokuments für Leserschaft mit Sehbehinderungen dient. Die HTML-Datei bildet dabei die Schnittstelle zwischen den einzelnen Kapiteln, auf die Studierende jederzeit direkten Zugriff haben. In der HTML-Ansicht des jeweiligen Dokuments finden sich die Verlinkungen zum Inhaltsverzeichnis am oberen und am unteren Rand des Dokuments.

Innerhalb des Inhaltsverzeichnisses finden sich direkte Verlinkungen in die einzelnen Kapitel und Unterkapitel des Gesamtdokument, je nachdem welche Einstellungen man in der Metadatei eingetragen hat.

Fünfte Ebene - Im Kapitelordner

Screenshot des Projektordners in Atom

Die einzelnen Kapitel bzw. einzelne Vorlesungen eines Semesters finden sich innerhalb der Kapitelordner. Dabei gilt in der Folge, dass alle Angaben, die hier gemacht werden, selbstverständlich auch auf die Dateien eines Anhangs oder des Vorwortes zu übertragen sind. Hierbei ist dann allerdings die veränderte Namenskonvention zu beachten.

Weitere Ordner wie audio und video ebenfalls unterstützt werden (zum Beispiel durch das PowerPoint-Plugin). Da aber die Praxis gezeigt hat, dass Dozenten wenn überhaupt eher auf Verlinkungen ins Internet setzen, anstatt solche Medien direkt einzubinden, ist dies ein Sonderfall, der sich allerdings ähnlich verhält, wie der Bilderordner.

Dokumentendatei

Das eigentliche Dokument findet sich in den Dateien k01.md und k01.html (bzw. je nach Nummerierung). Hier ist der gesamte Fließtext des Quelldokuments sowie eine Verlinkung zu allen genutzten Medien der Quelldatei hinterlegt. Dabei gilt die Originalgetreuheit und Zitierfähigkeit als oberstes Ziel der Bearbeitung.

Das Dokument besteht zusätzlich aus den Seitenzahlen zu Beginn jeder Seite, die von Matuc ausgelesen und referenziert werden können. Die Navigationsleiste hingegen, die Matuc mithilfe der Seitenzahlen zu Beginn und Ende des Dokuments stellt (genau wie den Link zum Inhaltsverzeichnis), befindet sich lediglich in der HTML-Datei. Matuc generiert sowohl die Kopf- und Fußzeile der Navigation, als auch das Inhaltsverzeichnis variabel nach bzw. in den Zwischenschritten der Bearbeitung, wodurch die HTML-Datei bei wiederholten Veränderungen jedes Mal neu überschrieben wird. Die Markdown-Datei soll von diesen Veränderungen unangetastet bleiben und lediglich manuell verändert werden (zum Beispiel zur Fehlerkorrektur oder während des Bearbeitungsprozesses).

Um die Performance bei der Bearbeitung mit dem Editor Atom zu gewährleisten, empfiehlt die AGSBS, dass die Datei eines Kapitels sinnvolle Unterbrechungen beinhaltet und eine einzelne Datei daher im Idealfall 2000 Zeilen (besser weniger) nicht überschreitet. Nun liegt es selbstverständlich nicht in der Hand des Bearbeiters, welchen Aufwand eine Quelldatei macht und wie viele Zeilen unter Umständen notwendig sind. Aus diesem Grund ist es ratsam, wenn die Dokumentendatei seinerseits in mehrere einzelne Dateien aufgesplittet wird. Der Namenskonvention k{..}.md folgt dabei einfach eine weitere Reihenfolge mit zwei Ziffern, beispielsweise k0101.md und k0102.md. Matuc erkennt diese aufgeteilten Dateien, generiert für jede Markdown-Datei eine eigene HTML und referenziert diese ebenfalls in Navigationsleiste und Inhaltsverzeichnis.

Einziges Problem: Pro Kapitelordner sollte sich in den Dokumentendateien nur eine einzige Überschrift erster Ordnung befinden. Matuc nummeriert sein Inhaltsverzeichnis automatisch und nutzt die Überschriften erster Ordnung als Ausgangswert bei der Generierung.

Achtung!:

Unter Umständen kann sich eine .htex-Datei mit demselben Namen wie die Dokumentendatei im Ordner befinden. Sollte dies der Fall sein, ist die Konvertierung der Datei fehlgeschlagen, weil eine TeX-Formel innerhalb der Dokumentendatei nicht korrekt umgesetzt wurde oder unterstützt wird. Konvertiert man die Datei ohne Hilfsmittel direkt in den Eingabeaufforderungen, wird die dabei entstehenden Fehlermeldung angezeigt und der Bearbeiter kann den Fehler im TeX beheben.

Bildbeschreibungsdatei

Innerhalb der bilder.md und bilder.html befinden sich die ausgelagerten Bildbeschreibungen der einzelnen Grafiken eines Kapitels. Die Dokumentendateien verlinken innerhalb des Bildes auf die ausgelagerte Beschreibung und leitet die Leserschaft direkt zur Beschreibung. Die Bildbeschreibungsdateien werden nicht von Matuc direkt referenziert und es befindet sich auch kein Link zurück zur Grafik des Dokuments an den einzelnen Bildbeschreibungen. Dies hat den Grund, weil unter Umständen dasselbe Bild mehrmals in einem Kapitel vorkommen kann. Damit man die Beschreibung nicht mehrfach verfassen muss, wird lediglich der Link zur jeweiligen Bildbeschreibung wiederholt.

Die Datei selber besteht aus der Überschrift erster Ordnung Bildbeschreibungen (welche allerdings manuell hinzugefügt werden muss) am oberen Rand. Die einzelnen Bildbeschreibungen besitzen Überschriften zweiter Ordnung, zu denen der Referenzlink aus der Dokumentendatei direkt geleitet wird (ID in HTML-Datei), und werden dabei von horizontalen Linien dazwischen unterbrochen.

Bilderordner

Screenshot des Projektordners in Atom

Der Ordner bilder beinhaltet alle relevanten, grafischen Elemente, die bezüglich der Bearbeitung von der Dokumentendatei zu Rate gezogen werden müssen. Es können allerdings auch andere Datei-Arten im Bilderordner unter Umständen vorhanden sein.

• Bilderdatei: Das Format für die jeweilige Grafik, die in das Dokument eingebunden werden muss, ist frei wählbar. Auch bewegte Gif-Dateien sind unter Umständen zugelassen, diese sind allerdings aus einem anderen Grund eine Schwierigkeit für die Bildbeschreibungen.
• eqn{...}.png: Diese Grafiken sind die von MikTeX erzeugten PNG-Dateien, die als Vorlage für die mit TeX verfassten Formeln innerhalb des Dokuments dienen.
• gladtex.cache: Diese Grafik wird bei der Erstellung der Formelbildern automatisch erzeugt und bei wiederholter Konvertierung überschrieben. Sie enthält die notwendigen Daten für die Erstellung der grafischen Formel aus dem TeX-Code.
• outsourced-descriptions.html: Wenn eine Formel in TeX zu kompliziert wurde, werden die dabei erzeugten Alternativtexte in diese Datei ausgelagert.