docs+test(epub): document EPUB math-to-speech (#1355) and harden its tests - #1369
Merged
Conversation
…tests Follow-up to #1355 (EPUB MathML/LaTeX -> speech). Tests: the three new epub math tests asserted exact spoken phrasing, which depends on the installed backend — they pass in CI (template fallback) but fail wherever MathCAT is installed (e.g. a full local install), which renders the same equations differently ("1 half" vs "the fraction 1 over 2"). Rewrite them to assert the stable `[Math Equation: ...]` marker and a non-empty rendering rather than any one engine's words, so they pass with or without MathCAT. Docs: document the feature across all four surfaces — - PRD §5.94 (Math in QUILL): a paragraph on EPUB extraction detecting MathML + LaTeX and reading it via speech.speak() with graceful fallback. - User guide (EPUB Navigator): equations in e-books are spoken, not skipped. - CHANGELOG (1.0.0 New) and release notes (Equations section). HTML/EPUB artifacts regenerated for the three docs under docs/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #1355 (EPUB MathML/LaTeX → speech), which I reviewed and merged.
Review finding: brittle tests (fixed here)
The three new math tests asserted exact spoken phrasing, which depends on the installed math backend. They pass in CI (which hits the template fallback) but fail wherever MathCAT is installed — e.g. a full local install renders
a²+b²=c²as "eigh squared plus b squared, is equal to c squared" and½as "1 half", not the template's "…equals…" / "the fraction 1 over 2". This PR rewrites them to assert the stable[Math Equation: …]marker and a non-empty rendering (via a small_math_equationshelper), so they pass with or without MathCAT and don't pin to one engine's words. Verified locally (MathCAT present) and structurally CI-safe.The feature code itself is sound — correct MathCAT→template→raw fallback, lazy imports, no impact on non-math books — so it stands as merged.
Documentation (all four surfaces)
speech.speak()with graceful fallback.HTML/EPUB regenerated for the three docs under
docs/; parity gate passes; the epub tests pass locally and lint is clean.🤖 Generated with Claude Code