diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md new file mode 100644 index 0000000..89fdebd --- /dev/null +++ b/BEDIENUNGSANLEITUNG.md @@ -0,0 +1,362 @@ +# 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). diff --git a/README.md b/README.md index 687e7e6..a460f63 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ YAML-Metadaten, Inhaltsverzeichnis, maschinenlesbarem Manifest und einem Konvert Gedacht für die Weiterverarbeitung mit Markdown-Renderern, Pandoc, Obsidian/Zettelkasten, Git, RAG-/Embedding-Pipelines, Volltextsuche und lokale LLMs. +Eine Schritt-für-Schritt-Anleitung für Anwender steht in der [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md). + Das Projekt enthält zwei Programme: | Programm | Zweck |