First Draft of an Internal Locators Section

[tcole3]

Added as section 6.5 (under enhancements); may be better elsewhere.
Since Selectors and States can't be a normative ref, I've included (at Ivan's suggestion) examples of all Web Anno selectors and states mapped to a proposed new fragment identifier. For clarity also included along the way some text redundant with Web Anno Recs. Result is long.
WG can discuss what might be left out, but does not yet include a few features of EPub-CFI (e.g., Side Bias, Intended Target Location Correction). So may remain long.
For this reason should this be a separate document instead? Would that also make it more useful beyond WP - i.e., for other Publishing recs and/or in other domains?

---

Preview | Diff

[iherman]

@tcole3,

Thanks! I do have several remarks.

• In this text we have to be very careful to separate what is normative and what is not. I believe 6.5.1 and 6.5.2. are informative; there is nothing there that we would standardize. It is fine to have it there, but the differentiation may be important. What we would bring to the table is, actually, 6.5.3.

• (This is purely editorial) I think it is worth emphasizing after the first paragraph in 6.5.3 that such a dynamic fragment ID is necessary for use cases like setting temporary bookmarks on a specific text within a resource, or adding an annotation to a specific range.

• I believe it is worth improving, editorially, the examples to make them more readable. We should have no scrollbars in the examples, and no percent endoced text either, jut to make the example clear. At the moment, it is very difficult to read...)

• Le me pick up on your question: "For this reason should this be a separate document instead?". I would say "yes", this is what I think we should do. There are, actually, several reasons for that.

  • As you say, the current text is very long. It will make the final FPWD very unbalanced, which may be, editorially, a problem, would harm its readability, etc.
  • If we go down that route, we will have a slightly separate standardiation route on our hands with LFI: the document would have to serve as a basis for the registration of a fragment identifier by IANA, and it will make that process way easier to have a fully separate document.

  I.e., I would propose to have a separate document draft, probably entitled the "Locate Fragment Identifier", and contain most of the 6.5.3 section. It could be kind of a minimally modified copy of the selector note, actually...

[iherman]

All that being said, there is a genuine question of use cases vs. the tools we propose here. In some sense, there is a logical jump in our reasoning so far. What we say is: we need a way to identify a specific portion in the text for the purpose of, e.g., annotations or bookmarks (there may be other examples). Then we jump to the conclusion that, therefore, we need a fragment identifier. Are we sure? What if we re-use, almost verbatim, what we defined in the Annotation Spec, i.e., the selectors and states as they are there (i.e., for those who are not familiar with the Annotation spec, JSON structures to define the relevant portion or point in the document). We do not really argue why we need fragment identifiers instead of the JSON structures. (We may need some extensions of the annotation model, but that is another matter.)

I would think by separating (potentially) the LFI portion into a separate document, we should open this as a specific issue.

(One argument against the fragment ID approach is the standardization difficulties we would face doing so with IANA.)

(One argument in favour of a fragment ID is that this makes it possible to bind all those fragments into the RDF world more easily. With all my Semantic Web background I must admit that this is a weak argument…)

[tcole3]

Regarding the editorial improvements, etc. that have been suggested, they make good sense, but since I am coming around to a separate document approach for LFI (or whatever we end up with for 'internal' locators) and then a much smaller text for the Web Publication Rec itself referencing the separate document, I think we should reach consensus on whether or not to have a separate LFI document before making further editorial changes at this stage. I may be underestimating the process headaches, but I think separate document makes more sense.

In deciding between a fragment identifier approach and the json object approach already defined by the Web Annotation Data Model, I favor fragment identifier approach for a couple of reasons:

