feat: epub2md – EPUB nach kapitelweisem Markdown
Kommandozeilenwerkzeug, das DRM-freie EPUB-2/3-Dateien offline in kapitelweise Markdown-Dateien umwandelt. Erzeugt werden außerdem Medien, metadata.yaml, manifest.json, conversion-report.json und Diagnose-Dateien. - Spine-basierte Kapitelbildung mit --chapter-level, epub:type-Abschnitten, Fortsetzungsdateien und Erkennung von Layout-Überschriften - Code mit exakter Einrückung, sicheren Fences und konservativer Spracherkennung - MathML->TeX (konservativ), TeX aus alt-Texten, SVG-/Bildformeln bleiben Bilder - Fußnoten-Modi end-of-chapter, end-of-book, inline und keep-links - Interne Links/Anker werden umgeschrieben, Linkcheck über die Ausgabe - Sicher: kein Entpacken, Schutz vor Path Traversal und XXE, DRM-Erkennung, atomares Schreiben, --force nur für frühere Ausgaben - 82 pytest-Tests mit synthetischen EPUBs und Invariantentests für Beispiele/ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
02449734a2
1 changed files with 7726 additions and 0 deletions
928
Prompt.md
Normal file
928
Prompt.md
Normal file
|
|
@ -0,0 +1,928 @@
|
|||
Du bist ein erfahrener Python-Entwickler für Dokumentkonvertierung, EPUB-Interna, XML/HTML-Verarbeitung und semantische Markdown-Pipelines. Entwickle ein vollständiges, robustes Commandline-Programm namens `epub2md.py`.
|
||||
|
||||
## Ziel
|
||||
|
||||
Das Programm soll DRM-freie EPUB-Dateien lokal in eine strukturierte Sammlung von Markdown-Dateien konvertieren. Es muss für sehr unterschiedliche Buchtypen geeignet sein:
|
||||
|
||||
- Romane und Sachbücher
|
||||
- Bildbände mit Bildern, Bildunterschriften und Bildreferenzen
|
||||
- Programmierbücher mit Codeblöcken, Einrückungen, Quellcode und Tabellen
|
||||
- Mathematik- und Naturwissenschaftsbücher mit Formeln, Gleichungen, MathML, TeX/LaTeX, SVG-Formeln und Grafiken
|
||||
- Technische Fachbücher mit Fußnoten, Endnoten, Zitaten, Quellen, Glossar, Register und Inhaltsverzeichnis
|
||||
|
||||
Die Ausgabe soll für folgende Zwecke gut weiterverarbeitbar sein:
|
||||
|
||||
- Markdown-Renderer und statische Webseiten
|
||||
- Pandoc-Konvertierung nach HTML, PDF, DOCX oder EPUB
|
||||
- Obsidian, Zettelkasten- und Wissensdatenbanken
|
||||
- Git-Versionierung
|
||||
- RAG-, Embedding- und Chunking-Pipelines
|
||||
- Volltextsuche und lokale LLM-Verarbeitung
|
||||
|
||||
Die Konvertierung darf keine DRM-Schutzmechanismen umgehen. Unterstütze nur lesbare, DRM-freie EPUB-Dateien.
|
||||
|
||||
## Arbeitsverzeichnis und Beispieldaten
|
||||
|
||||
Im aktuellen Projektverzeichnis befindet sich ein Verzeichnis:
|
||||
|
||||
```text
|
||||
Beispiele/
|
||||
```
|
||||
|
||||
Darin liegen mehrere Beispiel-EPUB-Dateien unterschiedlicher Art. Nutze diese EPUBs ausschließlich lokal zur Analyse und zum Testen des Programms. Lies zunächst die Verzeichnisstruktur ein und identifiziere vorhandene EPUB-Dateien.
|
||||
|
||||
Beispielhafte Zielgruppen der Testbücher können sein:
|
||||
|
||||
- Roman mit Kapiteln, Fußnoten und Inhaltsverzeichnis
|
||||
- Programmierbuch mit Python-, Shell-, C-, JavaScript-, SQL- oder Konfigurationscode
|
||||
- Mathematikbuch mit Formeln in MathML, TeX, SVG oder als Bild
|
||||
- Bildband mit JPEG-, PNG-, WebP- oder SVG-Grafiken
|
||||
- Buch mit Glossar, Bibliografie, Endnoten sowie Personen- und Sachregister
|
||||
|
||||
Falls keine EPUB-Beispiele vorhanden sind, implementiere das Programm trotzdem vollständig und lege zusätzlich minimalistische synthetische Testdaten oder Tests an.
|
||||
|
||||
## Wichtige technische Anforderungen
|
||||
|
||||
Schreibe kein bloßes Proof-of-Concept. Das Ergebnis soll ein benutzbares, nachvollziehbares und fehlertolerantes Werkzeug sein.
|
||||
|
||||
Verwende bevorzugt:
|
||||
|
||||
- Python 3.12 oder kompatibel mit Ubuntu 24.04
|
||||
- Standardbibliothek, soweit sinnvoll
|
||||
- `beautifulsoup4`
|
||||
- `lxml`
|
||||
- optional `markdownify`, aber nicht als alleinige Konvertierungslogik
|
||||
- optional `Pillow` nur für Metadaten oder Bildprüfung
|
||||
- `pytest` für Tests
|
||||
|
||||
Vermeide schwere externe Laufzeitabhängigkeiten, sofern sie nicht klaren Mehrwert bringen. Insbesondere darf das Programm nicht zwingend Calibre, Pandoc, Java, Node.js oder einen Cloud-Dienst benötigen. Eine optionale Integration mit Pandoc darf angeboten werden, aber die Kernfunktion muss ohne Pandoc funktionieren.
|
||||
|
||||
Nutze für die EPUB-Verarbeitung die Tatsache, dass EPUB ein ZIP-Archiv mit OPF-, XHTML/HTML-, NCX-, NAV-, CSS-, Bild- und Mediendateien ist. Implementiere die Verarbeitung stabil anhand der OPF-Manifest- und Spine-Reihenfolge. Verlasse dich nicht nur auf Dateinamen oder ein vorhandenes Inhaltsverzeichnis.
|
||||
|
||||
## Kommandozeilenschnittstelle
|
||||
|
||||
Implementiere mindestens diese Schnittstelle:
|
||||
|
||||
```bash
|
||||
python3 epub2md.py INPUT.epub OUTPUT_VERZEICHNIS
|
||||
```
|
||||
|
||||
Beispiel:
|
||||
|
||||
```bash
|
||||
python3 epub2md.py Beispiele/mathematikbuch.epub output/mathematikbuch
|
||||
```
|
||||
|
||||
Zusätzliche Optionen:
|
||||
|
||||
```bash
|
||||
python3 epub2md.py --help
|
||||
|
||||
python3 epub2md.py INPUT.epub OUTPUT_VERZEICHNIS \
|
||||
--format gfm \
|
||||
--extract-media \
|
||||
--copy-original \
|
||||
--chapter-level 1 \
|
||||
--toc \
|
||||
--frontmatter \
|
||||
--footnotes end-of-chapter \
|
||||
--math auto \
|
||||
--images relative \
|
||||
--slug-language de \
|
||||
--verbose
|
||||
```
|
||||
|
||||
Implementiere mindestens diese Optionen:
|
||||
|
||||
```text
|
||||
--format {gfm,commonmark}
|
||||
Ziel-Markdown-Variante, Standard: gfm.
|
||||
|
||||
--extract-media / --no-extract-media
|
||||
Extrahiert Bilder und Medien nach OUTPUT_VERZEICHNIS/media/.
|
||||
Standard: aktiviert.
|
||||
|
||||
--copy-original / --no-copy-original
|
||||
Kopiert die originale EPUB-Datei optional nach OUTPUT_VERZEICHNIS/source/.
|
||||
Standard: deaktiviert.
|
||||
|
||||
--chapter-level N
|
||||
Überschriftenebene, ab der neue Markdown-Kapiteldateien erzeugt werden.
|
||||
Standard: 1.
|
||||
|
||||
--toc / --no-toc
|
||||
Erzeugt eine README.md bzw. index.md mit Inhaltsverzeichnis und Links auf Kapitel.
|
||||
Standard: aktiviert.
|
||||
|
||||
--frontmatter / --no-frontmatter
|
||||
Fügt YAML-Frontmatter in jede Kapiteldatei ein.
|
||||
Standard: aktiviert.
|
||||
|
||||
--footnotes {keep-links,end-of-chapter,end-of-book,inline}
|
||||
Strategie zur Ausgabe von Fußnoten und Endnoten.
|
||||
Standard: end-of-chapter.
|
||||
|
||||
--math {auto,tex,mathml,image}
|
||||
Strategie für Mathematik.
|
||||
Standard: auto.
|
||||
|
||||
--images {relative,flat,original-path}
|
||||
Strategie für Bildpfade.
|
||||
Standard: relative.
|
||||
|
||||
--slug-language {de,en,none}
|
||||
Regeln für lesbare Dateinamen und Umlautbehandlung.
|
||||
Standard: de.
|
||||
|
||||
--keep-html
|
||||
Erhalte nicht zuverlässig konvertierbare HTML-Fragmente als HTML im Markdown,
|
||||
statt Informationen zu verlieren.
|
||||
|
||||
--strict
|
||||
Brich bei nicht verarbeitbaren kritischen Fehlern ab.
|
||||
Ohne --strict sollen Warnungen gesammelt und die Konvertierung soweit möglich fortgesetzt werden.
|
||||
|
||||
--verbose
|
||||
Ausführliche Verarbeitungsschritte ausgeben.
|
||||
|
||||
--dry-run
|
||||
Analysiert EPUB-Struktur und geplante Ausgabedateien, schreibt aber nichts.
|
||||
|
||||
--report DATEI.json
|
||||
Schreibt einen maschinenlesbaren Konvertierungsbericht als JSON.
|
||||
```
|
||||
|
||||
Nutze `argparse`. Rückgabecodes:
|
||||
|
||||
```text
|
||||
0 Erfolgreich, möglicherweise mit nichtkritischen Warnungen
|
||||
1 Ungültige Parameter oder Eingabedatei nicht lesbar
|
||||
2 EPUB-/ZIP-/Containerfehler
|
||||
3 OPF-/Spine-/XHTML-Verarbeitungsfehler
|
||||
4 Unerwarteter interner Fehler
|
||||
```
|
||||
|
||||
## Erwartete Ausgabestruktur
|
||||
|
||||
Für eine Eingabe `mein-buch.epub` soll beispielsweise Folgendes entstehen:
|
||||
|
||||
```text
|
||||
output/mein-buch/
|
||||
├── README.md
|
||||
├── metadata.yaml
|
||||
├── conversion-report.json
|
||||
├── source/
|
||||
│ └── mein-buch.epub # nur mit --copy-original
|
||||
├── media/
|
||||
│ ├── images/
|
||||
│ │ ├── 0001-cover.jpg
|
||||
│ │ ├── 0002-abbildung-algorithmus.png
|
||||
│ │ └── 0003-formel-1.svg
|
||||
│ ├── audio/
|
||||
│ └── other/
|
||||
├── chapters/
|
||||
│ ├── 000-frontmatter.md
|
||||
│ ├── 001-vorwort.md
|
||||
│ ├── 002-kapitel-1-einleitung.md
|
||||
│ ├── 003-kapitel-2-grundlagen.md
|
||||
│ ├── 004-anhang.md
|
||||
│ ├── 005-glossar.md
|
||||
│ ├── 006-quellen-und-literatur.md
|
||||
│ ├── 007-sachregister.md
|
||||
│ └── 008-personenregister.md
|
||||
└── diagnostics/
|
||||
├── warnings.md
|
||||
└── unsupported-elements.md
|
||||
```
|
||||
|
||||
Die genaue Struktur darf verbessert werden, aber sie soll stabil, dokumentiert und skriptfreundlich bleiben.
|
||||
|
||||
## EPUB-Analyse
|
||||
|
||||
Implementiere eine saubere EPUB-Analyse:
|
||||
|
||||
1. Lies `META-INF/container.xml`.
|
||||
2. Ermittle darüber die OPF-Paketdatei.
|
||||
3. Lies aus der OPF-Datei mindestens:
|
||||
- Titel
|
||||
- Untertitel, falls vorhanden
|
||||
- Autorinnen/Autoren
|
||||
- Sprache
|
||||
- Identifier/ISBN, wenn vorhanden
|
||||
- Verlag
|
||||
- Veröffentlichungsdatum
|
||||
- Beschreibung
|
||||
- Rechteangaben
|
||||
- Cover-Referenz
|
||||
- Manifest
|
||||
- Spine-Reihenfolge
|
||||
4. Unterstütze EPUB 2 und EPUB 3.
|
||||
5. Lies, falls vorhanden:
|
||||
- EPUB-3-Navigation (`nav.xhtml`)
|
||||
- NCX-Inhaltsverzeichnis (`.ncx`)
|
||||
- Guide-Landmarks
|
||||
- Dokumenteigenschaften wie `epub:type`
|
||||
6. Verwende die Spine als verbindliche Lesereihenfolge.
|
||||
7. Nutze NAV/NCX und semantische EPub-Typen zur Erkennung von:
|
||||
- Titelblatt
|
||||
- Inhaltsverzeichnis
|
||||
- Vorwort
|
||||
- Kapitel
|
||||
- Teil
|
||||
- Anhang
|
||||
- Glossar
|
||||
- Bibliografie
|
||||
- Endnoten
|
||||
- Sachregister
|
||||
- Personenregister
|
||||
- Danksagung
|
||||
- Kolophon
|
||||
|
||||
## Kapitelbildung
|
||||
|
||||
Die Kapitelbildung muss robust sein. Viele EPUBs enthalten bereits eine XHTML-Datei je Kapitel; andere enthalten ein gesamtes Buch in wenigen Dateien.
|
||||
|
||||
Implementiere diese Priorität:
|
||||
|
||||
1. Berücksichtige die OPF-Spine-Reihenfolge.
|
||||
2. Erkenne innerhalb jeder XHTML-Datei Überschriften `h1` bis `h6`.
|
||||
3. Teile Inhalte anhand von `--chapter-level`.
|
||||
4. Falls keine geeigneten Überschriften vorhanden sind:
|
||||
- nutze die XHTML-Datei als Kapitel,
|
||||
- oder leite einen sinnvollen Titel aus `<title>`, `epub:type`, Dateiname oder NAV/NCX ab.
|
||||
5. Erhalte die Reihenfolge exakt.
|
||||
6. Verwende fortlaufende Dateinummern mit mindestens drei Stellen:
|
||||
- `001-...md`
|
||||
- `002-...md`
|
||||
7. Erzeuge konfliktfreie, stabile Slugs.
|
||||
8. Entferne keine Kapitel, nur weil sie kurz sind. Titelblatt, Widmung oder Epigraph dürfen als eigene Markdown-Datei erscheinen.
|
||||
9. Vermeide doppelte Ausgabe desselben Inhalts, etwa wenn das EPUB ein HTML-Inhaltsverzeichnis enthält und zusätzlich NAV/NCX besitzt.
|
||||
|
||||
## Markdown-Konvertierung
|
||||
|
||||
Erzeuge sauberes, semantisch brauchbares Markdown.
|
||||
|
||||
### Überschriften
|
||||
|
||||
- XHTML `h1` bis `h6` müssen zu Markdown-Überschriften werden.
|
||||
- Passe die Überschriftenebenen sinnvoll an die Kapiteldatei an.
|
||||
- Vermeide mehrere identische H1-Überschriften in derselben Kapiteldatei.
|
||||
- Gib Kapitelmetadaten im YAML-Frontmatter aus.
|
||||
|
||||
Beispiel:
|
||||
|
||||
```markdown
|
||||
***
|
||||
book_title: "Beispieltitel"
|
||||
book_author:
|
||||
- "Max Mustermann"
|
||||
language: "de"
|
||||
chapter_number: 3
|
||||
chapter_title: "Graphenalgorithmen"
|
||||
source_epub: "beispieltitel.epub"
|
||||
source_href: "Text/ch03.xhtml"
|
||||
epub_type:
|
||||
- "chapter"
|
||||
conversion_status: "converted"
|
||||
***
|
||||
|
||||
# Graphenalgorithmen
|
||||
```
|
||||
|
||||
### Fließtext und semantische Elemente
|
||||
|
||||
Konvertiere mindestens:
|
||||
|
||||
```text
|
||||
p, div, span, section, article, header, footer, aside,
|
||||
blockquote, q, cite, em, i, strong, b, u, del, s,
|
||||
br, hr, sup, sub, abbr, kbd, mark
|
||||
```
|
||||
|
||||
Regeln:
|
||||
|
||||
- Normaler Fließtext soll keine künstlichen Zeilenumbrüche innerhalb eines Absatzes erhalten.
|
||||
- `<br>` soll als echter Markdown-Zeilenumbruch oder, falls semantisch geeigneter, als Absatztrennung erscheinen.
|
||||
- `blockquote` soll als `>` ausgegeben werden.
|
||||
- Hervorhebungen sollen semantisch erhalten bleiben.
|
||||
- `<sup>` und `<sub>` müssen erhalten werden; falls normales Markdown nicht ausreicht, nutze HTML-Tags innerhalb der Markdown-Datei.
|
||||
- Unbekannte oder komplexe Elemente sollen nicht stillschweigend verloren gehen. Mit `--keep-html` sollen sie als bereinigtes HTML im Markdown erhalten bleiben.
|
||||
- Entferne Navigationsreste wie wiederholte „Next“, „Previous“, Seitenzahlen oder Reader-Bedienelemente, aber nur dann, wenn sie zuverlässig als Navigation identifizierbar sind.
|
||||
|
||||
### Listen
|
||||
|
||||
Unterstütze:
|
||||
|
||||
```text
|
||||
ul, ol, li, dl, dt, dd
|
||||
```
|
||||
|
||||
- Verschachtelte Listen müssen korrekt eingerückt sein.
|
||||
- Nummerierte Listen müssen ihre Reihenfolge behalten.
|
||||
- Definitionslisten sollen als gut lesbares Markdown oder gegebenenfalls HTML ausgegeben werden.
|
||||
|
||||
### Tabellen
|
||||
|
||||
Unterstütze HTML-Tabellen:
|
||||
|
||||
```text
|
||||
table, thead, tbody, tfoot, tr, th, td, caption
|
||||
```
|
||||
|
||||
Regeln:
|
||||
|
||||
- Einfache Tabellen sollen als GFM-Tabellen ausgegeben werden.
|
||||
- Bei `rowspan`, `colspan`, verschachtelten Elementen, mehrzeiligen Zellen oder komplexen Layouttabellen:
|
||||
- sichere den Inhalt,
|
||||
- verwende bevorzugt HTML im Markdown,
|
||||
- vermerke im Report eine Warnung,
|
||||
- verliere keine Daten.
|
||||
- Tabellenbeschriftungen müssen erhalten bleiben.
|
||||
|
||||
### Links und Anker
|
||||
|
||||
- Konvertiere externe Links vollständig.
|
||||
- Konvertiere interne EPUB-Links in funktionierende relative Links zu Zielkapiteln und, soweit möglich, Zielankern.
|
||||
- Erzeuge stabile Markdown-Anker oder verwende HTML-Anker, wenn erforderlich.
|
||||
- Interne Referenzen wie „siehe Kapitel 4“, „siehe Abbildung 3.2“ oder Fußnoten-Backlinks sollen möglichst erhalten bleiben.
|
||||
- Dokumentiere nicht auflösbare interne Ziele im Report.
|
||||
|
||||
## Programmcode
|
||||
|
||||
Programmierbücher sind ein zentraler Anwendungsfall.
|
||||
|
||||
Erkenne unter anderem:
|
||||
|
||||
```text
|
||||
pre, code, pre > code,
|
||||
div mit Klassen wie code, programlisting, sourcecode, listing, highlight,
|
||||
Syntax-Highlighting-Spans von Pygments, Prism, highlight.js oder ähnlichen Systemen.
|
||||
```
|
||||
|
||||
Anforderungen:
|
||||
|
||||
1. Ausgabe als fenced code blocks mit dreifachen Backticks oder einer ausreichend langen Backtick-Sequenz, falls der Code selbst Backticks enthält.
|
||||
2. Erhalte Leerzeichen, Tabs, Einrückung und Zeilenumbrüche exakt.
|
||||
3. Entferne keine relevanten Zeichen aus Code:
|
||||
- Backslashes
|
||||
- Anführungszeichen
|
||||
- `<`, `>`, `&`
|
||||
- Pipe-Zeichen
|
||||
- Hashes
|
||||
- Dollarzeichen
|
||||
- Unicode-Zeichen
|
||||
4. Versuche die Programmiersprache aus Klassen, `type`, `data-language`, Dateinamen oder bekannten Hinweisen zu erkennen.
|
||||
5. Unterstütze mindestens Sprachlabels wie:
|
||||
- `python`
|
||||
- `bash`
|
||||
- `sh`
|
||||
- `zsh`
|
||||
- `c`
|
||||
- `cpp`
|
||||
- `java`
|
||||
- `javascript`
|
||||
- `typescript`
|
||||
- `json`
|
||||
- `yaml`
|
||||
- `toml`
|
||||
- `xml`
|
||||
- `html`
|
||||
- `css`
|
||||
- `sql`
|
||||
- `dockerfile`
|
||||
- `makefile`
|
||||
- `ini`
|
||||
- `text`
|
||||
6. Wenn die Sprache nicht sicher erkennbar ist, verwende keinen falschen Sprachbezeichner.
|
||||
7. Inline-Code muss ebenfalls korrekt nach Markdown übersetzt werden.
|
||||
8. Zeilennummern, Copy-Buttons, Prompt-Dekorationen und rein visuelle Syntax-Highlighting-Tags sollen entfernt werden, sofern sie eindeutig als Präsentationsartefakte erkennbar sind.
|
||||
9. Wenn Text nicht sicher als Code erkennbar ist, darf er nicht aggressiv in einen Codeblock gezwungen werden.
|
||||
|
||||
Beispiel:
|
||||
|
||||
````markdown
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
def read_book(path: Path) -> str:
|
||||
return path.read_text(encoding="utf-8")
|
||||
```
|
||||
````
|
||||
|
||||
## Bilder, SVG und Medien
|
||||
|
||||
Extrahiere lokale Medien aus dem EPUB.
|
||||
|
||||
Unterstütze mindestens:
|
||||
|
||||
```text
|
||||
JPEG, PNG, GIF, WebP, SVG, AVIF, MP3, MP4, WebM, CSS-Dateien, eingebettete Schriftarten
|
||||
```
|
||||
|
||||
Regeln:
|
||||
|
||||
1. Speichere Bilder standardmäßig in `media/images/`.
|
||||
2. Erhalte die ursprüngliche Dateiendung, sofern möglich.
|
||||
3. Nutze stabile, kollisionsfreie Namen, beispielsweise:
|
||||
|
||||
```text
|
||||
0001-cover.jpg
|
||||
0002-abbildung-graph.png
|
||||
0003-formel-01.svg
|
||||
```
|
||||
|
||||
4. Erhalte Bildreferenzen in Markdown relativ:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
5. Übernimm:
|
||||
- `alt`
|
||||
- `title`
|
||||
- `figcaption`
|
||||
- Bildnummer und Bildunterschrift
|
||||
- interne Bildanker
|
||||
6. Nutze für `figure` und `figcaption` eine gut lesbare Struktur, beispielsweise:
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
*Abbildung 3.2: Darstellung eines Graphen.*
|
||||
```
|
||||
|
||||
7. SVG darf nicht gerastert werden. Bewahre SVG möglichst als SVG.
|
||||
8. Wenn ein SVG eine mathematische Formel darstellt, markiere dies im Report, aber behandle sie visuell korrekt als Bild.
|
||||
9. Extrahiere Medien nur einmal, auch wenn sie mehrfach referenziert werden.
|
||||
10. Erhalte Audio- und Video-Referenzen nach Möglichkeit als Links; dokumentiere nicht direkt in Markdown darstellbare Medien im Report.
|
||||
11. CSS muss nicht zwingend vollständig übernommen werden. Es darf aber für Heuristiken zur Code-, Tabellen- oder Formelklassifikation analysiert werden.
|
||||
|
||||
## Mathematik und Formeln
|
||||
|
||||
Mathematik ist ein zentraler Anwendungsfall. Formeln dürfen nicht stillschweigend verschwinden.
|
||||
|
||||
Erkenne und behandle mindestens:
|
||||
|
||||
```text
|
||||
MathML: <math>, <mrow>, <mi>, <mo>, <mn>, <msup>, <msub>, <mfrac>, ...
|
||||
LaTeX/TeX in Textknoten, data-Attributen oder Klassen
|
||||
Asciimath, sofern erkennbar
|
||||
SVG-Formeln
|
||||
Rastergrafiken mit Formeln
|
||||
HTML-Elemente mit Klassen wie math, equation, formula, MathJax, katex
|
||||
```
|
||||
|
||||
Implementiere die Modi:
|
||||
|
||||
### `--math auto`
|
||||
|
||||
Priorität:
|
||||
|
||||
1. Wenn eine Formel als TeX/LaTeX vorhanden ist: übernehme sie als TeX.
|
||||
2. Wenn MathML vorhanden ist:
|
||||
- versuche eine verlustarme Konvertierung nach TeX;
|
||||
- falls keine sichere Konvertierung möglich ist, behalte MathML als HTML/XML im Markdown oder sichere es als separate `.mathml`-Datei und verlinke sie;
|
||||
- verliere die Formel nicht.
|
||||
3. Bei SVG- oder Rasterformeln:
|
||||
- behalte die Grafikreferenz;
|
||||
- verwende vorhandenen Alternativtext, Bildunterschrift oder zugänglichen Text;
|
||||
- schreibe eine Warnung in den Report, dass keine semantische Textextraktion erfolgte.
|
||||
|
||||
### `--math tex`
|
||||
|
||||
- Gib möglichst \( ... \) für Inline-Mathematik aus.
|
||||
- Gib \[ ... \] für abgesetzte Mathematik aus.
|
||||
- Verwende keine Dollarzeichen als Mathe-Begrenzer.
|
||||
- Wenn eine Formel nicht zuverlässig nach TeX konvertierbar ist, behalte die Originalrepräsentation statt fehlerhaften TeX zu erzeugen.
|
||||
|
||||
### `--math mathml`
|
||||
|
||||
- Erhalte MathML als eingebettetes XML/HTML innerhalb der Markdown-Datei oder als referenzierte Datei.
|
||||
- Stelle sicher, dass die Formel maschinenlesbar bleibt.
|
||||
|
||||
### `--math image`
|
||||
|
||||
- Repräsentiere alle nichttrivialen Formeln als Bild/SVG-Referenz, sofern ein Bild vorhanden ist.
|
||||
- Bei reinem MathML ohne Bild darf die Formel nicht verschwinden; sichere sie dann als MathML.
|
||||
|
||||
Zusätzliche Regeln:
|
||||
|
||||
- Unterscheide Inline- und Blockformeln.
|
||||
- Erhalte Gleichungsnummern wie `(3.7)` und Gleichungsreferenzen.
|
||||
- Erhalte mathematische Sonderzeichen, Mengenlehre, griechische Buchstaben, Indizes, Exponenten und Matrizen soweit möglich.
|
||||
- Behalte Formeln in Tabellen und Fußnoten korrekt bei.
|
||||
- Dokumentiere jede nicht sicher konvertierte Formel im JSON-Report.
|
||||
|
||||
Falls sinnvoll, darfst du eine kleine MathML-nach-TeX-Konvertierung selbst implementieren. Unterstütze dabei mindestens häufige Elemente wie:
|
||||
|
||||
```text
|
||||
mi, mn, mo, mrow, mfrac, msup, msub, msubsup,
|
||||
msqrt, mroot, mfenced, mtext, mover, munder, munderover,
|
||||
mtable, mtr, mtd
|
||||
```
|
||||
|
||||
Die Konvertierung muss konservativ sein: Bei Unklarheit lieber MathML erhalten als mathematisch falsches TeX erzeugen.
|
||||
|
||||
## Fußnoten, Endnoten und Anmerkungen
|
||||
|
||||
Erkenne Fußnoten und Endnoten, unter anderem über:
|
||||
|
||||
```text
|
||||
epub:type="noteref"
|
||||
epub:type="footnote"
|
||||
epub:type="endnote"
|
||||
role="doc-noteref"
|
||||
role="doc-footnote"
|
||||
role="doc-endnote"
|
||||
Klassen wie footnote, footnotes, note, endnote, endnotes, fnref
|
||||
Links mit Fragment-IDs zu Anmerkungsabschnitten
|
||||
```
|
||||
|
||||
Implementiere folgende Modi:
|
||||
|
||||
### `--footnotes end-of-chapter`
|
||||
|
||||
- Fußnotenreferenzen im Text als Markdown-Fußnotenreferenz:
|
||||
|
||||
```markdown
|
||||
Text mit Anmerkung.[^fn-001]
|
||||
```
|
||||
|
||||
- Die Fußnoten am Ende der jeweiligen Kapiteldatei:
|
||||
|
||||
```markdown
|
||||
[^fn-001]: Vollständiger Fußnotentext.
|
||||
```
|
||||
|
||||
### `--footnotes end-of-book`
|
||||
|
||||
- Erzeuge eine eigene Datei, etwa:
|
||||
|
||||
```text
|
||||
chapters/999-anmerkungen.md
|
||||
```
|
||||
|
||||
- Interne Referenzen müssen zu dieser Datei zeigen.
|
||||
|
||||
### `--footnotes inline`
|
||||
|
||||
- Ersetze Fußnotenreferenzen nachvollziehbar inline, beispielsweise:
|
||||
|
||||
```markdown
|
||||
Text mit Anmerkung (Anmerkung: Vollständiger Fußnotentext).
|
||||
```
|
||||
|
||||
### `--footnotes keep-links`
|
||||
|
||||
- Erhalte die vorhandene EPUB-Linkstruktur so weit wie möglich.
|
||||
|
||||
Zusätzliche Anforderungen:
|
||||
|
||||
- Erhalte Rückverweise, soweit sinnvoll.
|
||||
- Mehrfachreferenzen auf dieselbe Fußnote dürfen nicht zu Datenverlust führen.
|
||||
- Fußnoten können Absätze, Hervorhebungen, Links, Code, Bilder, Tabellen oder Formeln enthalten.
|
||||
- Konvertiere diese Inhalte rekursiv mit derselben Qualität wie den Haupttext.
|
||||
- Fußnoten dürfen nicht versehentlich auch als regulärer Fließtext im Kapitel erscheinen.
|
||||
|
||||
## Glossar, Register und Quellen
|
||||
|
||||
Erkenne semantische Dokumentteile über EPUB-3-Attribute, NAV/NCX, OPF-Guide, IDs, Klassen, Überschriften und Dateinamen.
|
||||
|
||||
### Glossar
|
||||
|
||||
- Erzeuge eine eigene Markdown-Datei, wenn ein Glossar vorhanden ist.
|
||||
- Bewahre Begriffe, Definitionen, Verweise und alphabetische Sortierung.
|
||||
- Konvertiere Definitionslisten sinnvoll, zum Beispiel:
|
||||
|
||||
```markdown
|
||||
## Begriff
|
||||
|
||||
Definition des Begriffs.
|
||||
```
|
||||
|
||||
oder bei kurzer Form:
|
||||
|
||||
```markdown
|
||||
**Begriff:** Definition.
|
||||
```
|
||||
|
||||
- Interne Verweise auf Glossarbegriffe sollen möglichst als Links erhalten bleiben.
|
||||
|
||||
### Quellen, Literatur und Bibliografie
|
||||
|
||||
- Erzeuge eine separate Datei für Literatur, Quellen, Weblinks oder Bibliografie.
|
||||
- Bewahre Autoren, Titel, Herausgeber, Jahr, Verlag, DOI, ISBN, URLs, Zugriffsdatum und Seitenangaben.
|
||||
- Zerstöre keine bestehende Zitierstruktur.
|
||||
- Wenn Einträge semantisch erkennbar sind, kann eine strukturierte Darstellung ergänzt werden; der Originaltext muss jedoch erhalten bleiben.
|
||||
- Verlinke URLs korrekt.
|
||||
|
||||
### Sachregister und Personenregister
|
||||
|
||||
- Erzeuge eigene Markdown-Dateien für:
|
||||
- Sachregister
|
||||
- Personenregister
|
||||
- Erhalte alphabetische Abschnitte.
|
||||
- Erhalte Seiten-/Kapitelreferenzen als Text, auch wenn eine präzise Zuordnung zu EPUB-Locations nicht möglich ist.
|
||||
- Versuche interne Registerlinks auf Kapiteldateien und Anker umzuschreiben.
|
||||
- Wenn Seitenzahlen aus dem Drucksatz keine sinnvolle digitale Zielposition besitzen, behalte sie sichtbar, entferne sie nicht und vermerke dies gegebenenfalls im Report.
|
||||
|
||||
## YAML-Metadaten
|
||||
|
||||
Erzeuge eine globale Datei `metadata.yaml`.
|
||||
|
||||
Beispiel:
|
||||
|
||||
```yaml
|
||||
title: "Titel des Buches"
|
||||
subtitle: "Untertitel"
|
||||
authors:
|
||||
- "Autorin Eins"
|
||||
- "Autor Zwei"
|
||||
language: "de"
|
||||
publisher: "Beispielverlag"
|
||||
published: "2024-01-01"
|
||||
identifier: "urn:isbn:978..."
|
||||
source_file: "mein-buch.epub"
|
||||
source_sha256: "..."
|
||||
epub_version: "3.0"
|
||||
description: "..."
|
||||
rights: "..."
|
||||
subjects:
|
||||
- "Informatik"
|
||||
- "Algorithmen"
|
||||
cover_image: "media/images/0001-cover.jpg"
|
||||
conversion:
|
||||
tool: "epub2md"
|
||||
version: "0.1.0"
|
||||
generated_at: "ISO-8601-Zeitstempel"
|
||||
options: {}
|
||||
```
|
||||
|
||||
Behandle fehlende Daten sauber. Erfinde keine Metadaten.
|
||||
|
||||
## README und maschinenlesbare Manifestdatei
|
||||
|
||||
Erzeuge eine `README.md` mit:
|
||||
|
||||
- Buchtitel und Autorinnen/Autoren
|
||||
- kurzer Metadatenübersicht
|
||||
- Inhaltsverzeichnis mit Links zu allen Kapiteldateien
|
||||
- Hinweisen auf Glossar, Quellen, Register und Anmerkungen
|
||||
- Statistik:
|
||||
- Anzahl Kapitel
|
||||
- Anzahl Bilder
|
||||
- Anzahl SVGs
|
||||
- Anzahl extrahierter Medien
|
||||
- Anzahl erkannter Codeblöcke
|
||||
- Anzahl erkannter Formeln
|
||||
- Anzahl als Bild/SVG belassener Formeln
|
||||
- Anzahl Fußnoten
|
||||
- Anzahl Warnungen
|
||||
- Reproduktionskommando mit den verwendeten Optionen
|
||||
|
||||
Erzeuge zusätzlich eine maschinenlesbare Datei, beispielsweise `manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"book": {
|
||||
"title": "..."
|
||||
},
|
||||
"chapters": [
|
||||
{
|
||||
"number": 1,
|
||||
"title": "Einleitung",
|
||||
"file": "chapters/001-einleitung.md",
|
||||
"source_href": "Text/ch01.xhtml",
|
||||
"anchors": ["einleitung", "motivation"],
|
||||
"word_count": 1234,
|
||||
"code_blocks": 4,
|
||||
"images": 2,
|
||||
"math_blocks": 3,
|
||||
"footnotes": 5
|
||||
}
|
||||
],
|
||||
"media": [],
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
Diese Datei soll besonders für RAG- und Indexierungsprozesse nutzbar sein.
|
||||
|
||||
## Konvertierungsbericht und Diagnostik
|
||||
|
||||
Schreibe standardmäßig einen JSON-Bericht, z. B. `conversion-report.json`.
|
||||
|
||||
Er muss mindestens enthalten:
|
||||
|
||||
```text
|
||||
- Programmversion
|
||||
- Zeitstempel
|
||||
- Eingabedatei
|
||||
- SHA-256-Prüfsumme der Eingabe
|
||||
- erkannte EPUB-Version
|
||||
- verwendete Optionen
|
||||
- erkannte Kapitel
|
||||
- extrahierte Medien
|
||||
- erkannte und konvertierte Codeblöcke
|
||||
- erkannte Formeln und gewählte Formelrepräsentation
|
||||
- erkannte Fußnoten und Verarbeitungsmodus
|
||||
- erkannte Glossar-/Quellen-/Registerabschnitte
|
||||
- Warnungen
|
||||
- Fehler, die nicht zum Abbruch geführt haben
|
||||
- nicht aufgelöste interne Links
|
||||
- nicht unterstützte Elemente
|
||||
```
|
||||
|
||||
Zusätzlich soll `diagnostics/warnings.md` für Menschen lesbar sein.
|
||||
|
||||
Beispiele für Warnungen:
|
||||
|
||||
```text
|
||||
- Formel in Text/ch05.xhtml#eq-13 liegt nur als SVG vor; als Bild referenziert.
|
||||
- Tabelle in Text/ch07.xhtml enthält colspan; als HTML erhalten.
|
||||
- Interner Link Text/ch08.xhtml#unknown-target konnte nicht aufgelöst werden.
|
||||
- Codeblock in Text/ch03.xhtml besitzt keine erkannte Programmiersprache.
|
||||
- Fußnote fn-42 verweist auf ein nicht existentes Ziel.
|
||||
```
|
||||
|
||||
## Fehlerbehandlung und Sicherheit
|
||||
|
||||
- Behandle defekte oder unvollständige EPUBs robust.
|
||||
- Verhindere Path Traversal beim Entpacken von ZIP-Dateien.
|
||||
- Schreibe niemals Dateien außerhalb des angegebenen Ausgabeverzeichnisses.
|
||||
- Behandle ungültiges UTF-8 robust und dokumentiere Ersatzzeichen oder Dekodierungsprobleme.
|
||||
- Verwende temporäre Arbeitsverzeichnisse.
|
||||
- Bereinige temporäre Daten auch bei Fehlern.
|
||||
- Überschreibe ein existierendes Ausgabeverzeichnis nicht stillschweigend.
|
||||
- Implementiere entweder:
|
||||
- Abbruch, wenn das Ziel existiert, oder
|
||||
- explizite Option `--force` zum Überschreiben.
|
||||
- Dokumentiere die Entscheidung.
|
||||
- Behandle XML External Entities sicher. Deaktiviere externe Entitäten und vermeide XXE-Risiken.
|
||||
- Benutze keine Shell-Aufrufe mit unkontrollierten Eingaben.
|
||||
- Verwende keine Netzwerkzugriffe.
|
||||
|
||||
## Architektur
|
||||
|
||||
Strukturiere den Code modular und testbar. Eine mögliche, aber nicht zwingende Struktur:
|
||||
|
||||
```text
|
||||
epub2md.py
|
||||
epub2md/
|
||||
├── __init__.py
|
||||
├── cli.py
|
||||
├── epub_reader.py
|
||||
├── metadata.py
|
||||
├── spine.py
|
||||
├── navigation.py
|
||||
├── html_converter.py
|
||||
├── markdown_writer.py
|
||||
├── chapters.py
|
||||
├── footnotes.py
|
||||
├── math.py
|
||||
├── codeblocks.py
|
||||
├── media.py
|
||||
├── references.py
|
||||
├── diagnostics.py
|
||||
├── models.py
|
||||
└── utils.py
|
||||
tests/
|
||||
├── test_epub_reader.py
|
||||
├── test_chapters.py
|
||||
├── test_codeblocks.py
|
||||
├── test_math.py
|
||||
├── test_footnotes.py
|
||||
├── test_links.py
|
||||
└── test_integration.py
|
||||
```
|
||||
|
||||
Wenn du dich für eine kleinere Struktur entscheidest, begründe sie kurz in der Dokumentation. Wichtig ist, dass die Kernlogik nicht in einer einzigen unwartbaren Funktion endet.
|
||||
|
||||
Nutze Dataclasses oder vergleichbare Datenmodelle für Kapitel, Medien, Fußnoten, interne Links, Warnungen und Konvertierungsresultate.
|
||||
|
||||
## Tests
|
||||
|
||||
Schreibe aussagekräftige Tests mit `pytest`.
|
||||
|
||||
Mindestens testen:
|
||||
|
||||
1. Ein minimales EPUB 2 wird gelesen.
|
||||
2. Ein minimales EPUB 3 mit `nav.xhtml` wird gelesen.
|
||||
3. Spine-Reihenfolge wird eingehalten.
|
||||
4. Kapiteldateien werden korrekt benannt und nummeriert.
|
||||
5. H1- und H2-basierte Kapitelteilung funktioniert.
|
||||
6. Bilder werden extrahiert und mit funktionierenden relativen Links referenziert.
|
||||
7. Codeblöcke behalten Einrückung und Sonderzeichen.
|
||||
8. Verschachtelte Listen bleiben korrekt.
|
||||
9. Einfache Tabellen werden als GFM-Tabelle ausgegeben.
|
||||
10. Komplexe Tabellen bleiben als HTML erhalten.
|
||||
11. MathML wird mindestens für einfache Brüche, Hochstellungen und Indizes sinnvoll behandelt.
|
||||
12. Nicht konvertierbares MathML geht nicht verloren.
|
||||
13. SVG-Formeln bleiben als Bild erhalten.
|
||||
14. Fußnoten werden an das Kapitelende verschoben.
|
||||
15. Glossar und Bibliografie werden erkannt oder anhand bekannter Kennzeichnungen verarbeitet.
|
||||
16. Interne Links zwischen Kapiteln werden umgeschrieben.
|
||||
17. Warnungen landen im JSON-Report.
|
||||
18. `--dry-run` schreibt keine Ausgabedateien.
|
||||
19. Unsichere ZIP-Pfade werden abgelehnt.
|
||||
20. Bereits vorhandenes Ausgabeverzeichnis wird ohne `--force` nicht überschrieben.
|
||||
|
||||
Nutze, falls möglich, die EPUB-Dateien aus `Beispiele/` in Integrationstests. Tests dürfen aber nicht von urheberrechtlich geschützten Volltexten oder exakten Inhalten abhängen. Prüfe Struktur, Dateien, Links und Konvertierungsinvarianten statt konkreter Buchtexte.
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Erstelle eine ausführliche `README.md` für das Projekt mit:
|
||||
|
||||
- Zweck und Grenzen des Werkzeugs
|
||||
- Installation unter Ubuntu 24.04
|
||||
- Abhängigkeiten
|
||||
- Virtuelle Python-Umgebung
|
||||
- Beispiele für Aufrufe
|
||||
- Beschreibung aller Optionen
|
||||
- Erklärung der Verzeichnisstruktur
|
||||
- Erklärung der Math-Modi
|
||||
- Erklärung der Fußnoten-Modi
|
||||
- Hinweise zur Qualität bei:
|
||||
- formelbasierten EPUBs
|
||||
- SVG-Formeln
|
||||
- Layouttabellen
|
||||
- Syntax-Highlighting
|
||||
- gescannten Texten
|
||||
- DRM
|
||||
- Hinweise zur Weiterverarbeitung mit Pandoc
|
||||
|
||||
Füge konkrete Beispiele hinzu:
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
python3 epub2md.py \
|
||||
Beispiele/programmierbuch.epub \
|
||||
output/programmierbuch \
|
||||
--format gfm \
|
||||
--math auto \
|
||||
--footnotes end-of-chapter \
|
||||
--extract-media \
|
||||
--frontmatter \
|
||||
--toc \
|
||||
--verbose
|
||||
```
|
||||
|
||||
Pandoc-Beispiele für die Weiterverarbeitung:
|
||||
|
||||
```bash
|
||||
pandoc output/programmierbuch/chapters/*.md \
|
||||
--metadata-file=output/programmierbuch/metadata.yaml \
|
||||
-o programmierbuch.html
|
||||
```
|
||||
|
||||
```bash
|
||||
pandoc output/mathematikbuch/chapters/*.md \
|
||||
--metadata-file=output/mathematikbuch/metadata.yaml \
|
||||
--pdf-engine=xelatex \
|
||||
-o mathematikbuch.pdf
|
||||
```
|
||||
|
||||
Erkläre dabei klar: Die Qualität der Formelkonvertierung hängt stark davon ab, ob das EPUB Formeln als echtes MathML/TeX oder nur als SVG/Bitmap enthält. SVG- und Bitmap-Formeln dürfen bei Unsicherheit nicht in fehlerhaftes TeX „halluziniert“ werden.
|
||||
|
||||
## Vorgehensweise
|
||||
|
||||
Arbeite in dieser Reihenfolge:
|
||||
|
||||
1. Untersuche die vorhandene Projektstruktur und `Beispiele/`.
|
||||
2. Gib kurz wieder, welche EPUBs und welche wahrscheinlichen Dokumenttypen du gefunden hast.
|
||||
3. Plane Architektur und Abhängigkeiten.
|
||||
4. Implementiere das Programm vollständig.
|
||||
5. Implementiere Tests.
|
||||
6. Führe Tests aus.
|
||||
7. Führe das Programm testweise auf den Beispiel-EPUBs aus.
|
||||
8. Prüfe die erzeugten Markdown-Dateien stichprobenartig:
|
||||
- Kapitelstruktur
|
||||
- Bildlinks
|
||||
- Codeblöcke
|
||||
- Formeln
|
||||
- Fußnoten
|
||||
- Glossar/Register/Quellen, falls vorhanden
|
||||
9. Behebe offensichtliche Probleme.
|
||||
10. Gib am Ende eine präzise Zusammenfassung:
|
||||
- welche Dateien du erstellt oder geändert hast,
|
||||
- wie man das Programm startet,
|
||||
- welche Tests erfolgreich waren,
|
||||
- welche Einschränkungen bei den konkreten Beispielbüchern bestehen,
|
||||
- welche Warnungen oder nicht verlustfrei konvertierbaren Inhalte gefunden wurden.
|
||||
|
||||
## Qualitätsregeln
|
||||
|
||||
- Keine Pseudocode-Antwort.
|
||||
- Schreibe wirklich ausführbaren Python-Code.
|
||||
- Erfinde keine Testergebnisse und behaupte keine Ausführung, die nicht stattgefunden hat.
|
||||
- Keine Cloud-APIs, keine Telemetrie, keine Netzwerkzugriffe.
|
||||
- Konvertierung muss offline funktionieren.
|
||||
- Bei unsicherer Semantik: Originalinhalt erhalten, Warnung dokumentieren, keine stillschweigende Datenvernichtung.
|
||||
- Keine mathematisch falsche TeX-Erzeugung.
|
||||
- Keine aggressive Bereinigung, die Code, Zitate, Formeln, Fußnoten oder Quellen zerstört.
|
||||
- Priorität: semantischer Erhalt, Reproduzierbarkeit, robuste Diagnose und Nachbearbeitbarkeit.
|
||||
|
||||
|
||||
Loading…
Reference in a new issue