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/EPUB/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. Am Anfang stehen die Buchdaten (Titel, Autor, Verlag,
Datum als `13.01.2025`), die Pandoc für die Titelseite verwendet.

Nützliche Varianten:

```bash
# mit Inhaltsverzeichnis (Liste der Kapitel) hinter Cover, Titelseite und Impressum –
# für PDFs mit Pandoc nicht nötig, dort baut book.lua ein Verzeichnis mit Seitenzahlen (Kapitel 7)
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. Das Programm erkennt sehr große
Teile (über 30 000 Wörter) selbst und legt dann eine kurze Datei für den Teil und eine Datei pro
**Kapitel** an; kurze Abschnitte wie Vorwort oder Anhang bleiben eine Datei. Du musst dafür nichts
einstellen. Soll wirklich jeder Abschnitt mit Unterüberschrift eine eigene Datei werden, gilt:

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

### Roman (Szenenwechsel, Gedichte)

Szenenwechsel, die im Buch nur als Leerzeile zwischen zwei Absätzen erscheinen, werden als `* * *`
übernommen; sonst würden zwei Szenen nahtlos ineinanderlaufen. Gedichte und Liedtexte bleiben Zeile für
Zeile erhalten (als eingerückter Zitatblock, Strophen durch Leerzeile getrennt).

### 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
```

Hat das Programm viele Codeblöcke ohne Sprache gefunden, aber alle erkannten in derselben Sprache,
schlägt es diese Option im Bericht von sich aus vor (Hinweis `code-language-hint`). 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. Viele Verlage legen das TeX einer Formel in den Alternativtext eines Formelbildes;
epub2md übernimmt es und passt Schreibweisen an, die Pandoc nicht versteht (z. B. `\"u` → `ü`), ohne den
Inhalt zu ändern. 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` |

### Bildband (viele Bilder)

```bash
python3 epub2md.py bildband.epub output/bildband --chapter-level 3
```

- Jedes Bild wird genau einmal nach `media/images/` kopiert, auch wenn es mehrfach vorkommt. Die
  Dateinamen beginnen mit einer laufenden Nummer, gefolgt von einem Stichwort aus dem Bildtext.
- Alternativtexte (Bildbeschreibungen für Screenreader) und Bildunterschriften bleiben erhalten.
  Unterschriften erscheinen kursiv unter dem Bild.
- Bildbände haben oft sehr lange Großkapitel mit Hunderten Bildern. Mit `--chapter-level 2` oder `3`
  entsteht eine Datei pro Thema bzw. pro Projekt. Das ist übersichtlicher und lädt schneller.
  Beispiel: 9 Dateien beim Standard, 29 bei Stufe 2 und 78 bei Stufe 3.
- Bilder, die im E-Book zwar enthalten, aber nirgends eingebunden sind, werden trotzdem gespeichert.
  Im Bericht sind sie als `unreferenced` gekennzeichnet.

### Infokästen (Tipps, Hinweise, Warnungen)

Kästen aus dem Buch, etwa „Tipp“, „Achtung“, „Exkurs“ oder „Die MATLAB-Minute“, werden als hervorgehobene
Blöcke übernommen:

```markdown
> [!TIP]
> **Erwartungen an dieses Buch**
>
> Text des Kastens …
```

GitHub und Obsidian zeigen das als farbigen Kasten mit Symbol; andere Programme als eingerückten Zitatblock.
Für Pandoc (HTML, EPUB, PDF) gibt es einen Filter, der echte Kästen zeichnet, siehe Kapitel 7 („Weiterverarbeiten“).
Andere Darstellungen wählst du mit `--boxes`:

- `quote`: Zitatblock ohne `[!TIP]`
- `html`: HTML-`<div>`
- `plain`: wie normaler Text

### Farben, Schriftarten und Schriftgrößen

Markdown kennt keine Farben, Schriftarten oder Schriftgrößen. Standardmäßig übernimmt das Programm daher
nur, was eine Bedeutung trägt:

- **fett** und *kursiv*, auch wenn das Buch sie nur über sein Stylesheet setzt
- unterstrichen, hoch- und tiefgestellt
- farbig hinterlegter Text als `<mark>`-Markierung

Möchtest du das Aussehen möglichst erhalten, etwa für eine HTML-, EPUB- oder PDF-Ausgabe mit Pandoc oder zum
Lesen in Obsidian, wandle mit `--styles html` um. Dann bleiben Farbe, Hintergrund, Schriftgröße,
Schriftart, Kapitälchen und zentrierte oder rechtsbündige Absätze als HTML erhalten. Das gilt nur dort, wo
sie vom normalen Text abweichen. Fremdsprachige Passagen werden als solche gekennzeichnet. GitHub zeigt
diese Angaben nicht an.

### Seitenzahlen der Druckausgabe (zum Zitieren)

Viele E-Books enthalten unsichtbare Marken, wo im gedruckten Buch eine neue Seite beginnt. Standardmäßig
lässt das Programm sie weg. Mit `--page-markers visible` erscheinen sie im Text als `[S. 123]`, mit
`--page-markers comment` als unsichtbarer Kommentar `<!-- S. 123 -->`. Den findest du über die Suche, er
stört aber beim Lesen nicht.

```bash
python3 epub2md.py roman.epub roman-md --page-markers visible
```

In Codebeispielen stehen keine Seitenmarken, damit der Code unverändert bleibt. Enthält das E-Book keine
Seitenmarken, bleibt die Option ohne Wirkung; im Bericht steht dann `"page_markers": 0`.

### 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` |

