Zum Inhalt springen

PreTeXt

    Was ist PreTeXt?

    PreTeXt ist ein XML-basiertes Textsatzsystem, das speziell für das Schreiben und Veröffentlichen wissenschaftlicher Dokumente entwickelt wurde, insbesondere für mathematische und naturwissenschaftliche Inhalte. Es legt großen Wert auf Barrierefreiheit, klare Dokumentstruktur und hochwertige Ausgabeformate.

    Dokumente, die in PreTeXt verfasst sind, können in zahlreiche Formate konvertiert werden, darunter HTML, PDF, EPUB/Kindle, Reveal.js‑Folien, Jupyter‑Notebooks und Braille (über Liblouis). Damit eignet sich PreTeXt sowohl für klassische Lehrbücher als auch für moderne, interaktive Online‑Materialien.
    Durch vorhandene Konverter ist PreTeXt auch für die Aufbereitung bestehender LaTeX‑Dokumente geeignet.

    PreTeXt ist ein XML‑Vokabular: Die Struktur wird über Tags definiert, ähnlich wie in HTML. Mathematische Formeln werden überwiegend in LaTeX‑Syntax geschrieben, was den Einstieg für LaTeX‑Nutzende erleichtert.

    PreTeXt.plus

    PreTeXt.plus ist ein Online‑Editor für PreTeXt‑Dokumente. Er bietet eine Overleaf‑ähnliche Oberfläche, die den Einstieg stark erleichtert. Zu seinen Funktionen gehören:

    • Live‑Vorschau der HTML‑Ausgabe,
    • Integrierter LaTeX‑Konverter, der das Schreiben in LaTeX ermöglicht,
    • Automatische Konversion nach PreTeXt im Frontend,
    • Niederschwelliger Einstieg ohne lokale Installation.

    Wenn bestimmte PreTeXt‑Funktionen vom LaTeX‑Konverter noch nicht vollständig unterstützt werden, ist eine Konversion ins PreTeXt‑Format im Editor weiterhin notwendig (siehe Konverter-Nachbearbeitungen).

    Neben den regelmäßigen Drop-In-Sessions empfiehlt sich zum Einstieg dieser Workshop des PreTeXt-Teams.

    PreFigure

    PreTeXt unterstützt mehrere bekannte Grafiksprachen, z.B. TikZ und Asymptote. Darüber hinaus wird aber auch das von PreTeXt inspirierte System PreFigure unterstützt. Mit PreFigure erstellte Grafiken haben gegenüber anderen Grafiken erhöhte Barrierefreiheit und können beispielsweise direkt zu einer taktilen Grafik mit Braille-Labels exportiert werden. Die Syntax ähnelt HTML.

    Welche Dokumente kann ich mit PreTeXt erstellen?

    In PreTeXt geschriebene Dokumente können als HTML, PDF, EPUB, Reveal.js-Folien, Jupyter Notebooks oder auch Braille ausgegeben werden.

    Welche Vor- und Nachteile hat PreTeXt?

    Vorteile

    • Insb. mit PreTeXt.plus sehr benutzerfreundlich.
    • Für LaTeX-Nutzende leicht zu erlernen.
    • Unterstützt eine breite Palette an LaTeX-Features, z.B. auch Bildgenerierungsbibliotheken wie TikZ.
    • Mit PreFigure können generierte Zeichnungen über die Bildbeschreibung hinaus zugänglich gemacht werden.
    • Gibt gut strukturierte Dokumente aus, die sich leicht navigieren lassen.
    • Sehr ausführliche Dokumentation unter pretextbook.org/guide.html und pretextbook.org/examples.html
    • Es gibt mehrwöchentliche Drop-In Sessions sowie vielfältige weitere Unterstützungsangebote. Auf Rückmeldungen wird schnell reagiert.

    Nachteile

    • Das Layout wird weitgehend von PreTeXt vorgegeben; Feintuning ist begrenzt.
    • Bei Konversion von LaTeX sind noch händische Nachbearbeitungen notwendig. Bei Benutzung von PreTeXt.plus ist dafür eine Konversion in PreTeXt notwendig.
    • Nicht alle Nummerierungsstrukturen der Originaldokumente lassen sich direkt abbilden.
    • PreTeXt.plus kann bei sehr langen Dokumenten an Grenzen stoßen

    Wie kann ich selbst eine PreTeXt‑Datei erstellen?

    Es gibt drei grundlegende Wege, PreTeXt‑Dokumente zu erstellen und zu konvertieren:

    1. PreTeXt.plus (empfohlen für Einsteiger)
      • Keine Installation notwendig
      • Overleaf‑ähnliche Oberfläche
      • Ideal für kurze und mittlere Dokumente
      • Kann bei sehr großen Projekten an Leistungsgrenzen stoßen
    2. GitHub / Online‑Workflow
      • Geeignet für kollaborative Projekte
      • Gute Integration mit Git
      • Automatisierte Builds möglich (z. B. GitHub Actions)
    3. Lokale Installation
      • Empfohlen bei Datenschutzanforderungen oder sehr großen Projekten
      • Volle Kontrolle über Build‑Prozess
      • Erfordert technisches Vorwissen (CLI, Python, Git)

    Wie kann ich von LaTeX zu PreTeXt konvertieren?

    Das Team von PreTeXt stellt einen Konverter zur Verfügung, der sich auf verschiedene Arten nutzen lässt. Hierbei wird im Hintergrund immer der gleiche Konverter genutzt. Dieser wird dauerhaft weiterentwickelt. Zum Zeitpunkt des Schreibens sind noch einige Nachbearbeitungen nötig.

    Anleitung lokale Konversion mit Pandoc

    Wir nutzen den Pandoc-Converter von Oscar Levin: github.com/oscarlevin/pandoc-pretext

    Dieser ist theoretisch dazu in der Lage, auch lange Dokumente auf einmal zu konvertieren. Wir geben hier eine Anleitung für eine stückweise Konversion, um die Nachbearbeitung zu erleichtern.

    Die Verwendung wird im Repository beschrieben, hier aber nochmal für unseren bestimmten Fall:

    1. Pandoc (pandoc.org/installing.html) installieren
    2. Die Dateien pretext.lua, pretext-environments.lua und pretext-latex-reader.lua herunterladen und im custom-Ordner des Pandoc user data directory ablegen. Den Pfad des Directory findet man unter pandoc --version. Der Ordner muss ggf. noch angelegt werden.
    3. Das zu konvertierende LaTeX-Dokument öffnen.
    4. Die gesamte Preamble in ein neues Dokument kopieren.
    5. Ein neues PreTeXt-Projekt erstellen, hier kann man der Anleitung im PreTeXt Guide folgen: pretextbook.org/doc/guide/html/tutorial-first-document.html und ein Beispielbuch oder einen Beispielartikel erstellen.
    6. Die LaTeX-Datei in handliche Stücke zerteilen (macht die Fehlerkorrektur leichter, und man vermeidet, dass der Konverter Fehler mit der Dokumentenstruktur macht). Es empfehlen sich etwa die kleinsten Teile des LaTeX-Dokuments (z. B. Subsections).
    7. Die Struktur im PreTeXt-Ordner widerspiegeln (also ch-… Dateien für alle Kapitel, sec-… für Sektionen usw.) und die untergeordneten Teile jeweils in ihren Elternteilen mit <xi:include href="./DATEINAME.ptx" /> einbinden. Dieser Schritt dient nur der Übersichtlichkeit. Es bietet sich an, nicht alles auf einmal anzulegen, sondern nur nach und nach, wenn man auch schon die Inhalte für die entsprechenden Kapitel oder Sektionen hat.
    8. Jetzt iterativ:
      1. Einen Unterabschnitt auswählen und aus dem LaTeX-Dokument herauskopieren.
      2. In die vorbereitete LaTeX-Datei, die nur die Preamble enthält, einfügen. Bei uns heißt diese Datei main.tex.
      3. Für Windows: Die Eingabeaufforderung öffnen (Command Prompt). Mit „cd“ und „dir“ zum Ordner navigieren, in dem die beiden Dateien liegen. Wer sich gar nicht auskennt, dem hilft ein Crashkurs wie dieser.
      4. Den folgenden Command ausführen (eingeben und Enter drücken): 
        pandoc main.tex -t pretext.lua -o main.ptx
      5. Das Innenleben von main.ptx (alles innerhalb von <article> … </article>) herauskopieren und in die vorbereitete PreTeXt-Datei im Repo einfügen.
      6. Bekannte Fehler nach Auflistung korrigieren (siehe Konverter-Nachbearbeitungen).

    Konversion mit VS Code

    In VS Code in der Leiste unten im Fenster auf „Pretext“ klicken, oben im Fenster „Import Document“ auswählen, dann den Anleitungen folgen. Es gibt neben dem Pandoc-Konverter auch einen eingebauten, den wir nicht getestet haben. Zur Verwendung des Pandoc-Konverters muss zunächst Pandoc (pandoc.org/installing.html) installiert werden.

    Konversion in PreTeXt.plus

    In PreTeXt.plus auf „New Project“ klicken, dann „Import existing documents“ klicken. Im Editor gibt es für LaTeX-Dokumente eine Schaltfläche „Convert to PreTeXt“.

    Konverter-Nachbearbeitungen

    Was? Problembeschreibung Lösungsvorschlag
    Deutsche oder unübliche Theorem-Umgebungen Der Konverter erkennt Umgebungen wie „Definition“ oder „Theorem“, nicht aber solche, die nicht Englisch benannt oder unüblich sind, wie „Satz“ oder „laboratory“. Im PreTeXt-Code steht dann z. B. <!-- div attr= class="satz"-->, und die Blöcke werden im fertigen Dokument nicht richtig dargestellt. In anderen Fällen gibt es vielleicht einen Block mit dem gewünschten Namen, aber er verhält sich im Dokument nicht so wie gewünscht. Bspw. ist der „Problem“-Block beispielähnlich und somit zum Ausklappen, was in manchen Kontexten unerwünscht sein kann. In der LaTeX-Datei alle Umgebungen zunächst durch ihr englisches Äquivalent ersetzen (z. B. „Bemerkung“ zu „Remark“). Für unübliche Umgebungen und Umgebungen, die sich in PreTeXt nicht wie gewünscht verhalten, einen ansonsten ungenutzten Block aus der Blockübersicht mit dem gewünschten Verhalten auswählen und die Umgebung mit dessen Namen benennen. In der PreTeXt-Datei main.ptx dann das Attribut xml:lang zu „de-DE“ ändern, oder in PreTeXt.plus im Drop-Down-Menü links neben „Save and Manage“ die Sprache zu Deutsch ändern. Hierdurch werden die Titel der Blöcke im Ausgabeformat zu den deutschen Äquivalenten geändert. Einzelne Titel sind noch nicht übersetzt. Dies kann lokal durch ein Rename (siehe Blockübersicht) behoben werden. Wenn die Blöcke nun noch den falschen Namen tragen, der Anleitung hier folgen, um sie umzubenennen. Die docinfo findet sich in PreTeXt.plus unter Tools – Edit Macros – Other Elements.
    Mathematikumgebungen Das \begin{equation} und \end{equation} werden in den Code der Mathematikformeln geschrieben, sorgen dort aber für Fehler. Mit Strg+F alle \begin{equation} etc. entfernen.
    Mehrzeilige Mathematikumgebungen Mehrzeilige Mathematikumgebungen können in PreTeXt nicht einfach in LaTeX geschrieben werden, sondern nutzen ein Mischformat, das der Konverter aktuell nicht unterstützt. Im Ausgabedokument findet sich ein Fehler wie „Misplaced &“. Eine Anleitung zu mehrzeiligen Mathematikumgebungen gibt es hier. Für align-Umgebungen muss jede Zeile in <mrow>-Tags gesetzt werden. Innerhalb der Zeile muss das & durch ein \amp ersetzt werden. Ein Äquivalent zur Gather-Umgebung existiert zum Zeitpunkt des Schreibens nicht.
    Ungünstig benannte \label \label werden bei der Konversion zu xml:id’s gemacht. Diese haben allerdings strengere syntaktische Vorgaben als LaTeX-Label, bspw. sind keine Leerzeichen erlaubt. Bei der Konversion werden die Namen automatisch nachbearbeitet, was zu Verwirrung führen kann. Falls unerlaubte Namen bestehen bleiben, diese durch erlaubte Namen ersetzen (für erlaubte Namen s. z. B. hier).
    \cite und Bibliographie Bei Verwendung eines Bibliographiemanagements wie BibTeX wird die Bibliographie nicht in das konvertierte Dokument übernommen. \cite-Verweise werden syntaktisch richtig umgesetzt, verweisen aber ins Leere. Alle Einträge in der Bibliographie im Quelldokument in \bibitem übertragen. Dies geht z. B. mit diesem Online-Konverter. Alternativ händisches Nachtragen der Einträge der Bibliographie als <biblio>-Blöcke. Hierbei wird die ID der Quelle als xml:id des Blocks gesetzt. Eine mögliche Syntax wäre:

    <biblio type="bibtex" xml:id="Clarke">
  <author> Clarke, Frank H. </author>
  <title> Optimization and Nonsmooth Analysis </title>
  <publisher> Society for Industrial and Applied Mathematics&lt ;/publisher>
  <year> 1990 </year>
  <note> 10.1137/1.9781611971309 </note>
