Re: Rough Draft of Robust Anchoring: the RangeFinder API

Dear All,

I will try to summarize my comment that I brought up during the WG 
t-conf.

Roughly speaking, there are three major roles in the range finding 
interactions we are speaking about:

 1. There is the actor that wants to find a range of text, and wants to 
do something with it. ("client" from now on.)

 2. There is the actor that is able to perform the search, and identify 
the matches. ("search agent" from now on.)

 3. And finally, there is the actor the supplies to text to be 
searched. ("document" from now on.)

As far as I understand the purpose and scope of this draft, we are 
trying to specify the API between the *search agent* and the *client*.

The current version of the draft seems to be based on the unspoken 
assumption that the *document* is simply the DOM itself, and therefore 
the *search agent* has native access to it, making the separation of 
the roles between the *document* and the *search agent* meaningless. 
(It's all withing the browser.)

While this might cover a range of applications, there are other user 
cases where this is not the case.

Most importantly, I am concerned about use cases where the *document* 
we are working on is not something that lives in the DOM naturally; but 
something that is somehow [partially] projected (or rendered) to it, as 
in some kind of viewer. My most important example is PDF.js.

PDF.js works with a document that lives in the memory of the browser, 
but not in the DOM itself. (The DOM only holds a few pages, which are 
rendered as the user moves the "reading window" along the document as 
he is reading it.) To perform meaningful searches in cases like this, 
we need to go the the *real* document, which might be a different 
object, not directly accessible using the DOM api. (PDF.js's native 
find feature also uses this in-memory document for searching.)

All of the features that are actually required by the *search agent* 
can be provided by those other kinds of (non-DOM-native) documents, too.

Therefore, I am proposing that we also specify the interface between 
the *document* and the *search agent*.

The *document* only needs to provide a small set of core operations so 
that the *search agent* can work with it. (For example, "give me all 
the text you have", "tell me if the following character offset range is 
currently present in the projected DOM, and if yes, where is it", and 
so on.)

Relying on these core operations, the *search agent* can fulfill the 
requests of the *clients*, using the data provided by the *document*.

In the majority of use cases (where we are working with HTML 
documents), the *search agent* would simply use the *document* 
implementation provided by the DOM; but the *search agent* could have 
an API that allows us to connect other *documents* to it, besides the 
default one.

Doing this, it would be possible to expose all the useful functionality 
that is provided by the *search agent* to all the environments where 
the document is not native to the DOM. The applications would also 
greatly benefit from the functionality provided by the RangeFinder API, 
but if the RangeFinder API can only search the physical DOM, they can't 
utilize it. However, if they can connect their own document back-end to 
RangeFinder, then they could use it the same as normal HTML documents 
do.

Which would take us one step closer to having a unified text search API 
that works over all kinds of different platforms.

   * * *

Disclosure: we (in Hypothes.is) have a working implementation for this. 
Unfortunately, our internal API is not really well-documented at this 
point, and it could probably be made cleaner, but it is already 
sufficient to provide a unified *document* API that can abstract away 
the differences between the native DOM document and the in-memory 
PDF.js document, and expose the required features to our range finding 
modules in a unified way .

  * * *

Thank you for considering this.

If I failed to make my point clear, please don't hesitate to ask for 
clarifications or details.


   Kristof


2015. febr. 25., sze 6.48-kor-kor, Doug Schepers <schepers@w3.org> 
írta:
> Hi, folks–
> 
> Just a quick note. Rob asked me to move this file, to keep the 
> deliverables organized. It's now located at:
> 
>  http://w3c.github.io/web-annotation/api/rangefinder/
> 
> Even this is a temporary location, though... I'll be moving it to 
> specs.webplatform.org soon, and adding the annotation capability to 
> it.
> 
> Feel free to review, but be aware that the URL is transitory.
> 
> Regards–
> –Doug
> 
> On 2/24/15 1:33 PM, Doug Schepers wrote:
>> Hi, folks–
>> 
>> After talking about Robust Anchoring with many people over the 
>> course of
>> the last couple years (!), with encouragement and good criticisms, 
>> I've
>> refined my notion of what's needed for a client-side API for Robust
>> Anchoring.
>> 
>> I've drawn up a strawman of my current thinking for an API called
>> RangeFinder [1].
>> 
>> It's very rough in places, but I'd appreciate any feedback on the 
>> spec
>> as it stands. I'd greatly appreciate any thoughts or opinions on it 
>> at
>> this stage.
>> 
>> I'm not sure it's mature enough for this yet, but at some point, I'd
>> like to engage the research and academic communities and the experts
>> who've published on text search algorithms, to polish this up and 
>> make
>> it not quite as embarrassing as it is currently. If anyone knows who 
>> we
>> should contact in that regard, please chime in. This is a great
>> opportunity to leverage all that research in the service of Web
>> developers and browsers!
>> 
>> [1] http://w3c.github.io/web-annotation/rangefinder-api/
>> 
>> Regards–
>> –Doug
>> 
>