Nachhaltige Skripte

26.6.2021

Kennst du das? Du bereitest die nächste Veranstaltung vor und erstellst dein Skript mit allen Abläufen, Infos und Methoden. Das eine Element nimmst du aus dieser Word-Datei, das andere aus dieser OpenOffice-Datei, diesen Inhalt kopierst du von einer Webseite. Jetzt noch ein Bild dazu. Und nun möchtest du es auch noch alles so formatiert haben, wie es immer aussieht.

Kennst du das?

• Du bereitest die nächste Veranstaltung vor und erstellst dein Skript mit allen Abläufen, Infos und Methoden.
• Das eine Element nimmst du aus dieser Word-Datei, das andere aus dieser OpenOffice-Datei, diesen Inhalt kopierst du von einer Webseite.
• Jetzt noch ein Bild dazu.
• Und nun möchtest du es auch noch alles so formatiert haben, wie es immer aussieht.

Wenn ich die Zeit zusammenrechne, die ich damit verbracht habe vernünftige Word-Dokumente mit Skripten zu erstellen oder wie ich Papierskripte aus hunderten Einzeldateien zusammengedruckt habe, wird mir schlecht. Die Probleme heißen (unflexible) Textverarbeitung und die eigene Gewohnheit im Umgang mit Textdateien. Als ich mal wieder zwanzig Einzeldateien ausdruckte, um Skripte für das Seminarteam zu erstellen, beschloss ich damit Schluss zu machen. Und suchte nach einer Alternative, die nachhaltiger ist und mir das ewig neue Zusammenstellen erspart.

Voraussetzungen

markdown

Du musst die markdown-Syntax kennenlernen. Das geht schnell und kostet dich vielleicht eine Stunde Lebenszeit plus regelmäßiges Üben beim Anwenden.

Pandoc

Du musst den Dokumenten-Prozessor Pandoc installieren. Dieser wird für uns aus einzelnen Dokumenten eine schöne Ausgabedatei erstellen.

LaTeX

Da Pandoc selbst keine PDF-Dokumente erstellen kann, musst du zusätzlich LaTeX installieren. LaTeX ist ein Paket, dass deinem Rechner den Textsatz TeX beibringt und ist zudem modular erweiterbar.

Sowohl Pandoc, als auch LaTeX sind keine Programme mit grafischer Oberfläche, wie du es z. B. von OpenOffice gewohnt bist. Du findest sie etwa nicht unter deinen Programmen aufgeführt. Wenn das neu für dich ist: Lass dich davon nicht abschrecken. Wir werden im Laufe des Prozesses Pandoc über das Terminal zeigen, was wir ausgeführt haben möchten. Das sind wenige Zeichen Code mit großer Wirkung.

Vorgehensweise

markdown wird unser neuer Text-Standard

Wir werden unsere Inhalte, also z. B. Methoden und Abläufe, einzeln als markdown-Dateien erstellen. Die Aufteilung bietet sich insofern an, als dass so Änderungen einfacher vorgenommen werden können und wir später modularer Arbeiten können. Es erleichtert auch das Arbeiten im Team und sorgt schließlich dafür, dass wir in riesigen Textdateien nicht den Überblick verlieren. Eine grundsätzliche Etablierung von markdown ist kein grundlegender Verzicht auf Programme wie OpenOffice. markdown kann als Quellcode, als Ausgangsformat betrachtet werden, mit dem ich nahezu beliebige andere Formate erzeugen kann.

Wir legen einen Struktur-Standard fest

Damit wir uns die Arbeit später etwas erleichtern, hilft ein Struktur-Standard für Überschriften. Wir werden später mehrere Dokumente zusammenfügen und arbeiten dabei mit mehreren Hierarchien – die müssen ja dann auch zueinander passen. Ein guter html-Standard ist es, innerhalb von Dokumenten mit der dritten Überschriftenebene zu beginnen. So bleiben uns noch zwei Ebenen für weitere Unterteilungen über unseren Inhalten.

