Erstellen Sie eine Publikationskette mit Pandoc und Docker

Heute werden wir uns genauer ansehen, wie Fachleute die Hilfe von Pandoc in Anspruch nehmen können, um eine robuste und einfach zu implementierende Publikationskette zu erstellen. Pandoc ist ein extrem einfaches, aber leistungsstarkes Tool, mit dem Benutzer Dokumente je nach Bedarf in verschiedene Formate konvertieren können.

Es kann die Dokumentation und Veröffentlichung erheblich vereinfachen oder sogar einige neue Automatisierungsmöglichkeiten eröffnen. Das Beste: Pandoc setzt auf Git-freundliches Markdown, sodass Sie ohne zusätzlichen Aufwand auch ein Versionskontrollsystem für Ihre Dokumentation implementieren können.

Apropos Ärger, wir verlassen uns auf ein Docker-Image, um Pandoc und LaTeX mit einem einfachen Pull zu installieren. Die Installation von Software kann zeitaufwändig sein, und die Einrichtung einer funktionierenden Softwareumgebung von Grund auf neu, wenn Sie ein neues Projekt starten, ist kaum produktiv. Docker hilft, diese Probleme zu mindern, indem es Benutzern ermöglicht, alles innerhalb von Minuten einzurichten, unabhängig von der Plattform.

Darüber hinaus ist es nicht ungewöhnlich, dass Arbeitgeber verlangen, dass Sie Ihre eigene Computerhardware bereitstellen. Dies wird oft als Bring Your Own Device (BYOD) bezeichnet, und vergessen wir nicht, dass die COVID-19-Pandemie dazu geführt hat, dass die Arbeit von zu Hause aus viel häufiger geworden ist. Ohne Lösungen wie Docker wäre es schwierig, Anwendungen zu unterstützen, die auf unterschiedlicher Hardware und Betriebssystemen wie Windows, macOS und Linux ausgeführt werden.

Beginnen wir mit einem genaueren Blick auf Docker-Container und -Images, bevor wir mit Pandoc fortfahren.

Docker zur Rettung

Die Verwendung von Docker-Containern kann die Notwendigkeit beseitigen, mehrere Softwareanwendungen auf einem neuen Computer zu installieren. Vorgefertigte Docker-Images sind auf Docker Hub für eine große Anzahl von Anwendungen verfügbar. Führende Cloud-Anbieter wie AWS, Azure und Google bieten alle Containerregistrierungen an. Es gibt viele andere Registrierungen von Drittanbietern, darunter GitLab und Red Hat OpenShift.

Es ist wahrscheinlich, dass für die meisten (wenn nicht alle) Anwendungen ein Image verfügbar ist. Das bedeutet, dass die meisten Anwendungen und ihre Abhängigkeiten nicht installiert werden müssen. Die Anwendung kann einfach in einem Docker-Container ausgeführt werden. Dadurch werden Probleme beseitigt, die mit Teammitgliedern verbunden sind, die Anwendungen auf unterschiedlicher Hardware und unterschiedlichen Betriebssystemen ausführen. Das gleiche Image kann verwendet werden, um Container auf jedem System auszuführen, das sie ausführen kann, und Docker-Spezialisten können diesen Prozess extrem schnell und effizient gestalten.

Pandoc Anwendungsfall: Dokumentation

Die Dokumentation kann in mehreren verschiedenen Formaten erforderlich sein. Dasselbe Dokument muss möglicherweise in verschiedenen Formaten verfügbar sein, z. B. HTML für Präsentationen und PDF für Handouts. Das Konvertieren zwischen Dateiformaten kann mühsam sein und viel Zeit in Anspruch nehmen. Eine gute Lösung ist eine Publikationskette mit einer einzigen Quelle der Wahrheit. Alle Dokumente sollten in derselben Sprache verfasst sein. Es sollte eine textbasierte Sprache sein, da sie einfacher zu versionieren und in Git-Repositories zu speichern ist.

