What is the navigator pointer/location approach in Readium-2

rkwright commented 8 years ago

This is a Discussion

What is the navigation pointer technology? CFI? Part of the EPUB standard, but has flaws Something else? What?

rkwright commented 8 years ago

From Juan Corona: I'm aware of some of the flaws, but I've been made biased (figuratively, not literally) towards keeping CFIs. It would help if someone could list out the flaws.

rkwright commented 8 years ago

From Juan Corona: XPath? Query selectors? Roll our own with the goal of only using it internally?

HadrienGardeur commented 8 years ago

I think that we need more than one pointer, and an API that will return these different values.

HadrienGardeur commented 8 years ago

I had something like that in mind:

{
  "highlight": "Laurentides",
  "before": "Lors de ses vacances dans les ",
  "after": "il a décidé de réécrire Readium SDK",
  "locators": 
  {
    "cfi": "...",
    "xpath": "...",
    "page": 147,
    "position": 12.67
  }
}

rkwright commented 8 years ago

I like this (especially the quote :-) But it could get quite messy in terms of resolving mismatches, i.e. where the various methods don't agree. But I like the concept.

HadrienGardeur commented 8 years ago

Well, having multiple locators means that you have to resolve mismatch, but it also means that you have better chance of being able to anchor an annotation if the contain is ever updated.

IMO, a single locator is a very weak approach for a number of reasons:

for a search API or annotations, we need context that a CFI or XPath can't provide
locators that basically go through an XML tree (CFI, XPath) are much more likely to break when there's an update than the ones that are a little more "vague" (text, location)

It doesn't mean that we need to use 4-5 locators each and every time, but it should be part of the design.

llemeurfr commented 8 years ago

Another approach could be to consider that the RS must handle CFI + XPath + page ... but that a reference will be indicated either via one or the other option. This is more or less what XPointer tried a long time ago (with its different "schemes").

Note also that XPointer, as an extension of XPath, introduces the Point (position between characters) et Range, i.e what CFI mimics. I don't like XPointers for their complexity, but a streamed down version could be interesting if CFIs are rejected.

Re. the context of search/annotation (the "snippet" as Google names it) I think that this must be discussed at a different level, not the "pointer" level.

Also, the "location break if update" is a problem with no solution, isn't it?

mickael-menu-mantano commented 8 years ago

We don't have to resolve every locators, just the most precise one, thus ignoring mismatches.

Multiple kind of locators can be useful too when we want to go to a specific place, without knowing the exact content (CFI). For example, "go to page 45" using a progression control. Or "go to last page (-1) of spine item X" when trying to go backward to the previous spine item.

Also, the "location break if update" is a problem with no solution, isn't it?

That's where the context (snippet) could be useful, to recover broken locations.

olivierkorner commented 8 years ago

If we were to move from CFI as a location approach, migration of existing bookmarks could become a headache for vendors. Having multiple kind of locators might indeed make the transition smoother, but i think we need to keep a CFI resolver somewhere.

danielweck commented 8 years ago

The "Open Annotation in EPUB" draft proposes the use of multiple "selector" schemes too: http://www.idpf.org/epub/oa/#h.4o298bjh2atb ...but bear in mind that this is about an authoring and interchange serialization format, which has different design goals than an internal, implementation-specific, machine processing-oriented data model and persistence / archival syntax. Both care about interoperability, but the applicable scope is different.

As a developer, if I had to re-think from scratch a "document position / range" design, I would probably come-up with a design very similar to CFI. CFI character references operate at a low document level (UTF16 code units, although I will admit that code points have benefits too), so this maps well with DOM ranges and Javascript string libraries. Just like with character offsets, the CFI "XML path" syntax is ; crucially ; canonical, which allows comparing / sorting without having to load the target document / DOM. This is a useful quality, for example when storing / managing / rendering / navigating locations that target separate documents within a publication. Note that XPath, XPointer's various schemes, Selectors, etc. do not support this, which is why highlights / bookmarks / annotations services on the web usually implement their own internal format.