---

### Verzeichnisse: Quellen, Literatur, Register, Glossar

Quellen- und Literaturverzeichnisse, Sach- und Personenregister, Glossare und Anhänge aus dem E-Book werden
übernommen. Sie stehen jeweils in einer eigenen Datei und sind in der `README.md` unter „Besondere Abschnitte“
verlinkt. Das gilt auch, wenn ein solches Verzeichnis im Buch nur ein Unterabschnitt ist, etwa „Quellen“
im Anhang eines Romans. Neu erzeugt wird nichts: Hat ein Buch kein Register, entsteht auch keins.

- Register: Buchstabengruppen werden zu Überschriften, Untereinträge sind eingerückt, Verweise auf
  Textstellen bleiben anklickbare Links.
- Literatur: Autoren, Titel, DOI, ISBN und Internetadressen bleiben vollständig erhalten; Adressen
  bleiben 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.

### In andere Formate umwandeln (HTML, PDF, EPUB, Word …)

Dafür eignet sich **Pandoc**; für Kindle-Formate kommt **Calibre** (`ebook-convert`) dazu. Beide sind
eigenständige Programme und nicht Teil von epub2md. Installation unter Ubuntu:
`sudo apt install pandoc calibre`. Für PDF zusätzlich entweder LaTeX
(`sudo apt install texlive-xetex`) oder `pip install weasyprint`.

> **Wichtig:** Die Befehle im Ordner der jeweiligen Datei ausführen. Sonst findet Pandoc die Bilder nicht,
> weil die Bildpfade relativ angegeben sind.

#### Aus der Gesamtdatei (empfohlen)

```bash
python3 epub2md_merge.py output/meinbuch    # erzeugt output/meinbuch/meinbuch.md
cd output/meinbuch
```

`meinbuch.md` steht im Folgenden für den Namen der Gesamtdatei. Er entspricht dem Namen des
Original-E-Books. `$P` ist der Ordner mit den Pandoc-Hilfsdateien von epub2md; lege ihn einmal fest:

```bash
P=~/Python_Programs/epub2md/pandoc     # Pfad zu deinem epub2md-Ordner anpassen
```

