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, jedes Kapitel oder jeder Seitenbereich 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
git clone https://kitux.de/forgejo/dschlueter/pdf2md.git
cd pdf2md   # Ordner des Repos
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.
- `pix2text` braucht man nur für `--formulas` (Mathebücher, siehe Abschnitt 6):
  `pip install "pix2text[multilingual]"`.

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 pdf2md   # Ordner des Repos
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 pdf2md   # Ordner des Repos
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 |
| Sonderzeichen wörtlich | `\*`, `\_`, `\[`, `\<`, `\$` … (so erzeugt das Programm sie auch) | Zeichen erscheint wie geschrieben, ohne Formatierung |
| 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 pdf2md   # Ordner des Repos
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, Kapitel oder Seitenbereiche als Einzeldateien

```bash
cd pdf2md   # Ordner des Repos
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
  source_pages: [40, 43]        # Seiten der PDF-Datei (nicht die gedruckten Seitenzahlen)
  book: "Operation Ljutsch"
  author: "Reinhard Otto Kranz"
  ---
  ```
- Erkennt das Programm keine Gliederung, teilt es nach Länge (ca. 30 000 Zeichen, an
  Absatzgrenzen; ändern mit `--split-chars N`) in `Abschnitt 1`, `Abschnitt 2` … und meldet das.
- Anhang, „Der Autor“, Impressum usw. nach dem letzten Kapitel landen in `nn_nachspann.md`,
  sofern sie keine eigene Kapitelüberschrift haben.
- **Nach Seiten der PDF** (für Bücher ohne Kapitel):
  ```bash
  python3 pdf2md.py --split seiten --pages-per-file 25 buch.pdf Output/buch.md
  python3 pdf2md.py --split seiten --page-ranges 1-12,13-40,41- buch.pdf Output/buch.md
  ```
  Es geht kein Text verloren: Geschnitten wird vor dem ersten Absatz, der auf der Grenzseite
  beginnt. Ein Absatz, der über die Seitengrenze läuft, bleibt ganz in der vorigen Datei;
  eine Überschrift direkt vor dem Schnitt kommt in die neue Datei. Mit `--pages-per-file`
  wird bevorzugt an einer Überschrift geschnitten, die höchstens eine Seite neben der Grenze
  liegt; `--page-ranges` hält sich streng an die Seiten (Seiten außerhalb der Bereiche werden
  eigene Dateien). `source_pages` kann sich deshalb um eine Seite überlappen.
- **Ein EPUB je Datei:** `--epub-per-file` legt in `Output/band1/epub/` für jede Datei ein
  EPUB an („Buchtitel - Kapiteltitel“, mit Cover). Das Gesamt-EPUB entsteht nur mit `--epub`.
- **Bearbeitetes Markdown nachträglich teilen:**
  `python3 pdf2md.py --from-md Output/band1.md --split kapitel` → Ordner `Output/band1/`
  (Bildpfade werden angepasst; `--split seiten` geht hier nicht, dafür braucht es die PDF).
- **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` (alte Ebene wird verworfen) |
| Gedichtband, Liederbuch | zusätzlich `--keep-lines` (siehe unten) |
| Fraktur | `--ocr-language deu_latf` (Modell nachladen, siehe unten) oder `frk+deu` (Paket `tesseract-ocr-frk`, schwächer) |
| 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; die alte Ebene wird dabei verworfen.
- **Rauschen vom Scanrand** (Buchstabenfetzen neben dem Textbereich) wird entfernt.

- **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“.

**Gedichtbände und Liederbücher:** Füllen die Verse die Zeile fast, kann das Programm sie nicht
von Fließtext unterscheiden und fügt sie zusammen. Mit `--keep-lines` bleibt jede Zeile eine
Zeile, Strophen werden durch Leerzeilen getrennt, Einrückungen bleiben; nichts wird
zusammengefügt, auch keine Silbentrennung. Gescannte Seiten liest das Programm dann direkt aus
Tesseract (ohne Layout-Analyse, die bei Gedichten Zeilen verdoppelt oder verschränkt);
Gedichttitel kommen aus der PDF-Gliederung – in richtiger Schreibweise statt OCR-Lesart.

```bash
python3 pdf2md.py --epub --ocr always --keep-lines Neue_Gedichte_-_Rainer_Maria_Rilke.pdf Output/Neue_Gedichte_-_Rainer_Maria_Rilke.md
```

**Fraktur:** Das Modell `frk` aus dem Ubuntu-Paket ist alt und verwechselt oft ſ/f/k/l
(„ftarf“ statt „ſtark“). Deutlich besser liest das Modell `deu_latf` aus tessdata_best:

```bash
sudo wget -P /usr/share/tesseract-ocr/5/tessdata https://github.com/tesseract-ocr/tessdata_best/raw/main/deu_latf.traineddata
python3 pdf2md.py --epub --ocr-language deu_latf --keep-lines gedichte.pdf Output/gedichte.md
```

Das lange s bleibt als „ſ“ erhalten. Auch mit `deu_latf` bleiben Lesefehler; alte Scans muss
man nacharbeiten (Weg B).

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); Formeln `$…$`/`$$…$$` werden MathML |
| `--formulas` | Mathebücher: jede Formel auf der Seite finden, auch im Fließtext und in Merkkästen, und als Bild ausschneiden; Liste `formulas-*.json` für formula_img2latex (schaltet `--images` ein, braucht pix2text) |
| `--epub-file PFAD` | anderer Pfad für das EPUB |
| `--split teile\|kapitel\|seiten` | Teile, Kapitel oder Seitenbereiche als Einzeldateien (Abschnitt 4) |
| `--pages-per-file N`, `--page-ranges BEREICHE` | Seiten je Datei bzw. feste Bereiche für `--split seiten` |
| `--split-chars N` | Länge der Abschnitte, wenn keine Gliederung erkannt wird (Standard 30 000) |
| `--epub-per-file` | mit `--split`: ein EPUB je Einzeldatei |
| `--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-lines` | jede Zeile der PDF bleibt eine Zeile (Gedichte, Liedtexte); nichts wird zusammengefügt |
| `--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`) | wird normalerweise automatisch entfernt; bleibt sie, weil direkt eine Überschrift folgt, 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 oder als Zeichensalat (`x4n`) | `--formulas` verwenden und die Formeln danach mit formula_img2latex in LaTeX übersetzen; anschließend `--from-md` baut das EPUB mit MathML |
| Alter Scan: falsche Überschriften, viele Lesefehler | `--ocr always` (vorhandene OCR-Ebene ignorieren) |
| Gedicht wird zu Fließtext (Verse zusammengefügt) | `--keep-lines` |
| 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 |