# 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 ``` 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. 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. ### 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 -s -o meinbuch.html && \ pandoc meinbuch.html --toc --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 PDF immer den Umweg über HTML nehmen, wie oben gezeigt. Beim direkten Weg von Markdown nach PDF lässt Pandoc komplexe Tabellen weg, und Querverweise im PDF funktionieren nicht. Die `README.md` im Ausgabeordner enthält die passenden Befehle für dein Buch. ### 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 `�` | | `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 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).