| Ziel | Befehl |
| --- | --- |
| PDF (empfohlen) | `pandoc meinbuch.md -s --lua-filter $P/book.lua --lua-filter $P/callouts.lua --css $P/print.css --pdf-engine=weasyprint -o meinbuch.pdf` |
| Webseite (HTML) | `pandoc meinbuch.md -s --lua-filter $P/book.lua --lua-filter $P/callouts.lua -o meinbuch.html` |
| Webseite mit Formeln | wie HTML, zusätzlich `--mathml` |
| E-Book (EPUB) | `pandoc meinbuch.md --toc --lua-filter $P/callouts.lua -o meinbuch.epub` |
| E-Book mit Formeln | wie EPUB, zusätzlich `--mathml` |
| Word | `pandoc meinbuch.md --toc --lua-filter $P/callouts.lua -o meinbuch.docx` |
| LibreOffice | `pandoc meinbuch.md --toc --lua-filter $P/callouts.lua -o meinbuch.odt` |
| PDF mit LaTeX (Bücher mit Formeln) | `pandoc meinbuch.md -s --mathml --lua-filter $P/book.lua --lua-filter $P/callouts.lua -o meinbuch.html && pandoc meinbuch.html --lua-filter $P/book.lua --lua-filter $P/callouts.lua --pdf-engine=xelatex -o meinbuch.pdf` |
| Kindle (AZW3) | erst EPUB wie oben, dann `ebook-convert meinbuch.epub meinbuch.azw3` |

Die drei Hilfsdateien:

- **`book.lua`** ordnet den Buchanfang wie im gedruckten Buch: Cover, Titelseite, Impressum, dann das
  Inhaltsverzeichnis, jeweils auf einer neuen Seite. Ohne den Filter setzt Pandoc mit `--toc` das
  Inhaltsverzeichnis (und seinen eigenen Titelkopf) vor das Cover. Mit `book.lua` deshalb **kein** `--toc`
  angeben. Hat das Buch keine eigene Titelseite, setzt der Filter Pandocs Titelkopf hinter das Cover. Das
  gilt für HTML und für beide PDF-Wege (beim LaTeX-Weg den Filter in beiden Schritten angeben); EPUB, Word
  und LibreOffice bauen ihr Verzeichnis mit `--toc` selbst. Kurze Seiten zwischen Titelseite und Impressum
  (Auflagenvermerk, Verlagsbrief, „Über dieses Buch“) bleiben im Vorspann; das Inhaltsverzeichnis folgt vor
  dem ersten Teil, Vorwort oder nummerierten Kapitel.
- **`callouts.lua`** zeichnet die Infokästen (`> [!TIP]`). Pandoc in der Ubuntu-Version kennt diese
  Schreibweise nicht und druckt „[!TIP]“ sonst einfach mit. In HTML, EPUB und im PDF über weasyprint werden
  daraus gerahmte, farbige Kästen mit Titel („Tipp: …“), im PDF über LaTeX und in Word/LibreOffice ein
  eingerückter Block mit fettem Titel.
- **`print.css`** liefert das Druck-Layout für weasyprint: A4, Seitenzahlen (nicht auf dem Cover), jedes
  Kapitel auf einer neuen Seite, Inhaltsverzeichnis mit Seitenzahlen, Silbentrennung und umbrechende lange
  Codezeilen. Ohne sie
  übernimmt weasyprint das Bildschirmlayout, und lange Codezeilen werden am Seitenrand abgeschnitten.

Du musst die Befehle nicht abtippen: Die `README.md` im Ausgabeordner enthält sie fertig, mit allen Pfaden.

**Zum PDF:**

- **Mit weasyprint** (empfohlen für Bücher ohne Formeln) genügt ein Schritt. Tabellen, Farben,
  Infokästen und die Gestaltung aus `--styles html` bleiben erhalten.
