epub2md/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung epub2md

Diese Anleitung zeigt Schritt für Schritt, wie du ein E-Book im EPUB-Format in Markdown umwandelst und
was du mit dem Ergebnis anfangen kannst. Technische Details stehen in der [README.md](README.md).

---

## 1. Was macht das Programm?

`epub2md` nimmt ein **DRM-freies E-Book** (Dateiendung `.epub`) und erzeugt daraus:

- **einen Ordner** mit je einer Markdown-Datei pro Kapitel, allen Bildern, einem Inhaltsverzeichnis und
  einem Prüfbericht (`epub2md.py`)
- auf Wunsch zusätzlich **eine einzige Markdown-Datei mit dem ganzen Buch** (`epub2md_merge.py`)

Markdown ist reiner Text mit einfachen Formatierungszeichen. Du kannst ihn in jedem Editor lesen,
in Obsidian ablegen, mit Git versionieren, mit Pandoc in HTML/PDF/Word umwandeln oder an ein lokales
Sprachmodell (RAG) übergeben.

Was das Programm **nicht** kann:

- **Kopiergeschützte E-Books** (DRM, z. B. aus manchen Online-Shops) öffnen. Sie werden mit einer
  Meldung abgelehnt.
- **Gescannte Bücher** in Text verwandeln (keine Texterkennung/OCR).
- **Formeln, die im E-Book nur als Bild vorliegen**, in echten Formeltext umwandeln. Sie bleiben Bilder.

---

## 2. Einmalige Einrichtung

Voraussetzung ist Python 3.12 (unter Ubuntu 24.04 vorinstalliert). Im Projektordner:

```bash
sudo apt install python3-venv       # nur falls noch nicht vorhanden
cd ~/Python_Programs/epub2md
python3 -m venv .venv               # eigene Python-Umgebung anlegen (einmalig)
source .venv/bin/activate           # Umgebung aktivieren (in jedem neuen Terminal)
pip install -r requirements.txt     # benötigte Bibliothek installieren (einmalig)
```

Funktioniert die Einrichtung? Dieser Befehl muss eine Versionsnummer ausgeben:

```bash
python3 epub2md.py --version
```

> Tipp: Ist die Bibliothek `lxml` systemweit schon installiert, kannst du die virtuelle Umgebung auch
> weglassen.

---

## 3. Ein Buch umwandeln – der Normalfall

```bash
python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch
```

- Erster Wert: die **EPUB-Datei**.
- Zweiter Wert: der **Zielordner**. Er darf noch nicht existieren oder muss leer sein.

Am Ende erscheint eine Zusammenfassung, etwa so:

```text
epub2md: 25 Kapitel, 87 Mediendateien, 747 Codeblöcke, 0 Formeln, 27 Anmerkungen, 0 Warnungen, 0 Fehler
Ausgabe: output/meinbuch
```

Öffne danach `output/meinbuch/README.md`. Dort findest du Titel, Autor, ein klickbares
Inhaltsverzeichnis und eine Statistik.

### Vorher nur nachsehen, ohne etwas zu schreiben

```bash
python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --dry-run
```

Zeigt, welche Kapiteldateien entstehen würden. Es wird nichts gespeichert.

### Mehr sehen, was gerade passiert

```bash
python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --verbose
```

---

## 4. Was liegt danach im Zielordner?

```text
output/meinbuch/
├── README.md                 ← hier anfangen: Inhaltsverzeichnis, Metadaten, Statistik
├── chapters/                 ← das Buch, ein Kapitel pro Datei
│   ├── 001-cover.md
│   ├── 002-vorwort.md
│   └── 003-1-einleitung.md …
├── media/images/             ← alle Bilder (jedes nur einmal)
├── metadata.yaml             ← Titel, Autor, Verlag, ISBN … (nur, was im E-Book steht)
├── manifest.json             ← Kapitelliste für Programme (z. B. RAG-Import)
├── conversion-report.json    ← ausführlicher Prüfbericht für Programme
└── diagnostics/
    ├── warnings.md           ← Warnungen in Klartext – bei Problemen hier nachsehen
    └── unsupported-elements.md
```

Jede Kapiteldatei beginnt mit einem kleinen Datenkopf zwischen zwei `---`-Zeilen (Buchtitel,
Kapitelnummer, Herkunft). Die meisten Markdown-Programme blenden ihn aus oder zeigen ihn als
Eigenschaften an, z. B. Obsidian. Willst du ihn nicht haben, wandle mit `--no-frontmatter` um.

---

## 5. Das ganze Buch in einer Datei

```bash
python3 epub2md_merge.py output/meinbuch
```

Ergebnis: `output/meinbuch/meinbuch.md`. Die Datei heißt wie das Original-E-Book, nur mit `.md`.
Bilder und Querverweise funktionieren darin weiter.

