Re: Rough Draft of Robust Anchoring: the RangeFinder API

[not as chair]

Kristof

Much thanks for this clear and well-written explanation - it is very helpful and raises an important design issue in my opinion.  Adding the note to the list helps greatly adding much clarity to the call discussion.

I submit that with some minor changes the RangeFinder API might not need much change to accommodate this, though the following is probably appropriate

1. Update RangeFinder to note explicitly the actors you mention

2. Outline the model as noted in your email, giving both DOM and PDF.js as examples

3. Remove normative language that assumes the DOM (not much of that)

4. Add error language when implementation access to underlying document is not available (e.g. for non-DOM case)

5. Note that connection for cases apart from DOM may be implementation dependant

6. Clarify that DOM support is normatively required when direct-to-DOM is the case .

Thanks for the 'disclaimer' - lessons and suggestions from the implementation that impact the spec and/or testing would be helpful.
 
regards, Frederick

Frederick Hirsch
Co-Chair, W3C Web Annotation WG

www.fjhirsch.com
@fjhirsch

> On Mar 5, 2015, at 12:31 PM, Kristof Csillag <csillag@hypothes.is> wrote:
> 
> 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
>> 
>> 
>>

Received on Monday, 9 March 2015 22:14:04 UTC