- **Mit LaTeX** immer den Zwischenschritt über HTML nehmen, wie in der Tabelle. Beim direkten Weg von
  Markdown nach LaTeX lässt Pandoc komplexe Tabellen weg, und Querverweise im PDF funktionieren nicht. Für
  Bücher mit Formeln ist das der richtige Weg, weil weasyprint keine Formeln setzen kann. Farben und
  Kastenrahmen gehen dabei verloren; Kästen erscheinen als eingerückter Block mit fettem Titel. `book.lua`
  stellt dabei A4 ein und wählt die Schrift DejaVu, die auch Zeichen wie ∈, λ oder ≠ im Fließtext enthält.

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

#### Direkt aus den Kapiteldateien

Ohne Gesamtdatei geht es auch. Dann im Ordner `chapters/` arbeiten und die Buchdaten aus
`metadata.yaml` mitgeben:

```bash
cd output/meinbuch/chapters
pandoc *.md --metadata-file=../metadata.yaml -s --toc -o ../meinbuch.html
pandoc *.md --metadata-file=../metadata.yaml --toc -o ../meinbuch.epub
```

Das Ergebnis entspricht dem der Gesamtdatei. Querverweise zwischen Kapiteln funktionieren aber nur in der
Gesamtdatei zuverlässig. Bei Büchern mit vielen Verweisen also lieber die Gesamtdatei verwenden. Für PDF
gilt hier derselbe Umweg über HTML.

#### Weitere Formate und Tipps

- Pandoc kennt viele weitere Formate, z. B. `.rtf`, `.txt`, `.tex` (LaTeX-Quelltext), `.rst` oder
  `.adoc`. Meist genügt `-o datei.<endung>`. Alle Formate zeigt `pandoc --list-output-formats`.
- Wurde mit `--math tex` umgewandelt, braucht Pandoc zusätzlich `-f markdown+tex_math_single_backslash`.
- Die `README.md` im Ausgabeordner enthält im Abschnitt „Weiterverarbeitung“ die passenden Befehle mit
  dem richtigen Dateinamen. Bei Büchern mit Formeln steht `--mathml` dort schon dabei.

### 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.
- Sehr große Kapitel teilt das Programm selbst an ihren Unterkapiteln. Hast du `--chapter-level` fest
  eingestellt und erscheint die Warnung `chapter-large`, dann mit dem empfohlenen Wert 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>` |
| `undefined-entity` | Das E-Book verwendet Sonderzeichen-Namen (`&name;`), die nirgends definiert sind | Diese Zeichen fehlen in der Ausgabe; Fehler der Vorlage |
| `media-skipped` (Fehler) | Ein Bild/Medium war verdächtig groß oder stark komprimiert und wurde aus Sicherheitsgründen nicht übernommen | An seiner Stelle steht `[Bild nicht übernommen: …]`; mit `--strict` bricht das Programm ab |
| `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 |

Steht hinter einer Meldung `(×5)`, ist dieselbe Meldung an derselben Stelle mehrfach aufgetreten.

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 `auto`: Ebene 1, sehr große Kapitel werden an ihren Unterkapiteln geteilt) |
| `--code-language SPRACHE` | Sprache für Codeblöcke ohne erkannte Sprache |
| `--keep-wrap-markers` | Druck-Umbruchzeichen `↪` im Code stehen lassen |
| `--keep-invisible-chars` | unsichtbare Zeichen (Nullbreiten-Leerzeichen, weiche Trennstriche) behalten |
| `--boxes callout/quote/html/plain` | Darstellung von Infokästen |
| `--styles semantic/html` | Farben, Schriften, Größen, Ausrichtung und Sprache als HTML übernehmen (`html`) |
| `--page-markers none/visible/comment` | Seitenzahlen der Druckausgabe als `[S. 123]` oder `<!-- S. 123 -->` |
| `--no-css-emphasis` | Hervorhebungen nur aus HTML-Tags übernehmen, nicht aus dem Stylesheet des Buches (farbige Markierungen `<mark>` bleiben, sie gehören zu `--styles`) |
| `--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).