From d3178c7852f45cd71f0c597efed30acc761a4868 Mon Sep 17 00:00:00 2001 From: jpirnay Date: Thu, 26 Feb 2026 07:36:36 +0100 Subject: [PATCH] Doc update --- docs/contributing/koreader-sync-xpath-mapping.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/contributing/koreader-sync-xpath-mapping.md b/docs/contributing/koreader-sync-xpath-mapping.md index 570b2861..9df844c8 100644 --- a/docs/contributing/koreader-sync-xpath-mapping.md +++ b/docs/contributing/koreader-sync-xpath-mapping.md @@ -40,6 +40,8 @@ Implemented in `ProgressMapper::toCrossPoint`. The module reparses **one spine XHTML** on demand using Expat and builds temporary anchors: +Source-of-truth note: XPath anchors are built from the original EPUB spine XHTML bytes (zip item contents), not from CrossPoint's distilled section render cache. This is intentional to preserve KOReader XPath compatibility. + - anchor: `` - `textOffset` counts non-whitespace bytes @@ -63,6 +65,7 @@ The implementation intentionally avoids full DOM storage. ## Known Limitations - Page number on reverse mapping is still an estimate (renderer differences). +- XPath mapping intentionally uses original spine XHTML while pagination comes from distilled renderer output, so minor roundtrip page drift is expected. - Image-only/low-text chapters may yield coarse anchors. - Extremely malformed XHTML can force fallback behavior. @@ -74,10 +77,3 @@ The implementation intentionally avoids full DOM storage. - `percentage` when fallback path was used It also logs exactness (`exact=yes/no`) for XPath matches. - -## Validation - -Use test vectors in: - -- `test/koreader_sync/roundtrip_vectors.md` -- `test/koreader_sync/memory_resource_qa.md`