Matuc

Matuc ist ein Konverter von Markdown zu HTML, sowie ein Werkzeug zur Automatisierung von Arbeitsschritten bei der Bearbeitung von Lehrmaterialien. Es kann auch genutzt werden, um eigene Skripte oder andere Editor-Plugins zu entwerfen.

Installation / Download

Windows

Für Windows gibt es ein Installationspaket, welches Python, GladTeX und Pandoc automatisch mitliefert. Für die Benutzung von GladTeX muss aber auch eine LaTeX-Distribution instaliert sein. Am einfachsten ist es daher, zuvor MikTeX zu installieren.

Der aktuellste Installer kann hier herunter geladen werden. Des Weiteren können unter Probleme und neue Funktionen melden.

Die Installation sollte NICHT durchgeführt werden, wenn die Umgebungsvariable %PATH% Länger als 1024 Zeichen lang ist. Wenn Sie nicht wissen, was dies bedeutet, können Sie dies getrost ignorieren. Der PATH enthält Verzeichnisse, in denen automatisch nach ausführbaren Programmen gesucht wird. Wenn Sie viele Entwicklerwerkzeuge installiert haben, sollten Sie vorher unbedingt die Länge von %PATH% überprüfen, da diese Variable ansonsten durch die Installationsroutine beschädigt wird.

MikTeX - Installation von Paketen

Nach der Installation von MikTeX müssen noch einige LaTeX-Pakete manuell nachinstalliert werden. Die Installation der Pakete(Package) erfolgt über den MikTeX Package Manager. Starten Sie den MikTeX Package Manager als Administrator.

Die nachfolgenden Pakete sind zu installieren:

• zhmetrics
• preview
• koma-script
• amsmath

Für die Installation können Sie nach den Packagen suchen. Geben Sie den Eingabefeld Name den Namen des Pakets ein und klicken Sie anschließend auf Filtern. Anschließend müssen Sie das zu installierende Paket in der Auflistung auswählen und das Pluszeichen für die Installation wählen.

Andere Betriebssysteme

Die Installation unter anderen Betriebssystemen besteht aus mehreren Schritten. Sie kann aber, mit einigen Anpassungen, auch unter Windows durchgeführt werden.

Als erstes muss man alle Abhängigkeiten installieren: Pandoc (>= 1.16), python (Version >= 3.2), GladTeX (1) und LaTeX, falls GladTeX verwendet wird.

Als nächstes holt man den Quellcode mittels Git (github.com):

git clone https://github.com/TUD-INF-IAI-MCI/AGSBS-infrastructure.git

Nach dem Herunterladen wechselt man in das neue Verzeichnis und führt folgenden Befehl aus:

sudo python3 setup.py install

Generelle Funktionsweise

Matuc ist ein Kommandozeilenprogramm. Da es als "eierlegende Wollmilchsau" konzipiert ist, besitzt es Unterkommandos, damit man nicht von einer Fülle von Optionen erschlagen wird. Ruft man also Matuc auf, muss man dahinter angeben, welches Unterpgrogramm man möchte. Gibt man keines an, wird der Hilfebildschirm ausgegeben:

    matuc <command> <options>

    <command> determines which action to take. The syntax might vary between
    commands. Use matuc <command> -h for help.

    Available commands are:

    addpnum         - generate new page number, relative to its predecessors
    conf            - set, init or update a configuration
    conv            - convert a project
    fixpnums        - fix incorrect page numbering of a document
    imgdsc          - generate image description (snippets)
    iswithinlecture - test, whether a certain path is part of a project
    new             - create new project structure
    mk              - invoke "mistkerl", a quality assurance helper
    toc             - generate table of contents
    version         - output program version

Anlegen von Lehrmaterialien

Wer sich gern die korrekte Verzeichnisstruktur von Matuc generieren lassen möchte, der kann das Kommando new benutzen. Hilfebildschirm:

matuc new

Um z.B. ein Buch mit einem Vorwort, zwei Anhangkapitel, mit fünf Kapiteln und auf Englisch zu erstellen, führt man folgendes aus:

matuc new -l en -c 5 -a 2 -p "Neues Material"

Nun wird der Ordner "Neues Material angelegt. Die Struktur innerhalb des Ordner ist:

