# 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. ### 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 ``) 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 `�` | | `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 seltsam (z. B. `cinnertitle`)?** Manche E-Book-Seiten (Titelseite, Impressum) haben weder Überschrift noch Titel. Dann wird der interne Dateiname verwendet. **Warum steht in einem Codebeispiel ein `↪` oder ist es falsch eingerückt?** So steht es im E-Book selbst (Umbruchzeichen bzw. Satzfehler des Verlags). Der Code wird bewusst zeichengetreu übernommen. **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 | | `--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).