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
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 @@
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 @@
## 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 @@
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 [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 @@
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 document that is being annotated, dealing with changes in the annotated document, ensuring compatibility with other tools, and so on.