Machen Sie sich die Arbeit leicht, indem Sie komplexe Dokumente erst in Markdown schreiben und dann mit Pandoc konvertieren – mit allen Finessen.

Viele Menschen schätzen Programme wie Microsoft Word oder LibreOffice Writer, da sie das Erstellen ansprechend gestalteter Texte vereinfachen. Selbst bei optimalem Einsatz der Programme behindern sie aber die Texteingabe, da diese eng mit der Formatierung verzahnt ist. Das freie Werkzeug Pandoc ermöglicht einen anderen Ansatz, der Form und Inhalt voneinander trennt. Die vorgestellten Werkzeuge verarbeiten außerdem Dateitypen wie HTML, ODT, TEX und PDF sowie DOCX, das proprietäre, aber offengelegte Format, das Microsoft Word seit 2009 zugrunde liegt.

Ausgezeichnet

Werkzeuge wie Pandoc oder Asciidoc gehen einen anderen Weg als die klassische Textverarbeitung, indem sie die Auszeichnung der Elemente reduzieren. Hervorhebungen oder Überschriften kennzeichnen Sie dabei typischerweise durch bestimmte Zeichenfolgen (Tags) im Text.

Wie der englische Name “markup language” (ML) verrät, zählt die “hypertext markup language” HTML zu den Vertretern dieser Gattung, weitere sind LaTeX oder das daraus abgeleitete Rich Text Format RTF. Vereinfachte Auszeichnungssprachen passen sich dem Textfluss durch wenig aufdringliche Markierungen an.

Für den Anfang lohnt es sich, das Augenmerk auf Markdown zu legen, auf das sich unter anderem Programme wie Ipython Notebook/Jupyter oder R/knitr stützen. Die Tabelle “Markdown” fasst wichtige Kommandos zusammen, eine umfassende Beschreibung findet sich im Internet [1].

Pandoc

Seit unserem letzten Bericht vor vier Jahren [2] hat sich das Programm Pandoc deutlich weiterentwickelt. Für Nutzer von 32-Bit-Systemen steht lediglich Version 1.12 zur Verfügung, die es nicht erlaubt, alle Beispiele aus dem Beitrag nachzuvollziehen.

Für 64-Bit-Systeme bieten die Repositories der meisten Distributionen das Programm in der stabilen Version 1.16.0.2 an. Daneben hält die Webseite [3] die neuesten Pakete für Debian bereit, ebenso einen Installer für Mac OS X und Windows. Selbst wenn Sie die Funktionen im ersten Anlauf vielleicht nicht benötigen, lohnt es sich, die Pakete pandoc-citeproc und python-pandocfilters gleich mit zu installieren.

Pandoc erwartet Textdateien im UTF-8 Format – bei Linux eigentlich selbstverständlich, aber nicht unbedingt bei Windows. Der folgende Aufruf genügt, um einen Markdown-Text ins MS-Word-Format DOCX zu konvertieren:

$ pandoc test.md -o test.docx

Ursprünglich sollte Markdown nur die Eingabe von HTML-Code vereinfachen. Dieses Erbe merkt man der Sprache noch heute an. Wie bei HTML interpretiert die Software Leerzeichen und Zeilenumbrüche als einfache Worttrenner. Allerdings gibt es einige Ausnahmen: Beginnt eine Zeile mit vier Leerzeichen, formatiert der Interpreter sie als Codeblock in nichtproportionaler Schrift ohne Zeilenumbruch. Endet eine Zeile mit mindestens zwei Leerzeichen, fügt die Software bei der Ausgabe einen Umbruch ein.

Eine Überschrift leiten Sie mit einer Leerzeile ein, gefolgt von Doppelkreuzen am Beginn der folgenden Zeile. Spiegellisten, eingerückten Text oder auch Textblöcke umschließen Sie mit Leerzeilen. Auf Markierungen für die Einträge in Listen folgt mindestens ein Leerzeichen.

Word-Datei formatieren

In der ersten Zeile von Listing 1 lädt Wget eine Word-Datei herunter und speichert sie unter dem Namen demo2.docx im Dateisystem. Pandoc kann die Datei nicht selbst herunterladen, da es sich bei dem komprimierten Dateiformat DOCX nicht um eine Textdatei handelt. Der zweite Schritt wandelt das Dokument nach Markdown um. Die Schalter -f und -t legen dabei die Dateitypen fest. Da Markdown sie an den Dateiendungen erkennt, sind die Schalter entbehrlich.

$ wget https://vomunterrichtzumlernen.files.wordpress.com/2015/02/manual-podiumsdiskussion.docx -O demo2.docx
$ pandoc -f docx -t markdown --atx-headers --toc --extract-media="." demo2.docx -o demo2.md