</biblio>

    Hierbei wurde die DOI als Note gesetzt, da der Typ „bibtex“ kein Attribut „DOI“ oder „URL“ unterstützt. Alternativ können auch „plain“- und „CSL“-Style-Elemente genutzt werden. Deren Attribute und Funktionen muss man sich allerdings aus dem Sample-Artikel zusammensuchen.
    Elementnummerierung PreTeXt nummeriert grds. alle Blöcke fortlaufend. Wenn das umzusetzende Dokument eine gesonderte Nummerierung (z. B. Theorem 1, Lemma 1, Beispiel 1) vorsieht, lässt sich dies in PreTeXt nicht abbilden. Die Nummerierung lässt sich in der Datei publication.ptx steuern. Hier gibt es eine generelle Anleitung. Eine gesonderte Nummerierung jedes newtheorem lässt sich hiermit allerdings nicht umsetzen. In diesem Fall empfehlen wir, die ursprünglichen Namen mit Nummerierung als <title> des Blocks zu setzen, z. B. <title>Satz 7</title>. Gibt es im LaTeX-Dokument nur eine Umgebung, die gesondert nummeriert wird, dann kann das Problem umgangen werden, indem für diese Umgebung ein Block wie openproblem oder openquestion gesetzt und dann umbenannt wird. Dieser kann nun wie hier beschrieben gesondert nummeriert werden.
    Gleichungsnummerierung Das Nummerieren von und Verweisen auf Mathematikumgebungen funktioniert noch nicht problemlos. Der Konverter erstellt die Verweise (<xref>), nicht aber die xml:id’s, auf die sie verweisen. Im Dokument steht dann etwas wie „cross-reference to target(s) ‚Eq_Def_Subdiff‘ missing or not unique“. Im LaTeX-Code das entsprechende Label ausfindig machen (Vorsicht: Dieses könnte dort anders heißen, wenn es nachbearbeitet wurde, um eine gültige xml:id zu werden). Dann die entsprechende Stelle im PreTeXt-Code finden. Bei einzeiligen Umgebungen dann den öffnenden <md>-Tag folgendermaßen ersetzen: <md number="yes" xml:id="name_hier">. Bei mehrzeiligen Gleichungen kann man entweder das gesamte <md>-Element oder einzelne Zeilen (<mrow>) ebenso nummerieren. Benennung außerhalb der fortlaufenden Nummerierung, z. B. mit Symbolen, funktioniert über das „tag“-Attribut, s. auch hier. Beachte, dass viele Autoren in LaTeX align-Umgebungen so nummerieren, dass sie eigentlich nur die letzte Zeile nummerieren (die Alternative wäre eine „aligned“-Umgebung innerhalb einer „equation“). In diesem Fall sollte die Umsetzung dennoch das gesamte <md>-Element referenzieren.