Ein späteres Ändern ist auch möglich und auch automatisiert möglich. Es könnte aber nervig werden, z. B. wenn in markdown auch die ===und ---Auszeichnungen für Überschriften verwendet werden.

Wir sammeln unsere Skript-Elemente in einem Ordner

Zur Skripterstellung legen wir alle Elemente in einen Ordner. Durch die Dateibenennung können wir die Reihenfolge festlegen, in der die Dokumente aufgerufen werden. Hier sind mehrere Systeme denkbar und je nach Anwendungsfall gibt es bestimmt passende Systeme.

Wir legen die Metadaten fest

Zusätzlich zu den Inhalten legen wir eine Datei an, die Metainformationen für unser Skript enthält. Hier können wir das Aussehen und den Textsatz für das komplette Skript definieren.

Wir lassen Pandoc für uns ein Skript erstellen

Eine Kommandozeile genügt nun, um unser Skript erstellen zu lassen.

Beispiel

In meinem Team veranstalten wir im Jahr etwa 30 Seminarwochen. Die sind strukturell alle gleich und variieren inhaltlich. Es gibt viele wiederkehrende Elemente, aber auch eher spezielle und aktuelle Themen. Wir erstellen unsere Methoden und Abläufe in markdown-Dateien. Dafür haben wir eine Vorlage erstellt, damit die Dokumente immer die gleichen Elemente aufweisen. Alle (für gut befundenen) Seminarmethoden landen dann in einem Cloud-Ordner, die Dateien erhalten eine eindeutige Nummer und werden mit Schlagworten versehen. So sind sie unabhängig von z. B. Themenordnern oder weiteren Verschachtelungen auffindbar und können wiederverwendet und weiterentwickelt werden.

Für ein neues Seminar wird ein Plan erstellt, der vom Seminarteam ausgearbeitet wird. Dabei werden alte Methoden übernommen, angepasst oder weiterentwickelt und neue Methoden geschrieben. Diese Methoden landen zunächst im gemeinsamen Seminarordner und werden anhand des Ablaufs nummeriert. Hinzu kommen noch strukturierende Dateien, die z. B. Überschriften für die Wochentage festlegen.

Als letztes kommt eine .yaml-Datei mit den passenden Metainformationen hinzu und Pandoc erstellt das fertige Skript, dass wir für die Teammitglieder nur noch ausdrucken müssen. Nach dem Seminar werden Änderungen oder Erfahrungen/ Tipps in den markdown-Dateien ergänzt, um sie dann wieder im Cloud-Ordner einzusortieren oder neu anzulegen.

Mit dieser Arbeitsweise können wir an bestehende Erfahrungen anknüpfen und haben keinen Stress beim Zusammenkopieren oder Umformatieren von Dokumenten. In meinen Augen sehr produktiv und nachhaltig.

Schritt-für-Schritt

Quelldateien erstellen (Skriptinhalte)

Wenn du nicht alle Dateien selbst erstellen möchtest, kannst du auch abkürzen und hier alle fertigen Dateien als Archiv laden. Macht es aber nicht unbedingt nachvollziehbarer.

Arbeitseinheiten

Wir erstellen jetzt drei Beispiel-Arbeitseinheiten.

Erste Arbeitseinheit am Montag

Speichern als: 20-1-10 Erste Arbeitseinheit.md

      ###### Erste Arbeitseinheit am Montag

      Das hier ist die erste Arbeitseinheit.

          * Erst das
          * dann das
          * und am Ende das.
      

Erste Arbeitseinheit am Dienstag

Speichern als: 20-2-10 Erste Arbeitseinheit.md

      ###### Erste Arbeitseinheit am Dienstag

      Das hier ist die erste Arbeitseinheit.

      * Erst das
      * dann das
      * und am Ende das.
      

Abschlussreflexion

Speichern als: 20-5-10 Abschlussreflexion.md

      ###### Abschlussreflexion

      *REF fragen die Gruppe*

      "Wie fandet ihr die Woche?"

      Fertig.
      

