From 1eaf6a9d883a47444d0d68f4ab88bfba62c321d0 Mon Sep 17 00:00:00 2001 From: "Simen A. W. Olsen" Date: Thu, 28 May 2026 23:27:10 +0200 Subject: feat: add ziglang-docs-epub tool --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..0a5ea18 --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# ziglang-docs-epub + +Turns the [Zig language reference](https://ziglang.org/documentation/) into an +**EPUB**, one per Zig version. CI runs it on a schedule and commits the resulting +`.epub` files back into [`epubs/`](epubs/). + +## Why + +The reference ships as a single self-contained HTML page. This tool repackages it +as a standards-compliant EPUB3 so you can read it offline in any e-reader. + +## How it works + +Four decoupled concerns, each a small module that does one thing: + +| Module | Responsibility | +| ------------- | --------------------------------------------------------- | +| `index.zig` | discover versions + docs URLs from `download/index.json` | +| `fetch.zig` | HTTP GET via `std.http.Client` | +| `html.zig` | transform the page HTML5 → well-formed XHTML5 | +| `epub.zig` | assemble the EPUB3 container | +| `zip.zig` | minimal, reproducible ZIP writer (stored entries) | + +No external runtime dependencies — Zig's standard library provides HTTP and +CRC32. EPUB entries are stored uncompressed (Zig 0.15.2's std deflate +*compressor* is unfinished), which keeps the writer trivial and fully +spec-compliant at the cost of larger files. Output is **byte-for-byte +reproducible** (fixed ZIP timestamps), so CI only commits when the upstream docs +actually change. + +## Usage + +Requires **Zig 0.15.2**. + +```sh +zig build run # build every version that has docs +zig build run -- 0.15.2 # build only specific version(s) +zig build test # run unit tests +``` + +EPUBs land in `epubs/zig-.epub`. + +## Continuous integration + +`.forgejo/workflows/build-epubs.yml` runs on [Codeberg](https://codeberg.org) +(Forgejo Actions): daily, on push to `main`, and on manual dispatch. It installs +Zig, runs the tool, and commits any changed EPUBs with `[skip ci]`. + +## License + +Licensed under the [Apache License 2.0](LICENSE). + -- cgit v1.2.3