Wie wir noch sehen werden, könnten im konkreten Fall die Anweisungen --atx-headers (Überschriften durch vorangestelltes Raute-Zeichen auszeichnen statt durch Unterstriche) und --toc (Inhaltsverzeichnis erstellen) auch entfallen. Der Zusatz --extract-media weist das Programm an, alle Bilder zu extrahieren. Geben Sie dabei wie im Beispiel das aktuelle Verzeichnis an, überträgt das Programm sie in ein Unterverzeichnis mit der festen Bezeichnung media.

Die MS-Word-Datei, die freundlicherweise von Herrn Norbert Hillebrecht unter einer freien Lizenz zur Verfügung gestellt wurde, untersuchen wir im Folgenden ausschließlich in Hinblick auf die Gestaltung. Ein Vergleich von Original (Abbildung 1) und Markdown-Version (Abbildung 2) veranschaulicht die Arbeitsweise von Pandoc: Markdown beherrscht nur Formatierungen, die den Text strukturieren – Einfärbungen gehen verloren.

Abbildung 1: Ein Ausschnitt aus der Word-Datei zeigt, welche Formatierungen im Original zum Einsatz kamen.

Abbildung 2: Das Umsetzen der ursprünglichen Formate in Markdown gelingt nur bis zu einem gewissen Grad.

Ein genauer Blick in die Originaldatei zeigt, dass der Autor dort gar keine Überschriften festgelegt hat. Die Auszeichnungen erfolgten lediglich durch Hervorhebungen wie Fettschrift, Schriftgröße oder Farbe. Dadurch verliert der Text ein wichtiges Gestaltungselement, ein automatisches Erstellen eines Inhaltsverzeichnisses (--toc) gelingt so beispielsweise nicht.

Alle Aufzählungslisten kamen ebenfalls manuell zustande, das Nummerieren erfolgte von Hand. Aus diesem Grund kann Pandoc keine Spiegellisten erkennen und versucht daher, das Format so gut wie möglich wiederzugeben. Das Umsetzen der Tabellen in Markdown gelingt ebenfalls nicht ganz. Zum einen erstrecken sich die Zeilentrenner (-----) über viele Zeilen und erschweren das Lesen, zum anderen interpretiert die Software Absätze in Tabellen als neue Zeilen. Außerdem ignoriert Markdown Kopf- und Fußzeilen. Es besteht aber die Möglichkeit, die Originaldatei bei der Transformation in DOCX als Referenz anzugeben.

Pandoc kennt einige vordefinierte Variablen, die Sie am Textanfang durch drei Striche (---) klammern. Eine Struktur des Texts in Markdown finden Sie in Listing 2. Die Transformation nach Word geschieht mit folgendem Aufruf:

$ pandoc --toc --reference-doc=demo2.docx demo2r.md -o demo2r.docx

Über --reference-doc schaut sich der Konverter die Fuß- und Kopfzeilen aus der Referenzdatei demo2.doc ab. Darüber hinaus übernimmt er die Formate für Titel, Autor und Überschriften. Liegen in der Referenz keine Beschreibungen für Überschriften vor, wird ein Zwischenschritt notwendig. Am einfachsten führen Sie zunächst die Transformation ohne den Verweis auf die Originaldatei durch. Anschließend kopieren Sie das Ergebnis in die Referenzdatei. Passen Sie die Formate der Überschriften und Titel in Word Ihren Wünschen an, und wiederholen Sie die Transformation mit der erweiterten Referenzdatei.

---
author: Norbert Hillebrecht
title: Manual zur Vorbereitung und Auswertung der Veranstaltung
date: Datum
---
# Einleitung
Die Podiumsdiskussion wurde von der Profilklasse\\ 12 _MenschWelt_
vorbereitet
(...)
# Projektleitung, Malte Bartel
Folgende Aspekte sind zu beachten (...):
1. Verschiedene Projektbereiche definieren (...)
2. Gruppeneinteilung
3. Arbeitsaufträge
(...)

Fußnoten und Querverweise

Bei einer wissenschaftlichen Arbeit steht der Inhalt im Vordergrund. Die Formatierung erfolgt erst später, sobald der Inhalt geschrieben ist. Beliebt sind simple Textdateien, die keine Ansprüche an die Auswahl des Betriebssystems stellen und den einfachen Austausch mit Kollegen erlauben. Das Gerüst lässt sich schnell erstellen und mit Stichworten füllen, anschließend entsteht der ausformulierte Text. Bei Bedarf binden Sie noch Bilder und Tabellen ein.

Gleichungen folgen der Formatierungssprache von LaTeX. Mathematische Ausdrücke innerhalb des Texts schließen Sie mit einem Dollar-Zeichen ein. Komplexe mathematische Ausdrücke (Abbildung 3) stehen zwischen zwei Dollar-Zeichen in jeweils einer eigenen Zeile (Listing 3).

