They seem like Selectors? Is there a difference? And if not, please don't check something into an *openannotation* repo that acts like something from the model but is called something totally different!
Rob On Mon, Jun 16, 2014 at 6:10 PM, Randall Leeds <[email protected]> wrote: > On Wed, Jun 11, 2014 at 11:50 AM, Randall Leeds <[email protected]> > wrote: > >> +1 to releasing Range as a separate module. >> >> The best thing around besides ours seems to be Rangy and it unfortunately >> seems to be acquiring more stuff, such as a highlighter. >> >> A good Range package would be a great thing for the web dev community. >> > > I suggested to Kristof this morning that we create a "dom-range" repo > under openannotation. > > There was some disagreement [see transcript below] about whether this is a > good name. > In an attempt to resolve the issue, I'm taking stock of what's in this > module. > > Annotator.Range > ============= > > This module implements three Range objects: BrowserRange, SerializedRange, > and NormalizedRange > > BrowserRange > ---------------------- > > This serves to just provide a wrapper around the DOM Range object with two > additional functions. > > Its properties are the same as the DOM Range object, though it lacks > properties that aren't used in Annotator. > > In addition to these properties, it provides a normalize() and serialize() > call. The serialize() method returns an object fit for serialization (duh). > The normalize() method returns a NormalizedRange instance after normalizing > the range. Normalization involves moving the start or end of the range > based on some rules. > > NormalizedRange > --------------------------- > > This object provides different properties than the DOM Range, but > encapsulates the same concept. It also adds a few other methods. > > The serialize() method is actually the serialization as described in > BrowserRange. The BrowserRange serialize() method actually calls > normalize() first to get a NormalizedRange and then calls serialize() on > that. > > Most of serialization is a simple XPath builder with the added detail that > a relative root can be passed in. > > NormalizedRange objects also provide a function to get the text nodes they > contain, to get the string of text contained by those text nodes, and to > get a real DOM Range object. > > It's worth noting that NormalizedRange#text() is probably the equivalent > of the DOM Range #toString() method. > > A limit() method provides the ability to reduce the range to only the > nodes that fall inside the given container. > > SerializedRange > ------------------------- > > This serves as an OO wrapper around a serializable Range. It contains an > XPath expression for each of the DOM Range object's start- and endContainer > properties as well a the start and end offsets. Its normalize() method > first attempts to resolve to XPath to find this range in the document and, > having resolved the start- and endContainer nodes, returns a > NormalizedRange. > > Analysis > ====== > > Very little in this module actually deviates from the DOM Range spec. > > - Mostly, we don't implement the methods. > - Serialization and deserialization could be kept in Annotator itself. > This avoids having to extract our xpath code. We can evaluate that > separately. > - Normalization and limiting are potentially reasonable proposals for the > Range spec. It makes me wonder whether a normalization algorithm in the > spec would have saved us from a lot of interop woes. Rangy implements a > normalization algorithm, too. > > Conclusion > ======== > > I would support extracting the Range module from Annotator. However, I > don't see much value beyond normalization and limiting. > > The only other library on the radar that we see in use is Rangy. > > Rangy: > > - Implements Range and Selection in one library. > - The core weighs ~43KB minified compared with Annotator.Range at ~8KB. > > A think a library that just focuses on being a good compatibility wrapper > for Range and contains a cross browser CI suite would be great. It'd be > useful to uncover and document which browsers implement the newest whatwg > range calls, #createContextualFragment(), #getClientRects(), and > #getBoundingClientRect(). I think defining a normalization algorithm, > whether it's a new method or something browsers do implicitly, would be > great for HTML Editing. > > Rangy does contain an implementation of Range#createContextualFragment(). > > So, I don't think there's much "magic" here: > > - The sniff function is only a few lines to detect between the three Range > subclasses > - Serialization is probably best left out (for instance, Rangy has a CRC32 > based serialization). > - Normalization is the core contribution that seems to be missing from the > standards. > > Mostly we'd gain a place to keep this neat and separate, add tests as we > go, and perhaps plug some browser incompatibilities. We also get a place to > define our normalization algorithm exactly and implement it with tests so > others can use it. > > Therefore, I'm in favor of just calling it "dom-range" and making it > implement the spec. Depending on the required browser compatibility, most > of the implementation can be trusted to the browser built-in Range object. > > > [Transcript] > > 16:30:11 <csillag1> let's call the new repo MagicRange > 16:30:19 <tilgovi> No. > 16:30:20 <tilgovi> I'd rather not. > 16:30:28 <csillag1> Range sounds way too generic. > 16:30:34 <csillag1> It's not a useful name to identify a piece of code. > 16:30:35 <tilgovi> I actually think we should just call it dom-range > 16:30:43 <csillag1> Please no. > 16:30:48 <csillag1> It's not something which we want to > 16:30:48 <tilgovi> For now it can be extracted unchanged > 16:30:55 <csillag1> promote > 16:30:56 <Treora> ah that repo, I was looking at the one in hypothe.is > which has only one line of documentation. :) > 16:31:05 <csillag1> it's legacy code, which has only been created > 16:31:08 <csillag1> because of historical reasons. > 16:31:19 <csillag1> Don't name it in a way that indicates > 16:31:24 <tilgovi> But the best would be if we made a library that > actually just impediments a standard Range with tests and maybe new calls > for serialization > 16:31:24 <csillag1> that it's something generally useful > 16:31:29 <csillag1> part of our framework for the future, etc. > 16:31:31 <tilgovi> It should be generally useful > 16:31:33 <csillag1> I would actually get rid of it. > 16:31:58 <csillag1> I was created to work around problems > 16:32:02 <csillag1> which are probably long gone now. > 16:32:12 <tilgovi> That's not true or we wouldn't use it. > 16:32:15 <csillag1> The original research should be done again. > 16:32:23 <csillag1> We are using because much of our code depends on it. > 16:32:30 <tilgovi> And Rangy wouldn't exist. > 16:32:35 <csillag1> But we don't need to write new code around it. > 16:32:50 <csillag1> I don't know about the history of Rangy; > 16:33:02 <csillag1> I just know that the current Range implementation > 16:33:12 <csillag1> brings a large set of oddities along with it. > 16:33:17 <csillag1> It does solve other problems, > 16:33:22 <csillag1> but according to Nick, > 16:33:23 <tilgovi> What we see from IE issues is not that the MS team has > done something wrong, but that the HTML Editing specs are drafts. They are > vague. They have holes and requests for feedback. > 16:33:37 <csillag1> those problems are already gone now. > 16:33:41 <tilgovi> Rangy's stated goal is a spec compliant Range > 16:33:54 <csillag1> Well ... sounds like a nice goal, > 16:33:57 <csillag1> but it's not there yet. > 16:34:01 <csillag1> crashes under IE. > 16:34:05 <tilgovi> But the specs aren't even really compete > 16:34:06 <csillag1> Has a huge performance penalty. > 16:34:08 <tilgovi> Complete > > > >> On Jun 11, 2014 8:18 AM, "Kristof Csillag" <[email protected]> wrote: >> >>> Hi all, >>> >>> As some of you already know, currently I am working on separating all >>> the anchoring-related work that which Annotator does (both in the >>> Upstream version, both in the Hypothes.is fork) into a separate library, >>> which Annotator and other projects could use, but which can be developed >>> independently. >>> >>> As a part of this problem, I need to have the current Range >>> implementation (BrowserRange, NormalizedRange, SerializedRange) in that >>> library, too. >>> >>> How would you feel like releasing this part (the Range implementation) >>> as a separate NPM package, so that it can be plugged in easily wherever >>> we need it? >>> >>> Kristof >>> _______________________________________________ >>> annotator-dev mailing list >>> [email protected] >>> https://lists.okfn.org/mailman/listinfo/annotator-dev >>> Unsubscribe: https://lists.okfn.org/mailman/options/annotator-dev >>> >> > > _______________________________________________ > annotator-dev mailing list > [email protected] > https://lists.okfn.org/mailman/listinfo/annotator-dev > Unsubscribe: https://lists.okfn.org/mailman/options/annotator-dev > > -- Rob Sanderson Technology Collaboration Facilitator Digital Library Systems and Services Stanford, CA 94305
_______________________________________________ annotator-dev mailing list [email protected] https://lists.okfn.org/mailman/listinfo/annotator-dev Unsubscribe: https://lists.okfn.org/mailman/options/annotator-dev
