mgubi/texmacs

TeXmacs-Dokumente

Ein praktischer Leitfaden für Agenten, die mit GNU TeXmacs arbeiten, erstellt während der Konvertierung von Vorlesungsnotizen und Vorträgen, des Schreibens von Style-Paketen und der Prüfung langer mathematischer Manuskripte. Halten Sie ihn lebendig: Fügen Sie neu Gelerntes zu „Fallstricke“ hinzu und halten Sie die Skripte in scripts/ funktionsfähig. Projektspezifische Ergänzungen gehören in einen separaten lokalen Skill, der hierher verweist; der Abschnitt „Konventionen (zwingend erforderlich)“ gilt überall. Quelle: https://github.com/mgubi/texmacs-skill. Letzte Aktualisierung: 2026-11-04.

Diesen Skill aktuell halten

Dieser Skill soll als Git-Klon installiert werden (normalerweise ~/.claude/skills/texmacs). Bevor Sie an TeXmacs-Dokumenten arbeiten:

• Aktualisieren Sie ihn: führen Sie git -C <Skill-Verzeichnis> pull --ff-only aus (falls SSH zu GitHub fehlschlägt, pull von https://github.com/mgubi/texmacs-skill.git main). Wenn der Klon lokale Änderungen oder Commits hat, die nicht gepusht wurden, informieren Sie den Benutzer anstatt darüber zu pullen.
• Tragen Sie bei: wenn etwas Neues über TeXmacs gelernt wird, fügen Sie es hier hinzu (normalerweise zu „Fallstricke“ oder korrigieren Sie ein Skript), committen Sie es im Klon und pushen Sie es nach GitHub (oder öffnen Sie einen Pull-Request, wenn Sie nicht pushen können), damit jede Installation es erhält. Projektspezifisches Material verbleibt im Projekt.

Das Dateiformat

• Eine .tm-Datei ist ein serialisierter Baum: <tag|arg1|arg2> inline, <\tag>…</tag> (mit <|tag> zwischen Argumenten) für Block-Argumente, Absätze werden durch Leerzeilen getrennt, Einrückung dient nur der Darstellung. Innerhalb von Zeichenketten ist \<alpha\> ein Symbol, <less>/<gtr> sind </>, \| ist ein senkrechter Strich, <#89AB…> sind hexadezimale Rohdaten (eingebettete Bilder).

• Kodierung: Zeichenketten sind Cork (T1) kodiert, nicht UTF‑8. Akzentuierte lateinische Buchstaben stimmen größtenteils mit Latin‑1-Bytes überein (é = 0xE9, à = 0xE0, ö = 0xF6), aber z. B. Gedankenstrich = 0x15, Geviertstrich = 0x16, § = 0x9F; jedes andere Unicode-Zeichen wird als <#XXXX> (hex Codepunkt) geschrieben. Schreiben Sie <#XX> nicht selbst als eigenständiges Token: es wird als Rohdaten gelesen (siehe „Style-Pakete schreiben“). Konsequenzen: Bearbeiten Sie eine .tm niemals mit UTF‑8-Werkzeugen (die Bearbeitungs-/Schreibwerkzeuge verweigern oder beschädigen sie). Lesen/Schreiben mit Python encoding='latin-1', newline='', oder besser über den stree-Weg unten und lassen Sie TeXmacs die Datei schreiben.

• Manuelles Schreiben einer .tm-Datei: Kopieren Sie dieses Skelett genau. Die Elemente der obersten Ebene werden durch Leerzeilen getrennt; ohne sie behält TeXmacs nur den <TeXmacs|…>-Header und verwirft leise alles andere (der stree-Dump ist (document (TeXmacs "2.1.5")), das PDF ist leer, und es gibt keine Fehlermeldung):

  <TeXmacs|2.1.5>
  
  <style|<tuple|article|british>>
  
  <\body>
    Erster Absatz mit <math|x<rsup|2>>.
  
    Zweiter Absatz.
  </body>
  
  <\initial>
    <\collection>
      <associate|font|TeX Gyre Pagella>
    </collection>
  </initial>
  

  Innerhalb von <\body> werden Absätze (und die Blöcke jedes <\tag>…</tag>) ebenfalls durch Leerzeilen getrennt; ein einzelner Zeilenumbruch setzt denselben Absatz fort. Schließen Sie jedes Block-Tag in einer eigenen Zeile, maskieren Sie Symbole als \<alpha\> und literale <, >, | im Text als <less>, <gtr>, \|, und halten Sie die Datei Cork/Latin-1 (schreiben Sie sie mit Python, nicht mit printf oder dem Schreibwerkzeug, sobald sie ein Nicht-ASCII-Zeichen enthält).

• Bevorzugen Sie Generierung gegenüber manueller Eingabe. Für alles, was über ein paar Zeilen hinausgeht, bauen Sie den stree in Python (scripts/latex2tm/stree.py) und lassen Sie TeXmacs ihn serialisieren (tm-undump in dump.scm); oder schreiben Sie das Fragment, tm-dump Sie es und fügen Sie den Baum zusammen. Wenn Sie von Hand schreiben, überprüfen Sie das Ergebnis, bevor Sie es verwenden: tm-dump Sie es und bestätigen Sie, dass der Körper die erwartete Anzahl von Absätzen hat, oder setzen Sie es und bestätigen Sie, dass der PDF-Text nicht leer und vollständig ist (mutool draw -F txt). Ein leeres oder kurzes PDF oder ein Dump mit einem riesigen Knoten bedeutet einen Formatierungsfehler, keinen TeXmacs-Fehler.

• Große Dateien: Vorträge betten Bilder als Rohdaten ein (10+ MB). Entfernen Sie <#…>-Läufe vor dem Lesen: re.sub(r'<#[0-9A-F]{200,}>', '<#HEX>', s).

TeXmacs serverlos ausführen

Binärdatei (macOS): /Applications/TeXmacs.app/Contents/MacOS/TeXmacs; unter Linux texmacs. Getestet mit 2.1.4 und 2.1.5. scripts/latex2tm/run.sh enthält den Pfad; passen Sie ihn dort an.

• Konvertieren: TeXmacs -headless -c in.tex out.tm -q (LaTeX-Import), -c in.tm out.pdf -q (PDF des aktuellen Puffers).
• Scheme: TeXmacs -headless -x "(begin (load \"/abs/dump.scm\") … (quit-TeXmacs))". Wickeln Sie den Körper immer in (catch #t (lambda () …) (lambda args (display args))) und enden Sie mit (quit-TeXmacs): ein Fehler lässt den Prozess ansonsten für immer hängen. Führen Sie ihn im Hintergrund aus und pollten Sie seine PID (siehe scripts/latex2tm/run.sh); töten Sie nur diese PID — niemals pkill TeXmacs (der Benutzer könnte TeXmacs geöffnet haben).
• Serverlose Läufe schreiben TeXmacs' eigenen Zustand unter ~/.TeXmacs/system; das ist normal.

Scheme-API, die serverlos funktioniert (scripts/latex2tm/dump.scm)

• (tree-import (string->url f) "texmacs") / "latex", und (tree-export t (string->url f) "texmacs"): Datei ↔ Baum ohne Puffer.
• (tree->stree t) / (stree->tree s): s‑Ausdrücke. Schreiben Sie sie mit (call-with-output-file f (lambda (p) (write s p))) — with-output-to-file leitet in TeXmacs' Guile nicht um. Guile schreibt Steuerzeichen als \xHH-Maskierungen (behandelt von scripts/latex2tm/stree.py).
• Setzen: (load-buffer u) (switch-to-buffer u) (export-buffer-main u (string->url pdf) "pdf" (list)) — der PDF-Export ist das, was setzt. (update-document "all") tut serverlos nichts (es ist ein verzögerter Leerlaufbefehl); rufen Sie (generate-all-aux) (update-current-buffer) direkt auf, um das Inhaltsverzeichnis/Literaturverzeichnis zu füllen, exportieren Sie erneut, dann (buffer-pretend-modified u) (buffer-save u), um <\references> zu speichern. Eine neue Datei benötigt zwei Setzläufe, in separaten Prozessen, jeder mit einem echten PDF-Export, bevor alle Referenzen aufgelöst sind (scripts/latex2tm/typeset.sh). Exportieren Sie immer mit (list :overwrite) als Optionen: serverlos fragt export-buffer-main ansonsten nach Bestätigung zum Ersetzen einer vorhandenen Datei, niemand antwortet, und der Export wird stillschweigend übersprungen (mgubi/texmacs#807). tm-typeset und tm-html in dump.scm tun dies.
• Präsentationen (screens) exportieren nur den aktuellen Bildschirm. Für eine visuelle Überprüfung erstellen Sie eine Vorschaukopie, bei der die Bildschirme in durch new-page* getrennte Seiten abgeflacht sind (scripts/latex2tm/preview_slides.py); liefern Sie die Bildschirmversion aus.
• Überprüfen Sie die Ausgabe mit mutool draw -r 60 -o p%d.png file.pdf und magick montage … -tile 4x1 -geometry +4+4; Text mit mutool draw -F txt -o - file.pdf (zählen Sie ? für unaufgelöste Referenzen).

HTML-Export

Führen Sie die HTML-Anpassung innerhalb von TeXmacs durch: Style-Pakete (oder ein Plugin) setzen die Variablen des Exporteurs und geben tmhtml--Darstellungen von Makros; eine Website wird erstellt, indem ein Verzeichnis exportiert wird (tmweb-convert-dir) mit TEXMACS_HOME_PATH, der auf den Plugin-Ordner der Site verweist, und (style-clear-cache). Verarbeiten Sie das generierte HTML nicht mit Skripten nach.

Sammeln Sie die generischen Korrekturen in einem Plugin (unten max-html genannt, verlinkt als ~/.TeXmacs/plugins/max-html), und behalten Sie dokumentspezifische Einstellungen im Paket des Dokuments. Ein solches Plugin enthält:

• progs/max-html/fixes.scm, geladen beim Start, korrigiert den MathJax-Export. Labels innerhalb von Formeln erhalten Anker (#617), \ring wird geschrieben \mathring (#607) und equations-base wird aligned geschrieben (#611). Es ersetzt die Bindung von tmhtml-mathjax-formula* innerhalb von (convert html tmhtml) (module-variable + variable-set!; interne Helfer wie cork->html über module-ref) und erweitert latex-mathjax mit tm-define … (former x).

• Das Paket max-html (Artikel) gibt gerahmte Theoreme, Listeneinträge und das Inhaltsseitenpanel div.max-toc. Das Paket max-html-slides gibt den Folienbetrachter und tmhtml-mytitle/myframed/myframed-2.

• resources/ enthält max-html.css/js und max-html-slides.css/js, die Sie neben die Seiten kopieren. Dokumentpakete <use-package|max-html> und weisen das gesamte html-extra-css-Tupel erneut zu (Plugin-Datei zuerst): merge funktioniert nicht, da der Exporteur die Variable unausgewertet liest. Schriftarten sind CSS-Variablen (--max-text-font, --max-slide-font).

• Generische Korrekturen für den HTML-Export gehen in das Plugin. Dokumentspezifische Dinge (Schriftarten, Favicon, Vortragsmakros) gehen in das Paket des Dokuments.

• Export: (tm-html in out mathjax?) in scripts/latex2tm/dump.scm (Einstellungen texmacs->html:mathjax|css|images, dann (export-buffer-main u (string->url "x.html") "html" (list))). Exportieren Sie das gesetzte .tm (gespeicherte <\references> geben die Nummern). doc.tm#label Links werden zu doc.html#label; Bilder werden <base>-N.png neben der Seite; MathJax 3 kommt von jsdelivr.

• Stilvariablen, die vom Exporteur gelesen werden (setzen Sie sie in einem Style-Paket): html-css (ersetzt das standardmäßige Inline-CSS), html-extra-css (Tupel von zusätzlichen Stylesheets, Standard-CSS bleibt erhalten), html-extra-javascript-src (Tupel, verzögert), html-extra-javascript, html-head-javascript(-src), html-head-favicon, html-title, html-doc-title, html-site-version.

• HTML-Darstellungen von Makros: definieren Sie tmhtml-NAME neben NAME. Der Exporteur verwendet es anstelle von NAME. Markup-Helfer dafür: html-div-class|class|body (Block), html-class|class|body (Inline-Spanne), html-style, html-div-style, html-attr, html-tag, html-javascript. Dies funktioniert nur für Makros, die in einem Style-Paket definiert sind: Makros, die in der hide-preamble des Dokuments zugewiesen werden, werden vor dem Export erweitert und ihre tmhtml--Varianten werden ignoriert. Platzieren Sie Präsentationsmakros also in einem Paket.

• Ein Paket foo.ts neben dem Dokument wird gefunden, wenn das Style-Tupel foo auflistet. Nach dem Bearbeiten eines Pakets rufen Sie (style-clear-cache) auf (TeXmacs speichert Style-Umgebungen im Cache unter ~/.TeXmacs/system/cache), sonst werden alte Definitionen verwendet.

• Inhaltsverzeichnis (und andere generierte Listen): die Einträge werden in die aux-Daten bereits erweitert geschrieben (write wertet sein Argument aus), also verschwinden Wrapper um toc-main-*/toc-1…5 und ihre tmhtml- Varianten werden nie gesehen. Nur das äußere table-of-contents-Makro kann eine tmhtml--Darstellung haben. Marker, die Erweiterung und Export überleben: <b> (fette Abschnitte), <with|font-size|…> → <font style=…>, font-shape → <i>/Kapitälchen, color → <font color>; par-left-Einrückung geht verloren. Jeder Eintrag endet mit <a href="#auto-N">page</a>. Seitenpanel-Rezept (Plugin-Paket max-html): tmhtml-table-of-contents → div.max-toc links fixiert; verstecken und dehnen Sie den Seitenlink mit .max-toc p a[href^="#auto-"] {position:absolute; inset:0; font-size:0} (Auswahl nach href: ein eqref in einem Titel ist ebenfalls ein Link); markieren Sie Einträge auf Absatzebene, indem Sie toc-3…5 mit einem verschachtelten <with|font-size|0.92|…> neu definieren und p:has(> font) auswählen. Regenerieren Sie das Inhaltsverzeichnis (zwei Setzläufe) nach dem Ändern von toc-*-Makros.

• Hervorheben des aktuellen Abschnitts im Panel benötigt JavaScript: max-html.js (Plugin), angehängt mit html-extra-javascript-src im Paket; es ordnet den #auto-N-Link jedes Eintrags der Überschrift mit dieser ID zu, markiert die letzte Überschrift über 25 % des Viewports (p.toc-current, und ihr fettes Elternelement p.toc-current-section) und scrollt das Panel, um sie sichtbar zu halten.

• Gerahmte Theoreme (Joris van der Hoevens Web-Artikel, z. B. texmacs.org/joris/fftcomp; das Vorbild ist styles/article/texmacs/tmarticle.ts in TeXmacs): definieren Sie tmhtml-render-theorem → <html-div-class|theorem|<render-enunciation|…>> und tmhtml-render-enunciation mit <html-class|enunciation-name|which>; Theorem, Proposition, Lemma, Korollar und Definition verwenden render-theorem, während Bemerkungen und Beweise render-remark verwenden. Joris' CSS (texmacs.org/css/theme-dark-colored.css) ist .theorem {border: 1px solid; border-left: 1em solid; padding: 0 1em}; eine gedämpfte Farbe und eine 0,5em breite Leiste funktionieren ebenfalls gut (max-html.css). Dies ist nur HTML; das PDF bleibt unverändert. Farben (auch wie in Joris' Theme): h1…h6, strong, b, dt, .enunciation-name in einem gedämpften Dunkelrot, MathJax-Ausgabe via mjx-container {color: …}; setzen Sie b innerhalb des Inhaltsverzeichnis-Panels zurück.

• Der HTML-Export verwandelt jede enumerate-alpha|Alpha|roman in eine einfache <ol> (dezimal Labels). Korrektur: tmhtml-enumerate-alpha → <html-div-class|enum-alpha|<enumerate|…>> plus .enum-alpha > ol > li::marker {content: "(" counter(list-item, lower-alpha) ") "}.

• MathJax: der Konverter schreibt die Ring-Akzentuierung <abovering> als \ring{…} (LaTeX-Paket accents), die MathJax fehlt (mgubi/texmacs#607). Korrigiert durch das Plugin. Eine Alternative auf Seitenebene ist eine Inline-MathJax-Konfiguration in html-extra-javascript (sie wird vor dem MathJax <script> ausgeführt): `window.MathJax = {tex: {macros: {ring: [String.fromCharCode(92)

  • 'mathring{#1}', 1]}}}`.

• MathJax: aligned innerhalb einer equation wird vom HTML-Exporteur vorerweitert zu equations-base und erreicht MathJax als \begin{equationsbase} (mgubi/texmacs#611). Korrigiert durch das Plugin; die Alternative auf Seitenebene ist environments: {equationsbase: […aligned…]} in dieser Konfiguration.

• Überprüfen Sie alle Formeln eines Exports mit scripts/mathjax-check/: npm install [email protected] in einem temporären deps/-Ordner, dann python3 extract.py HTMLDIR formulas.json (verwendet einen HTML-Parser: rohes < in \(t < \infty\) ist Text, wie in Browsern) und node check.js deps/node_modules formulas.json. Es rendert jede Formel ohne das Paket noundefined (das im Browser stillschweigend undefinierte Makros in Rot anzeigt) und gruppiert die Fehler. Es sieht keine leeren Formeln (zählen Sie \(\displaystyle \) separat) oder tote Links: überprüfen Sie auch, dass jeder interne href="…x" einen passenden id="x" hat.

• Folien: Ein Bild mit width=100%, verengt durch eine CSS max-height, bleibt am linken Rand seines Absatzes; zentrieren Sie es mit div.toggle img.image {display: block; margin: 0 auto}.

• Serverloses Firefox: die content-override-Einstellung in user.js trat nicht in Kraft; zum Ändern des Standard-User-Agents verwenden Sie export MOZ_REMOTE_SETTINGS_DISABLED=1 und die Serverlos-Flag, bevor Sie firefox --headless in scripts/latex2tm/run.sh starten.

Style-Pakete schreiben

• Hängen Sie immer ein Test-Tag an <TeXmacs|2.1.5> an (<TeXmacs|2.1.5|foo>). Das Symbol foo wird dann in den Status des Style-Pakets aufgenommen und macht es zu einer „Paket“-Quelle (siehe TeXmacs-Handbuch, Abschnitt 5.3), was die Konvertierungsroutinen auslöst, die sonst (völlig korrekt) einen Konvertierungsfehler ausgeben würden, wenn sie auf ein Template-Makro mit unbekannten Argumenten treffen. Es ist ein Leer-Tag, das Sie nicht weiter verwenden.
• Fügen Sie tmdoc zur Style-Liste hinzu, wenn Sie Paketbefehle wie <svar|…> oder <explain|…> im Dokument verwenden möchten. (Das Test-Tag gehört in die .ts-Datei, nicht in das Dokument.)
• Entwickeln Sie Method-Style-Makros: Manuelles Erstellen von <\nonum-cases> aus <cases> funktioniert nicht. Definieren Sie stattdessen <new-edit|nonum-cases|true> und eine <render-nonum-cases> mit render-cases über tm-define (Guile). Kopieren Sie scripts/latex2m/stree.py, um das Skript zu schreiben, das das Paket erstellt (stree.ts).
• <assign|font|…>, <assign|par-left|…>, <assign|par-first|…> im Paket haben keine Wirkung auf das Setzen, da sie durch die Absatz-Stil-Umgebung überschrieben werden. Verwenden Sie stattdessen <new-style|mypar|…>.
• Horizontale Positionierung anstelle von manuellem Leerraum: <space|…>, <hspace|…>, <tab|…>. Verwenden Sie <tab|#|…> für wiederholte Füllungen (z. B. <tab|1fn|.> für Inhaltsverzeichnisse) und <tab|#|2spc|#|*>, um einen zweiten Eintrag rechtsbündig auszurichten.

Unverzichtbare Konventionen (für Projekte)

Der Punkt unten gilt für alle Dateien, die mit diesem Skill erstellt werden. Er wird in der SKILL.md des Projekts (für Menschen) wiederholt und in der CLAUDE.md des Projekts (für Agenten).

Aufbewahrungsfrist: Löschen Sie niemals Rohmaterial (Aufnahmen, Faksimiles, Handskizzen) vor dem endgültigen Überprüfungstermin. Dieses Datum liegt 6 Monate nach der Veröffentlichung, die das Material verwendete. Wenn es überschritten ist, fragen Sie den Benutzer, ob gelöscht werden kann.

Fallstricke

• Keine UTF-8-Dateien. Niemals. Verwenden Sie encoding='latin-1' und überprüfen Sie, dass der Text .tm wörtliche Bytes >0x7F enthält (die Latein-ähnlichen).
• Kein printf oder echo, um eine .tm-Datei zu schreiben, die mehr als ein paar Zeilen enthält. Verwenden Sie Python.
• Kein pkill von TeXmacs.
• Keine tmhtml--Varianten für Makros in hide-preamble; sie werden erweitert, bevor der Exporteur sie sieht.
• TeXmacs-Problem export-buffer-main ohne :overwrite fragt nach Bestätigung, erhält sie nicht und tut nichts (mgubi/texmacs#807).
• TeXmacs-Problem with-output-to-file in Guile leitet display nicht um (mgubi/texmacs#858).
• TeXmacs-Problem update-document ist ein Leerlaufbefehl und tut serverlos nichts. Verwenden Sie stattdessen (generate-all-aux) (update-current-buffer).
• TeXmacs-Problem #617: MathJax-Konverter schreibt Labels in Formeln als <a …>, das MathJax als \label{…} markiert, aber der Anker wird nicht generiert; Korrektur: \def\label#1{\ltxml@attribute{href}{#1}}.
• TeXmacs-Problem tm-dump von <#89AB…> wird mit einer Byte-Längenangabe gedumpt (z. B. #[2300 …]), was der Parser in stree.py nicht mehr zurück zu <#…> serialisieren kann.
• setzen: zwei Läufe für ein neues Dokument, das ein Inhaltsverzeichnis oder eine Bibliographie enthält.
• HTML-Export: <#89AB…> in Schriftarten: Jeder Font, der ein <#ff>…-Bild enthält, erzeugt eine PNG-Datei mit dem Inhalt des Tags; obwohl dieses Bild leer ist, wird der Text danach korrekt im Browser angezeigt. Der Exporteur darf nicht mit #<…>-Token umgehen; dies ist normal.