Nützliche Varianten:

```bash
# mit Inhaltsverzeichnis am Anfang
python3 epub2md_merge.py output/meinbuch --toc

# an einen anderen Ort schreiben (Bildpfade werden automatisch angepasst)
python3 epub2md_merge.py output/meinbuch -o ~/Dokumente/meinbuch.md

# eine schon vorhandene Gesamtdatei überschreiben
python3 epub2md_merge.py output/meinbuch --force
```

> Wichtig: Verschiebst du die Gesamtdatei später von Hand, findet sie ihre Bilder nicht mehr. Nutze
> dafür `-o`, dann stimmen die Pfade.

---

## 6. Rezepte für typische Bücher

### Roman (Teile und Kapitel)

Viele Romane gliedern sich in „Teil 1, Teil 2 …“ mit Kapiteln darin. Standardmäßig entsteht eine Datei
pro **Teil**. Das können sehr große Dateien werden. Das Programm warnt dann mit `chapter-large` und
empfiehlt die passende Einstellung. Eine Datei pro **Kapitel** bekommst du so:

```bash
python3 epub2md.py roman.epub output/roman --chapter-level 2
```

### Programmierbuch

```bash
python3 epub2md.py python-buch.epub output/python-buch
```

Programmcode bleibt zeichengenau erhalten, inklusive Einrückung. Die Programmiersprache wird nur
eingetragen, wenn sie eindeutig erkennbar ist. Ist das ganze Buch in **einer** Sprache geschrieben,
kannst du sie für alle übrigen Codeblöcke vorgeben:

```bash
python3 epub2md.py python-buch.epub output/python-buch --code-language python
```

Das hilft Editoren beim Einfärben des Codes. Nachteil: Auch Programmausgaben und Shell-Befehle im Buch
werden dann als Python markiert.

Zu lange Codezeilen sind im gedruckten Buch oft umbrochen und die Fortsetzung mit `↪` markiert. Das
Programm fügt solche Zeilen automatisch wieder zusammen, damit der Code lauffähig ist. Wer die
Druckfassung unverändert haben möchte, gibt `--keep-wrap-markers` an.

### Mathematikbuch

```bash
python3 epub2md.py mathe.epub output/mathe
```

Formeln, die im E-Book als echte Formeln (MathML oder TeX) vorliegen, werden zu TeX: `$…$` im Text,
`$$…$$` als eigene Zeile. Formeln, die nur als Bild vorliegen, bleiben Bilder und erscheinen in
`diagnostics/warnings.md`.

| Gewünschte Formeldarstellung | Option |
| --- | --- |
| TeX mit `$` (GitHub, Obsidian, Pandoc) | Standard (`--math auto`) |
| TeX mit `\(…\)` und `\[…\]` | `--math tex` |
| Formeln als MathML (für Browser/HTML) | `--math mathml` |
| Formeln möglichst als Bilder | `--math image` |

### Buch mit vielen Fußnoten

Standardmäßig stehen die Fußnoten am Ende des jeweiligen Kapitels. Alternativen:

| Wunsch | Option |
| --- | --- |
| Alle Anmerkungen gesammelt in einer eigenen Datei am Buchende | `--footnotes end-of-book` |
| Anmerkung direkt in Klammern im Text | `--footnotes inline` |
| Fußnoten an ihrer Originalstelle mit Links lassen | `--footnotes keep-links` |

---

## 7. Weiterverarbeiten

### In Obsidian lesen

Kopiere den ganzen Ausgabeordner, z. B. `output/meinbuch`, in deinen Obsidian-Tresor. Die Kapitel
erscheinen als einzelne Notizen, Bilder und Links auf andere Kapitel funktionieren. Der Datenkopf wird
als Eigenschaften angezeigt. Sprünge an eine bestimmte Stelle *innerhalb* eines Kapitels (HTML-Anker wie
`<a id="…">`) unterstützt Obsidian nur eingeschränkt. Solche Links öffnen dann einfach das Kapitel.

### Mit Pandoc in HTML, PDF oder EPUB umwandeln

Am einfachsten über die Gesamtdatei. Wechsle dazu in den Ausgabeordner, damit die Bildpfade stimmen:

```bash
python3 epub2md_merge.py output/meinbuch
cd output/meinbuch
pandoc meinbuch.md --toc -s -o meinbuch.html              # Webseite
pandoc meinbuch.md --toc -o meinbuch.docx                 # Word
pandoc meinbuch.md --pdf-engine=xelatex -o meinbuch.pdf   # PDF (LaTeX nötig)
```

Bei Büchern mit Formeln für HTML zusätzlich `--mathml` angeben, sonst bleiben Matrizen als TeX-Text stehen.

### Für ein lokales Sprachmodell (RAG)

