Von der Präsentation zum Dokument

Erstellen der Unterlagen

• Texteditor, zb. geany oder ghostwriter:
  • Format markdown
• Pandoc:
  • Generierung des html-Codes.
• Shell Script build.sh
  • Automatisierung der Dateierstellung.
• Eigene Templates;
  • für Html- und PDF-Dateien.
• Weasyprint um die PDF-Datei zu erstellen, alternativ prince xml (Barrierefreie PDF).

Folien erstellen

• Eine Reihe von Slide Frames ist verfügbar:
  • slideous
  • s5
  • dzslides
  • revealjs
  • slidy

Vorgehensweise

Planung ist notwendig!

Der Aufbau muss durchdacht sein. Zuerst müssen die Folien erstellt werden.

Die Folientitel können auf verschiedenen Ebenen wie in den Gesamtdokumenten vorgesehen sein.

Danach kann die ausführliche Dokumentation (html und PDF) ergänzt werden. Dieser Text kann z.B. aus normalen Absätzen bestehen, diese sind auf den Folien nicht sichtbar.

Das fertige Gesamtdokument, HTML-Seite oder PDF-Ausgabe, wird dank Layout-Regeln (CSS) sauber generiert, inklusive einer Nummerierung, die auf der Folie nicht unbedingt sinnvoll ist.

Danach kann die ausführliche Dokumentation (html und PDF) hinzugefügt werden. Dieser Text kann z.B. aus normalen Absätzen bestehen. Diese auf den Folien nicht sichtbar.

Das fertige Gesamtdokument, HTML-Seite oder PDF-Ausgabe wird durch Layout-Regeln (CSS) sauber zusammengefügt. Eine Nummerierung, die auf der Folie nicht unbedingt sinnvoll ist, wird ebenfalls durchgeführt.

Automatisierung

Es werden drei Dokumenttypen erstellt:

• Folien.
• Vollständiges HTML-Dokument.
• Vollständiges PDF-Dokument.

 #!/bin/sh
 file=slides-zur-doc
 template=$HOME/TEMPLATES/mslide
 
 coverPage=true
 newPage=true
 color=false
 titleCount=true
 ownSlideCss=ul.css
 ownDocCss=docul.css
 usePrince=false

 pandoc -L "$template/convertHeader.lua" \
 -i "$file.md"  \
 --resource-path="$resourcePath" \
 --to html5 \
 --section-div \
 --template mslide.html \
 --include-in-header stb.html \
 --include-in-header main.css \
 --include-in-header theme.css \
 --include-in-header color.css \
 --include-in-header "$ownslidecss" \
 --include-in-header color.css \
 --include-in-header anim.css \
 --include-in-header ste.html \
 --include-in-header jsb.html \
 --include-in-header mslide.js \
 --include-in-header jse.html \
 --include-before-body $help |\
 $SED 's/href="#cb[0-9][0-9a-z-]*"//' |\
 data-uri -i - -o "$file-slide.html"

 pandoc -i "$file.md"  \
 --section-div \
 --resource-path ".:$template" \
 --to html5 --template mweb.html \
 --section-divs \
 --include-in-header stb.html \
 --include-in-header docmain.css \
 --include-in-header "$titlecount" \
 --include-in-header "$colorcss" \
 --include-in-header "$owndoccss" \
 --include-in-header "$coverpage" \
 --include-in-header "$newpage" \
 --include-in-header page-$lang.css \
 --include-in-header ste.html |\
 $SED 's/href="#cb[0-9][0-9a-z-]*"//'|\
 $SED 's/><a ><\/a>/> <a><\/a>/' |\
 cover | data-uri -i - -o  "$file.html"
 weasyprint -s "$template/weasyprint.css" "$file.html" -o "$file.pdf"

Template Dateien

build.sh
convertHeader.lua (Untertiteln auf Ebene 1 bringen)
mslide.js
mslide.html       (Template Datei)
main.css
color.css
anim.css
help-de.css
help-en.css
...

build.sh
convertHeader.lua (Untertiteln auf Ebene 1 bringen)
mweb.html       (Template Datei)
docmain.css
page-de.css
...
empty.css

Schriftgrad: CSS

 body {
     font-size:max(16px,2vw);
 }

Durch die Angabe von max(16px,2vw) erfolgt die Skalierung automatisch, sie wird vom Browser selbstständig stufenlos angepasst. Alle Größenangaben müssen relativ sein (rem, em, %).

1 vw entspricht 1 % der Breite des Ausgabefensters. Für einen Bildschirm mit Breite von 1920px ist die Schriftgröße dementsprechend 19,20*2 = 38,40 px. Für einen Bildschirm mit einer Breite von 1280px würde die Schriftgröße 25,6 px betragen.

Wenn die Breite des Browsers verringert wird, passt sich die Schriftgröße automatisch an, es wird jedoch kein Wert eingestellt, der kleiner als 16 px ist.

 body {
     font-size:max(12px,3.9vmin);
 }

Schriftgröße der einzelnen Elemente