The problem with CFI is that it is ; by definition / by design ; not a human-friendly serialization format. CFI references are really only meant to be generated and consumed by tools / software libraries.

So, I too think that from a usability perspective, a multi-prong approach is necessary . That being said, behind the scenes I would keep working with CFI. Contrary to popular belief (and that is partly our fault because we tend to label evil pagination bugs with the term "cfi" ;) ), the part that is hard to implement is all to do with DOM / CSS idiosyncrasies (browser discrepancies). The CFI bits are actually already pretty solidly implemented.

Dan

HadrienGardeur commented 8 years ago

@danielweck lack of readability and implementation outside of EPUB-land are just two of the problems with a CFI only approach.

There are other valid reasons:

an extra context (text, position in the table of contents, page number) is necessary to display a number of things such as annotations or search results to the user
CFI can very easily break if the document is updated, and since we want to prepare for the future this covers PWP/BFF where publications will live on the Web and can be frequently updated

CFIs might still be our number one priority when we attempt to anchor back an annotation to a document, but relying strictly on it is IMO potentially harmful. Also, I don't think that the left part of the CFI should be used at all, only the right part is truly useful.

We also need to explore if using HTML instead of XHTML will have an impact on CFI.

llemeurfr commented 8 years ago

I followed @danielweck link and moved to the W3C Open Annotation spec https://www.w3.org/TR/2016/CR-annotation-model-20160906/#selectors which is more recent than the OpenAnnotation link given in he IDPF spec. I read there that "Multiple Selectors can be given to describe the same Segment in different ways in order to maximize the chances that it will be discoverable later, and that the consuming user agent will be able to use at least one of the Selectors." -> this is what @HadrienGardeur has proposed.

BigBlueHat commented 8 years ago

(apparently I forgot to click "comment" about 3.5 hours ago...glad you found Web Annotation @llemeurfr! :smiley:)

Hi all. I'd highly recommend a look at Open Annotation's successor Web Annotation (full disclosure, I'm one of the editors :smiley_cat:).

It supports storing selectors precisely for serving the "multi-prong approach" use cases @danielweck mentioned: https://www.w3.org/TR/annotation-model/#selectors

Using that model, it's possible to store CFI, XPath, and CSS together and use them together or in succession to accomplish the anchoring, positioning, or reading state retrieval.

Also, the New York Public Library is using the model to share reading state for patrons as they move between various devices. So it's flexible beyond just highlighting, commenting, and bookmarking.

Lastly, to @HadrienGardeur's comment, it's quite possible to re-use Selector's (from Web Annotation) across media types (vs. fragment identifiers such as CFI which are media type specific). This is at minimum useful for reapplying selectors among variations of (X)HTML, but the more broadly applicable selectors like TextQuoteSelector can work across EPUB, PDF, CommonMark/Markdown, HTML, etc.

danielweck commented 8 years ago

@llemeurfr also take a look at http://w3c.github.io/web-annotation/selector-note/#selectors I posted an issue about TextPositionSelector: http://w3c.github.io/web-annotation/selector-note/#TextPositionSelector_def here: https://github.com/w3c/web-annotation/issues/350

danielweck commented 8 years ago

And just a shout-out for a useful TextPositionSelector implementation: https://github.com/tilgovi/dom-anchor-text-position https://github.com/tilgovi/dom-seek ;)

BigBlueHat commented 8 years ago

I'll also note (now that you've found @tilgovi's fabulous code), that there's an effort to build some amount of the selection bits into the upcoming Apache Annotator (incubating) project--which is the hopeful successor of the AnnotatorJS project.

We're just getting that on it's feet, but you're welcome to participate, and certainly we hope to have code built there which Redium (and everyone) can benefit from.

Apache Annotator (incubating) Mailing List

danielweck commented 8 years ago

Thanks @BigBlueHat for the heads-up re. Apache Annotator!

iherman commented 8 years ago

Just to be clear: that note (the plan is to publish it as a formal note early 2017) is just an extract of the Web Annotation Model specification, making it easier to use for those who are only interested by selectors.

Ivan

On 11 Oct 2016, at 21:50, Daniel Weck notifications@github.com wrote:

@llemeurfr https://github.com/llemeurfr also take a look at http://w3c.github.io/web-annotation/selector-note/#selectors http://w3c.github.io/web-annotation/selector-note/#selectors I posted an issue about TextPositionSelector: http://w3c.github.io/web-annotation/selector-note/#TextPositionSelector_def http://w3c.github.io/web-annotation/selector-note/#TextPositionSelector_def w3c/web-annotation#350 https://github.com/w3c/web-annotation/issues/350 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/readium/readium-2/issues/9#issuecomment-253025028, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfyE1Ay7VCvQNUgwp_iv2cgxjnm-k9_ks5qy-hvgaJpZM4KDJN6.

danielweck commented 7 years ago

@HadrienGardeur 's doc: https://github.com/readium/readium-2/tree/master/locators

Note that 3.1 Fragment Selector lists EPUB3 CFI as a valid potential type: http://w3c.github.io/web-annotation/selector-note/index-respec.html#FragmentSelector_def ...but this is different from Hadrien' suggestion to use only the rightmost part of CFI expressions (without dereferencing the leftmost OPF / spine -related "path").

PS, fun fact: Web Annotation Data Model is a W3C Proposed Recommendation dated 17 January 2017 ;) (in the future from now!) http://w3c.github.io/web-annotation/model/wd2/

