docs: BEDIENUNGSANLEITUNG.md für Anwender

Schritt-für-Schritt-Anleitung: Einrichtung, Umwandeln, Gesamtdatei,
Rezepte für Roman/Programmier-/Mathebuch/Fußnoten, Weiterverarbeitung
(Obsidian, Pandoc, RAG), erneutes Umwandeln, Warnungen und Fehlermeldungen
mit Abhilfe, FAQ und Optionsübersicht. README verlinkt sie.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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
+`<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 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).