Publish The Body That Asks EPUB reader
This commit is contained in:
parent
620f9dbba9
commit
d6a4186076
9 changed files with 183 additions and 59 deletions
18
scripts/fiction/README.md
Normal file
18
scripts/fiction/README.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Fiction EPUB Builder
|
||||
|
||||
`build_epub.py` is the single EPUB packaging and validation path for Aetheria fiction. It derives the title, movements, chapter order, navigation, and spine from the promoted manuscript while taking the output path and stable public identifier explicitly.
|
||||
|
||||
It accepts both live manuscript heading schemes:
|
||||
|
||||
- `# Title`, `## Movement`, `### Chapter`
|
||||
- `# Title`, `# Movement`, `## Chapter`
|
||||
|
||||
Build the published books from the repository root:
|
||||
|
||||
```powershell
|
||||
python scripts/fiction/build_epub.py --source "Aetheria/Fiction/The Burden of Proof.md" --output "Aetheria/static/fiction/the-burden-of-proof.epub" --identifier-url "https://aetheria.gamecult.org/Fiction/The-Burden-of-Proof" --expected-chapters 28 --expected-title "The Burden of Proof"
|
||||
|
||||
python scripts/fiction/build_epub.py --source "Aetheria/Fiction/The Body That Asks.md" --output "Aetheria/static/fiction/the-body-that-asks.epub" --identifier-url "https://aetheria.gamecult.org/Fiction/The-Body-That-Asks" --expected-chapters 28 --expected-title "The Body That Asks"
|
||||
```
|
||||
|
||||
Use the same arguments with `--check` to validate an existing artifact without rebuilding it. Set `SOURCE_DATE_EPOCH` when byte-for-byte reproducibility across filesystems is required.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Build and validate The Burden of Proof as a deterministic EPUB 3 archive."""
|
||||
"""Build and validate an Aetheria fiction manuscript as a deterministic EPUB 3 archive."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
|
@ -15,14 +15,9 @@ from pathlib import Path
|
|||
from xml.etree import ElementTree
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
DEFAULT_SOURCE = ROOT / "Aetheria" / "Fiction" / "The Burden of Proof.md"
|
||||
DEFAULT_OUTPUT = ROOT / "Aetheria" / "static" / "fiction" / "the-burden-of-proof.epub"
|
||||
BOOK_ID = f"urn:uuid:{uuid.uuid5(uuid.NAMESPACE_URL, 'https://aetheria.gamecult.org/Fiction/The-Burden-of-Proof')}"
|
||||
|
||||
|
||||
@dataclass
|
||||
class Chapter:
|
||||
number: int
|
||||
title: str
|
||||
movement: str
|
||||
blocks: list[str]
|
||||
|
|
@ -53,17 +48,42 @@ def parse_manuscript(source: Path) -> tuple[str, list[Chapter]]:
|
|||
|
||||
title = lines[0][2:].strip()
|
||||
movement = ""
|
||||
movement_level: int | None = None
|
||||
heading_schema: tuple[int, int] | None = None
|
||||
chapters: list[Chapter] = []
|
||||
current: Chapter | None = None
|
||||
|
||||
for line in lines[1:]:
|
||||
if line.startswith("## "):
|
||||
movement = line[3:].strip()
|
||||
elif line.startswith("### "):
|
||||
current = Chapter(line[4:].strip(), movement, [])
|
||||
heading = re.fullmatch(r"(#{1,3})\s+(.+?)\s*", line)
|
||||
if heading and re.match(r"Movement\s+", heading.group(2), re.IGNORECASE):
|
||||
level = len(heading.group(1))
|
||||
if heading_schema is not None and level != heading_schema[0]:
|
||||
raise ValueError("Movement heading level changes within the manuscript")
|
||||
movement = heading.group(2)
|
||||
movement_level = level
|
||||
current = None
|
||||
elif heading and (chapter_match := re.match(r"Chapter\s+(\d+)\b", heading.group(2), re.IGNORECASE)):
|
||||
number = int(chapter_match.group(1))
|
||||
expected = len(chapters) + 1
|
||||
if number != expected:
|
||||
raise ValueError(f"Expected Chapter {expected}, found Chapter {number}")
|
||||
if not movement:
|
||||
raise ValueError(f"Chapter {number} has no movement")
|
||||
schema = (movement_level, len(heading.group(1)))
|
||||
if schema not in {(1, 2), (2, 3)}:
|
||||
raise ValueError("Use H1 movements with H2 chapters, or H2 movements with H3 chapters")
|
||||
if heading_schema is None:
|
||||
heading_schema = schema
|
||||
elif schema != heading_schema:
|
||||
raise ValueError("Movement and chapter heading levels must remain consistent")
|
||||
current = Chapter(number, heading.group(2), movement, [])
|
||||
chapters.append(current)
|
||||
elif heading:
|
||||
raise ValueError(f"Unsupported heading after title: {line}")
|
||||
elif current is not None and line.strip():
|
||||
current.blocks.append(line.strip())
|
||||
elif line.strip():
|
||||
raise ValueError(f"Prose appears before the first chapter: {line}")
|
||||
|
||||
if not chapters or any(not chapter.blocks for chapter in chapters):
|
||||
raise ValueError("Every chapter must contain prose")
|
||||
|
|
@ -82,6 +102,9 @@ def xhtml_page(title: str, body: str, body_class: str = "") -> str:
|
|||
def chapter_xhtml(chapter: Chapter) -> str:
|
||||
paragraphs = []
|
||||
for block in chapter.blocks:
|
||||
if block in {"***", "* * *", "---", "_ _ _"}:
|
||||
paragraphs.append('<hr class="scene-break"/>')
|
||||
continue
|
||||
rendered = inline_markup(block)
|
||||
css_class = " class=\"pov\"" if re.fullmatch(r"<strong>[^<]+</strong>", rendered) else ""
|
||||
paragraphs.append(f"<p{css_class}>{rendered}</p>")
|
||||
|
|
@ -97,8 +120,41 @@ def modified_timestamp(source: Path) -> str:
|
|||
return datetime.fromtimestamp(epoch, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
def build(source: Path, output: Path) -> None:
|
||||
def archive_timestamp(source: Path) -> tuple[int, int, int, int, int, int]:
|
||||
epoch = int(os.environ.get("SOURCE_DATE_EPOCH", source.stat().st_mtime))
|
||||
value = datetime.fromtimestamp(epoch, timezone.utc)
|
||||
if value.year < 1980:
|
||||
value = datetime(1980, 1, 1, tzinfo=timezone.utc)
|
||||
return value.year, value.month, value.day, value.hour, value.minute, value.second
|
||||
|
||||
|
||||
def write_entry(
|
||||
archive: zipfile.ZipFile,
|
||||
name: str,
|
||||
data: str,
|
||||
timestamp: tuple[int, int, int, int, int, int],
|
||||
compress_type: int = zipfile.ZIP_DEFLATED,
|
||||
) -> None:
|
||||
info = zipfile.ZipInfo(name, date_time=timestamp)
|
||||
info.compress_type = compress_type
|
||||
info.create_system = 3
|
||||
info.external_attr = 0o644 << 16
|
||||
archive.writestr(info, data)
|
||||
|
||||
|
||||
def build(
|
||||
source: Path,
|
||||
output: Path,
|
||||
identifier_url: str,
|
||||
expected_chapters: int | None = None,
|
||||
expected_title: str | None = None,
|
||||
) -> None:
|
||||
title, chapters = parse_manuscript(source)
|
||||
if expected_title is not None and title != expected_title:
|
||||
raise ValueError(f"Expected title {expected_title!r}, found {title!r}")
|
||||
if expected_chapters is not None and len(chapters) != expected_chapters:
|
||||
raise ValueError(f"Expected {expected_chapters} chapters, found {len(chapters)}")
|
||||
book_id = f"urn:uuid:{uuid.uuid5(uuid.NAMESPACE_URL, identifier_url)}"
|
||||
output.parent.mkdir(parents=True, exist_ok=True)
|
||||
chapter_items = "\n".join(
|
||||
f'<item id="chapter-{i}" href="text/chapter-{i:02}.xhtml" media-type="application/xhtml+xml"/>'
|
||||
|
|
@ -115,32 +171,33 @@ def build(source: Path, output: Path) -> None:
|
|||
)
|
||||
package = f'''<?xml version="1.0" encoding="utf-8"?>
|
||||
<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="book-id" xml:lang="en-GB">
|
||||
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:identifier id="book-id">{BOOK_ID}</dc:identifier><dc:title>{html.escape(title)}</dc:title><dc:creator>GameCult</dc:creator><dc:language>en-GB</dc:language><meta property="dcterms:modified">{modified_timestamp(source)}</meta></metadata>
|
||||
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:identifier id="book-id">{book_id}</dc:identifier><dc:title>{html.escape(title)}</dc:title><dc:creator>GameCult</dc:creator><dc:language>en-GB</dc:language><meta property="dcterms:modified">{modified_timestamp(source)}</meta></metadata>
|
||||
<manifest><item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/><item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/><item id="css" href="styles/book.css" media-type="text/css"/><item id="title" href="text/title.xhtml" media-type="application/xhtml+xml"/>{chapter_items}</manifest>
|
||||
<spine toc="ncx"><itemref idref="title"/>{spine}</spine>
|
||||
</package>'''
|
||||
nav = f'''<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en-GB"><head><meta charset="utf-8"/><title>Contents</title></head><body><nav epub:type="toc"><h1>Contents</h1><ol>{nav_points}</ol></nav></body></html>'''
|
||||
ncx = f'''<?xml version="1.0" encoding="utf-8"?>
|
||||
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1"><head><meta name="dtb:uid" content="{BOOK_ID}"/></head><docTitle><text>{html.escape(title)}</text></docTitle><navMap>{ncx_points}</navMap></ncx>'''
|
||||
title_page = xhtml_page(title, f'<main class="title-page"><h1>{html.escape(title)}</h1><p>A novella set in Aetheria</p><p class="author">GameCult</p></main>', "title")
|
||||
css = """body{font-family:Georgia,serif;line-height:1.62;margin:5%;color:#18191b;background:#faf8f3}h1{line-height:1.15}p{margin:0 0 .85em}.movement{text-transform:uppercase;letter-spacing:.08em;font:700 .72em system-ui,sans-serif;color:#666}.pov{margin:1.25em 0 1.5em;font-family:system-ui,sans-serif}.title-page{text-align:center;margin-top:30vh}.title-page h1{font-size:2.4em}.author{margin-top:3em}code{font-family:monospace;font-size:.9em}@media(prefers-color-scheme:dark){body{color:#e9e7e1;background:#18191b}.movement{color:#aaa}}"""
|
||||
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1"><head><meta name="dtb:uid" content="{book_id}"/></head><docTitle><text>{html.escape(title)}</text></docTitle><navMap>{ncx_points}</navMap></ncx>'''
|
||||
title_page = xhtml_page(title, f'<main class="title-page"><h1>{html.escape(title)}</h1><p>A story set in Aetheria</p><p class="author">GameCult</p></main>', "title")
|
||||
css = """body{font-family:Georgia,serif;line-height:1.62;margin:5%;color:#18191b;background:#faf8f3}h1{line-height:1.15}p{margin:0 0 .85em}.movement{text-transform:uppercase;letter-spacing:.08em;font:700 .72em system-ui,sans-serif;color:#666}.pov{margin:1.25em 0 1.5em;font-family:system-ui,sans-serif}.scene-break{border:0;text-align:center;margin:1.75em 0}.scene-break::after{content:"* * *";letter-spacing:.6em}.title-page{text-align:center;margin-top:30vh}.title-page h1{font-size:2.4em}.author{margin-top:3em}code{font-family:monospace;font-size:.9em}@media(prefers-color-scheme:dark){body{color:#e9e7e1;background:#18191b}.movement{color:#aaa}}"""
|
||||
container = '''<?xml version="1.0" encoding="utf-8"?><container xmlns="urn:oasis:names:tc:opendocument:xmlns:container" version="1.0"><rootfiles><rootfile full-path="EPUB/package.opf" media-type="application/oebps-package+xml"/></rootfiles></container>'''
|
||||
|
||||
timestamp = archive_timestamp(source)
|
||||
with zipfile.ZipFile(output, "w") as archive:
|
||||
archive.writestr("mimetype", "application/epub+zip", compress_type=zipfile.ZIP_STORED)
|
||||
archive.writestr("META-INF/container.xml", container)
|
||||
archive.writestr("EPUB/package.opf", package)
|
||||
archive.writestr("EPUB/nav.xhtml", nav)
|
||||
archive.writestr("EPUB/toc.ncx", ncx)
|
||||
archive.writestr("EPUB/styles/book.css", css)
|
||||
archive.writestr("EPUB/text/title.xhtml", title_page)
|
||||
write_entry(archive, "mimetype", "application/epub+zip", timestamp, zipfile.ZIP_STORED)
|
||||
write_entry(archive, "META-INF/container.xml", container, timestamp)
|
||||
write_entry(archive, "EPUB/package.opf", package, timestamp)
|
||||
write_entry(archive, "EPUB/nav.xhtml", nav, timestamp)
|
||||
write_entry(archive, "EPUB/toc.ncx", ncx, timestamp)
|
||||
write_entry(archive, "EPUB/styles/book.css", css, timestamp)
|
||||
write_entry(archive, "EPUB/text/title.xhtml", title_page, timestamp)
|
||||
for i, chapter in enumerate(chapters, 1):
|
||||
archive.writestr(f"EPUB/text/chapter-{i:02}.xhtml", chapter_xhtml(chapter))
|
||||
validate(output, len(chapters))
|
||||
write_entry(archive, f"EPUB/text/chapter-{i:02}.xhtml", chapter_xhtml(chapter), timestamp)
|
||||
validate(output, len(chapters), title)
|
||||
|
||||
|
||||
def validate(epub: Path, expected_chapters: int | None = None) -> None:
|
||||
def validate(epub: Path, expected_chapters: int | None = None, expected_title: str | None = None) -> None:
|
||||
with zipfile.ZipFile(epub) as archive:
|
||||
entries = archive.infolist()
|
||||
if not entries or entries[0].filename != "mimetype" or entries[0].compress_type != zipfile.ZIP_STORED:
|
||||
|
|
@ -151,20 +208,42 @@ def validate(epub: Path, expected_chapters: int | None = None) -> None:
|
|||
for name in xml_entries:
|
||||
ElementTree.fromstring(archive.read(name))
|
||||
chapters = [name for name in archive.namelist() if re.fullmatch(r"EPUB/text/chapter-\d+\.xhtml", name)]
|
||||
expected_names = [f"EPUB/text/chapter-{i:02}.xhtml" for i in range(1, len(chapters) + 1)]
|
||||
if chapters != expected_names:
|
||||
raise ValueError("Chapter files must be sequential and ordered")
|
||||
if expected_chapters is not None and len(chapters) != expected_chapters:
|
||||
raise ValueError(f"Expected {expected_chapters} chapters, found {len(chapters)}")
|
||||
package = ElementTree.fromstring(archive.read("EPUB/package.opf"))
|
||||
title = package.find(".//{http://purl.org/dc/elements/1.1/}title")
|
||||
actual_title = None if title is None else title.text
|
||||
if expected_title is not None and actual_title != expected_title:
|
||||
raise ValueError(f"Expected title {expected_title!r}, found {actual_title!r}")
|
||||
spine_items = package.findall(".//{http://www.idpf.org/2007/opf}spine/{http://www.idpf.org/2007/opf}itemref")
|
||||
if len(spine_items) != len(chapters) + 1:
|
||||
raise ValueError("Spine must contain the title page and every chapter")
|
||||
nav = ElementTree.fromstring(archive.read("EPUB/nav.xhtml"))
|
||||
nav_items = nav.findall(".//{http://www.w3.org/1999/xhtml}li")
|
||||
if len(nav_items) != len(chapters):
|
||||
raise ValueError("Navigation must contain every chapter")
|
||||
ncx = ElementTree.fromstring(archive.read("EPUB/toc.ncx"))
|
||||
ncx_items = ncx.findall(".//{http://www.daisy.org/z3986/2005/ncx/}navPoint")
|
||||
if len(ncx_items) != len(chapters):
|
||||
raise ValueError("NCX must contain every chapter")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--source", type=Path, default=DEFAULT_SOURCE)
|
||||
parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
|
||||
parser.add_argument("--source", type=Path, required=True)
|
||||
parser.add_argument("--output", type=Path, required=True)
|
||||
parser.add_argument("--identifier-url", required=True)
|
||||
parser.add_argument("--expected-chapters", type=int)
|
||||
parser.add_argument("--expected-title")
|
||||
parser.add_argument("--check", action="store_true", help="Validate the existing output without rebuilding")
|
||||
args = parser.parse_args()
|
||||
if args.check:
|
||||
validate(args.output)
|
||||
validate(args.output, args.expected_chapters, args.expected_title)
|
||||
else:
|
||||
build(args.source, args.output)
|
||||
build(args.source, args.output, args.identifier_url, args.expected_chapters, args.expected_title)
|
||||
print(args.output)
|
||||
|
||||
|
||||
Loading…
Reference in a new issue