Charts in Markdown

“Jetzt ist er ganz bekloppt” könnte der normale Leser von mir denken. Schließlich nutze ich für meinen Dokumenten-Workflow¹ reinen (Markdown-)Text als “Single Source of Truth”² und nun komme ich mit dem Wunsch um die Ecke, in Übersichten schöne Diagramme zur Visualisierung zu nutzen. Keine ASCII-Balken! Nein, runde Piecharts sollen es sein. Genau das, was Manager und Entscheider sehen wollen. Klingt nach einem unüberwindbaren Zielkonflikt. Mit der gesunden Portion Selbstbewusstsein behaupte ich, das elegant gelöst zu haben.

Ich nutze in meinem Dokumenten-Workflow bereits Snippets.³ Das sind Platzhalter im Fließtext für Textbausteine, die von Hilfsskripten mit den gewünschten Inhalten gefüllt werden. Damit ich beispielsweise in Projekten nicht immer den Namen einer Organisation schreiben und beim nächsten Projekt anpassen muss, verwende ich das Snippet {{ snippet: global_text_organisation }}. Oder ich lasse mir das Datum der letzten Änderung aus Git mit {{ snippet: document_last_change }} einfügen. Warum dann nicht auch ein Snippet für Piecharts?

{{ snippet: piechart id="name" values="20,80" labels="erledigt, nicht erledigt"}}

Das Parsen der Parameter ist dabei kein Problem. Dafür setze ich auf awk, dem besten Werkzeug für genau diesen Anwendungsfall.⁴ Die eigentliche Herausforderung für mich bestand darin, das Ganze mit LaTeX via Pandoc in ein PDF zu bringen.

Ich arbeite bereits mit LaTeX-Vorlagen sowie Overrides, etwa um zwischen Hoch- und Querformat zu wechseln. An dieser Stelle kommen TikZ⁵ als Grafiksystem für LaTeX und \expandafter ins Spiel.⁶ Die notwendigen Anweisungen für die Charts hänge ich einfach in meine bestehenden .tex-Overrides. Individuell für jedes Piechart mit seiner eindeutigen id.

Doch hier aufzuhören wäre zu kurz gedacht. Ich möchte Dokumente nicht manuell pflegen müssen. Insbesondere nicht mit der latenten Gefahr, veraltete oder falsche Werte zu verwenden.

Ein Piechart muss “in die Dokumente hineinschauen”, es muss deterministisch prüfen, ob ein bestimmter Status wie “Freigegeben” in Form einer ausgewählten Checkbox [x] Freigegeben gesetzt ist.

Diese Aufgabe übernimmt bereits ein Snippet namens document_checkbox. Bislang jedoch nur für einzelne Dateien. Daher habe ich einen Wrapper mit dem Namen folder_checkbox gebaut. Dieser durchsucht rekursiv alle Dateien eines Ordners und nutzt intern das bestehende document_checkbox.

In der objektorientierten Programmierung würde man sagen: Ich habe Vererbung genutzt und den file Parameter überladen.⁷ Anstelle einer einzelnen Datei wird jetzt ein Ordnerpfad erwartet. Selbstredend wird die Ordnerstruktur rekursiv durchsucht. Hier zum Beispiel das komplette /tisax-Verzeichnis mit allen Unterordnern und Dokumenten:

{{snippet: folder_checkbox file="tisax/" action=count_checked from=3 to=4}}

Das Ganze kombiniert mit der Gesamtanzahl aller Dokumente (action=count_all) und ich habe ein dynamisches Piechart. Die beiden Snippets werden einfach in das Piechart-Snippet eingesetzt:

{{snippet: piechart 
  id="name" 
  reference={{snippet: folder_checkbox file="tisax/" action=count_all from=3 to=4}}
  values={{snippet: folder_checkbox file="tisax/" action=count_checked from=3 to=4}}
  labels="Anzahl der freigegebenen Dokumente"
}}

Und voilà! Das Piechart aktualisiert sich automatisch anhand der Inhalte der Dokumente. Mit Snippets und etwas Bash-Logik habe ich mir eine Menge Arbeit erspart und gleichzeitig die Fehleranfälligkeit deutlich reduziert.

Dokumente systematisch denken.

In diesem Sinne,
Tomas Jakobs