baip/skills

Barrierefreie Kursnotizen aus handschriftlichen und getippten Originalen

Das Ergebnis ist eine Markdown-Datei pro Dokument plus ein Figurenzeichnungsskript pro Dokument. Ein getaggtes PDF und eine Website werden daraus mit dem hier gebündelten Toolkit generiert. Das Markdown ist die einzige Quelle: Korrekturen erfolgen in der .md, niemals im generierten .tex oder HTML.

                     ┌─ python mkweb.py → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
                     └─ python md2tex.py → <class>.cls → lualatex  → PDF neben der .md

Ein Projekt sieht so aus:

md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py   Build-Skripte, vom Stamm aus ausgeführt
<class>.cls  contents.yaml  CONVENTIONS.md  BUILD.md
src/                 Vorlesungen: NN_Name.md, mit NN_Name.tex und .pdf daneben
2026/                Aufgaben und Prüfungen eines Jahrgangs, gleiche Anordnung
figures/             fig_<dokument>_<NN>_<name>.svg und die daraus erstellten PDFs
scripts/figures_audit.py
scripts/figures/     figlib.py, make_figures_<dokument>.py, Datenhelfer
originals/  work/    die Originale und Seitenbilder, nicht versioniert

Was gebündelt ist

Pfad	Nutzung
scripts/init_project.py	Ein neues Projekt erstellen oder in einem bestehenden --update-toolkit ausführen
scripts/render_pages.py	Seiten eines Originals (und vergrößerte Ausschnitte) rendern, um sie zu lesen
scripts/contact_sheet.py	geänderte SVG-Figuren auf ein PNG rendern, um sie zu prüfen und zu versenden
scripts/notation_lint.py	Notation-Kompromisse melden: Grenzwerte in Worten, beschriftete Anmerkungen, abgeflachte Indizes, Buchstaben außerhalb des Mathematikmodus, fehlerhafte Alt-Blöcke, Glyphen, die der PDF-Schriftart fehlen
assets/toolkit/	die Build-Skripte und notes.cls, platziert durch init_project.py in einem Projekt
assets/templates/	contents.yaml, eine Beispielvorlesung und ein Zeichnungsskript, .gitignore, package.json
references/transcribing.md	Lesen von Originalen, OneNote-Besonderheiten, Vorlesungen und Hausaufgaben, Prüfungen vor der Übergabe
references/figures.md	Wie man Abbildungen zeichnet, die einer Überprüfung standhalten
references/notation-pass.md	Überarbeiten bestehender Dokumente in echte Notation, alleine oder mit parallelen Helfern
references/review-and-delivery.md	Überprüfungsrunden, Git, Arbeiten über einen Dateitransfer, Veröffentlichung
references/conventions.md, references/building.md	werden zum CONVENTIONS.md und BUILD.md des Projekts

0. Projekt einrichten oder finden

1. Nach einem bestehenden Projekt suchen: contents.yaml, md2tex.py, eine *.cls, CONVENTIONS.md, BUILD.md. Wenn vorhanden, zuerst dessen CONVENTIONS.md und BUILD.md lesen und befolgen, wo sie von diesem Skill abweichen, da sie die Entscheidungen des Autors festhalten. Auch die letzten Commits des Projekts prüfen: Der Autor überarbeitet Dokumente oft von Hand, und diese Überarbeitungen sind der aktuelle Hausstil (Frontmatter-Formulierung, was die Schlussnotizen enthalten).

2. Sonst ein neues erstellen:

   python3 <skill>/scripts/init_project.py <verzeichnis> \
       --title "CHEM 101 — Allgemeine Chemie" --short "CHEM 101" \
       --class chem101 --author "…" --copyright "…"
   

   Die Beispielvorlesung einmal bauen, um zu bestätigen, dass der Rechner eingerichtet ist (BUILD.md listet die Installationen auf), dann aus contents.yaml, src/, scripts/figures/ und figures/ entfernen.

3. In einer Runde fragen, was nicht abgeleitet werden kann: Kursname und Kurzcode, welche Dokumente zuerst kommen, wo die Originale und das Projekt liegen (Uploads, ein Ordner auf dem Rechner des Autors, ein Git-Repository), ob das PDF und die Website in jeder Runde gebaut werden sollen und wer pusht. Sofern nicht anders angegeben, lokal committen und niemals pushen.

4. Die stehenden Anweisungen gelten für jede spätere Runde, bis sie aufgehoben werden („nicht bauen“, „selbst pushen“).

