add epubgen: python script to generate sample epub files

1 files changed, 53 insertions, 0 deletions

diff --git a/README.md b/README.md
index e69de29..8feee2f 100644
--- a/README.md
+++ b/README.md
@@ -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`