Wie besprochen beginnen wir in unseren Inhalten mit der dritten Überschriftenebene und lassen Ebene 1 und 2 reserviert für unsere Skriptstruktur. Was nicht sofort auffällt, aber sehr wichtig ist: Die Texte beginnen und enden mit einer leeren Zeile. In markdown sind mehrere leere Zeilen irrelevant, da sie später ignoriert werden. Eine einzelne Leerzeile kann aber einen großen Unterschied machen, denn unter Umständen werden Überschriften ohne vorangehende Leerzeile nicht korrekt interpretiert. Da wir später Pandoc alle Einzeldateien hintereinander schreiben lassen, ist eine Leerzeile wichtig. Ich beginne und beende aus Gewohnheit jedes markdown-Dokument mit einer Leerzeile.

Strukturierende Inhalte

Wir möchten die Arbeitseinheiten nach Tagen gliedern und zusätzlich zum Programm ein Orga-Kapitel anlegen.

Orga-Kapitelüberschrift

Speichern als: 10 Organisatorisches.md

      # Organisatorisches

      **Programm-Kapitelüberschrift**
      

Speichern als: 20 Programm.md

      # Programm
      

Tages-Überschriften

Speichern als: 20-1 Montag.md, 20-2 Dienstag.md, 20-3 Mittwoch.md, 20-4 Donnerstag.md, 20-5 Freitag.md

(Mit jeweils anderem Inhalt)

      ### Montag
      

Dieses Dateien sollten jetzt in einem Ordner liegen:

Beispiel
         |-10 Organisatorisches.md
         |-20 Programm.md
         |-20-1 Montag.md
         |-20-1-10 Erste Arbeitseinheit.md
         |-20-2 Dienstag.md
         |-20-2-10 Erste Arbeitseinheit.md
         |-20-3 Mittwoch.md
         |-20-4 Donnerstag.md
         |-20-5 Freitag.md
         |-20-5-10 Abschlussreflexion.md

Wie du siehst, haben wir die Dateinamen nicht per Zufall gewählt, denn wir möchten, dass die Dokumente anhand des Dateinamens so sortiert werden, dass sie unserer Reihenfolge im Skript entsprechen. Die Systematik ist beliebig, die hier gewählte (Zehnerschritte) hat den Vorteil, dass noch Zwischenräume bleiben, falls ich z. B. noch ein Kapitel Vorbereitung zwischen Orga und Programm einfügen möchte. Bei der zweiten Ebene, die den Wochentagen entspricht, habe ich das gelassen, weil es nur sieben Wochentage gibt.

Yaml-Datei mit Metadaten

Als letztes benötigen wir eine Datei, die die Metainformationen unseres Skriptes trägt. Dafür verwenden wir ein Dokument, dass einen YAML-Block enthält und nennen diese pdf.yaml.

      ---
      title: |
        Das ist der Titel deiner Veranstaltung
      subtitle: |
        Und hier noch ein Untertitel (vielleicht ein Hinweis zur Gruppe)
      extratitle: false
      lang: de-de
      colorlinks: true
      links-as-notes: false
      papersize: a4
      fontsize: 12pt
      numbersections: true
      toc-depth: 2
      lof: false
      classoption:
        - oneside
        - headings=small
      toc: true
      geometry:
        - top=3cm
        - right=3cm
        - left=3cm
        - bottom=3cm
      chapters: false
      documentclass: scrbook
      linestretch: 1.2

      # Zusätzliche LaTeX-Pakete
      header-includes: |
        \usepackage{graphicx}
        \usepackage{csquotes}
        \usepackage{pdflscape}
       ---
      

Wir könnten hier noch mehr Attribute verändern, das sind eher Basiseinstellungen. Wir verwenden die KOMA-Script-Klasse scrbook, die anpassbarer ist, als die Standard book-Klasse.

Der Dateiname ist eigentlich egal, wir müssen ihn nur gleich korrekt angeben.

Skript mit Pandoc erstellen

Pandoc ist ein Programm ohne grafische Oberfläche. Es wird also über ein Kommandozeilentool bedient. Windows und Linus/macOS ticken hier anders. Daher brauchen wir zwei verschiedene Lösungen .

