dschlueter
3ac5e1a8cc
Seiten ohne Überschrift, NAV-Eintrag und <title> werden am Inhalt erkannt: - Bild am Buchanfang -> Cover - Buchtitel und Autor -> Titelseite - ©/ISBN/urheberrechtlich -> Impressum - sonst die ersten acht Wörter Erst danach greift der Dateiname. Im Roman-Beispiel werden aus cinnertitle/cimprint so 'Titelseite' und 'Impressum'. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
367 lines
15 KiB
Markdown
367 lines
15 KiB
Markdown
# 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).
|