diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 53 |
1 files changed, 53 insertions, 0 deletions
@@ -0,0 +1,53 @@ +# epubgen + +Python EPUB 3.3 generator for making test files. It will pull paragraphs from a text file randomly to generate the content of the book. It also has a torture mode which randomly adds unusual characters to try to break parsers. + +## Usage + +```sh +python epubgen.py -m normal -c 10 -p 5 +``` + +| Option | Default | Meaning | +| ------------------ | ------------------------------ | ------------------------------------------------- | +| `-o, --out` | `normal.epub` / `torture.epub` | output path (single mode) or name prefix (`both`) | +| `-m, --mode` | `both` | `normal`, `torture`, or `both` (one of each) | +| `-c, --chapters` | `5` | number of chapters | +| `-p, --paragraphs` | `10` | paragraphs per chapter | +| `-t, --title` | `The Testing EPUB` | book title | +| `-a, --author` | `Test Author` | book author | +| `--seed N` | random | RNG seed for reproducibility | +| `--texts FILE` | `paragraphs.txt` | one paragraph per line | +| `--no-ncx` | off | omit the EPUB 2 NCX fallback | +| `-v, --version` | | print version | + +## What the generated EPUB contains + +- `mimetype` — `application/epub+zip`, STORED, first entry, no extra fields +- `META-INF/container.xml` +- `OEBPS/content.opf` — EPUB 3.3 package: `urn:uuid` identifier, title + `title-type` + refine, creator + `marc:relators` role refine, language, `dcterms:conformsTo`, + publisher, date, `dcterms:modified` (required by spec), rights; manifest items with + `properties="nav"`, `cover-image`, `svg`; NCX in the manifest for legacy readers +- `OEBPS/nav.xhtml` — `epub:type="toc"` (front matter / chapters / back matter groups) + and `epub:type="landmarks"` guide +- `OEBPS/toc.ncx` — EPUB 2 NCX fallback so old readers work +- `OEBPS/cover.xhtml` + `OEBPS/cover.png` — SVG-wrapped procedural gradient cover +- `OEBPS/title.xhtml` — title page +- `OEBPS/chapNN.xhtml` — chapters with numbered paragraphs (anchors for link testing) +- `OEBPS/index.xhtml` — back-matter index with links into chapters +- `OEBPS/colophon.xhtml` — back matter, spine `linear="no"` +- `OEBPS/style.css` — stylesheet + +## torture mode + +A technically valid EPUB with syntax designed to trip up sloppy parsers: + +- bidi override/embedding characters, combining marks, zero-width characters +- mixed RTL/LTR, CJK, emoji, private-use characters, exotic space variants +- numeric character references (`&#xNNNN;`) injected mid-text +- deeply nested `<span>`s, `<pre xml:space="preserve">`, tables, comments +- unusual-but-valid `xml:lang` (`zh-Hant-TW-u-ca-gregory`), `dir="rtl"` package +- chapter filenames with spaces and `&` (percent-encoded in every href) +- NCX with the DOCTYPE omitted and `playOrder` values out of document order +- CSS `@import`, media queries, vendor prefixes, `content` unicode escapes, `!important` |