- Die einzelnen Kapiteldateien eignen sich als Abschnitte. Die Metadaten im Datenkopf (Buch, Kapitel,
  Herkunft) helfen beim Zuordnen von Fundstellen.
- `manifest.json` listet alle Kapitel mit Titel, Datei, Wortanzahl und Ankern.
- Achte auf die Warnung `chapter-large`: Sehr große Kapiteldateien lassen sich schlecht zerlegen. Dann
  mit höherem `--chapter-level` neu umwandeln.

---

## 8. Ein Buch erneut umwandeln

Ist der Zielordner schon vorhanden, bricht das Programm zum Schutz deiner Daten ab:

```text
epub2md: Fehler: Ausgabeverzeichnis existiert bereits und ist nicht leer: output/meinbuch
```

Zum Ersetzen einer **früheren epub2md-Ausgabe**:

```bash
python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --force
```

`--force` löscht nur Ordner, die erkennbar von epub2md stammen. Ordner mit anderen Inhalten, dein
Home-Verzeichnis oder den aktuellen Arbeitsordner rührt es nicht an.

> Achtung: `--force` ersetzt den **ganzen** Ordner, also auch eine dort erzeugte Gesamtdatei und alles,
> was du selbst hineingelegt hast. Eigene Notizen also nicht im Ausgabeordner speichern.

---

## 9. Warnungen verstehen

Warnungen bedeuten: Die Umwandlung hat funktioniert, aber etwas verdient einen Blick. Alle Warnungen
stehen gesammelt in `diagnostics/warnings.md`.

| Meldung (Code) | Bedeutung | Was tun? |
| --- | --- | --- |
| `chapter-large` | Eine Kapiteldatei ist sehr groß (> 30 000 Wörter) und hat Unterkapitel | Mit dem empfohlenen `--chapter-level` neu umwandeln |
| `formula-image`, `formula-svg` | Formel liegt im E-Book nur als Bild vor | Nichts. Das Bild bleibt erhalten, als Text gibt es diese Formel nicht |
| `mathml-kept` | Formel war zu komplex für eine sichere TeX-Umwandlung | Nichts. Sie bleibt als MathML erhalten, HTML-fähige Programme und Browser zeigen sie an |
| `table-html` | Tabelle mit verbundenen Zellen o. Ä. | Nichts. Sie bleibt als HTML-Tabelle erhalten, das zeigen die meisten Programme an |
| `unresolved-link` | Ein Querverweis im E-Book zeigt ins Leere | Nichts. Der Linktext bleibt stehen, nur ohne Link |
| `anchor-missing` | Sprungziel im Kapitel nicht gefunden | Der Link führt zum Kapitelanfang |
| `image-missing`, `media-missing` | Bild/Medium fehlt im E-Book selbst | Fehler der Vorlage, Platzhaltertext eingefügt |
| `noteref-unresolved` | Fußnotenzeichen ohne zugehörige Fußnote | Fehler der Vorlage |
| `note-unreferenced` | Fußnote, auf die nichts verweist | Bleibt an ihrer Stelle im Text |
| `decode-error` | Zeichen im E-Book waren beschädigt | Betroffene Zeichen erscheinen als `<60>` |
| `no-toc` | E-Book ohne Inhaltsverzeichnis | Kapiteltitel werden aus dem Inhalt abgeleitet |
| `broken-output-link` | Interne Prüfung fand einen kaputten Link in der Ausgabe | Bitte melden, das sollte nicht vorkommen |

Fehler, nach denen trotzdem weitergearbeitet wurde, etwa eine fehlende Kapiteldatei im E-Book, stehen
ebenfalls dort. Mit `--strict` bricht das Programm bei solchen kritischen Fehlern stattdessen ab, ohne
eine Ausgabe zu schreiben.

---

## 10. Fehlermeldungen und Lösungen

| Meldung (Auszug) | Ursache | Lösung |
| --- | --- | --- |
| `Eingabedatei nicht gefunden` | Pfad zur EPUB-Datei falsch | Pfad prüfen, ggf. in Anführungszeichen setzen (Leerzeichen!) |
| `Ausgabeverzeichnis existiert bereits` | Zielordner ist nicht leer | Anderen Zielordner wählen oder `--force` (siehe Kapitel 8) |
| `--force verweigert` | Zielordner stammt nicht von epub2md | Ordner prüfen und selbst leeren oder anderen Ordner wählen |
| `Ausgabeverzeichnis nicht beschreibbar` | Keine Schreibrechte | Ordner mit Schreibrechten wählen |
| `Keine gültige ZIP/EPUB-Datei` | Datei ist beschädigt oder kein EPUB | Datei neu herunterladen |
| `container.xml fehlt` | Beschädigtes oder unvollständiges EPUB | Datei neu herunterladen; ggf. mit Calibre reparieren |
| `verschlüsselt/DRM-geschützt` | Kopiergeschütztes E-Book | Wird nicht unterstützt |
| `ZIP-Eintrag zu groß` | Ungewöhnlich großer, verdächtiger Inhalt | Schutzfunktion, Datei nicht verwenden |
| `Die Spine enthält keine lesbaren XHTML-Dokumente` | E-Book hat keinen lesbaren Text | Datei prüfen |
| `invalid choice` / `Fehler: argument …` | Option falsch geschrieben | `python3 epub2md.py --help` ansehen |