HadrienGardeur commented 7 years ago

@danielweck the list of selectors in the W3C Web Annotation Data Model spec is indeed a good source of inspiration, and I think we're aiming for something quite similar.

For the syntax though, I'm not entirely sure that we need to adopt their JSON-LD based model since we're not dealing with annotations (at least not yet) and so far the only place where we plan on representing locators is in search, where a different syntax would probably be more useful.

iherman commented 7 years ago

The WG is planning to issue a separate Note that 'extracts' the selections from the annotation spec. This was done primarily for the purpose of an easier reference. There is also an attempt (informal, this is just a Note!) to map the selectors on fragment ID-s. See [1] for the latest version (disregard the turtle formatting and colouring, that will be part of the final editing); [2] will be the final URL for this, eventually,.

The plan is to finalize this document in February. Any comments are welcome!

I am not sure whether the fragment id is the best alternative syntax. But it may be a start…

On 5 Jan 2017, at 13:24, Hadrien Gardeur <notifications@github.com mailto:notifications@github.com> wrote:

@danielweck https://github.com/danielweck the list of selectors in the W3C Web Annotation Data Model spec is indeed a good source of inspiration, and I think we're aiming for something quite similar.

For the syntax though, I'm not entirely sure that we need to adopt their JSON-LD based model since we're not dealing with annotations (at least not yet) and so far the only place where we plan on representing locators is in search, where a different syntax would probably be more useful.

HadrienGardeur commented 7 years ago

Thanks for those links @iherman !

For search, we don't really need a fragment id based syntax since we'll need to output a JSON document anyway. But it could prove useful to support a fragment id based syntax purely for navigation. It would be up to the reading system to decide when such fragments are useful.

iherman commented 7 years ago

On 5 Jan 2017, at 14:36, Hadrien Gardeur <notifications@github.com mailto:notifications@github.com> wrote:

Thanks for those links @iherman https://github.com/iherman !

For search, we don't really need a fragment id based syntax since we'll need to output a JSON document anyway. But it could prove useful to support a fragment id based syntax purely for navigation. It would be up to the reading system to decide when such fragments are useful.

Yes, that is exactly why that definition is there.

I would be interested to see what other syntax you think are of value as an alternative to JSON(-LD). I wonder whether it is worth getting into a syntax definition; but I cannot really judge until I have a clearer idea what it should look like

readium / architecture

What is the navigator pointer/location approach in Readium-2 #9

This is a Discussion