619421ef10
- load_link_uris: Linkziele aus den Link-Annotationen der PDF lesen - link_urls: URLs als Autolink <https://…> schreiben; beim Zeilenumbruch zerbrochene URLs mit den Linkzielen abgleichen (tolerant gegenüber Bindestrichen, Leerraum, "/" am Ende, Abfrageteil, .html) und utm-Parameter entfernen; ohne Linkziel aus dem gedruckten Text zusammensetzen - Bindestrich am Zeilenende innerhalb einer URL bleibt erhalten - pandoc liest mit +autolink_bare_uris - Tests, README, Bedienungsanleitung und TODO ergänzt Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# 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:
|
||
|
||
```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) |
|
||
|
||
Ein Band mit ca. 700 Seiten dauert etwa anderthalb Minuten.
|
||
|
||
---
|
||
|
||
## 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 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):
|
||
|
||
```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
|
||
|
||
Im Ordner der Markdown-Datei starten (wichtig für die Bilder):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```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) |
|
||
| schneller auf vielen Kernen | `--jobs 8` (Standard 4) |
|
||
| OCR erzwingen, auch für vorhandene OCR-Ebenen | `--ocr always` |
|
||
| englisches Buch | `--ocr-language eng --lang en` (Sprachpaket `tesseract-ocr-eng` nötig) |
|
||
| 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 4) |
|
||
| `--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 `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:
|
||
```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“).
|
||
|
||
---
|
||
|
||
## 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 |
|