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.

---

1. Installation und Prüfung

Einmalig unter Ubuntu 24.04:

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:

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

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:

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

Wenn du kein Cover und kein Probe-EPUB brauchst, reicht --images statt --epub.

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
Bild	 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):

## Er ging nach Hause.

**4 Flucht aufs Land**

Am nächsten Morgen ...

Nachher:

Er ging nach Hause.

### 4 Flucht aufs Land

Am nächsten Morgen ...

Schritt 3: EPUB aus dem bearbeiteten Markdown erzeugen

Im Ordner der Markdown-Datei starten (wichtig für die Bilder):

cd ~/Downloads/ljutsch/Output
pandoc band1.md \
  --from markdown-yaml_metadata_block+autolink_bare_uris --to epub3 \
  --output band1.epub \
  --resource-path . \
  --split-level=3 --toc-depth=3 \
  --metadata title="Operation Ljutsch" \
  --metadata author="Reinhard Otto Kranz" \
  --metadata lang=de \
  --epub-cover-image band1_images/cover.jpg

Das sind dieselben Einstellungen, die pdf2md.py --epub verwendet. Titel und Autor trägst du selbst ein. Ohne Cover lässt du die letzte Zeile weg und entfernst den \ am Ende der Zeile davor.

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. Gescannte PDFs

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

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.

---

5. Alle Optionen

Option	Bedeutung
pdf	Eingabe-PDF
markdown	Ausgabe-Datei; ohne Angabe: gleicher Name wie die PDF mit .md
--ocr auto|always|never	OCR-Entscheidung (Standard auto, siehe Abschnitt 4)
--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)
--epub	zusätzlich EPUB erzeugen (schaltet --images ein)
--epub-file PFAD	anderer Pfad für das EPUB
--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

---

6. Ergebnis prüfen

1. Überschriften auflisten. So sieht man schnell, ob Teile und Kapitel stimmen:

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

---

7. 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
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
Meine Änderungen in der .md sind weg	Schritt 1 wurde erneut ausgeführt → vorher Kopie anlegen