Falls eine größere Schriftgröße (weniger Zeilen / Dia) gewünscht wird, können die entsprechenden CSS-Anweisungen in einer eigenen neuen CSS-Datei verankert werden. Zum Beispiel schrift-groesse.css. Die Datei build.sh muss entsprechend ergänzt werden:

 body { font-size: 32px; } /* alles um den Faktor 2 skalieren */
                           /* (nur HTML-Datei)                */

Bildgröße

Bilder müssen ebenfalls skaliert werden. Dazu muss die Höhe oder Breite angegeben werden.

Da die Höhe des Ausgabefensters entscheidend ist, ist die Festlegung der Bildhöhe der bessere Weg.

Da die Folien auch eine zweispaltige Darstellung ermöglichen sollen und die Bilder sehr unterschiedliche Größen und Seitenverhältnisse haben können, müssen CSS-Regeln vorhanden sein, die in der Regel eine korrekte Skalierung ermöglichen.

 img {
     max-height:70vh;
     width:100%;
     object-fit: contain;
 }
 .h80 img, img.h80 { max-height: 80vh;}
 .h75 img, img.h75 { max-height: 75vh;}
 .h70 img, img.h70 { max-height: 70vh;}
 ...
 .h20 img, img.h20 { max-height: 20vh;}
 .h15 img, img.h15 { max-height: 15vh;}
 .h10 img, img.h10 { max-height: 10vh;}

In den meisten Fällen sollte dies funktionieren. Bei Bedarf kann die Höhe des Bildes durch die Angabe der Höhe .h10 bis .h80 angegeben werden.

Für die HTML- bzw. PDF-Ausgabe sind die entsprechenden CSS-Eigenschaften enthalten, die Höhenangabe muss entweder in px, em oder besser mm’, erfolgen.

Eine Lösung ist die Berechnung der Höhe:

 @media screen {
 img { height: calc(800px * .70); }
 .h80 img, img.h80 { height: calc(800px * .80); }
 ...
 }