Markdown ist eine gute Wahl, um eine Single Source of Truth zu schaffen. Software, die Markdown-Dokumente in eine Vielzahl anderer Formate konvertieren kann, ist leicht verfügbar und tendenziell zuverlässig.

Pandoc

Pandoc ist ein Softwarepaket, das Dokumente in verschiedene Formate konvertieren kann. Insbesondere kann es Markdown in HTML, PDF und andere weit verbreitete Formate konvertieren. Der Konvertierungsprozess kann mithilfe von Vorlagen und Metadaten in der Markdown-Quelle angepasst werden.

Pandoc benötigt eine LaTeX-Installation, um PDF-Dateien zu erstellen. Die Installation von Pandoc und LaTeX ist ziemlich zeitaufwändig. Glücklicherweise gibt es ein Docker-Image namens pandoc/latex , das die Installation von etwas anderem als Docker überflüssig macht.

Docker-Befehle

Es muss ein passendes Docker-Image gefunden oder erstellt werden, das die notwendige Software enthält. Es ist ratsam, das Image in die lokale Registrierung zu ziehen, da der Download einige Zeit in Anspruch nehmen kann.

 docker pull pandoc/latex

Um einen Befehl in einem Docker-Container auszuführen, ist ein Wrapper erforderlich, um den Docker-Container auszuführen und einen Befehl im Container auszuführen. Eine gute Lösung hierfür ist das Schreiben einer Shell-Funktion auf einem macOS- oder UNIX/Linux-System. Die Funktion kann in beliebige Anmeldeskripts oder in eine separate Datei wie $HOME/.functions . Es ist auch möglich, ein Skript oder einen Alias ​​mit der gleichen Funktionalität zu schreiben.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Diese Funktion bewirkt Folgendes:

• Es gibt den Befehl auf dem Bildschirm aus.
• Es führt einen Docker-Container aus dem pandoc/latex -Image aus.
• Die Option -it erstellt eine interaktive Terminalsitzung und macht die Ausgabe des Befehls sichtbar.
• Die Option --rm löscht den Container, sobald der Befehl beendet ist.
• Die Option -v $PWD:/work hängt das aktuelle Verzeichnis auf dem Host in das Verzeichnis /work im Container ein.
• Das -w /work macht das Verzeichnis /work im Container zum Arbeitsverzeichnis.
• Das letzte pandoc "$@" führt den pandoc Befehl im Container aus und übergibt alle an die Funktion übergebenen Befehlszeilenoptionen.

Eine Shell oder ein Skript muss die Funktion in den Speicher laden.

 . $HOME/.functions

Die Funktion ist jetzt ein eigenständiger Befehl und verhält sich genauso, als ob die pandoc Binärdatei lokal installiert wäre. Dieser Ansatz kann für jeden Befehl verwendet werden, der in einem Docker-Image verfügbar ist.

Markdown zu HTML

Um Markdown in HTML umzuwandeln, ist es besser, eine Vorlage und Metadaten im Markdown zu verwenden.

Markdown-Metadaten

Die Markdown-Quelle kann einen Header-Abschnitt haben, der beliebige Metadaten enthalten kann. Die Metadaten haben die Form von Schlüssel-Wert-Paaren. Die Werte können in der HTML-Vorlage ersetzt werden.

 --- title: Document title links: prev: index next: page002 ...

Die Kopfzeile beginnt mit einer Zeile, die nur drei Bindestriche enthält --- . Es endet mit einer Linie, die nur drei Punkte enthält ... . Schlüssel sind einzelne Wörter, gefolgt von einem Doppelpunkt und seinem Wert. Schlüssel können verschachtelt werden. Das Beispiel zeigt die Definition von Schlüsseln namens title, links.prev und links.next .