• Neues Material
  • .lecture_meta_data.dcxml
  • inhalt.md
  • anh01
    • anh01.md
  • anh02
    • anh02.md
  • k01
    • k01.md
  • k02
    • k02.md
  • k03
    • k03.md
  • k04
    • k04.md
  • k05
    • k05.md
  • v01
    • v01.md

Konfiguration

Matuc soll sich möglichst viele Einstellungen abhängig von Lehrmaterial automatisch merken. Dazu gehört u.a.:

• Bearbeiter
• Arbeitsgruppe, Institution
• Titel, Quelle des Lehrmaterials
• Semester der Bearbeitung
• Tiefe der Nummerierung im Inhaltsverzeichnis
• ...

Dies wird in einer Datei namens ".lecturemetadata.dcxml" im obersten Verzeichnis des zu bearbeitenden Lehrmaterials abgelegt.

Anlegen einer Konfiguration

Initial legt man eine Konfiguration mittels des Kommandos

matuc conf init

im aktuellen Verzeichnis, am besten dem Stammverzeichnis des Materials (des obersten Verzeichnisses des Bearbeiteten Lehrmaterials) an.

Man sollte nun unbedingt die Werte für die Konfiguration anpassen, siehe nächster Abschnitt.

Anpassung der Konfiguration

Die Informationen der Konfiguration sind sehr wichtig, da sie in jedes konvertierte Dokument eingebettet werden und daher korrekt sein müssen. Außerdem ist das Setzen der Sprache sehr wichtig für den Bearbeitungsprozess und für den Bildschirmleser des Benutzers der fertigen Dokumente.

Man kann sich mit

matuc conf show

alle Optionen anzeigen lassen, die es gibt. Mit

matuc conf update

kann man dann eine Option neu setzen. Lässt man bei genanntem Befehl die Argumente weg, so wird ein Hilfebildschir ausgegeben.

Es folgt ein Beispiel zum Setzen des Quelldokuments:

matuc conf -s "Interne Vorlesungsunterlagen" update

Aufbau der Konfigurationsdatei

Im Allgemeinen ist es nicht erforderlich die Konfigurationsdatei manuell zu bearbeiten. Die Anpassung kann direkt über Matuc erfolgen (siehe Anpassung der Konfiguration). Trotzdem kann man die Konfiguration auch per Hand mit einem UTF-8-fähigen Editor bearbeiten.

Die Konfigurationsdatei beinhaltet Meta-Informationen über das Buch und Zusatzinformationen, die die Konvertierung beeinflussen. Das Format der Datei ist XML. Dabei wird das Dublincore Format verwendet. Zusätzlich nutzt das MAGSBS-Modul einen gleichnamigen Namensraum, um zusätzliche INformationen abzuspeichern.

Im Folgenden sind die Felder des DublinCore-Formats bzw. des MAGSBS-Moduls mit ihrer jeweiligen Verwendung aufgeführt und durch ein Beispiel erklärt.

• Autor der Quelldokumente: <MAGSBS:sourceAuthor>Max Mustermann, Karla Korrekturleserin</MAGSBS:sourceAuthor>
• Bearbeiter des barrierefreien Materials: <dc:creator>Max Muster</dc:creator>
• Herausgeber: <dc:publisher>TU Dresden</dc:publisher>
• Arbeitsgruppe der Bearbeitung (Institution): <dc:contributor>AGSBS</dc:contributor>
• Quelle des Lehrmaterials: <dc:source>Vorlesungsunterlagen des Lehrstuhls für Mensch-Computer Interaktion</dc:source>
• Titel des Lehrmaterials/Buches: <dc:title>Titel des Buches/Vorlesung</dc:title>
• Semester der Bearbeitung <dc:date>SS2016</dc:date>
  • An dieser Stelle sollten nur die Bezeichner SS und WS und die zwei- bzw. vierstellige Jahreszahl verwand werden
• Tiefe des Inhaltsverzeichnisses: regelt, bis zu welcher Ebene Überschriften ins Inhaltsverzeichnis übernommen werden <MAGSBS:tocDepth>2</MAGSBS:tocDepth>
• Abstand zwischen den Seitennavigationslinks: <MAGSBS:pageNumberingGap>5</MAGSBS:pageNumberingGap>
• Präfix des Anhangs: Regelt, ob vor dem Inhaltsverzeichnis der Präfix "A" (Anhang) vorangestellt wird: <MAGSBS:appendixPrefix>0</MAGSBS:appendixPrefix>
• Sprache des bearbeiteten Materials: <dc:language>de</dc:language>

