pdf2md/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung: pdf2md.py – PDF → Markdown → EPUB

`pdf2md.py` wandelt PDF-Bücher in sauberes Markdown um: echte Absätze, Überschriften mit
richtiger Ebene, Bilder und ohne Seitenzahlen. Daraus entsteht auf Wunsch direkt ein EPUB für
den PocketBook-Reader. Das funktioniert mit digitalen PDFs (Text lässt sich markieren) ebenso wie
mit gescannten PDFs (nur Seitenbilder, der Text wird per OCR erkannt).

Es gibt zwei Arbeitswege:

- **Weg A:** PDF → EPUB in einem Schritt, wenn das Ergebnis ohne Nacharbeit passt.
- **Weg B:** PDF → Markdown → von Hand bearbeiten → EPUB, wenn du Überschriften, Text oder
  Bilder noch korrigieren willst.
- **Weg C:** wie Weg B, aber jeder Teil bzw. jedes Kapitel in einer eigenen Datei – zum
  Umsortieren, für RAG oder andere Formate.

---

## 1. Installation und Prüfung

Einmalig unter Ubuntu 24.04:

```bash
sudo apt install tesseract-ocr tesseract-ocr-deu pandoc
cd ~/Downloads/ljutsch
pip install -r requirements.txt
```

- `tesseract-ocr` + `tesseract-ocr-deu` braucht man nur für gescannte PDFs.
- `pandoc` braucht man nur für das EPUB.

Prüfen, ob alles da ist:

```bash
tesseract --list-langs      # muss "deu" enthalten
pandoc --version            # Version 3.x
python3 pdf2md.py --help # zeigt alle Optionen
```

---

## 2. Weg A – PDF → EPUB in einem Schritt

```bash
cd ~/Downloads/ljutsch
python3 pdf2md.py --epub Operation_Ljutsch_Band_1_-_Reinhard_Otto_Kranz.pdf Output/band1.md
```

Das Programm meldet zuerst, was es in der PDF gefunden hat:

```
706 Seiten: 705 Text, 1 Scan/Bild, 0 mit OCR-Ebene, 0 leer → 0 Seiten werden per OCR gelesen
Hinweis: 1 Bildseite(n) ohne Text bleiben ohne OCR (Fotos/Cover oder --ocr never).
  [1/15] Seiten 1–50 (Text) fertig
  ...
```

| Begriff | Bedeutung |
| :-- | :-- |
| Text | Seiten mit echter Textebene, keine OCR nötig |
| Scan/Bild | Seiten, die nur aus einem Bild bestehen (Scan, Foto, Cover) |
| mit OCR-Ebene | Scans, die schon unsichtbaren Text enthalten (z. B. von `ocrmypdf`) |
| „Hinweis: … Bildseite(n)“ | Bildseiten, die bewusst *nicht* per OCR gelesen werden, meist das Cover |

Danach liegen in `Output/`:

| Datei | Inhalt |
| :-- | :-- |
| `band1.md` | das Buch als Markdown |
| `band1_images/` | Bilder als JPEG, dazu `cover.jpg` (Seite 1 der PDF) |
| `band1.epub` | das fertige E-Book (Titel und Autor aus der PDF, siehe unten) |

Ein Band mit ca. 700 Seiten dauert etwa anderthalb Minuten.

**Titel und Autor im EPUB** stammen aus den Metadaten der PDF. Fehlen sie, wertet das Programm
den Dateinamen nach dem Muster `Autor_-_Titel.pdf` aus: `Katja_Adler_-_Rolle_rückwärts.pdf` ergibt
Titel „Rolle rückwärts“ und Autor „Katja Adler“. Ohne ` - ` im Namen wird der ganze Dateiname
(mit Leerzeichen statt `_`) zum Titel. Es lohnt sich also, PDFs vorher passend umzubenennen.

---

## 3. Weg B – Markdown von Hand bearbeiten, dann EPUB

### Schritt 1: Markdown erzeugen

Wie bei Weg A, also **mit** `--epub`. So entstehen gleich das Cover (`cover.jpg`) und ein erstes
EPUB zum Vergleichen:

```bash
cd ~/Downloads/ljutsch
python3 pdf2md.py --epub Operation_Ljutsch_Band_1_-_Reinhard_Otto_Kranz.pdf Output/band1.md
```

Wenn du kein Probe-EPUB brauchst, reicht `--images` statt `--epub` (das Cover wird trotzdem
abgelegt).

