Einfachen Text schreiben -- viele Formate erhalten

Jeder Software-Entwickler sollte sich darum kümmern, dass seine Programme durch eine ordentliche Dokumentation abgedeckt sind. Aber viele Programmierer erledigen das äußerst ungern. Darum ist die Erstellung von Dokumentation häufig ein "Stiefkind" von Projekten.

Viele Software-Benutzer würden gerne etwas zur Dokumentation beitragen und dadurch zu Committern werden -- und manche tun es schon, oft sogar im Zusammenhang mit mehreren Projekten. Aber dann verwenden unterschiedliche Projekt vielleicht jeweils andere Formate und Werkzeuge zum Schreiben: OpenDocument, HTML, LaTeX, DocBook, ...

Wäre es nicht viel besser, alles in reinem Text zu schreiben? Und dann aus diesem Text automatisiert das End-Format zu erzeugen, welches man verwenden möchte? Oder gar alle möglichen Endformate?

Mit der einfachen Text-Auszeichnungssprache Markdown ist es möglich. Zum Konvertieren in beliebige Zielformate verwendet man das Kommandozeilen-Tool pandoc. Zur Automatisierung ein Makefile...

---

Markdown ist ein dermaßen einfaches Textauszeichnungsformat, dass man bei Kenntnis von ca. 12 verschiedenen, einfachen, sehr intuitiv zu erlernenden Formatierungs-Regeln bereits sehr anspruchsvolle Dokumente zustande bringt -- und zwar in allen möglichen Formaten, und in sehr vielen anpaßbaren Stilen.

1. Standard-Absätze
2. Eingerückte Absätze (Zitat-Blöcke)
3. Überschriften erster, zweiter, ... sechster Ordnung
4. Nummerierte Aufzählungen (wie diese hier)
   • verschachtelte Aufzählungen (wie diese hier)
   • (ich bin mir nicht sicher, ob ich dies nicht besser als 14. Regel deklarieren sollte)
5. Un-nummerierte Aufzählungen
6. Code-Beispiele: pandoc --to=html erzeugt HTML-Ausgabe
7. kursiv hervorgehobene Wörter
8. fett hervorgehobene Wörter
9. fett+kursiv hervorgehobene Wörter
10. Hyper-Links
11. Bilder (Beispiel siehe unten)
12. Code-Blöcke (Beispiel siehe unten)
13. Tabellen

Code-Block-Beispiel

pandoc \
    --toc \
    --slide-level=2 \
    --to=beamer \
    --highlight-style=zenburn \
    --chapters \
    --normalize \
    --filter=pandoc-citeproc \
    --latex-engine=xelatex \
    --from=markdown+mmd_title_block+pandoc_title_block+raw_html+markdown_in_html_blocks \
    --output=orr2014-paper.pdf \
     -V geometry:margin=1.8cm \
     -V geometry:paperwidth=21cm \
     -V geometry:paperheight=29.7 cm \
      orr2014-paper.mmd

 

Bild-Beispiel

Wer komplexere Formatierungen benötigt, kann innerhalb des Markdown-Quellcodes auch HTML-Schnipsel verwenden. pandoc gibt diese beim Übersetzen 1:1 in das Zielformat weiter. (Falls das Ziel-Format LaTeX oder PDF ist, kann man sogar LaTeX-Schnipsel einbetten.)

Die Konvertierung des Markdown-Quelltextes in das gewünschte Dokumenten-Format erfolgt durch das Kommandozeilen-Tool pandoc. Dabei stehen eine ganze Reihe unterschiedlicher Ziel-Formate zur Wahl: erwähnt seien hier nur Open/LibreOffice ODT, MS Word DOCX, LaTeX, DocBook, HTML, PDF, EPUB, EPUB3, ConTeXt und MediaWiki.

Das endgültige Aussehen der Dokumente lässt sich dadurch beeinflussen, dass man eigene CSS-Dateien, Vorlagen- oder Referenz-Dokumente einbindet. Ansonsten erhält man schlichte Dokumente mit den jeweils vor-eingestellten Stilen. Beim Bau eigener CSS-Stile sind einem versierten Anwender so gut wie keine Grenzen gesetzt, bei der Erstellung eigener Vorlagen und Referenzen gibt es ebenfalls erstaunlich viele Möglichkeiten.

Der Workshop gliedert sich in mehrere Teile:

1. Einrichten der Erstell-Umgebung: Installation der neuesten Version von pandoc aus den entsprechenden Quellen
2. Kurz-Vorstellung der Markdown-Syntax
3. Kurz-Vorstellung von pandoc
4. Besprechung des verwendeten Makefile
5. Erstellung eigener Dokumente in mehreren Formaten aus demselben Markdown-Quellcode

Die Workshop-Teilnehmer erhalten Zugriff auf ein Zip-Archiv mit folgendem Inhalt:

• Die in diesen Workshop verwendeten Vortrags-Präsentationen.
• Zwei (oder mehr) Papers, welche der Autor über das Pandoc + Markdown-Duo geschrieben hat.
• Eine Reihe von Markdown-Dateien, die als Ausgangspunkt der Beispiel-Dokumente dienten.
• Ein Makefile (funktionierend unter Mac OS X oder Linux) zum Generieren der fertigen Beispiel-Dokumente.
• Die für die unterschiedlichen Dokumenten-Stile der Beispiele verwendeten CSS- und Referenz-Dateien.
• Sonstige interessanten Dateien.