Markdown und Co.

Eine effiziente Vorgehensweise ist es, das Schreiben der Inhalte von der endgültigen Formatierung zu trennen. Trotzdem sollen die Formatierungen schon im ASCII-Text (naja, Unicode-Text) erkennbar sein. Weitere Vorteile ergäben sich, wenn man eine Versionsverwaltung wie Git einsetzen würde, da diese zeilenweise Textdateien versioniert. Damit kann man z.B. bei einem Buch, das in einer Markdown-Datei geschrieben wird, jede Änderung nachvollziehen. Dies ist mit einem Textverarbeitungsprogramm (Word, Writer) so nicht möglich. Mein restlicher Workflow ist allerdings Cloud-basiert, so dass Git eine zusätzliche und für mich nicht vorteilhafte Verkomplizierung wäre.

Idee

Markdown ist bekanntlich eine vergleichsweise einfache Methode um sofort gut lesbaren strukturierten Text zu schreiben. Ohne Menüs, eine Maus oder Tastatur-Shortcuts zu nutzen kann man Texte mit hierarchischen Überschriften, Fett/Kursivschrift, Tabellen, Zitaten, Links, Fußnoten und Code-Fragmenten schreiben. Es sind bereits einige Bücher sowie viele E-Books in Markdown geschrieben worden.

Mein persönlicher Bedarf:

Ich verfasse für den Physik- und Informatikunterricht Skripte zu meinem Unterricht (primär für mich und als Tafelbild - kein Lehrwerk). Dabei werden die üblichen Features genutzt: Hierarchische Überschriften, Abbildungen, Einteilung in Spalten (meist für Beschreibungen neben Bildern), Mathematische Formeln (in TeX), Tabellen, Quelltexte (in unterschiedlichen "Sprachen"), Definitionen usw.

Dies alles geht problemlos in Markdown mit den Erweiterungen von Pandoc und mir (s.u.). Da eine Funkübertragung an die digitalen Tafeln am ehesten mit iPads funktioniert, erzeuge ich zwei PDF-Ausgaben: Slides im Querformat für die Tafel und in A4 um es ggf. digital zur Verfügung zu stellen. PDF-Dateien haben den Vorteil, dass alle Daten in einer Datei sind und diese final formatiert ist.

Meine Ergänzungen

Ich habe einige Ergänzungen in CSS geschrieben bzw. in einem Python-Präprozessor programmiert.

Quelltexte

werden in einem hellgrauen Kasten angezeigt, der rechts oben z.B. ein oranges "JS" enthält, wenn der Quelltext Javascript ist. Entsprechend für alle bei mir vorkommenden Sourcen (Python, Java, HTML, CSS, Bash usw.).

```{.java .execute}
System.out.println("Hello World");
```

System.out.println("Hello World");

Hello World

Mermaid

ist eine textuelle Beschreibung von Diagrammen. Siehe auch deren Live-Editor. Dort geklicktes kann hier als Quelltext eingefügt werden und ergibt z.B.:

```mermaid
flowchart LR
    A[Idee] -->|Nachdenken| B(Planen)
    B --> C{Evaluieren}
    C -->|fragwürdig| D[Einstellen]
    C -->|realistisch| E((Durchführen))
    C -->|unausgegoren| B
```

flowchart LR
    A[Idee] -->|Nachdenken| B(Planen)
    B --> C{Evaluieren}
    C -->|fragwürdig| D[Einstellen]
    C -->|realistisch| E((Durchführen))
    C -->|unausgegoren| B

Marginalien

Randbemerkungen, die aber bei Platzmangel wieder in den Fließtext zurückkehren: Eine
Beispielmarginalie.

Praxis

Dienste wie z.B. Github zeigen Markdown-Dateien automatisch als gut aussehendes HTML an. Aber jeder kann selbst Tools einzusetzen, die optisch ansprechende Dokumente in vielen verschiedenen Formaten erzeugen können. Ich ziele derzeit nur auf HTML und daraus erzeugtes PDF (so werden beide mit CSS formatiert). [Man kann aber auch von Pandoc direkt PDF-, odt- oder epub-Dateien erzeugen lassen. Zu den Möglichkeiten siehe hier.]

• Der Markdown Editor Ghostwriter hilft mir reinen Markdown-Text zu verfassen.
• Die Konvertierungssoftware Pandoc erzeugt aus einer Markdown-Datei eine HTML-Datei.
• Den Ausdruck der HTML-Datei in eine PDF-Datei erledigt der Chromium-Browser oder auch Google-Chrome von der Kommandozeile aus.

Pandoc alleine erzeugt eine korrekte, aber nicht so hübsche HTML-Datei. Aber man kann mit der Kommandozeilenoption -H eine zusätzliche Datei in den Header der HTML-Datei einfügen lassen. Damit ist es einfach viele CSS-Styles einzubinden. Am Ende kann man mit -F eine weitere Datei als eine Art Fußzeile einfügen lassen. Dann gibt es noch den Befehl -``-toc, der ein Inhaltsverzeichnis generiert, das wiederum erst nach einer Formatierung mit obigen Styles wunschgemäß aussieht.

Chromium/Chrome kann über die Kommandozeile eine HTML-Datei direkt als PDF-Datei "ausdrucken". Dabei werden Formatierungsanweisungen der HTML-Datei beachtet, z.B. page-break-before, so dass man Kapitel oder Folien mit einer neuen Seite anfangen lassen kann. Man kann sogar das Aussehen der PDF-Datei komplett anders gestalten, da dabei @media print { ... } beachtet wird. Selbst Papiergrößen in CSS werden berücksichtigt.

Inzwischen werden bei mir mehrere Dateien inkludiert, die CSS-Zeilen regelmäßig ergänzt sowie der Aufruf von Pandoc und Chrome per Skript automatisiert. Deshalb benötige ich einen Prozess um diesen Workflow auf mehreren Rechnern identisch durchführen zu können:

• Ich erstelle dazu ein Dockerimage, von diesem ein
• Backup (xz-komprimiert), das
• auf andere Rechner kopiert und
• dort mit docker load backup.xz geladen wird (ohne Auspacken).
• Ein Pythonskript im Userverzeichnis ruft dieses dockerimage für pandoc und Chrome auf und regelt ansonsten die Konvertierung in HTML, DIN-A4-PDF und ggf. SLIDES-PDF. Dazu überwacht es auch Verzeichnisse auf Änderung und legt ggf. Inhaltsverzeichnisse von ihnen an, welche in den HTML-Dateien eingeblendet werden können (sidebar).

Die Vorgehensweise wird bei Gelegenheit ausführlicher dokumentiert.

Christian Bienmüller