Am Anfang von `band1.md` steht ein **YAML-Kopf** mit den Angaben für das EPUB:

```yaml
---
title: "Operation Ljutsch"
author: "Reinhard Otto Kranz"
lang: "de"
cover: "band1_images/cover.jpg"
---
```

Hier kannst du Titel, Autor, Sprache oder Cover ändern. Werte immer in `"…"` schreiben.

### Schritt 2: `band1.md` bearbeiten

Öffne die Datei in einem beliebigen Texteditor und halte dich an diese Regeln:

| Element | Schreibweise | Wirkung im EPUB |
| :-- | :-- | :-- |
| Teil | `## Teil I: Das Vermächtnis` | eigener Abschnitt im Inhaltsverzeichnis |
| Kapitel | `### 1 Der Notar` | eigenes Kapitel (eigene Datei im EPUB), unter dem Teil eingeordnet |
| Absatz | durch **eine Leerzeile** vom nächsten getrennt | neuer Absatz |
| Zeilenumbruch innerhalb eines Absatzes | einfacher Umbruch | wird zu einem Leerzeichen |
| Zeile erzwingen (Register, Vers, Adresse) | `\` am Zeilenende | neue Zeile im selben Absatz |
| Einrückung außerhalb von Code | geschützte Leerzeichen (U+00A0) am Zeilenanfang | bleibt erhalten (normale Leerzeichen verschwinden) |
| Code | zwischen zwei Zeilen ```` ``` ````, Einrückung mit Leerzeichen | Schreibmaschinenschrift, Einrückung bleibt, lange Zeilen werden umbrochen |
| Bild | `![](band1_images/…jpg)` auf eigener Zeile | Bild an dieser Stelle |
| kursiv / fett | `_Wort_` / `**Wort**` | kursiv / fett |
| Link | `<https://beispiel.de/seite>` oder `[Text](https://beispiel.de/seite)` | anklickbarer Link |

Wichtig:

- Der Ordner `band1_images/` muss **neben** `band1.md` liegen bleiben. Benennst du die
  Markdown-Datei um, ändern sich die Bildpfade nicht, die Bilder bleiben gültig.
- Bildzeilen nicht verändern, nur löschen, wenn das Bild weg soll.
- Nach `#` immer ein Leerzeichen: `## Titel`, nicht `##Titel`.

Beispiel: Eine falsch erkannte Überschrift korrigieren.

Vorher (ein Satz, der als Überschrift erkannt wurde, und ein Kapiteltitel ohne Überschrift):

```markdown
## Er ging nach Hause.

**4 Flucht aufs Land**

Am nächsten Morgen ...
```

Nachher:

```markdown
Er ging nach Hause.

### 4 Flucht aufs Land

Am nächsten Morgen ...
```

### Schritt 3: EPUB aus dem bearbeiteten Markdown erzeugen

```bash
cd ~/Downloads/ljutsch
python3 pdf2md.py --from-md Output/band1.md
```

Das erzeugt `Output/band1.epub` mit denselben Einstellungen wie `--epub`. Titel, Autor, Sprache
und Cover kommen aus dem YAML-Kopf; `--title`, `--author`, `--lang` oder `--epub-file PFAD`
überschreiben sie bei Bedarf.

Schritt 2 und 3 kannst du beliebig oft wiederholen. **Achtung:** Schritt 1 erneut auszuführen
überschreibt deine Änderungen in `band1.md`. Leg dir vorher eine Kopie an oder nimm einen anderen
Dateinamen.

---

## 4. Weg C – Teile oder Kapitel als Einzeldateien

```bash
cd ~/Downloads/ljutsch
python3 pdf2md.py --epub --split kapitel Operation_Ljutsch_Band_1_-_Reinhard_Otto_Kranz.pdf Output/band1.md
```

Statt `band1.md` entsteht der Ordner `Output/band1/`:

```
band1/
  index.md                                  Reihenfolge der Dateien + YAML-Kopf des Buchs
  00_vorspann.md                            Titelei und Inhaltsverzeichnis
  01_vorwort-berlin-2015.md
  02_teil-i-das-vermaechtnis.md             Teil-Überschrift (und ggf. Einleitung)
  03_1-der-notar.md
  …
  40_impressum.md
  images/                                   Bilder und cover.jpg
```

- `--split kapitel` schneidet an Teilen **und** Kapiteln, `--split teile` nur an Teilen (ein Teil
  mit all seinen Kapiteln pro Datei).