1. I suspect in the end that even if we go json object model, the extensions of and/or deviations from Web Anno Data Model will be enough to warrant a new document anyway (just as even if we try to start with EPUB-CFI instead of Web Anno, there'll be enough different about the fragment identifier needed for Web Publications to warrant a new doc) - so this is not a useful consideration for whether or not to use fragment identifier approach or json object model approach.

2. Most annotation use cases require an object describing the annotation body anyway such that describing the range being annotated also in json at the same time makes sense. But many of the other digital publishing use cases that have come up - e.g., bookmarking (without a comment), linking from manifest (which in current WP draft alludes to OPDS/Atom and rel="webmention" links), random access to content (e.g., teasers, abstract only views) do seem more amenable to a single URL-based approach for internal locators, i.e., fragment identifiers, which have the potential at least to work well in html5 elements, not to mention in reading orders and manifests (well can't mention since definition of manifest serialization is still a bit uncertain).

I do recognize that the json approach facilitates processing, e.g., sorting and clustering bookmarks, but the Selectors and States Note (and EPub CFI) have convinced me that if well-designed, fragment identifiers are also relatively easy to process while still be recognizable for other purposes as URL components.

Anyway, I would be happy to close this PR, contribute to creation of a separate document, and then propose a much shorter PR of what to include in Web Publication.

[iherman]

Regarding the editorial improvements, etc. that have been suggested, they make good sense, but since I am coming around to a separate document approach for LFI (or whatever we end up with for 'internal' locators) and then a much smaller text for the Web Publication Rec itself referencing the separate document, I think we should reach consensus on whether or not to have a separate LFI document before making further editorial changes at this stage. I may be underestimating the process headaches, but I think separate document makes more sense.

I agree. Let us do that.

• I suspect in the end that even if we go json object model, the extensions of and/or deviations from Web Anno Data Model will be enough to warrant a new document anyway (just as even if we try to start with EPUB-CFI instead of Web Anno, there'll be enough different about the fragment identifier needed for Web Publications to warrant a new doc) - so this is not a useful consideration for whether or not to use fragment identifier approach or json object model approach.

I agree that we may be forced to come up with a new document anyway, even if we choose a JSON based approach. And I also agree that this does not really affect whether we choose JSON over fragments or vice versa. The only thing that is true that if we do fragments, then a separate document becomes almost inevitable.

Actually… because we would depart from the Annotation model, albeit slightly, I think if we have a separate document for fragment id-s we would have to provide a definition for each selector and the best way of doing that maybe be to use JSON for clarity…

• Most annotation use cases require an object describing the annotation body anyway such that describing the range being annotated also in json at the same time makes sense. But many of the other digital publishing use cases that have come up - e.g., bookmarking (without a comment), linking from manifest (which in current WP draft alludes to OPDS/Atom and rel="webmention" links), random access to content (e.g., teasers, abstract only views) do seem more amenable to a single URL-based approach for internal locators, i.e., fragment identifiers, which have the potential at least to work well in html5 elements, not to mention in reading orders and manifests (well can't mention since definition of manifest serialization is still a bit uncertain).

Many of those use cases, or the implementation thereof, is still out in the open. And I would think that all of those could be implemented via JSON structures.

I do recognize that the json approach facilitates processing, e.g., sorting and clustering bookmarks, but the Selectors and States Note (and EPub CFI) have convinced me that if well-designed, fragment identifiers are also relatively easy to process while still be recognizable for other purposes as URL components.

Yes, that is true. However, I would put it another way. If we define fragments then we do have a bunch of extra administrative and social problems on our hands. Much as I like fragment ID-s :-) we should go down that route if and only if we are convinced that is way better than using JSON structures. Hence, at this point, I think we should make that an open and clear issue.

Anyway, I would be happy to close this PR, contribute to creation of a separate document, and then propose a much shorter PR of what to include in Web Publication.

Actually… at this point I believe it is perfectly fine if we take the current Selectors and States notes and starts from there modifying/extending it to what we need. Meaning that many of the text is already at our disposal. The resulting document would contain all the definition in JSON and in the form of fragment ID-s, and then the choice would become way clearer for people: which 'half' of the document would be normative?

I am happy to help on this; after all, I edited the original note. Just tell me what would you want me to do.

[iherman]

Merged per resolution on the 16th of October '17