Matuc: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
|||
Zeile 30: | Zeile 30: | ||
Als erstes muss man alle Abhängigkeiten installieren: Pandoc (>= 1.12), python (Version >= 3.2), GladTeX ([http://gladtex.sf.net]) und LaTeX, falls GladTeX verwendet wird. | Als erstes muss man alle Abhängigkeiten installieren: Pandoc (>= 1.12), python (Version >= 3.2), GladTeX ([http://gladtex.sf.net]) und LaTeX, falls GladTeX verwendet wird. | ||
Als nächstes holt man den Quellcode mittels Git ( | Als nächstes holt man den Quellcode mittels Git (github.com): | ||
<pre>git clone | <pre>git clone https://github.com/humenda/AGSBS-infrastructure.git</pre> | ||
Man wechselt nun in das neue Verzeichnis und gibt | Man wechselt nun in das neue Verzeichnis und gibt |
Version vom 21. Oktober 2014, 09:08 Uhr
Matuc ist ein Konverter von Markdown zu HTML, sowie ein Werkzeug zur Automatisierung von Arbeitsschritten bei der Bearbeitung von Lehrmaterialien.
Installation / Download
Windows
Für Windows gibt es ein Installationspaket, welches Python und GladTeX automatisch mitliefert. Für die Benutzung von GladTeX muss aber auch eine LaTeX-Distribution instaliert sein.
Die Installationsdatei findet sich unter
Die Installation sollte NICHT durchgeführt werden, wenn
%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.
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.12), python (Version >= 3.2), GladTeX ([2]) und LaTeX, falls GladTeX verwendet wird.
Als nächstes holt man den Quellcode mittels Git (github.com):
git clone https://github.com/humenda/AGSBS-infrastructure.git
Man wechselt nun in das neue Verzeichnis und gibt
sudo matuc python3 setup.py install
Genereller Funktionsweise
Matuc ist ein Kommandozeilenprogramm. Da es als "eierlegende Wollmilchsau" konzipiert ist, besitzt es Unterkommandos, um nicht von einer Fülle von Optionen erschlagen zu werden. 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 navbar - generate navigation bar at beginning of each page new - create new project structure mk - invoke "mistkerl", a quality assurance helper toc - generate table of contents
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.
Initiales Anlegen einer Konfiguration
Initial legt man eine Konfiguration mittels
matuc conf init
im aktuellen Verzeichnis, am besten dem Stammverzeichnis des Materials (des obersten Verzeichnisses des Bearbeiteten Lehrmaterials) an.
Benutzung
Mittels "matuc conf show" kann man sich alle Optionen ansehen und mittels "matuc conf <Option> update" diese Option setzen. Ein Beispiel zum Setzen des Quelldokuments:
matuc conf -s "Interne Vorlesungsunterlagen" update
Die Optionen bekommt man durch tippen von "matuc conf".
Alternativ kann man auch die XML-Datei öffnen und seine Werte darin händisch eintragen.
Unterverzeichnisse
Falls Material von mehreren Teilnehmern bearbeitet wird und dies nicht durch eine Komma-separierte Liste geschehen soll, sondern der genaue Autor angegeben werden soll, so kann man für jedes Unterverzeichnis eine Konfiguration erstellen.
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 kann eingebettete LaTeX-Formeln automatisch in Bilder mit zugehörigem Alternativtext umwandeln. Dazu wird die Option "-g" verwendet, damit intern GladdTeX ausgeführt wird. "Hallo.md" würde man dann so umwandeln:
matuc conv -g "Hallo.md"
Dies legt übrigens auch gleich ein Verzeichnis "bilder" an (falls es noch nicht existiert) und legt dort die Bilder der Formeln ab.
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" .
Die Navigationsleiste mit Link zum Inhalt und den Links zu den Seiten muss nicht von Hand generiert werden. Dies übernimmt "matuc navbar". Die Navigationsleiste für immer für ein ganzes Verzeichnis (Lehrmaterial oder Kapitel) generiert. Dabei werden nur Dateien berücksichtigt, die nach dem Schema "kXX", "anhXX" oder "vXX" benannt sind.
Wenn man sich im Stammverzeichnis des Lehrmaterials befindet, könnte ein Aufruf so aussehen:
matuc navbar .
Weitere Optionen erhält man mit "matuc navbar".
Der Abstand der Seitenzahlen die in die Navigationsleiste kommen, kann mit dem Konfigurationsschlüssel "pageNumberingGap" gesetzt werden. Siehe dazu auch den Abschnitt zum Verwalten der Konfiguration.