Validate text fragment locators (#:~:text=) in media overlay text src

[richwaters]

As discussed in this issue from the EPUB spec: w3c/epub-specs#2934, text fragments are both valid and useful as values for the src attribute in media overlays. Given that, epubcheck should validate these when they are encountered in place of a fragment identifier.

Currently (as discussed at #1248) epubcheck warns with MED_017 - "URL fragment should indicate an element ID" for these locators. This issue proposes that #:~:text= locators be validated explicitly rather than treated like other non-ID fragments. Specifically, the locator should be validated to ensure that it is well-formed and resolves to a single location in the target document.

References:

• W3C Text Fragments spec: https://wicg.github.io/scroll-to-text-fragment/
• UAX 29 (word boundaries): https://unicode.org/reports/tr29/
• EPUB spec issue: Authoring Media Overlay with text fragments instead of an ID epub-specs#2934

[richwaters]

One issue I've encountered centers around block boundaries. The spec restricts where they can be crossed, but the exact definition of a 'block' element is based on the rendered CSS and not the DOM. For the purposes of epubcheck (and EPUB producers) a DOM-based approach seems reasonable.

Additionally, it is unclear how <br/> should be treated. Browsers treat it like a block element, but that might not be the best approach for EPUBs as it reduces valid disambiguations for a text chunk.

Beyond that, in EPUBs there are cases where specifying an unambiguous locator is impossible without crossing a block boundary. epubcheck should report a warning rather than an error when it encounters an unambiguous locator that requires crossing a block boundary to match. Syntax errors, unresolvable locators, and ambiguous locators should all report an error.

From scroll-to-text-fragment spec:

While the matching text and its prefix/suffix can span across block-boundaries, the individual parameters to these steps cannot. That is, each of prefix, start, end, and suffix will only match text within a single block.

A node has block-level display if it is an element and the computed value of its display property is any of block, table, flow-root, grid, flex, list-item.

[mattgarrish]

the locator should be validated to ensure that it is well-formed and resolves to a single location in the target document

The second part of the request is likely going to be problematic. Epubcheck doesn't render the content of a publication and text fragments can't be resolved reliably from the source.

But the problem doesn't look like it's exclusive to media overlays. If annotations are also going to use text selectors, and there's an expectation that epubcheck will verify the fragments resolve, the same problem will arise.

[richwaters]

The second part of the request is likely going to be problematic. Epubcheck doesn't render the content of a publication and text fragments can't be resolved reliably from the source.

Can you explain further? I've had good results resolving from the DOM, but I'm using a single generator and, while I've tested on many books, they're all kind of similar.

in case you'd like to give it a try, my code for this issue is at:

https://github.com/richwaters/epubcheck/tree/feature/mo-textfrags

It's targeted at 3.3 epubs and not the newer 3.4 nested locator stuff. I'm not familiar with the annotations issue.

[mattgarrish]

Can you explain further? I've had good results resolving from the DOM

Any browser/css generated text, for example, isn't going to be present in the parsed xml dom. I'm assuming such text will be read in the overlay and present in text selectors - and that for annotations the user will be able to select and annotate such text.

I'm not saying you can't get good results from a parsed xml dom most of the time, but if it's not perfect then we end up in the usual place where we can't emit warnings/errors because it will block publishers from distributing their content.

[richwaters]

Any browser/css generated text, for example, isn't going to be present in the parsed xml dom. I'm assuming such text will be read in the overlay and present in text selectors - and that for annotations the user will be able to select and annotate such text.

Well, that's enlightening. Is there a solution other than to just check the syntax and not validate the locators? Or is a dom-based approach still useful, but only for informational reporting? Is that the 'usual place' you're referring to?

Beyond that, this seems like at least a partial repudiation of the idea of using text fragments for these purposes. An automated alignment tool might generate a locator that appears unique based on the DOM, only for the rendered text to make it ambiguous.