psi-slides · Präsentationssoftware für Lehrende · This page in English
Folien, Notizen und Handouts aus einer Datei.
Eine einfache Textdatei in Markdown wird zu vier HTML-Dateien: der Projektion für den Raum, einem Presenter-Cockpit auf dem eigenen Bildschirm (die Folie, die eigene Notiz dazu und was als Nächstes kommt) und zwei Handouts – dem vollständigen Text der Vorlesung allein und demselben Text mit den eigenen Notizen darin. Alle vier entstehen aus dieser einen Datei. Sie können nicht auseinanderlaufen, weil es nichts gibt, was man synchron halten müsste, und jede bringt alles mit, was sie zum Öffnen braucht.
Auf die Folie kommt, was der Raum braucht, um zu folgen; ins Handout kommt alles, was man behalten will. Diese Trennung kostet Freiheit im Layout – weniger Möglichkeiten als in PowerPoint – und bringt dafür vier Ausgaben statt einer. Eine Vorlesung kann hervorgehobenen Code, LaTeX-Formeln und Video enthalten, und jeder Link bekommt einen QR-Code, den der Raum von der Wand abscannen kann. Für die Stunde im Hörsaal gibt es Übersichtstafel, Volltextsuche, Live-Annotationen, eine Uhr und sieben Farbschemata. Das alles läuft auf dem eigenen Laptop und funktioniert auch offline, ohne Cloud und ohne Dienstleister.
Dieselben vier Absätze, einmal geschrieben. Zwischen den ersten beiden Bildern liegt ein Tastendruck; das dritte ist eine andere Datei aus derselben Quelle, und der Schalter zeigen: in der Titelzeile des zweiten Bildes holt sie hervor. Ein Klick auf ein Bild öffnet es in voller Größe.
Die Kurzfassung in einer Minute
Das Argument dieser Seite als Film: woraus eine Vorlesung besteht, was aus einer Datei entsteht und wie die Stunde im Hörsaal aussieht. Gut eine Minute, mit Untertiteln. There is an English version, too.
Die Datei liegt auf einem Server des Lehrstuhls an der Universität Bamberg, nicht im Repository, und wird erst geladen, wenn man auf Abspielen drückt.
Jede Vorlesung besteht aus drei Sorten Text
Da ist der Text, der auf die Folie kommt, knapp genug, dass man ihn aus der letzten Reihe lesen kann. Da ist das Skript – die Sätze, die die Sache wirklich erklären und die in ein Handout gehören statt an die Wand. Und da sind die Notizen für einen selbst: erst die Gruppe fragen; das hier weglassen, wenn die Zeit knapp wird; das geht nicht raus.
Die gängigen Präsentationsprogramme bieten Folien und ein Notizfeld. Für das Skript ist darin kein Platz vorgesehen, und ausgerechnet das ist der Teil, den Studierende am meisten wollen. Das Skript nimmt dann einen von zwei Wegen. Entweder übernehmen die Folien seine Aufgabe und werden so voll, dass sie aus der letzten Reihe niemand mehr lesen kann – Death by PowerPoint. Oder das Skript steht in einem zweiten Dokument, das ab der ersten Änderung nicht mehr zu den Folien passt.
Mit psi-slides schreibt man jeden Absatz einmal und markiert den einen Satz,
der den Absatz trägt. Die Projektion bekommt nur diesen Satz, das Handout
bekommt den ganzen Absatz, und die Zeilen hinter > note: bleiben
auf dem eigenen Bildschirm.
Was aus dem Markdown wird
Das hier ist das Markdown hinter der Folie auf den Bildern oben. Die Vorlesung, aus der sie stammt, ist eine echte: eine Python-Einführung aus 36 Chunks – ein Chunk ist eine Überschrift mit dem Text darunter, und jeder Chunk wird zu einer Folie. Zwei der vier Absätze sind gekürzt, damit der Ausschnitt auf diese Seite passt; die Vorlesung selbst ist auf Englisch.
## free: Why Playwright | the modern web is rendered, not served {.wide #why-playwright}
::: cols 2
**A lot of the web is rendered by JavaScript in the browser.**
**`requests` and plain `urllib` see only the HTML shell** – often just
`<div id="app"></div>` plus a pile of script tags. Useful text, links, and
titles never arrive.
**Playwright drives a real browser** – Chromium, Firefox, or WebKit – over a
debugging protocol. The page renders, scripts execute, the DOM settles, and
then you query it. You see what a human sees.
**For a link scanner this matters a lot.** …
**The cost is weight.** …
:::
::: footnote
`requests` is still the right tool for an API that answers in JSON. The
browser is for pages meant to be looked at.
:::
> note: Show the difference live if the room is awake: open a JS-heavy site,
> curl it, and let them find the missing text themselves.In der Projektion fallen die zwei Spalten zu einer zusammen, weil sich vier gekürzte Absätze nicht ausbalancieren lassen. Ohne Kürzung und im Handout bleiben die beiden Spalten aus der Quelle erhalten.
> note: aus der Quelle steht unter der
gespiegelten Folie, wo sie sonst niemand sieht, in einer Größe, die man mit
den zwei Knöpfen neben der Notiz einstellt; der Streifen zeigt, was kommt. Die
beiden Fenster halten sich direkt im Browser im Gleichschritt, ohne Server
dazwischen.
print.html trägt nur das Skript und ist das für die Studierenden,
print-notes.html ergänzt die Sprechnotizen und bleibt bei einem
selbst.Titelfolien und Trenner
Die Voreinstellung steht unten, der Rest ist einen Klick entfernt. Anklicken zeigt eine Kachel in voller Größe.
Das hier ist eine Vorschau, wie die Figurensprache
weiter unten. Es steckt nicht in Version 1.0.0: Wer ein
cover: oder ein section: schreibt, braucht das
Repository statt des Downloads auf der Releases-Seite.
Loslegen hat beides.
cover: benennt die Titelfolie. Sie sind von
leise nach laut sortiert.
classic der Satz im unteren linken Drittel. Die Vorgabe
panel helle Schrift auf einem ganzflächigen Feld der Akzentfarbe
hero das Bild füllt die Folie, der Satz steht auf einem dunklen VerlaufDie anderen sieben Titelfolien
masthead der Titel an der Oberkante, die Credits unter einer Linie am Fuß, dazwischen der Text des Chunks
stack auf beiden Achsen zentriert, für einen Anfang, der still sein will
display der Titel so groß, dass er die Folie füllt, alles andere klein darunter
quote der Vortrag beginnt mit einer Behauptung, der Titel liest sich als Zuschreibung
split der Satz links, rechts läuft ein Bild über den Rand hinaus
beside der Inhalt des Chunks neben dem Titel – so kann eine Zeichnung das Cover sein
above derselbe Inhalt oben, der Titel zentriert im Band daruntercover-align: setzt den Satz
nach oben, in die Mitte oder nach unten, bei den Kompositionen, die ihm dort
Freiheit lassen. cover-ratio: ist ein
Prozentsatz und sagt, wie viel der Folie das Bild bekommt, bei denen, die sie
teilen.
cover: stack mit cover-align: bottom
cover: beside mit cover-ratio: 62%section: zeichnet die Trennerfolie, mit der
ein neuer Teil der Vorlesung aufmacht. Sie sind alle leiser als jede
Titelfolie.
plain die Überschrift allein. Die Vorgabe
tinted der Akzent bei 12%. Aus der letzten Reihe kommt die Farbe vor jedem Wort an
rule die leiseste, und eine, die einen Schwarzweißdruck übersteht
card die Überschrift auf einer getönten Fläche
number eine große Ziffer über der Überschrift, die die Teile der Vorlesung zählt
outline die laufende Gliederung: welcher Teil, von wie vielen, und wie weit hineinAlles, was eine einzelne Vorlesung gleichzeitig tragen kann – eine Schlussfolie, Trenner mit Zitat, Foto oder Abbildung, Inhalte als Karten gesetzt, ein ganzflächiges Foto, das sich auf Leertaste öffnet – steht in der Dekorations-Vorlesung.
Vorlesungen selbst öffnen
Auf dieser Seite liegen fünf Vorlesungen. python-intro ist die, aus der die Bilder stammen. Das Tutorial ist eine selbstbezügliche Tour, die das Werkzeug erklärt, indem sie es benutzt. Die Figures-Vorlesung zeichnet jede Konstruktion, die die Abbildungssprache kennt, darunter Abbildungen aus einer echten Vorlesung, und ist das ausgearbeitete Beispiel hinter Figures you write. Decoration zeigt jede Konstruktion, die etwas anderes als eine Textspalte auf eine Folie bringt: die Titelfolien, die Trenner, Inhalte als Karten gesetzt, ein Foto, das sich mit Leertaste öffnet. Das Kurzbeispiel ist ein Ausschnitt aus einer Netzwerk-Vorlesung im ersten Semester, auf Deutsch: gut 80 Zeilen Markdown, kurz genug, um sie ganz zu lesen und daneben zu sehen, was daraus wird (Quelle, gesetzt nach den Vorlesungsnotizen unter CC BY-NC-SA 4.0).
| python-intro | Tutorial | Figures | Decoration | Kurzbeispiel | |
|---|---|---|---|---|---|
| Die Projektion | audience | audience | audience | audience | audience |
| Das Cockpit | speaker | speaker | speaker | – | speaker |
| Das Dokument | |||||
| Mit den Notizen | print-notes | print-notes | print-notes | – | print-notes |
Dekoration und Figuren zeigen beide, was nicht in
Version 1.0.0 steckt – die Titelfolien, die Abschnittstrenner,
Karten und Zeilen, Hintergrundbilder, und Abbildungen als
::: draw. Beide Vorlesungen sagen das auf ihrer dritten Folie,
und beide brauchen zum Bauen das Repository. Von der Dekoration sind nur die
Projektion und das Dokument veröffentlicht.
Am besten mit der Projektion anfangen. Pfeiltasten blättern, Leertaste blendet den nächsten Abschnitt ein, C schaltet zwischen gekürztem und vollem Text um, O (der Buchstabe, nicht die Null) öffnet die Übersichtstafel, / sucht, ? listet alle Tasten auf. Ein Cockpit, das über die Tabelle oben geöffnet wird, zeigt zwar das Layout, ist aber mit nichts verbunden; ein verbundenes Cockpit öffnet man mit S in der Projektion.
Alle vier Dateien sind in sich geschlossen: die Gestaltung, die Skripte,
die Bilder, die gesetzten Formeln und die Schriften stecken in der HTML-Datei
selbst. Zur Laufzeit wird nichts nachgeladen, und die Dateien lassen sich aus
einem Ordner auf der Festplatte (file://) genauso öffnen wie von
diesem Server.
Loslegen
Es gibt zwei Fassungen, und sie können unterschiedlich viel.
Das
aktuelle Release ist 1.0.0. Sein Quellformat liegt fest, eine
Vorlesung baut also später noch genauso wie heute. Die .zip oder
die .tar.gz herunterladen und auspacken; Tutorial, python-intro
und Kurzbeispiel von oben sind darin schon gebaut, ein Doppelklick auf
lectures/tutorial/audience.html startet die Tour ohne jede
Installation. Eine Zeile macht dasselbe ohne Klicken:
curl -L https://github.com/UBA-PSI/psi-slides/releases/latest/download/psi-slides.tar.gz \
| tar xzDas
Repository enthält, was in 1.0.0 noch fehlt: Abbildungen als
::: draw, die Titelfolien und Abschnittstrenner, Karten und
Reihen sowie den grafischen Abbildungseditor. Wer wegen einer dieser Sachen
hier ist, nimmt diese Fassung. Dafür gilt die Formatzusage nicht – an diesen
Teilen kann sich noch etwas ändern, eine damit geschriebene Vorlesung braucht
bis zum Release also vielleicht eine Anpassung.
git clone https://github.com/UBA-PSI/psi-slidesOhne git: Download ZIP unter dem grünen Code-Knopf des Repositorys.
Für eine eigene Vorlesung braucht man Node 20 oder neuer,
damit läuft build.js, sonst nichts: kein LaTeX, kein Pandoc,
keinen Server, nichts, was systemweit installiert werden müsste.
cd psi-slides
# einmalig: die mitgelieferten Schriften und die wenigen Pakete für den Bau
npm install
# alle vier Ansichten neben source.md bauen, dann die Projektion öffnen
node build.js lectures/tutorial/source.md
open lectures/tutorial/audience.html # macOS; sonst xdg-open oder der BrowserFalls Node noch nie installiert wurde und das Terminal unbekannt ist
Die folgenden Schritte führen von einem Windows- oder macOS-Rechner, auf dem nichts installiert ist, zu einem gebauten Tutorial.
Node installieren
nodejs.org öffnen. Der Knopf bietet die
LTS-Version an – die mit langfristiger Pflege – in der passenden Datei für
den jeweiligen Rechner; diesen Download nehmen. Unter macOS kommt ein
.pkg: doppelklicken, durch den Installer klicken, das Passwort
eingeben, wenn danach gefragt wird. Unter Windows kommt ein
.msi: doppelklicken, die Vorgaben übernehmen und das Häkchen
für die Werkzeuge für native Module in Ruhe lassen. psi-slides braucht sie
nicht.
Wer schon einen Paketmanager benutzt: brew install node
unter macOS und winget install OpenJS.NodeJS.LTS unter Windows
tun dasselbe.
Ein Terminal öffnen
Unter macOS Command-Leertaste drücken, terminal tippen,
Return. Unter Windows das Startmenü öffnen und terminal tippen:
Windows Terminal nehmen, falls es erscheint, sonst PowerShell. Es kommt ein
Fenster mit einem Cursor darin. Man tippt eine Zeile, drückt Return, und es
antwortet.
node --versionDie Antwort ist eine Versionsnummer. Alles ab v20 funktioniert, und ein
frischer LTS-Download liegt deutlich darüber. Kommt stattdessen
command not found oder is not recognized, das
Fenster schließen und ein neues öffnen: ein Terminal, das beim Installieren
von Node schon offen war, hat es noch nicht gesehen.
Die Dateien holen
Eine der beiden Fassungen von oben nehmen. Im Zweifel
das
Release; Download ZIP unter dem grünen Code-Knopf
des Repositorys ist
dieselbe Art Datei und bringt zusätzlich die Abbildungen, die Titelfolien
und die Karten mit. Auspacken wie jeden anderen Download; auf beiden
Systemen genügt ein Doppelklick. Es entsteht ein Ordner, dessen Name mit
psi-slides beginnt, und dieser Ordner ist das ganze Werkzeug.
Ihn irgendwo ablegen, wo er wiederzufinden ist, denn das Terminal muss
gleich darauf gerichtet werden.
Unter Windows die .zip wirklich auspacken und nicht per
Doppelklick öffnen: Windows zeigt den Inhalt eines ZIP-Archivs wie einen
Ordner an, aber darin lassen sich keine Befehle ausführen.
Das Terminal auf den Ordner richten
cd psi-slidesDie cd-Zeile muss benennen, wo der Ordner tatsächlich liegt, unter Windows
also etwa cd C:\Users\du\Downloads\psi-slides. Statt den Pfad
zu tippen: cd und ein Leerzeichen eingeben und dann den Ordner
aus dem Dateimanager ins Terminalfenster ziehen – der Pfad schreibt sich
selbst.
Holen, was der Bau braucht
npm installnpm install läuft einmal, in diesem Ordner, und dauert ein
paar Sekunden. Es holt
die Schriften, die psi-slides in jede Vorlesung einbettet, und die wenigen
Pakete, die der Bau benutzt. Alles landet in einem Ordner
node_modules neben build.js: systemweit wird
nichts installiert, und die gebauten Vorlesungen laden beim Öffnen nichts
nach.
Das Tutorial bauen
node build.js lectures/tutorial/source.mdDieselbe Zeile unter Windows und macOS, Schrägstriche eingeschlossen: Node nimmt sie überall. Sie meldet, was eingebettet wurde – die Bilder, die Schriften, die QR-Codes, die gesetzten Formeln – und endet damit, was geschrieben wurde.
Wrote lectures/tutorial/print.html, lectures/tutorial/print-notes.html, lectures/tutorial/audience.html, lectures/tutorial/speaker.html (11 columns, 59 chunks)Öffnen
lectures/tutorial/audience.html doppelklicken. Es öffnet sich
im Browser, und mehr braucht es nicht: ? listet die Tasten,
S öffnet das Cockpit. Die Datei an jemanden mailen, der nichts
davon installiert hat, und sie funktioniert trotzdem.
Für Linux: all diese Werkzeuge sind ohnehin da. Die Pakete
der Distributionen hängen manchmal mehrere Versionen hinterher, deshalb
lohnt sich node --version auch dort.
Das Tutorial erklärt das Werkzeug, indem es das Werkzeug benutzt.
? zeigt die Tastenübersicht, S öffnet das Cockpit. Die
source.md des Tutorials ist die Referenz zum Schreiben eigener
Vorlesungen, und die vier gebauten Dateien kann man verschieben, mailen oder
hochladen – sie tragen alles bei sich, was sie brauchen.
Dann die eigene Vorlesung schreiben
# ein Verzeichnis mit gültigem Frontmatter anlegen
node build.js --new my-lecture
# bei jedem Speichern neu bauen und alle offenen Tabs neu laden
node build.js lectures/my-lecture/source.md --watch
# Chunk-IDs, Wortbudgets, offene Direktiven, zu große Assets
node lint.js lectures/my-lecture/source.mdEditor, Projektion und Cockpit nebeneinander offen halten:
--watch baut bei jedem Speichern neu und lädt die beiden
Browserfenster nach, sobald der Bau fertig ist. Am Ende sind die vier
HTML-Dateien neben der source.md das, was man weitergibt. Mehr muss
nicht mitreisen.
Auch eine Abbildung ist Text
Die Abbildungen einer Vorlesung veralten dort, wo sie in einem Zeichenprogramm liegen. psi-slides hat dafür eine kleine Sprache: eine Abbildung besteht aus ein paar Zeilen in derselben Markdown-Datei wie die Folie, auf der sie steht, und der Build zeichnet sie. Außer dem ersten Element sitzt darin nichts auf einem Punkt einer Zeichenfläche – jeder Kasten wird an einen anderen gesetzt – also zieht ein verschobener Kasten mit, was an ihm hängt, und eine Abbildung kann vor dem Publikum Schritt für Schritt entstehen.
Eine Folie aus einer echten Vorlesung, vom Build gezeichnet.
Ein Teil ihres Quelltexts steht unten: die vier Kästen, eine der drei Notizen
und der Schritt, der diese Notiz hereinholt. Zwei Dinge muss man wissen, um sie
zu lesen. Längen zählen in Rasterzellen, nicht in Pixeln – die erste
Zeile setzt die Zelle auf 150 mal 54, deshalb ist w 0.88 h 0.85
ein Kasten, der viel breiter als hoch ist, und eine Abbildung behält ihre
Proportionen, wenn die Zelle sich ändert. Und -- fh.cx,fh.top
ist eine Anschlusslinie: sie richtet die Notiz auf eine Stelle
eines anderen Kastens aus, sucht sich ihren Weg selbst und bleibt daran
hängen, wenn der Kasten sich bewegt.
::: draw 150x54
default box {.tone-3 .sharp} w 0.88 h 0.85
box fh "Frame\nHeader" at 0,0
box dh "Datagram\nHeader" right of fh gap 0 same as fh
box sh "Segment\nHeader" right of dh gap 0 same as fh
box pl "Payload" right of sh gap 0 same as fh {.paper}
text lmac "Ethernet source\nand destination\naddresses*" above fh gap 0.5 -- fh.cx,fh.top {.muted @l1}
step ethernet
show @l1
emph fhDas hier ist eine Vorschau. Sie steckt nicht in der Version 1.0.0, der Download auf der Releases-Seite hat sie also nicht. Zum Ausprobieren braucht es das Repository selbst – entweder einen Klon oder Download ZIP im Code-Menü des Repositorys. Das auf einer Release-Seite angebotene Source code (zip) enthält den getaggten Release und damit diese Vorschau gerade nicht.
git clone https://github.com/UBA-PSI/psi-slides
cd psi-slides
npm install
node build.js lectures/diagrams/source.md
open lectures/diagrams/audience.html # jedes Konstrukt, gezeichnetVorschau heißt nicht nur, dass die Verpackung fehlt: das Quellformat
kann sich noch ändern, und eine heute geschriebene Abbildung braucht
möglicherweise eine Anpassung, wenn es erscheint. Die Zeichnung oben ist
eine von sechsunddreißig in lectures/network-security, wo die
Sprache am Umfang einer echten Vorlesung erprobt wurde.
Figures you write ist die Begründung für die Sprache – was eine Vorlesungsabbildung leisten muss, woran ein Zeichenprogramm und eine Auto-Layout-Sprache dabei jeweils scheitern. Das Handbuch baut eine Abbildung Zeile für Zeile auf, führt dann jede Anweisung, die Gestaltungsregeln und ausgearbeitete Beispiele auf und zeigt den grafischen Editor, mit dem sich ein Kasten in der laufenden Folie ziehen lässt, während der Quelltext mitgeschrieben wird. Beide Seiten sind auf Englisch.
Dokumentation
- Der Vergleich mit anderen Werkzeugen – Beamer, reveal.js, Quarto, Marp, Slidev, PowerPoint und Verwandte, in beide Richtungen, samt den Stellen, an denen psi-slides verliert. Auf Englisch.
- Figures you write – die Begründung für die Figurensprache, die noch eine Vorschau ist: was eine Abbildung in einer Vorlesung leisten muss und woran ein Zeichenprogramm und eine Auto-Layout-Sprache dabei jeweils scheitern. Das Handbuch daneben baut eine Abbildung Zeile für Zeile auf und listet danach jede Anweisung, die Gestaltungsregeln und ausgearbeitete Beispiele. Auf Englisch.
- Die Tutorial-Vorlesung – jedes Konstrukt des Formats im Betrieb, und daneben ihr Quelltext, der die Referenz dafür ist, wie man es schreibt. Auf Englisch.
Quellcode
github.com/UBA-PSI/psi-slides – die README-Datei erklärt das Format und sagt, wofür das Werkzeug taugt und wofür nicht. Auf Englisch.