This is an automated email from the ASF dual-hosted git repository. gerben pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/incubator-annotator-website.git
commit 4c7f6d736aca4d0ceb4b9b1e9376eeca9617fd4d Author: Gerben <[email protected]> AuthorDate: Sat Jun 5 19:36:00 2021 +0200 Fixes & updates - Css support is no longer “partly”! - Tweak the support table (consistently link to matcher functions) - Pass node as scope in “Getting started” example. - List node 16 as supported - tweak text here and there --- src/docs/develop.md | 2 +- src/docs/getting-started.md | 10 +++------- src/docs/index.md | 24 ++++++++++++------------ 3 files changed, 16 insertions(+), 20 deletions(-) diff --git a/src/docs/develop.md b/src/docs/develop.md index c676ef5..f1c8bb5 100644 --- a/src/docs/develop.md +++ b/src/docs/develop.md @@ -13,7 +13,7 @@ This project’s source code is available directly [from the ASF](https://gitbox If you’d like to code on the project, you will need the following: - [git](https://git-scm.com/) -- [node](https://nodejs.org) version ^12.20 || ^14.15 || ^15.4 +- [node](https://nodejs.org) version ^12.20 || ^14.15 || ^15.4 || ^16.0 - [yarn](https://www.yarnpkg.com/) version ^1.5 ### Install diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md index 5423c8c..6f3d52f 100644 --- a/src/docs/getting-started.md +++ b/src/docs/getting-started.md @@ -30,9 +30,9 @@ See [Develop](/docs/develop/). ## Usage example: a text quote highlighter -A typical goal of web annotation is to let users highlight a phrase of text in a web page, and perhaps add a note to it. The example code below enables this use case. +A typical goal of web annotation is to let users highlight a phrase of text in a web page, and perhaps add a note to it. The example code below creates such a highlighter (without note-taking functionality). -First, we define the way to describe the user’s selection as a TextQuoteSelector. +First, we define the way to describe the user’s selection as a [TextQuoteSelector](https://www.w3.org/TR/2017/REC-annotation-model-20170223/#text-quote-selector). ``` js import { describeTextQuote } from '@apache-annotator/dom'; @@ -63,11 +63,7 @@ Next, we define roughly the inverse function: given a TextQuoteSelector, we high import { createTextQuoteSelectorMatcher, highlightRange } from '@apache-annotator/dom'; async function highlightSelectorTarget(textQuoteSelector) { - // Search in the whole document - const scope = document.createRange(); - scope.selectNodeContents(document); - - const matches = createTextQuoteSelectorMatcher(textQuoteSelector)(scope); + const matches = createTextQuoteSelectorMatcher(textQuoteSelector)(document.body); for await (const match of matches) { highlightRange(match); } diff --git a/src/docs/index.md b/src/docs/index.md index 9d9d5c3..25afcad 100644 --- a/src/docs/index.md +++ b/src/docs/index.md @@ -17,17 +17,17 @@ The main functionality Apache Annotator offers is to map a [Web Annotation Selec The [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model) outlines a number of different selectors types, to accomodate various use case on different types of documents and selections (e.g. an annotation may target a phrase of text, or a region within an image). The table below shows the full list of defined types and the implementation status of each. -| Selector | Description | Implemented? | -| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| [Fragment](https://www.w3.org/TR/annotation-model/#fragment-selector) | Uses the fragment part of an IRI defined by the representation’s media type. | No | -| [CSS](https://www.w3.org/TR/annotation-model/#css-selector) | CSS Selectors allow for a wide variety of well supported ways to describe the path to an element in a web page. | [Partly](/docs/api/modules/dom.html#createcssselectormatcher) | -| [XPath](https://www.w3.org/TR/annotation-model/#xpath-selector) | Implements an XPath based selection. | No | -| [Text Quote](https://www.w3.org/TR/annotation-model/#text-quote-selector) | This Selector describes a range of text, including some of the text immediately before (a prefix) and after (a suffix) it to distinguish between multiple copies of the same sequence of characters. | Yes, both [for DOM](/docs/api/modules/dom.html#describetextquote) and [generic](/docs/api/modules/selector.html#textquoteselectormatcher) | -| [Text Position](https://www.w3.org/TR/annotation-model/#text-position-selector) | This Selector describes a range of text by recording the start and end positions of the selection in the stream. | Yes, both [for DOM](/docs/api/modules/dom.html#describetextposition) and [generic](/docs/api/modules/selector.html#textpositionselectormatcher) | -| [Data Position](https://www.w3.org/TR/annotation-model/#data-position-selector) | Similar to the Text Position Selector, the Data Position Selector uses the same properties but works at the byte in bitstream level rather than the character in text level. | No | -| [SVG](https://www.w3.org/TR/annotation-model/#svg-selector) | An SvgSelector defines an area through the use of the Scalable Vector Graphics standard. | No | -| [Range](https://www.w3.org/TR/annotation-model/#range-selector) | A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors. | Yes, [for DOM](/docs/api/modules/dom.html#makecreaterangeselectormatcher) | -| [Refinement](https://www.w3.org/TR/annotation-model/#refinement-of-selection) | Select a part of a selection, rather than as a selection of the complete resource. | [Yes](/docs/api/modules/selector.html#makerefinable) | +| Selector | Description | Implemented? | +| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Fragment](https://www.w3.org/TR/annotation-model/#fragment-selector) | Uses the fragment part of an IRI defined by the representation’s media type. | No | +| [CSS](https://www.w3.org/TR/annotation-model/#css-selector) | CSS Selectors allow for a wide variety of well supported ways to describe the path to an element in a web page. | Yes ([for DOM](/docs/api/modules/dom.html#createcssselectormatcher)) | +| [XPath](https://www.w3.org/TR/annotation-model/#xpath-selector) | Implements an XPath based selection. | No | +| [Text Quote](https://www.w3.org/TR/annotation-model/#text-quote-selector) | This Selector describes a range of text, including some of the text immediately before (a prefix) and after (a suffix) it to distinguish between multiple copies of the same sequence of characters. | Yes ([for DOM](/docs/api/modules/dom.html#createtextquoteselectormatcher) and [on any text](/docs/api/modules/selector.html#textquoteselectormatcher)) | +| [Text Position](https://www.w3.org/TR/annotation-model/#text-position-selector) | This Selector describes a range of text by recording the start and end positions of the selection in the stream. | Yes ([for DOM](/docs/api/modules/dom.html#createtextpositionselectormatcher) and [on any text](/docs/api/modules/selector.html#textpositionselectormatcher)) | +| [Data Position](https://www.w3.org/TR/annotation-model/#data-position-selector) | Similar to the Text Position Selector, the Data Position Selector uses the same properties but works at the byte in bitstream level rather than the character in text level. | No | +| [SVG](https://www.w3.org/TR/annotation-model/#svg-selector) | An SvgSelector defines an area through the use of the Scalable Vector Graphics standard. | No | +| [Range](https://www.w3.org/TR/annotation-model/#range-selector) | A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors. | Yes ([for DOM](/docs/api/modules/dom.html#makecreaterangeselectormatcher)) | +| [Refinement](https://www.w3.org/TR/annotation-model/#refinement-of-selection) | Select a part of a selection, rather than as a selection of the complete resource. | [Yes](/docs/api/modules/selector.html#makerefinable) | ### Web Annotation JSON validator @@ -43,6 +43,6 @@ With the `--url` option you can pass in a URL or a local path to a JSON file. See some [example JSON files](https://github.com/w3c/web-annotation-tests/tree/master/tools/samples) from the W3C. Note that this validator only tests the data model is followed, and not e.g. whether its target actually exists. -## What Apache Annotator it not +## What Apache Annotator is not Apache Annotator is **not an all-in-one annotation tool**; rather, it *helps others create* annotation tools. It does not have opinions regarding in which database on which computer annotations are stored, nor how they are made, exchanged or displayed. Those questions are considered application-specific and left to the developer. Our goal is that the developer can focus on exactly those questions, and forget about issues that are common among annotation tools: finding the part in the doc [...]