- Jede Datei beginnt mit einem YAML-Kopf, z. B.:
  ```yaml
  ---
  title: "3 Die Grauen nehmen die Spur auf"
  part: "Teil I: Das Vermächtnis"
  chapter: 3
  order: 5
  book: "Operation Ljutsch"
  author: "Reinhard Otto Kranz"
  ---
  ```
- **Umsortieren:** in `index.md` die Zeilen verschieben. **Weglassen:** Zeile löschen.
  Dateien dürfen umbenannt werden, wenn der Link in `index.md` mitgeändert wird.
- **EPUB neu bauen:** `python3 pdf2md.py --from-md Output/band1/` → `Output/band1.epub`
  (Kapitel in der Reihenfolge von `index.md`).

---

## 5. Gescannte PDFs

Bei Scans liest das Programm den Text per OCR (Tesseract). Der Aufruf ist derselbe:

```bash
python3 pdf2md.py --epub scan.pdf Output/scan.md
```

| Situation | Option |
| :-- | :-- |
| Buch in Deutsch (Standard) | – (`--ocr-language deu`) |
| Deutsch und Englisch gemischt | `--ocr-language deu+eng` (Sprachpaket `tesseract-ocr-eng` nötig) |
| mehr oder weniger parallele OCR-Prozesse | `--jobs N` (Standard: halbe Kernzahl, höchstens 8) |
| OCR erzwingen, auch für vorhandene OCR-Ebenen | `--ocr always` |
| englisches Buch | `--ocr-language eng` (Sprachpaket `tesseract-ocr-eng` nötig; EPUB-Sprache wird automatisch `en`) |
| keine OCR | `--ocr never` oder `--no-ocr` |

So entscheidet das Programm von selbst (`--ocr auto`):

- **Scanseiten** werden per OCR gelesen. Richtwert: ca. 1 Sekunde pro Seite mit 4 Prozessen,
  also ca. 5 Minuten für 300 Seiten.
- **Scans mit vorhandener OCR-Ebene** (z. B. von `ocrmypdf`): Eine gerade Ebene wird
  übernommen, das geht sehr schnell. Eine schiefe Ebene (Scan nicht entzerrt) wird neu erkannt,
  weil ihre Lesereihenfolge oft falsch ist. Alte OCR-Ebenen (z. B. aus Digitalisaten älterer
  Bücher) sind oft schlecht: Kolumnentitel werden zu Überschriften, Buchstaben sind falsch
  erkannt. Dann mit `--ocr always` neu erkennen lassen.
- **Reine Bildseiten in einem sonst digitalen PDF** (Fotos, Cover) werden nur übernommen, wenn eine
  Probe-OCR echten Fließtext liefert. Sonst bleiben sie Bild, und das Programm meldet einen
  „Hinweis“.

Kolumnentitel und Seitenzahlen gedruckter Bücher werden automatisch entfernt, getrennte Wörter
(„Geheim-|dienst“) zusammengefügt.

---

## 6. Alle Optionen

| Option | Bedeutung |
| :-- | :-- |
| `pdf` | Eingabe-PDF (entfällt bei `--from-md`) |
| `markdown` | Ausgabe-Datei; ohne Angabe: gleicher Name wie die PDF mit `.md` |
| `--ocr auto\|always\|never` | OCR-Entscheidung (Standard `auto`, siehe Abschnitt 5) |
| `--no-ocr` | Kurzform für `--ocr never` |
| `--ocr-language` | Tesseract-Sprache(n), z. B. `deu+eng` (Standard `deu`) |
| `--ocr-dpi` | Auflösung für die OCR (Standard 300) |
| `--jobs N` | parallele OCR-Prozesse (Standard: halbe Kernzahl, höchstens 8) |
| `--images` | Bilder in `<name>_images/` speichern und im Markdown verlinken |
| `--image-format jpg\|png` | Bildformat (Standard `jpg`; `png` verlustfrei, aber ca. 3× größer) |
| `--jpeg-quality 1-100` | JPEG-Qualität (Standard 85; 95 fast verlustfrei, Bilder ca. 1,7× größer) |
| `--epub` | zusätzlich EPUB erzeugen (schaltet `--images` ein) |
| `--epub-file PFAD` | anderer Pfad für das EPUB |
| `--split teile\|kapitel` | Teile bzw. Kapitel als Einzeldateien (Abschnitt 4) |
| `--from-md PFAD` | nur EPUB aus `.md`-Datei oder `--split`-Ordner (Abschnitt 3, 4) |
| `--title`, `--author` | Titel/Autor im EPUB vorgeben |
| `--lang` | Sprache im EPUB (Standard: aus `--ocr-language` abgeleitet, `deu`→`de`, `eng`→`en`; sonst `de`) |
| `--keep-headers` | Kolumnentitel/Seitenköpfe nicht entfernen |
| `--keep-footers` | Seitenzahlen/Seitenfüße nicht entfernen |

