Matuc
HINWEIS: Diese Seite befindet sich noch in der Überarbeitung. Es handelt sich nicht um die finale Version.
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.
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: conf - set, init or update a configuration conv - convert a markdown file using pandoc imgdsc - generate image description (snippets) iswithinlecture - test, whether a certain path is part of a lecture new - create new project structure master - perform toc generation (see below) and call `conv` on every file 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, ohne Anhang, mit fünf Kapiteln und auf Englisch zu erstellen, führt man folgendes aus:
matuc new -l en -c 5 -p "Neues Material"
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>
Unterverzeichnisse
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.
Die Konvertierung geschieht mittels des Unterkommandos "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.
Erstellung eines automatischen Inhaltsverzeichnisses
Das Unterkommando "matuc toc" ermöglicht es automatisiert Inhaltsverzeichnisse zu erstellen. Die Überschriften der jeweiligen Kapitel und Unterkapitel werden automatisch mit der richtigen Nummerierung eingetragen. 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" .
Alles in einem Kommando: Master
Matuc master wurde konzipiert um ganze Lehrmaterialverzeichnisse auf einmal zu Konvertieren. Der Aufruf ist denkbar einfach:
matuc master VERZEICHNIS
Wobei VERZEICHNIS entweder "." ist, wenn man sich bereits in dem korrekten Verzeichnis befindet, oder eben der Verzeichnisname, in dem die Konvertierung stattfinden soll.
Folgende Schritte werden ausgeführt:
- matuc navbar
- matuc toc
- matuc conv (für alle Dateien)
Matuc-Fehlermeldungen
Diese Kapitel ist noch in der Entstehung. Die Fehlermeldungen sind noch nicht vollständig!
Die Überprüfung des angelegten Materialien erfolgt auf der Konsole durch den Aufruf matuc mk $PATHNAME$
oder matuc mk $DATEINAME$
.
Bei den entwickelten Plugins für die Editoren Sublime und Atom sind Shortcuts für die Überprüfung definiert.
Des Weiteren erfolgt eine Überprüfung bevor die Dateien generiert werden. Anscheinend werden die Fehler gegeben.
Fehlermeldung
Nachfolgend sind die mögliche Fehler aufgelistet. Dies ist nur ein Auszug und wird daher stetig ergänzt.
Dateiname | Fehlermeldung | Lösung |
---|---|---|
.lecture_meta_data.dcxml | Zeile 4: Fehler in der Konfiguration: Der Wert $WERT$, z.B. title, ist nicht gesetzt, wodurch die Kopfdaten in den HTML-Dateien nicht erzeugt werden können. | Für Sublime Text: Die Datei .lecture_meta_data.dcxml in der Zeile 4 einen Wert für $WERT$ z.B. Titel eintreten. Wichtig! Die XML-Struktur erhalten, d.h. nur den Wert für unknown ändern. |
k0x.md | k01.md line: 389, 48 message: formula: Missing delimiter (. inserted) |
Die Formel in Zeile 389 enthält einen Fehler. In diesem Beispiel ist der LaTexbefehl falsch. Es muss $\rightarrow$ lauten.
|
k0x.md | Error: Command failed: matuc_js imgdsc -d "Hier steht der Alternativtext" bilder/Abbildung 7-1 Schema für Formulierungen.png | Entfernen Sie die Leerzeichen im Dateinamen des Bildes. |
MAGSBS/Matuc
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
- 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. Ferner nutzt das Sublime-Plugin das MAGSBS-Modul intern.
Installation und Benutzung
Die Installation und Benutzung von Matuc wird in diesem Artikel behandelt.