Konfigurationen in Unterverzeichnissen

Falls Lehrmaterial nicht nur von einem Studenten bearbeitet wird, sollte in dem Unterverzeichnis des Materials, welches dem Studenten zugeteilt wurde, eine zusätzliche Konfiguration angelegt werden. Diese sollte dann den Namen des Beareiters enthalten.

Alle Unterkommandos von Matuc werden automatisch zuerst die Konfiguration verwenden, die "am nähsten" an der aktuellen Datei liegt, d.h. entweder im aktuellen Verzeichnis, dem darüber und so weiter. Damit kann z.B. im Stammverzeichnis der Bearbeiter auf "Max Mustermann" und im Verzeichnis anh01 der Bearbeiter auf "Otto Normalverbraucher" gesetzt werden.

Konvertierung von Dateien

Die Konvertierung nutzt intern Pandoc, erweitert dies aber um zusätzliche Ausgabefilter und Standardvorlagen. Pandoc sollte daher zur Umwandlung von Lehrmaterial nicht verwendet werden, da z.B. Seitenzahlen nicht umgewandelt werden.

Konvertierung einzelner Dateien

Die Konvertierung erfolgt mit dem Unterkommando "conv", die Umwandlung von "Hallo.md" würde also wie folgt ablaufen:

matuc conv "Hallo.md"

Matuc wird automatisch erkennen, ob LaTeX-Formeln in das MarkDown-Dokument eingebettet wurden und GladTeX und damit LaTeX aufrufen. Dies wird auch ein Verzeichnis bilder anlegen, sofern es noch nicht existiert.

Konvertierung mehrer Datien oder Materialien

matuc conv VERZEICHNIS konvertiert das gesamte Lehrmaterialverzeichnis.

Der Aufruf ist:

matuc conv VERZEICHNIS

Wobei VERZEICHNIS entweder "." ist, wenn man sich bereits in dem korrekten Verzeichnis befindet, oder eben der Verzeichnisname, in dem die Konvertierung stattfinden soll.

Zuerst erstellt matuc conv VERZEICHNIS das Inhaltsverzeichnis, so wie es auch

matuc toc

erstellen würde. Im Anschluss konvertiert es, mit Hilfe der Kopfdaten über die Veranstaltung aus der Konfiguration, alle Markdown-Dateien.

Erstellung eines automatischen Inhaltsverzeichnisses

Das Unterkommando matuc toc ermöglicht es automatisiert Inhaltsverzeichnisse zu erstellen. Dies wird von bei der Generierung der mehrerer Dateien mittels matuc conv VERZEICHNIS

automatisch ausgeführt.

Überschriften der jeweiligen Kapitel und Unterkapitel werden automatisch aus den Dateien extrahiert und nummeriert ins Inhaltsverzeichnis übernommen. Dies setzt allerdings voraus, dass die Verzeichnisstruktur auch den Vorgaben der Tutorenanleitung entspricht.

Matuc toc erwartet das Verzeichnis als Parameter, in dem nach Kapiteln gesucht werden soll. Wenn man sich im Stammverzeichnis des Lehrmaterials befindet, tippt man ".". Die Ausgabe wird direkt auf das Terminal geschrieben. Möchte man sie stattdessen in einer Datei speichern, muss der Parameter "-o", gefolgt von einem Dateinamen verwendet werden. Beispiel:

matuc toc -o "inhalt.md" .

Programmierschnittstelle MAGSBS

Das Modul MAGSBS ist ein in der Programmiersprache Python implementiertes Modul, welches folgende Funktionalitäten bereitstellt:

• Konvertierung von Dokumenten mittels Pandoc
  • Modifikation einiger Konvertierungsprozesse, um die Barrierefreihei tund die Integration zu erhöhen
  • Ergänzung von Markdown um Syntaxelemente, wie z.B. Auszeichnung für Seitenzahlen
• Automatisierung der Erstellung von Inhaltsverzeichnissen, Navigationsleisten o.ä.
• automatisierte Verlinkung von Bildbeschreibungen, automatisierte Erstellung von Formelgrafiken sowie Alternativtexten durch LaTeX
• Fehlersuche in Markdown-Dokumenten für häufig auftretende Fehler
• uvm.

Zusammen mit dem MAGSBS-Modul kommt eine beispielhafte Kommandozeilenoberfläche mit dem Namen Matuc.