---

## 7. Ergebnis prüfen

1. **Überschriften auflisten.** So sieht man schnell, ob Teile und Kapitel stimmen:
   ```bash
   grep -n "^#" Output/band1.md
   ```
   Erwartet: `## Teil …` und darunter `### 1 …`, `### 2 …` usw. Ganze Sätze als Überschrift
   (endend mit `.` oder `«`) sind Erkennungsfehler, die du in Weg B korrigierst. Die Ebenen
   kommen aus der Gliederung (Lesezeichen) der PDF; ist sie flach, stehen alle Kapitel auf
   einer Ebene.
2. **Stichproben** am Anfang, in der Mitte und am Ende des Markdowns mit der PDF vergleichen:
   Fehlen Absätze, sind Absätze zusammengeklebt, stehen Bilder an der richtigen Stelle?
3. **EPUB auf dem PocketBook testen:** Inhaltsverzeichnis, Kapitelsprünge, Bilder, Cover.
4. Für Feinarbeit direkt am EPUB eignen sich **Sigil** oder der **Calibre-Editor** („Buch bearbeiten“).

---

## 8. Häufige Probleme

| Meldung / Problem | Lösung |
| :-- | :-- |
| `Tesseract-Sprachdaten fehlen: deu – installieren mit: …` | den angezeigten Befehl ausführen, z. B. `sudo apt install tesseract-ocr-deu` |
| `Tesseract nicht gefunden` | `sudo apt install tesseract-ocr tesseract-ocr-deu` |
| `pandoc nicht gefunden` | `sudo apt install pandoc` |
| Bilder fehlen im EPUB (Weg B) | pandoc im Ordner der `.md` starten (`cd Output`) bzw. `--resource-path` auf diesen Ordner setzen; der `_images`-Ordner muss daneben liegen |
| Gescannter Text fehlt, Meldung „Hinweis: … Bildseite(n)“ | die Seite wurde für ein Foto gehalten → `--ocr always` |
| Satz als Überschrift oder Kapitel ohne Überschrift | in Weg B von Hand korrigieren (Abschnitt 3) |
| Überschrift besteht nur aus einer Zahl (`## 90`, `## XX`) | meist Fußnotenzeichen oder Seitenzahl → in Weg B löschen |
| Buchstaben fehlen („Offzielle“, „treff ch“) | Ligatur (fi, fl) ohne Textzuordnung in der PDF; von Hand korrigieren |
| Überschrift gesperrt („M e i n k l e i nes Stück“) | Buchstaben einzeln gesetzt in der PDF; von Hand korrigieren |
| Link führt ins Leere oder ist abgeschnitten | URL in der PDF nachsehen und in `<…>` korrigieren; manche PDFs enthalten selbst abgeschnittene Linkziele |
| Register, Verse oder Code zu einem Absatz verklebt | Zeilen in Weg B mit `\` am Ende trennen bzw. Code in ```` ``` ```` einschließen; das Programm erkennt nur Umbrüche, bei denen das nächste Wort noch in die Zeile gepasst hätte |
| Fließtext zerfällt in einzelne Zeilen mit `\` | in Weg B die `\` am Zeilenende entfernen |
| Formeln erscheinen als Bilder | bei Mathebüchern normal; dafür ist das Programm nicht gebaut |
| Alter Scan: falsche Überschriften, viele Lesefehler | `--ocr always` (vorhandene OCR-Ebene ignorieren) |
| Auf Scans fehlen Leerzeichen („deutetin“) | OCR-Fehler; höhere Auflösung versuchen (`--ocr-dpi 400`) oder von Hand korrigieren |
| EPUB zu groß | `--image-format jpg` (Standard) verwenden; PNG ist ca. 3× größer; `--jpeg-quality 70` spart weiter |
| `--from-md`: „In index.md genannt, aber nicht vorhanden“ | Datei umbenannt oder gelöscht → Link in `index.md` anpassen |
| Meine Änderungen in der `.md` sind weg | Schritt 1 wurde erneut ausgeführt → vorher Kopie anlegen |