1. Originale lesen

Textextraktion liefert nur getippten Text. Handschrift und Skizzen sind Tinte, also die Seiten rendern und als Bilder lesen, bei kleinen Details vergrößern:

python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5

references/transcribing.md vor dem ersten Dokument lesen.

2. Transkribieren

Dem CONVENTIONS.md des Projekts folgen. Die wichtigsten Regeln:

• Wohin es kommt. Eine Vorlesung ist src/NN_Name.md; Hausaufgaben und Prüfungen kommen in den Jahresordner (2026/hausaufgabe03_loesung.md). Jede in contents.yaml mit checked: false eintragen. Nur der Autor setzt es auf true, was die Veröffentlichung auf der Website bewirkt.
• Frontmatter. title, docheading (die einzige h1), lang, runningfoot, description („ Vorlesungsnotizen: .“), subtitle („.“). Überschriften im Text beginnen bei ## und überspringen keine Ebene. Kein „Über diese Transkription“-Hinweis und keine Seitenbegrenzungsmarkierungen: Der Autor entfernt sie, also keine hinzufügen.
• Hausaufgabenlösungen. Nur die Lösungen transkribieren, unter ## Aufgabe N und ### Teil (a): <was gefunden wird>. Stellt der Autor die Aufgabensammlung bereit (als .tex oder .pdf), diese verwenden, um die Lösungen und die Notation zu verstehen, nicht als zu konvertierenden Text.
• Mathematik: Notation des Originals, korrekt gesetzt. LaTeX in $…$ und $$…$$ innerhalb von ::: eq. Summen, Produkte und Integrale tragen ihre Grenzen; Matrizen und Determinanten werden gesetzt; Schreibschrift ist \mathcal{}; laufende Indizes kursiv, Bezeichnungen aufrecht; echte verschachtelte Indizes (x_{j}, niemals x\, j); Wörter in \text{}; kein \left(\right) um einen nackten Bruch, es sei denn gezeichnet; \, nur nach einem Komma in einer Indexliste, zwischen benachbarten Brüchen und vor einem Differential; {} nach einer \underbrace, gefolgt von einem Operator; \exp(…) für einen Exponenten, der einen Bruch trägt.
• Handschriftliche Anmerkungen werden Notation (\cancel, \underbrace{…}_{0}, beschriftete Klammern, \overset{…}{=}, \boxed, Evaluierungsstriche), und eine solche Gleichung erhält eine gesprochene Form: ::: {.eq alt="…"}, die genau eine angezeigte Gleichung enthält, mit einem einfachen Satz, der die Markierungen benennt (kein LaTeX, keine doppelten Anführungszeichen). Gewöhnliche Gleichungen erhalten kein Alt: MathJax' MathML erlaubt es einem Screenreader, sie zu durchlaufen.
• Dem PDF-Textschrift fehlen einige Symbole (⋮, ①, π, ′, ≪, ≫). Sie als Mathematik schreiben ($\vdots$), und „Zustand 1“ für eingekreiste Zahlen. Der Build schlägt bei jedem fehlenden Zeichen fehl.
• Tabellen: Nur Pipe-Tabellen, mit einer Kopfzeile, keine Regeln. Bei einer langen Tabelle eine Abbildung davor setzen, niemals direkt danach. Tabellen schmal genug für die Seite halten (der Build warnt, wenn eine zu breit ist).
• Blöcke: ::: eq, ::: problem, ::: keep, ::: flush, ::: quote, ::: note. Es gibt kein [H].
• Fehler im Original werden wie geschrieben transkribiert und in den Schlussnotizen mit Beleg gekennzeichnet, niemals stillschweigend korrigiert. Wenn der Autor sagt, einen zu korrigieren, dann korrigieren.
• Schlussnotizen (## Anmerkungen zu Barrierefreiheitsänderungen) enthalten nur das, was der Autor prüfen oder entscheiden muss: mögliche Fehler, unsichere Lesarten, Ergänzungen. Keine Standardtexte.

Vor dem Bauen python3 <skill>/scripts/notation_lint.py <dokument>.md ausführen: seine Fehler müssen behoben, seine Warnungen am Original überprüft werden.

3. Jede Abbildung neu zeichnen

Jede Skizze wird zu einem SVG, gezeichnet von scripts/figures/make_figures_<dokument>.py auf Basis von figlib.py, benannt als fig_<dokument>_<NN>_<name>.svg, relativ vom Markdown aus referenziert als:

![**Titel.** Lange Beschreibung.](../figures/fig_....svg){#fig-<dokument>-<NN> width=NNN alt="…"}

und zitiert als [](#fig-<dokument>-<NN>). Niemals eine Abbildungsnummer von Hand schreiben. references/figures.md vor dem Zeichnen lesen. Kurzgefasst: Kurven aus Gleichungen berechnen, im Plot zentrieren, Pfeile an den Objekten beginnen und enden lassen, Beschriftungen nahe und deutlich fern von Linien halten (place_label in dichten Plots), Akzente und eingekreiste Zahlen zeichnen statt tippen, viewBox auf die Zeichnung dimensionieren und die Bildunterschrift aktualisieren, wenn die Zeichnung sich ändert.

4. Bauen und prüfen

python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <name>                  # z. B. 09_Mischungen oder hausaufgabe03_loesung
python3 buildtex.py <name>                # 12 Prüfungen plus eine Warnung bei zu breiten Tabellen
python3 mkweb.py && python3 checkweb.py   # 9 Prüfungen pro Seite, inkl. MathJax-Fehler
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<dokument>_*.svg

• Das Ausgabe ansehen. Das Kontaktblatt jeder geänderten Abbildung betrachten und die PDF-Seiten mit geänderten Gleichungen, Tabellen und Abbildungen rendern. Das Blatt dem Autor zusenden.
• Ein mit checked: false zurückgehaltenes Dokument erscheint nicht auf der Website. Um die Seite zu testen, die Website in einer temporären Kopie mit true setzen.
• Prüfung 11 („Alternativtext von Formeln ist kein rohes LaTeX“) schlägt auf älteren TeX-Live-Versionen vor tagpdf 1.0 fehl. Wenn es auf dem Rechner fehlschlägt, der die veröffentlichten PDFs erstellt, dies mitteilen, nicht verstecken.
• Wenn der Autor gesagt hat, nicht zu bauen, keine Build-Ergebnisse in seinen Ordner schreiben. Eine temporäre Kopie anderswo ist in Ordnung, um riskante Änderungen zu prüfen.
• Die Prüfungen sind notwendig, nicht hinreichend. PAC 2024 auf den PDFs und ein WCAG-Audit der Website vor der Veröffentlichung empfehlen.

5. Überprüfungsrunden und Stapelüberarbeitungen

references/review-and-delivery.md lesen. Kurzgefasst: zuerst mit den aktuellen Dateien des Autors synchronisieren, eine Aufgabe pro Aufzählungspunkt plus eine Überprüfungsaufgabe erstellen, jeden Punkt am Original gegenseitig prüfen, Fragen getrennt von Bearbeitungen beantworten (für eine Frage nichts ändern, bis der Autor entscheidet), projektweite Konventionen im Toolkit und in CONVENTIONS.md korrigieren und mit einer Zeile pro Punkt berichten.

Wenn der Autor dieselbe Überarbeitung für viele Dokumente verlangt (z. B. „05–10 an das anpassen, was ich bei 01–04 gemacht habe“), references/notation-pass.md lesen: Die eigene Überarbeitung des Autors als Modell studieren, die mechanischen Teile mit einem Skript erledigen und die arbeit pro Gleichung an parallele Helfer übergeben, zwei oder drei Dokumente pro Helfer, mit einem schriftlichen Auftrag.

6. Lieferung

• Auf dem Rechner des Autors bearbeiten, wenn das Projekt dort liegt. SVGs neu generieren, indem das Zeichnungsskript dort ausgeführt wird, anstatt sie zu kopieren, da Dateitransfers Bilder unterwegs umschreiben können. Beim Kopieren per Prüfsumme bestätigen.
• Mit der eigenen Identität des Autors committen und einer Nachricht, die die Punkte auflistet. Niemals pushen, es sei denn darum gebeten, und Hooks ablehnen, die dazu auffordern.
• Wenn die Verbindung zum Rechner des Autors abbricht, im eigenen Clone committen und ein Git-Bundle übergeben (git bundle create x.bundle <deren-zweig>..main), das sie pullen können, oder es anwenden, wenn die Verbindung zurückkehrt.
• python3 package.py erstellt ein Archiv des gesamten Projekts aus contents.yaml und verweigert dies, solange scripts/figures_audit.py fehlschlägt.
• Um ein Projekt mit einem neueren Toolkit zu versehen: python3 <skill>/scripts/init_project.py <verzeichnis> --update-toolkit.