Bei diesem Ansatz wird für jede Seite eine separate Datei verwendet. In diesem Beispiel ist die vorherige Seite index.md , die aktuelle Seite page001.md und die nächste Seite page002.md . In der Praxis würden aussagekräftigere Dateinamen verwendet, um das Neuordnen und Einfügen von Seiten zu erleichtern.

HTML-Vorlage

Eine HTML-Vorlage ist einfach eine HTML-Datei. Metadatensubstitution und einfache Kontrollstrukturen können zwischen Dollarzeichen hinzugefügt werden. Hier ist ein einfaches Beispiel einer HTML-Vorlage für Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

Das Beispiel zeigt eine Vorlage. Der $body$ wird durch den in HTML konvertierten Markdown-Text ersetzt. Die bedingten Anweisungen erzeugen den HTML-Link nur, wenn die Metadaten im Markdown-Header definiert sind.

Generieren von HTML aus Markdown

Pandoc muss lediglich mitgeteilt werden, wie die Eingabe- und Ausgabedateien sowie alle Vorlagendateien heißen. Das standardmäßige Eingabedateiformat ist Markdown . Es kann das Ausgabedateiformat von der angegebenen Ausgabedateierweiterung ableiten.

Die Befehle zum Generieren von Ausgaben können ein Skript oder ein Makefile sein.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Für jede .md -Datei im Project -Verzeichnis wird eine entsprechende .html -Datei im HTML/Project -Verzeichnis erstellt, wenn die Ausgabedatei älter als die Eingabedatei oder nicht vorhanden ist.

Beamer PDF aus Markdown generieren

Beamer ist ein LaTeX-Paket zur Erstellung von Präsentationen. Die Ausgabe ist eine PDF-Diashow.

Für die Generierung des Beamer-PDFs können die gleichen Markdown-Quelldateien verwendet werden.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Die Befehlsdetails sind:

• Die -t beamer besagt, dass LaTeX und Beamer verwendet werden, um das PDF zu generieren.
• Die Option -o gibt die Ausgabedatei an.
• Die -V -Optionen wählen das Beamer-Design und das Farbdesign aus.
• Der Befehl endet mit einer Liste von Markdown-Dateien, die in der angegebenen Reihenfolge verkettet werden.

Die gesamte Verarbeitung wird in einem Docker-Container durchgeführt.

Markdown zu PDF

Das Konvertieren eines Markdown-Dokuments in ein PDF-Dokument ist ebenfalls recht einfach. PDF wird immer generiert, indem zuerst der Markdown in LaTeX konvertiert wird. Metadaten können dem Markdown-Header hinzugefügt werden, um die Ausgabe anzupassen, z. B. das Festlegen der Papiergröße und der Randgröße.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

PDF aus Markdown generieren

Der Befehl zum Konvertieren des Markdowns in PDF ist einfach:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

Die Option -s erstellt ein eigenständiges Dokument.

Fazit

Es ist nicht mehr notwendig, viele Tage mit der Installation von Software zu verbringen. Durch einfaches Ausführen eines Befehls in einem Docker-Container entfällt die Installation. Viele Anwendungen haben passende Docker-Images auf Docker Hub. Wenn die Software aktualisiert werden muss, ziehen Sie einfach das neueste Docker-Image.

Das Einrichten eines neuen Computers ist nur eine Frage der Installation von Docker, des Abrufens der erforderlichen Images und des Erstellens einiger Skripts.

Es ist nicht mehr notwendig, Dokumente in unterschiedlichen Formaten zu erstellen. Ein einziges Format wie Markdown kann für alle Dokumente verwendet werden. Tools wie Pandoc können dann Dokumente aus Markdown in einer Vielzahl unterschiedlicher Formate generieren.

Da Markdown eine Textdatei ist, ist beim Einchecken in ein Git-Repository ein vollständiger Versionsverlauf verfügbar. Git-Repositories rendern Markdown auch automatisch und ermöglichen es Benutzern, Änderungen zu kommentieren, ohne unordentliche Änderungsverläufe in der Dokumentdatei selbst verwenden zu müssen.