epub2md/Prompt.md

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
![Alternativtext](../media/images/0002-abbildung-graph.png "Bildtitel")
```

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.