hypothesis/annotator — pull request #16 by csillag (2013-11-13 17:42:58+00:00)
Title: Introducing typed anchor support

This work involves a comprehensive overhaul of two-type anchoring, and introduced typed anchors.

Some new/renamed concepts to learn:

* We have `anchoring strategies`, which can create `anchors` out of the targets of the annotations, using the data in the selectors, and also utilizing the `document access strategy` in place, to inspect the document.
* Anchors are created `virtual`, which means that they don't exist inside the DOM yet; they just know where they should go.
* Anchors are objects. There can be different kinds of anchors, implemented in different classes.
* Any anchoring strategy is free to produce any kind of anchor.
* Annotator core contains one anchor type: the TextRangeAnchor, which describes a text range, using the character offsets.
* Both anchoring strategies in Annotator core (xpath and position) produce this kind of anchor. The fuzzy strategies do the same.
* When the conditions are right (for example, the relevant part of the DOM is rendered), anchors can be `realized`, which means that the corresponding `highlights` are created in the DOM.
* Anchors can also be `virtualized` again, which means that the highlights are removed from the DOM. (This can be done on a per-page
basis.)
* Highlights are objects. There can be different kinds of highlights, implemented in different classes.
* The highlight classes are responsible to do all actual DOM manipulation. Everything which needs to happen to the DOM goes through them.
* Highlights are created by anchors. Typically, a given type of anchor always creates a given type of highlight.
* Annotator core has one highlight type defined: TextHighlight, which creates the usual text highlight in the DOM.
* When a TextRangeAnchor is realized, it creates TextHighlights.
* An anchor can several highlights, if it spans several pages.
* We always think about the document as if it had pages. Individual pages can be rendered an un-rendered at will.
* When a page is rendered, all the anchors on it are realized. (The highlights are created.)
* When a page is un-rendered, the anchors are (partially) virtualized. (The highlights disappear.)
* An anchor can be partially realized, if some of it's pages are rendered, and some are not.
* All the code of Annotator (and H) outside the actual anchors/highlights is forbidden to assume anything about the internals of anchors/highlights; they can only access them via the interface defined on the abstract classes. (Anchor and Highlight)