Rückgabecodes für Skripte:

| Code | Bedeutung |
| --- | --- |
| 0 | Erfolg, ggf. mit Warnungen |
| 1 | Bedienfehler: Optionen, Eingabedatei, Zielordner |
| 2 | E-Book-Datei beschädigt, kopiergeschützt oder unsicher |
| 3 | Inhalt des E-Books nicht verarbeitbar |
| 4 | Unerwarteter Programmfehler. Mit `--verbose` wiederholen und die Meldung notieren |

---

## 11. Häufige Fragen

**Werden meine E-Books irgendwohin hochgeladen?**
Nein. Das Programm arbeitet vollständig offline und greift nicht aufs Netz zu.

**Wird das Original-E-Book verändert?**
Nein, es wird nur gelesen. Mit `--copy-original` wird zusätzlich eine Kopie in den Ausgabeordner gelegt.

**Warum heißen manche Kapiteldateien „Titelseite“, „Impressum“ oder nach ihren ersten Wörtern?**
Manche E-Book-Seiten haben weder Überschrift noch Titel. Das Programm erkennt sie dann am Inhalt.
Gelingt das nicht, werden die ersten Wörter der Seite verwendet, nur im Notfall der interne Dateiname.

**Warum ist ein Codebeispiel falsch eingerückt?**
So steht es im E-Book selbst (Satzfehler des Verlags). Der Code wird bewusst zeichengetreu
übernommen. Nur die Druck-Umbruchzeichen `↪` werden aufgelöst (abschaltbar mit `--keep-wrap-markers`).

**Können Dateinamen Umlaute enthalten?**
Standardmäßig werden Umlaute umschrieben (`ä` → `ae`). Mit `--slug-language none` bleiben sie erhalten,
mit `--slug-language en` wird `ä` zu `a`.

**Kann ich die Bilder anders ablegen lassen?**
`--images flat` legt alle Medien direkt in `media/`. `--images original-path` behält die Ordnerstruktur
des E-Books bei. Mit `--no-extract-media` werden gar keine Bilder gespeichert.

**Woher weiß ich, ob alles geklappt hat?**
Steht in der Zusammenfassung `0 Fehler`, ist die Umwandlung durchgelaufen. Warnungen erklärt Kapitel 9.
Das Programm prüft am Ende selbst alle Links und Bildverweise der Ausgabe.

---

## 12. Alle Optionen auf einen Blick

```bash
python3 epub2md.py --help
python3 epub2md_merge.py --help
```

| Option | Kurz erklärt |
| --- | --- |
| `--dry-run` | nur anzeigen, nichts schreiben |
| `--verbose` | ausführliche Ausgabe |
| `--force` | frühere Ausgabe ersetzen |
| `--chapter-level N` | ab welcher Überschriftenebene eine neue Datei beginnt (Standard 1) |
| `--code-language SPRACHE` | Sprache für Codeblöcke ohne erkannte Sprache |
| `--keep-wrap-markers` | Druck-Umbruchzeichen `↪` im Code stehen lassen |
| `--math auto/tex/mathml/image` | Formeldarstellung |
| `--footnotes end-of-chapter/end-of-book/inline/keep-links` | Fußnoten-Platzierung |
| `--format gfm/commonmark` | Markdown-Variante; `commonmark` für sehr strikte Programme |
| `--images relative/flat/original-path` | Ablage der Bilder |
| `--no-extract-media` | keine Bilder speichern |
| `--copy-original` | Original-EPUB mit in den Ordner legen |
| `--no-frontmatter` | ohne Datenkopf in den Kapiteln |
| `--no-toc` | ohne README/Inhaltsverzeichnis |
| `--slug-language de/en/none` | Umgang mit Umlauten in Dateinamen |
| `--keep-html` | Unbekanntes als HTML erhalten statt nur als Text |
| `--strict` | bei kritischen Fehlern im E-Book abbrechen |
| `--report DATEI.json` | Prüfbericht zusätzlich an anderer Stelle speichern |

Merge-Programm: `-o DATEI.md` (Zielort), `--toc` (Inhaltsverzeichnis), `--no-frontmatter` (ohne Buch-Kopf),
`--force` (überschreiben).