Илья Поляков
112 lines
5.1 KiB
Markdown
112 lines
5.1 KiB
Markdown
---
|
|
name: pdf-to-kindle
|
|
description: Convert a text-layer PDF (usually one generated by calibre from an ebook) into EPUB/AZW3 for Kindle while preserving italics, bold, chapter headings, sidebars/journal blocks, images and cross-page paragraphs. Use when the user asks to read a PDF book on Kindle or another e-reader, to convert a PDF to EPUB/AZW3/MOBI, or complains that a converted book lost its italics, merged its chapters, or reflows badly on the device. Not for scanned PDFs (no text layer) — those need OCR first.
|
|
---
|
|
|
|
# PDF to Kindle
|
|
|
|
`ebook-convert book.pdf book.epub` silently destroys formatting: poppler infers
|
|
style from font names and misses abbreviated ones like `MinionPro-It`, and
|
|
calibre labels body text as `<h2>` when the most common font is not the body
|
|
font. Measured on a 399-page novel: 435 italic runs in the PDF became 1 `<i>`
|
|
tag, and 2817 body paragraphs became `<h2>`.
|
|
|
|
`scripts/pdf2html.py` extracts spans with PyMuPDF, where style comes from span
|
|
properties, and emits semantic XHTML. calibre is then used only as the
|
|
XHTML→EPUB packer.
|
|
|
|
## Workflow
|
|
|
|
1. **Verify a text layer exists.** `pdfinfo` and `pdffonts` on the file. No
|
|
embedded fonts / no extractable text means a scan — stop and say OCR is
|
|
needed; this skill does not apply.
|
|
2. **Check tooling.** `ebook-convert` must be on PATH. For PyMuPDF, prefer an
|
|
existing interpreter that has it; otherwise build a throwaway venv in the
|
|
scratchpad — do not install into the system Python:
|
|
|
|
```bash
|
|
python3 -m venv "$SCRATCH/venv" && "$SCRATCH/venv/bin/pip" -q install pymupdf
|
|
```
|
|
|
|
3. **Profile the fonts** before converting anything:
|
|
|
|
`python scripts/pdf2html.py --fonts book.pdf`
|
|
|
|
Read off: the body font (largest character count), the italic variant, the
|
|
heading sizes, and any secondary family used for sidebars, journal entries,
|
|
chat logs or slides.
|
|
4. **Tune the thresholds** in `block_kind()` and `style()` to that output. The
|
|
defaults target a 15pt/letter calibre layout: `>= 28` or a display font is a
|
|
title, `>= 24` a chapter/part `h1`, `>= 17` an `h2` subtitle, a secondary
|
|
family is `p.note`. `INDENT_X` (default 88) is the x-coordinate that
|
|
separates an indented first line from a continuation line — verify it
|
|
against the real `x0` values, not by assumption.
|
|
5. **Convert to XHTML:**
|
|
|
|
`python scripts/pdf2html.py book.pdf out/book.html`
|
|
|
|
6. **Verify before packing** (see Verification). Fix thresholds and re-run until
|
|
the counts are sane. Cheap to iterate; do not skip to packing.
|
|
7. **Pack with calibre**, always passing explicit TOC XPaths — without them
|
|
calibre applies its own heuristics and re-breaks the chapters:
|
|
|
|
```bash
|
|
ebook-convert out/book.html "Title.epub" \
|
|
--title="Title" --authors="Author" --language=en \
|
|
--cover=out/images/cover.jpg \
|
|
--level1-toc='//h:h1' --level2-toc='//h:h2' \
|
|
--page-breaks-before='//h:h1' \
|
|
--no-default-epub-cover
|
|
ebook-convert "Title.epub" "Title.azw3"
|
|
```
|
|
|
|
Take title/author from the user or the book's own title page — PDF metadata
|
|
is often an ASIN or a filename.
|
|
8. **Deliver both files** and say what each is for: `.epub` for Send to Kindle
|
|
(Amazon converts server-side), `.azw3` for USB copy into `documents/`.
|
|
Delete intermediate artifacts left in the user's directories.
|
|
|
|
## Verification
|
|
|
|
Never report success on the converter's own summary line alone. Check:
|
|
|
|
```bash
|
|
python3 - <<'EOF'
|
|
import re
|
|
t = open('out/book.html').read()
|
|
print('italic:', t.count('<i>'), 'bold:', t.count('<b>'))
|
|
print('h1:', len(re.findall(r'<h1', t)))
|
|
print('double spaces:', re.sub('<[^>]+>', '', t).count(' '))
|
|
EOF
|
|
```
|
|
|
|
- italic count near zero on a novel means `style()` missed the font-name pattern;
|
|
- an `h1` count in the hundreds means a size threshold is too low and body text
|
|
is being promoted;
|
|
- many double spaces means line joining is off;
|
|
- list the extracted headings (`grep -o '<h1[^>]*>.\{0,60\}'`) and read them —
|
|
they become the TOC, and a wrong one is obvious at a glance;
|
|
- read one full page of body text and confirm paragraphs merge across page
|
|
breaks and hyphenated words are rejoined.
|
|
|
|
After packing, confirm the EPUB: `ebook-meta` for metadata, and the `.ncx`
|
|
navPoint count for the TOC size.
|
|
|
|
## What the script does
|
|
|
|
- style from span font names (`-It`, `Italic`, `Bold`, `Semibold`) → `<i>`/`<b>`;
|
|
- headings by font size, sidebars by font family;
|
|
- one PDF block = one paragraph; an unindented block that opens a page is
|
|
appended to the previous page's paragraph;
|
|
- trailing hyphens dropped, adjacent `</i><i>` runs merged, doubled spaces collapsed;
|
|
- images written to `images/`, cover rendered from page 1 at 150 dpi;
|
|
- absolute positioning is deliberately discarded so text reflows at any font size.
|
|
|
|
## Limits
|
|
|
|
- Headers/footers are not stripped — calibre-made PDFs have none. A typeset PDF
|
|
with running heads and page numbers needs blocks filtered by `y` coordinate
|
|
near the margins; add that before trusting the output.
|
|
- Multi-column layouts are not handled; block order would need column sorting.
|
|
- Thresholds are per-layout constants. Always re-run `--fonts` for a new book.
|