Öffne die Shell (Linux), das Terminal (macOS) oder die PowerShell (Windows). Du beginnst in deinem Benutzerverzeichnis. Von hier musst du nun zum Ordner navigieren, in dem unsere erstellten Dateien liegen. Um in einen tieferen Ordner zu wechseln, nutzt du den Befehl cd (change directory) gefolgt von dessen Name. Um wieder eine Ebene nach oben zu gehen verwendest du cd... Wenn du jeweils Enter drückst, wird dein Befehl ausgeführt und dein neuer Standort wird dir angezeigt. Wenn du im richtigen Verzeichnis angekommen bist, können wir Pandoc an die Arbeit schicken

Linux und macOS

pandoc *.md pdf.yaml -s -o skript.pdf

Mit diesem Befehl sagen wir:

• pandoc
  • Verwende pandoc
• *.md
  • Nimm dir alle Dateien, die auf .md enden
• pdf.yaml
  • und die Datei pdf.yaml
• -s
  • mache daraus ein eigenständiges Dokument (standalone)
• -o skript.pdf
  • der output soll skript.pdf heißen

Windows

Die PowerShell von Windows versteht leider das * als Wildcard nicht und sucht verzweifelt nach einer Datei, die *.md heißt. Da sie die nicht finden wird, müssen wir einen Umweg bauen:

pandoc (get-item *.md).FullName pdf.yaml -s -o skript.pdf

Wenn wir keinen Fehler gemacht haben, legt uns Pandoc nun eine neue PDF-Datei in den Ordner – unser fertiges Skript.

Vielleicht wirst du vorher aufgefordert LaTeX-Pakete zu installieren. Das passiert nur, wenn diese noch fehlen und fällt beim zweiten Mal weg. Egal auf welchem System du die Prozedur durchführst: Sie wird bestehende Dateien mit dem Namen skript.pdf im gleichen Verzeichnis erbarmungslos überschreiben. Du kannst den Namen aber beliebig ändern.

Anmerkungen

Zugegeben: Dieser Workflow fordert einiges an Vorbereitung. Er zahlt aber unter allen Umständen auf das persönliche Zeitkonto ein:

• Methoden aus großen Sammlungen können schnell neu zusammengestellt werden.
• Kein Formatieren mehr, keine Fummelei in Textverarbeitungsprogrammen
• Einheitliches Layout ohne manuelle Schritte
• Den gleichen Inhalt mit zwei Klicks in zwei Layouts bringen
• Neben einem PDF auch noch eine html-Datei zur Veröffentlichung oder zur Nutzung auf kleinen Bildschirmen erstellen.

Über Pandoc und LaTeX ließen sich noch beliebige Anpassungen vornehmen. Dafür ist dann ein wenig Code und Expertise notwendig.

Das Vorgehen macht im Grunde nicht anderes, als das Prinzip der Trennung von Inhalt, Struktur und Layout umzusetzen. Was einen rein praktischen Nutzen hat, hat auch einen (bildungs)politischen Hintergrund: Inhalte lassen sich so offen teilen, verändern und weiternutzen.

Fehlender Umbruch nach Überschriften der vierten Ebene bei Outputformat PDF

Pandoc verwendet für die Konvertierung in PDF LaTeX. LaTeX verwendet nur drei Ebenen von Überschriften, danach folgt bereits der Absatz. Das hat zur Folge, dass in so erstellten PDF-Dokumenten in den Metadaten nur die ersten drei Überschriftenebenen zur Verfügung stehen. Außerdem fehlt aus diesem Grund einem Textabsatz nach einer Überschrift der vierten Ebene ein vorausgehender Umbruch. Das ist zugegeben etwas unpraktisch. Wir können dieses Problem umgehen, indem wir Absätzen einen vorangehenden Umbruch hinzufügen. Dafür ergänzen wir in der Kommandozeile:

pandoc *.md -V block-headings pdf.yaml -s -o skript.pdf