Abbildung 3: Pandoc erzeugt bei Bedarf selbst komplexe mathematische Formeln, die Sie im Quelltext in einem an LaTeX angelehnten Format eingeben.

$$
\bar{x}_{\mathrm{arithm}}  = \frac{1}{n} \sum_{i=1}^n{x_i}
$$ {#eq:item}

Mit dem Ausdruck @eq:item verweisen Sie bei Bedarf auf die Formel, der Sie die Referenz {#eq:item} mitgegeben haben. Das Referenzieren erfordert eine Erweiterung [4], die Sie als Filter beim Aufruf von Pandoc einbinden – Ähnliches gilt für Bilder [5] und Tabellen [6]. Listing 4 zeigt, wie Sie diese Addons in Pandoc integrieren. Die Fehlermeldung in der zweiten Zeile fordert zur Installation des Python-Paketmanagers Pip auf, falls dieser auf dem System noch fehlt.

$ pip install pandoc-fignos
The program 'pip' is currently not installed.
$ sudo apt install python-pip
$ sudo pip install pandoc-fignos
$ sudo pip install pandoc-eqnos
$ sudo pip install pandoc-tablenos

Pandoc bringt Werkzeuge mit, um die Quellenangaben aus Fachzeitschriften in das richtige Format zu bringen. Die Erläuterung der zugehörigen CSL-Formatdateien (“Citation Style Language”) würde allerdings den Umfang dieses Artikels sprengen. Ähnliches gilt auch für das Verwalten von Quelltexten in Formaten wie BibTeX oder BibLaTeX.

Verweise auf Überschriften und Fußnoten bringt Pandoc von Haus aus mit. Die Tabelle “Verweise” zeigt die Schreibweisen für die unterschiedlichen Referenzen. Um auch die anderen genannten Querverweise zu nutzen, rufen Sie das Programm wie in Listing 5 gezeigt auf. Aktuell arbeiten die Entwickler daran, die Filter zusammenzufassen und Referenzlisten automatisch zu erzeugen [7].

$ pandoc --filter pandoc-fignos --filter pandoc-eqnos --filter pandoc-tablenos --filter pandoc-citeproc myfile.md -o myfile.docx

Wie typische Textverarbeitungsprogramme kann auch Pandoc Änderungen in Dokumenten nachverfolgen. Mit dem Kommando aus der ersten Zeile von Listing 6 übernehmen Sie alle Änderungen aus dem Office-Dokument office.docx in das Markdown-Dokument myfile.md. Die Anweisung aus Zeile 2 verwirft alle Änderungen, die aus Zeile 3 protokolliert diese.

$ pandoc office.docx -o myfile.md --track-changes=accept
$ pandoc office.docx -o myfile.md --track-changes=reject
$ pandoc office.docx -o myfile.md --track-changes=all

Markdown greift auf HTML-Syntax zurück, sobald es auf nicht standardisierte Anweisungen trifft. So entsteht aus der in Abbildung 4 gezeigten Datei office.docx durch den Aufruf aus der letzten Zeile von Listing 6 der Markdown-Schnipsel aus Listing 7.

Abbildung 4: Markierungen zeigen an, an welchen Stellen Autoren ein Dokument im Verlauf der Arbeit geändert haben. Pandoc greift bei der Ausgabe in Markdown auf HTML-Syntax zurück.

~~~ {.html}
Beispiel für streichen,
und ein Beispiel für einfügen in Pandoc Markdown->Office.
~~~

Um Änderungen zu übernehmen, löschen Sie die Span-Tags aus der Markdown-Datei. Nach der Transformation von Markdown nach DOCX lassen sich die Markierungen für Überarbeitungen nicht mehr von denen unterscheiden, die ursprünglich im Office-Programm vorlagen. Fehlen Angaben zum Autor und Datum der Änderung, ergänzt das Programm sie aus dem Kontext.

Fazit

Dem Pandoc gelingt fast das Unmögliche: Es erstellt aus Office-Dokumenten einfache Textdateien, deren Formatierung sich an Markup-Sprachen anlehnt. Umgekehrt wandelt es Textdateien in wohlgeformte Dokumente für Büro-Textverarbeitungsprogramme um. Das einfachere Arbeiten mit sauber strukturierten Dokumenten entschädigt dafür, dass bei den Transformationen auch manchmal eine Formatierung unter den Tisch fällt.

Das Erzeugen von Office-Dokumenten im ODT- oder DOCX-Format bildet nur einen Teilaspekt von Pandoc. Die eigentliche Stärke des Programms verbirgt sich im Generieren von HTML, TeX, LaTeX und PDF. Die Komplexität der entsprechenden Auszeichungssprachen erfordert jedoch eine intensive Auseinandersetzung mit den Sprachelementen. Zumindest im Ansatz folgt die Bearbeitung jedoch den hier vorgestellten Regeln.