Für die PDF-Ausgabe wird die Berechnung von weasyprint nicht unterstützt, daher ist im Abschnitt @media print { für jeden Eintrag die entsprechende Höhe in mm angegeben werden.

CSS-Farben

 :root {
     --background: #eeffff;
     --color: #000000;
     --h1-shadow: #ffffff;
 ...
     --co: hsl(192,33%,53%);
 ...
 }
 html[mode=dark]:root {
     --background: #110000;
     --color: #ffffff;
     --h1-shadow: #000000;
 ...
     --co: hsl(192,33%,47%);
 ...
 }

Um Farbanpassungen zu erleichtern, sind die Definitionen in der Datei color.css hinterlegt.

:root ist eine Pseudoklasse, die an das HTML-Element angehängt werden kann. Die Definitionen werden wie üblich an die Unterelemente vererbt.

Die Verwendung des entsprechenden Regelsatzes wird z.B. durch den Selektor html[mode=dark]:root bewirkt.

Damit dies funktioniert, muss im HTML-Element ein Attribut “mode” mit dem Wert “dark” per Javascript hinzugefügt werden. Natürlich können auch andere Namen verwendet werden. Dies muss jedoch im Javascript berücksichtigt werden. Es könnten auch viel mehr Darstellungsmodi vorgesehen werden, z.B. “weiß”, “grau”, “schwarz”…

Durch die Zuweisung von Farben über Variablen können die Folien leicht an die der Umgebung und den Wünschen des Betrachters angepasst werden.

 li::marker { content: '➭ '; }
 li li::marker { font-size: 0.8em ;}
 ul a::after { content: " (" attr(href) ")"; }

 ul { padding-inline-start: max(1em,40px); }
 li::marker { content: '➭'; }
 li li::marker { font-size: 0.8em; }
 li::marker { color: #057b39;}
 html[mode=dark] li::marker { color: gold; }

Bedienung

Ohne Kurzanleitung geht es nicht!

Da die Präsentationen über verschiedene Systeme (PC, Smartphone, Tablet) gezeigt werden sollen, wird die Bedienung über Tastatur, Maus oder Touch-event unterstützt. Touch-events simulieren nur die Bedienung mit der Maus.

Cursor-Tasten: Blättern.
[h] Hilfe ein-/ausblenden.
[v] Mobil: Hilfe ein-/ausschalten.
[m] Darstellung mit hellen/dunklen Farben.
[b] Folien ausblenden/einblenden.
[f] Vollbildmodus ein-/ausschalten.
[a] Animation ein-/ausschalten.
[l] Virtueller Laserpointer ein/aus.
[w] Breitenmodus zur Berechnung der Schriftgröße an/aus.

Links oben: rückwärts blättern.
Oben rechts: Vorwärts blättern.
Oben Mitte: Vollbild an/aus.
Unten links: Bedienmenü einblenden.

Bedienung Mobile Geräte.

Die rot umrandeten Rechtecke sind die Bedienelemente für die Steuerung mit Touch-Gesten (Smartphone).

Das mittlere obere Feld steuert den Vollbildmodus (auch über die Taste [f] erreichbar).

Die oberen Felder links und rechts ermöglichen den Wechsel zur vorhergehenden bzw. zur nächsten Folie.

Unten links wird das Menü geöffnet, um die Modi einzustellen.

Das Feld rechts unten ermöglicht die Hervorhebung der Schaltflächen.

Einstellung der Darstellungsarten

• A Animation ein-/ausschalten.
• B (Blank) Inhalt sichtbar/unsichtbar.
• M Hintergrund hell/dunkel.
• • Virtuelle Zeiger an/aus.
• ↓ Menü schließen.
• W Schriftgrößenberechnung abhängig von der Höhe.

Das Menü wird in der linken unteren Ecke angezeigt und ermöglicht einige Einstellungen.

Folien als PDF ausdrucken

Der Browser wird benötigt.

Das Drucken der Taste [p] fügt dem Element html die Klasse print=“print” hinzu. Dies hat zur Folge, dass alle Folien sichtbar werden und somit eine Druckausgabe mit dem Browser ausgelöst werden kann.

Die Ausgabe eignet sich eher zur Dokumentation, Listenelemente, die in der HTML-Präsentation nacheinander angezeigt werden, erscheinen alle auf einer Seite, Zwischenstufen werden nicht berücksichtigt.

Die „PDF”-Ausgabe sollte im Querformat und in Farbe erstellt werden.

Markdown Datei

---
title: Vom Vortragsfolien zur Dokumentation
author: Jean-Jacques Sarton
lang: de
opts:
  dark: true
  anim: true
  incMode: true
---

# Vom Vortragsfolien zur Dokumentation

> Vortragsfolien publizieren ist nicht immer sinnvoll, es wäre besser
die Unterlagen so aufzubereiten, dass ein richtige Dokument entsteht

## Erstellen der Unterlagen

* Texteditor, z.b. **geany**
...
### Eigene Lösung
...

Die Überschriften ( # bis ###### ) müssen mit der Dokumentation übereinstimmen. Die Folien sollten nur eine Ebene haben, sonst gibt es Probleme. Als Vorverarbeitung werden im Markdown-Stream alle Titelebenen auf ein einfaches # „geschrumpft”.

Der von Pandoc erzeugte HTML-Code verschachtelt die verschiedenen Abschnitte wenn das Dokument verschiedene Überschriftenebenen hat. Dies ist für eine Präsentation nicht sinnvoll. Daher ist es notwendig, alle Titel und Untertitel in <h1>-Titel umzuwandeln. Dies geschieht durch ein ``lua``` Miniscript.

Die Absätze erscheinen nicht auf der Folie, können aber wie folgt eingeblendet werden.

:::{.vis}
Paragraf 1

Paragraf 2
:::

Es ist auch möglich, spezielle Seiten zu erstellen, die wie die erste Seite aussehen und auf der HTML-Seite und der PDF-Datei nicht angezeigt werden.

:::{.noDoc}
# Titel

Paragraf
:::

Barrierefreie Bilder

Die Bilder sollten eine kurze Beschreibung enthalten (Attribut alt). Das Bild sollte auch einen Untertitel enthalten.

:::{.col2 .h50}
![Bild 1](gruen.png){alt="Beschreibung 1" }

![Bild 2](blau.png){alt="Beschreibung 2" }
:::

Der “alte” Eintrag enthält die Beschreibung für den Screenreader. Bildschirmleser, der Sehende sieht nur die Bildunterschrift.

Die Leerzeile ist wichtig!

2-spaltiges Layout mit einem Bild

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Verwendete Programme

sh / gosh.exe

bash, ksh, zsh

sed / sed-go.exe

Korrekturen, Entfernen störender Links, Kode für der Druckausgabe verbessern.

awk / goawk.exe

verschiedene kleine Anpassungen

data-uri / data-uri.exe, ein eigenes Binary.

Ziel ist es, die Bilder als Data-URI in die Präsentation einzubinden. Damit nicht mehrere Dateien übertragen/kopiert werden müssen.

data-uri.exe Wurde mit Pelles C unter Windows kompiliert.

Die ersten 3 exe Dateien stammen aus den entsprechenden Projekten auf github.com. Sie wurden kompiliert und zu Testzwecken auf einer Windows Installation verwendet.

Die benötigten Programme können in das Template-Verzeichnis kopiert werden. Dadurch wird sichergestellt, dass sie vom Skript gefunden werden.

Kompatibilität

• Anzeige:
  • Firefox.
  • Chromium basierten Browser (Chrome, Edge, …).
  • Safari (Fullscreen nicht auf iPhone und Ipad).
• Erzeugung:
  • Linux.
  • MacOS.
  • Windows, die zuvor genannten Programme müssen verfügbar sein.

Je nach Betriebssystem, Distribution und Benutzerpräferenzen können verschiedene Shells verfügbar sein. Das Skript build.sh kann von dash, zsh, ksh, bash und gosh (Windows) ausgeführt werden.

Links