Defaults: create PDF handouts from Markdown files

[cagix]

Aus dem in #291 erzeugten Gesamt-GFM-File kann ein PDF für das Skript erstellt werden.

• LaTeX oder quick&dirty per PagedJS o.ä.?
• Was ist mit den Links und den Abbildungen?
• Was ist mit dem Literaturverzeichnis?
• Verlinkung des PDFs: Im Readme.md?

---

Students are asking for a PDF version of the individual lessons and exercise sheets.

Preliminary concept:

• Definition of a new default file ( mix of beamer.yaml and homework.yaml)
  • from markdown with relative paths
  • to pdf
  • variables: scartcl
  • filter: prepareHTML, tex, handout (new)
• New filter: "handout" to remove all extra (slides related) formatting (vspace, bigskip, smallskip, vfill, ...)
• Makefile: new rule for handout
  • First step: as for web: copy all images, preprocess all markdown files
  • Second step: as for Beamer, only other default file and other folder
• GitHub workflow, new auxiliary branch
• Readme: all pages in the "timetable" with the addition [pdf] and link to the auxiliary branch

Using #160 we could even have special sections like "tldr" or "wrap-up" or "outcomes" in the generated pdf!

[cagix]

1. Schritt 1: Übersetzung in Ordner ohne das "lecture/"-Element (analog zum Web-Preprocessing)

2. Schritt 2: Erzeugen einzelner PDFs für jede Einheit: pandoc <options> --rebase_relative_paths path/to/local/markdownfile.md -o path/to/pdf/generated-name.pdf

   • Berücksichtigung der extra Abschnitte (TLDR, Videos, ...) im YAML-Header: eigenes Template?!
   • Literatur, Quellen, Referenzen: Pandoc-Citeproc?

3. Schritt 3: Erzeugen eines Gesamt-Buchs für die gesamte Veranstaltung

   • Option 1: pandoc <options> --rebase_relative_paths readme.md topicA/readme.md topicA/file1.md topicA/file2.md topicB/readme.md topicB/subtopic1/readme.md topicB/subtopic1/file1.md

     • Notwendig: Befehlszeile basteln durch rekursives Ablaufen des Startdokuments (Pandoc, Filter, Makefile-Regeln)
     • Schwierig:
       • Ordner dürfen nicht verschränken
       • Überschriften für Ordner (Chapter, Section) => über die readme.md in den Ordnern?
       • Down-Shifting der Überschriften in den Markdowndateien

   • Option 2: pandoc -L recursiveinclude readme.md

     • Wie (1), nur ohne Erzeugung von Zwischenelementen (die Verkettung passiert im Filter)
     • Schwierig zusätzlich: Links in Startdatei müssen u.U. anders behandelt werden: Tabelle mit Markdown-Links => können dort nicht einfach eingefügt werden

   • Option 3: pandoc book.md

     • Gliederungsdatei book.md muss erzeugt werden, Aufbau analog zur "summary.md" bei mdBook (Gliederungsüberschriften, "freistehende" Links auf Markdown-Dateien)
     • Rekursives Ablaufen der Links in der Startdatei
     • Indizierte Datenstruktur (Verhalten wie Set, Zugriff per Index, Reihenfolge des Hinzufügens): je Ebene genau eine Liste, Elemente der Ebene (Dateien, Ordner) in der Reihenfolge des Auftretens beim rekursiven Ablaufen der Startdatei einfügen => Toplevel-Ordner bleiben in der Reihenfolge erhalten, Ordner werden nicht verschränkt, Reihenfolge der Markdown-Dateien bleibt erhalten
     • Bucherzeugung dann mit include-Filter (Links statt speziellen Code-Blöcken)

   Problem: relative Links! Web-Preprocessing "löst" die Links auf und ersetzt diese durch den (eindeutigen) Dateinamen und Hugo macht daraus einen richtigen Link. Möglicherweise ist es doch am besten, für die Buchgenerierung die Ordnerstruktur zu belassen.

weitere Ideen:

• Gliederungs-Überschriften zusammen mit den Ordnern oder im jeweiligen readme.md? Letzteres dürfte einfacher sein ...
• Gliederungstiefe automatisch mit jedem Betreten eines Ordners hochsetzen und bei Verlassen eines Ordners wieder heruntersetzen
• Filter wie in (3) wird in jedem Fall benötigt
• title (YAML) in jedem Markdown wie H1-Header (restl. Header sind bereits H2) => auf der Basis dann Down-Shifting