psi-slides · zurück zur Startseite · This page in English
Loslegen
Zwei Wege, und beide enden am selben Ort: Beide führen
dasselbe build.js aus und schreiben neben die
source.md dieselben vier Ansichten – die Projektion für den
Raum, das Cockpit für die Vortragenden, zwei Handouts zum Drucken.
Option 1: Man lädt eine App
herunter, die die Dateien auf Knopfdruck baut. Man öffnet darin eine
source.md, und nach jedem Speichern baut sie neu. Sonst muss
nichts installiert werden: kein Node, kein Terminal, nicht einmal
psi-slides selbst – die App trägt die Kopie, mit der sie paketiert
wurde.
Option 2: Man baut seine Folien auf
der Kommandozeile – oder
lässt einen KI-Agenten das tun. Das Repository bringt die Skills mit, die
einem Sprachmodell das Format beibringen. Dieser Weg beginnt mit den Quellen
und einem npm install, und so baut auch ein CI-Job
unbeaufsichtigt.
Die App
Die source.md einer Vorlesung öffnen oder auf
das Fenster ziehen, und die vier Ansichten sind gebaut. Das Fenster neben
dem Texteditor offen lassen, und die App baut sie nach jedem Speichern
erneut.
Eine Zeile sagt, ob der letzte Build funktioniert hat, und über vier Knöpfe öffnet man die Ansichten, die er geschrieben hat. Es gibt auch kein Projekt einzurichten und keine Einstellungen, die vor dem ersten Build auszufüllen wären.
Darunter zählt das Fenster, was in der Vorlesung steckt – Abschnitte, Folien, Bilder, Zeichnungen und wie viele Wörter ins Handout gegangen sind und wie viele in die Sprechernotizen – sodass der Umfang eines Vortrags ablesbar ist, ohne ihn zu öffnen.
Herunterladen
Das Paket für das eigene System aus den dreien unten holen. Bis 2.0.0
erscheint die App getrennt von psi-slides selbst, unter einem eigenen Tag,
builder-0.1.1, und auf GitHub als Pre-Release
markiert: nicht die aktuelle Version von irgendetwas, sondern ein früh
angebotenes Paket.
Windows 64 Bit (experimentell)
Installationsprogrammläuft ohne Rückfrage durch und startet die Apppsi-slides-builder-win-x64.exe
macOS Apple Silicon
Disk-Imageöffnen, die App in „Programme“ ziehenpsi-slides-builder-mac-arm64.dmg
Der erste Start
Windows und Linux sind experimentell. Diese beiden Pakete kommen vom Build-Rechner und sind auf einem echten nicht gestartet worden. Gut möglich, dass sie laufen; getestet ist es nicht. Wer eines ausprobiert: ob es läuft oder umfällt, ist ein Issue wert, in beide Richtungen. Das macOS-Paket ist auf einem echten Mac benutzt worden, und das ist der ganze Unterschied zwischen den drei Blöcken oben.
Die Pakete sind nicht signiert, außer dem für macOS: Das wird vor dem Hochladen von Hand signiert und notarisiert – Apples eigene Prüfung. Ist diese Signatur noch nicht erfolgt, sagt macOS beim Doppelklick, der Entwickler lasse sich nicht überprüfen: die App einmal mit Rechtsklick und Öffnen starten, dann ist die Warnung weg. Windows zeigt einmal seine SmartScreen-Warnung – Weitere Informationen, dann Trotzdem ausführen. Ein AppImage muss erst ausführbar sein.
Was sie ist und was nicht
Schlägt ein Build fehl, steht die Meldung von build.js
unverändert da, mit der Zeile in der Quelle. Die vier Ansichten behalten
den letzten Build, der lief; ein kaputtes Speichern nimmt einem nicht
mitten in der Vorlesung die Folien weg.
Es gibt zwei Schalter. Setzt man Die Ansichten über eine lokale Webadresse öffnen, bekommt man einen kleinen lokalen Server: Eingebettete YouTube- und Vimeo-Player laufen aus einer Datei heraus nicht, sie brauchen eine Adresse. Unter Die Ansichten öffnen in wählt man Chrome oder Edge, worin psi-slides getestet wird, oder das, womit das System HTML öffnet.
Die App ist kein Markdown-Editor. Die Vorlesung schreibt man in dem Texteditor, den man ohnehin benutzt; das Fenster beobachtet die Datei. Es gibt keine geteilte Ansicht, keine Vorschau daneben, keinen Git-Client und keine Stelle, an der man Build-Befehle tippt.
Die zwei Wege sind auch nicht zwei Werkzeuge: Die App führt dasselbe
build.js auf derselben source.md aus und erzeugt
dieselben vier Ansichten. Nichts verlässt den Rechner. Kein
Konto, keine Telemetrie, kein Update-Aufruf, kein Netzzugriff – und die
lokale Webadresse oben hängt an 127.0.0.1, erreichbar von
diesem Rechner und von sonst nichts.
Die Kommandozeile
Derselbe Build wie in der App, nur selbst getippt: für
einen Rechner, auf dem ohnehin ein
Terminal offen ist – und das, was ein CI-Job ausführt. Es braucht
Node 20 oder neuer, womit
build.js läuft, und sonst nichts: kein LaTeX, kein Pandoc, keinen
Server, nichts systemweit Installiertes. Nicht einmal git: Der Clone unten ist
der schnellste Weg zu den Dateien, und das
ZIP
der aktuellen Quellen sind dieselben Dateien, nur entpackt.
Das Tutorial bauen
Man führt npm install einmal aus. Es holt die Schriften,
die psi-slides in jede Vorlesung einbettet, und die Handvoll Pakete, die der
Build benutzt – alles in einen Ordner node_modules neben
build.js.
Die vier Ansichten erscheinen als HTML-Dateien neben der
source.md, und sie sind das, was man weitergibt: Jede trägt
ihre Schriften, Bilder und ihren Code selbst und lädt beim Öffnen nichts
nach.
git clone https://github.com/UBA-PSI/psi-slides
cd psi-slides
# einmalig: die Schriften und die Abhängigkeiten des Builds
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 BrowserWährend man schreibt
Mit --watch baut der Build bei jedem Speichern
neu und lädt jeden offenen Tab neu, sodass Texteditor, Projektion und
Cockpit gleichzeitig sichtbar bleiben. Das tut die App von sich aus.
--serve ist für das, was eine Datei auf der Platte
nicht kann: eingebettete YouTube- und Vimeo-Player abspielen.
lint.js prüft eine Vorlesung vor der Weitergabe, hat in der App
keinen Knopf und wohnt hier.
# bei jedem Speichern neu bauen, jeden offenen Tab neu laden
node build.js lectures/tutorial/source.md --watch
# dasselbe, über http auf diesem Rechner, für eingebettete Player
node build.js lectures/tutorial/source.md --watch --serve
# Chunk-IDs, Wortbudgets, offene :::-Blöcke, zu große Dateien
node lint.js lectures/tutorial/source.mdVon einem Rechner ohne alles
Die Schritte führen von diesem Rechner zu einem gebauten
Tutorial. Der Reihe nach
durchgehen: Wer npm install vor dem cd aufruft, installiert in den falschen
Ordner.
Die App oben braucht nichts davon.
Wer noch nie Node installiert oder ein Terminal benutzt hat
Node installieren
Auf nodejs.org gehen. Der Knopf bietet
die LTS-Fassung – die mit Langzeitunterstützung – in der richtigen Datei
für den Rechner an, den man vor sich hat; die nehmen. Auf macOS bekommt man
ein .pkg: doppelklicken, durch den Installer klicken, das
Passwort eingeben, wenn danach gefragt wird. Auf Windows bekommt man ein
.msi: doppelklicken, die Voreinstellungen übernehmen, das
Häkchen bei den Werkzeugen für native Module in Ruhe lassen. psi-slides
braucht diese Werkzeuge nicht.
Wer schon einen Paketmanager benutzt: brew install node auf
macOS und winget install OpenJS.NodeJS.LTS auf Windows tun
dasselbe.
Ein Terminal öffnen
Auf macOS Command-Leertaste drücken, terminal tippen,
Return. Auf Windows das Startmenü öffnen und terminal tippen:
Windows Terminal, wenn es erscheint, sonst PowerShell. Man bekommt 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 passt, und ein frisches
LTS liegt deutlich darüber. Kommt stattdessen command not found
oder ist nicht erkannt, das Fenster schließen und ein neues
öffnen: ein Terminal, das schon lief, als Node installiert wurde, hat es
noch nicht gesehen.
Die Dateien holen
Wer git hat, nimmt einen git clone, sonst das
ZIP
der aktuellen Quellen – dieselbe Datei, die der grüne
Code-Knopf des
Repositories als
Download ZIP anbietet. Es ist nicht das Source code (zip),
das an einem Release hängt: Das ist der getaggte Stand 1.0.0 und nicht der
aktuelle. Das ZIP
entpacken wie jeden anderen Download; auf beiden Systemen genügt ein Doppelklick. Man
bekommt einen Ordner, dessen Name mit psi-slides anfängt, und
dieser Ordner ist das ganze Werkzeug. Irgendwohin legen, wo man ihn
wiederfindet, denn gleich muss man das Terminal darauf zeigen.
Unter Windows das .zip wirklich entpacken und nicht nur per
Doppelklick öffnen: Windows zeigt den Inhalt eines ZIP wie einen Ordner an,
aber darin lassen sich keine Befehle ausführen.
Das Terminal auf den Ordner zeigen
cd psi-slidesDie cd-Zeile muss benennen, wo der Ordner tatsächlich liegt:
unter Windows etwa cd C:\Users\du\Downloads\psi-slides. Statt
den Pfad zu tippen, cd und ein Leerzeichen tippen und dann den
Ordner aus dem Dateimanager ins Terminalfenster ziehen – der Pfad schreibt
sich selbst.
Holen, was der Build benutzt
npm installMan führt npm install einmal aus, in diesem Ordner, und es
dauert ein paar Sekunden. Es holt die Schriften, die psi-slides in jede Vorlesung
einbettet, und die Handvoll Pakete, die der Build benutzt. Alles landet in
einem Ordner node_modules neben build.js:
systemweit wird nichts installiert, und die gebauten Vorlesungen öffnen
sich auch ohne diesen Ordner.
Das Tutorial bauen
node build.js lectures/tutorial/source.mdDer Build berichtet, was eingebettet wurde – die Bilder, die Schriften, die QR-Codes, die gesetzten Formeln – und endet damit, was er geschrieben hat. Dieselbe Zeile funktioniert auf Windows und macOS, Schrägstriche eingeschlossen: Node nimmt sie auf beiden.
Wrote lectures/tutorial/print.html, lectures/tutorial/print-notes.html, lectures/tutorial/audience.html, lectures/tutorial/speaker.html (12 columns, 92 chunks)Öffnen
Doppelklick auf lectures/tutorial/audience.html. Es öffnet
sich im Browser, und ein Browser ist alles, was es braucht: mit ? bekommt man die
Tastenliste, mit S das Cockpit. Die Datei an jemanden mailen, der
nichts davon installiert hat, und sie funktioniert trotzdem.
Für Linux: all das kommt aus dem Paketmanager.
Distributionspakete hinken manchmal mehrere Versionen hinterher, ein
node --version lohnt sich also trotzdem.
Was noch nicht festgeschrieben ist
Beide Wege oben bauen alles, was psi-slides kann. Was sie noch nicht mitgeben können, ist eine Zusage über alles davon: Das Quellformat liegt seit 1.0.0 fest, und was seitdem dazugekommen ist, fällt bis zum nächsten Release nicht unter diese Zusage.
Abbildungen als ::: draw, die
Titelfolien und Trenner, Karten und
Zeilen und der grafische Abbildungseditor kamen
nach 1.0.0. Man bekommt sie auf beiden Wegen: Die App wurde mit ihnen
paketiert, und ein Clone oder ein Quell-ZIP ist der aktuelle Stand des
Projekts.
Es sind keine Experimente. Die Referenzvorlesungen auf dieser Website sind damit gebaut, ebenso die sechsunddreißig Folien Netzsicherheit, für die die Abbildungssprache geschrieben wurde.
Nicht zugesagt ist, dass sie genau so bleiben, wie man sie heute
schreibt. Alles, was eine Vorlesung schon vor 1.0.0 benutzt hat, baut
unverändert weiter. Eine Vorlesung mit einem cover:, einem
::: dock oder einem ::: draw-Block kann eine
Änderung an der eigenen Quelle nötig machen, wenn diese Teile ein eigenes
Release erreichen.
Beide haben eine eigene Seite hier, geschrieben gegen den Stand, den man bekommt: Eine Folie ist ein Rahmen und Figures you write.
Eine eigene Vorlesung schreiben
Eine Vorlesung ist ein Ordner mit einer source.md
darin. Diese erste Datei lieber schreiben lassen, als von einem leeren Blatt
anzufangen: Der Einstellungsblock oben in einer source.md, ihr
Vorspann, hat Schlüssel, die ein leeres Blatt nicht erraten kann.
Was in diese Datei gehört, lehrt die Tutorial-Vorlesung, eine Vorlesung über das Schreiben von Vorlesungen: das Format im Betrieb gezeigt statt beschrieben, mit ihrer Quelle daneben.
Drei Befehle
Mit --new bekommt man einen Ordner mit gültigem
Einstellungsblock und ein paar Beispiel-Chunks – ein Chunk, eine Folie.
Danach lässt man --watch mitlaufen.
lint.js laufen lassen, bevor man etwas
weitergibt: doppelte Chunk-IDs, offene :::-Blöcke, Folien über
ihrem Wortbudget, Dateien zu groß zum Einbetten.
# einen neuen Vorlesungsordner anlegen, Einstellungsblock inklusive
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 :::-Blöcke, zu große Dateien
node lint.js lectures/my-lecture/source.mdIn der App fragt Neue Vorlesung… nach einem Ordnernamen und
einem Ort und legt dieselbe Starter-Vorlesung an, die --new
anlegt, bis hin zu einer kleinen Abbildung, die der Editor öffnen kann. Bei
jedem Speichern neu zu bauen ist der Normalzustand des Fensters und kein
Schalter, den man setzt, und es zeigt, was der Build sagt, und nicht mehr
als das – weshalb lint.js etwas bleibt, das man tippt; seine
Meldungen nennen die Regel und die Zeilennummer, man liest sie also neben der
eigenen Quelle.
Zum Weiterlesen
- Was psi-slides ist Die Startseite: eine Vorlesung, wie der Raum sie sieht und wie die Lesenden sie bekommen, und warum das dieselbe Datei ist.
- Wie psi-slides sich vergleicht Beamer, reveal.js, Quarto, Marp, Slidev, PowerPoint und andere, in beide Richtungen, einschließlich der Stellen, an denen psi-slides verliert.
- Figures you write Die Begründung für die Abbildungssprache, und das Handbuch daneben, das eine Abbildung Zeile für Zeile aufbaut und jede Anweisung auflistet.
- Das Repository Die README erklärt das Format und sagt, wofür das Werkzeug taugt und wofür nicht.