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 2bcd3cd534f9cd09693bb728b109cea29370c4f9 Author: Gerben <[email protected]> AuthorDate: Sun May 16 23:24:28 2021 +0200 Add actual documentation Partly derived from the code repo’s README, partly new. --- src/_includes/docs_nav.hbs | 3 +- src/docs/develop.md | 62 +++++++++++++++++++++++++++++ src/docs/getting-started.md | 96 ++++++++++++++++++++++++++++++++++++++++++++- src/docs/index.md | 44 +++++++++++++++++++-- 4 files changed, 200 insertions(+), 5 deletions(-) diff --git a/src/_includes/docs_nav.hbs b/src/_includes/docs_nav.hbs index 29cc66d..134da78 100644 --- a/src/_includes/docs_nav.hbs +++ b/src/_includes/docs_nav.hbs @@ -4,6 +4,7 @@ --}} <nav class="ui secondary stackable pointing menu" style="justify-content: center;"> <a href="/docs/" class="{{#if isDocsIndex}}active {{/if}}item">Overview</a> - <a href="/docs/getting-started" class="{{#if isGettingStarted}}active {{/if}}item">Getting Started</a> + <a href="/docs/getting-started/" class="{{#if isGettingStarted}}active {{/if}}item">Getting Started</a> + <a href="/docs/develop/" class="{{#if isDevelop}}active {{/if}}item">Develop</a> <a href="/docs/api/" class="{{#if isApiReference}}active {{/if}}item">API reference</a> </nav> diff --git a/src/docs/develop.md b/src/docs/develop.md new file mode 100644 index 0000000..a0cdf4f --- /dev/null +++ b/src/docs/develop.md @@ -0,0 +1,62 @@ +--- +title: Develop Apache Annotator +isDevelop: true +layout: docs +--- + +## Install from source + +This project’s source code is available directly [from the ASF](https://gitbox.apache.org/repos/asf?p=incubator-annotator.git) or [via GitHub](https://github.com/apache/incubator-annotator). + +### Requirements + +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 +- [yarn](https://www.yarnpkg.com/) version ^1.5 + +### Install + +To retrieve the code using git: + +``` +$ git clone https://gitbox.apache.org/repos/asf/incubator-annotator.git apache-annotator +``` + +Then install dependencies using yarn: + +```sh +$ cd apache-annotator +$ yarn install +``` + +## Build + +To compile (‘transpile’) the code: + +```sh +$ yarn build +``` + +For each module, the TypeScript source code is in `packages/…/src` and the Javascript is output in `packages/…/lib`. + +To use your local build of the code in an application that depends on annotator, have a look at the [`yarn link`](https://yarnpkg.com/cli/link) or [`npm link`](https://docs.npmjs.com/cli/v7/commands/npm-link) command. + +## Play + +To run a webserver running [the demo](https://annotator.apache.org/demo/): + +``` +$ yarn start +``` + +Now open `http://localhost:8080/` (or whichever address the command prints) in your web browser to play with the demo. The server continuously rebuilds and hot-reloads to the source code after any edits, so you can directly try out any changes you make to the features it demonstrates. + +## Run tests + +This runs the tests for all packages and reports their code coverage: + +```sh +$ yarn test +``` diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md index 5941fd3..1b110d9 100644 --- a/src/docs/getting-started.md +++ b/src/docs/getting-started.md @@ -4,4 +4,98 @@ isGettingStarted: true layout: docs --- -Please checkout the [demo](/demo/) for now, but we'll explain it here soon. +## Install via NPM + +Currently we only support installation through NPM packages. You will need to use a bundler (such as [webpack](https://webpack.js.org/)) to use the modules in a web browser. + +The project is made up of multiple modules. Each module is [available on the NPM registry](https://www.npmjs.com/org/apache-annotator) as individual packages in the `@apache-annotator` scope, and all of them together in the [`apache-annotator`](https://www.npmjs.com/package/apache-annotator) ‘meta-package’. You can install either and then import packages in your code as `@apache-annotator/package` or `apache-annotator/package`, respectively. + +For example: + +```sh +$ yarn add @apache-annotator/dom +``` + +…with in your code: + +```js +import { highlightRange } from '@apache-annotator/dom'; +``` + + +## Install from source + +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. + +First, we define the way to describe the user’s selection as a TextQuoteSelector. + +```js +import { describeTextQuote } from '@apache-annotator/dom'; + +async function describeCurrentSelection() { + const userSelection = window.getSelection()?.getRangeAt(0); + if (!userSelection || userSelection.isCollapsed) return; + return describeTextQuote(userSelection); +} +``` + +If the user had selected the word *“ipsum”* in the befamed *“Lorem ipsum dolor amet …”*, the return value of describeCurrentSelection() might resolve to this: + +``` +{ + type: 'TextQuoteSelector', + exact: 'ipsum', + prefix: 'Lorem ', + suffix: ' dolor' +} +``` + +The *prefix* and *suffix* attributes are there to know which of multiple occurrences of *“ipsum”* the Selector points to. They will include just enough surrounding words to make the selector unambiguous. + +Next, we define roughly the inverse function: given a TextQuoteSelector, we highlight the text it points to. + +```js +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); + for await (const match of matches) { + highlightRange(match); + } +} +``` + +As the [`for await … of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement suggests, the matcher does not return just one match, but a stream (an async iterable) of matches. This is because it cannot be certain that a selector only has a single match (even when it includes a prefix & suffix, perhaps the document changed!). + +We could use the functions defined above in many ways; keeping highlighted quotes in local storage, or in one’s bookmarks, or sharing them with others, and so on. For this example, we keep it simple and highlight each selection upon release of the mouse button; and store the selector to make it appear again after a page reload. + +```js +document.addEventListener('mouseup', async () => { + const selector = await describeCurrentSelection(); + const existingSelectors = JSON.parse(localStorage[document.URL] || '[]'); + localStorage[document.URL] = JSON.stringify([...existingSelectors, selector]); + await highlightSelectorTarget(selector); +}); + +// Highlight the last selection that was stored, if any. +async function highlightStoredSelectors() { + if (localStorage[document.URL]) { + const selectors = JSON.parse(localStorage[document.URL]); + for (const selector of selectors) { + await highlightSelectorTarget(selector); + } + } +} +highlightStoredSelectors(); +``` + +To see similar pieces of code in action, have a look at [the demo](/demo/). diff --git a/src/docs/index.md b/src/docs/index.md index 7101932..c533e42 100644 --- a/src/docs/index.md +++ b/src/docs/index.md @@ -4,7 +4,45 @@ isDocsIndex: true layout: docs --- -We're working on some initial documentation for getting started with Apache -Annotator, and to help folks understand how it fits in their projects. +Apache Annotator provides software modules to facilitate annotation tools in web browser environments. For example, it could be used in web-based document viewers or browser extensions that let users highlight phrases and place virtual sticky notes on the pages they visit. -Stay tuned for more! +The modules are written in [TypeScript](https://www.typescriptlang.org/), and distributed as Javascript/ECMAScript modules [on NPM](https://www.npmjs.com/org/apache-annotator). Read further for a high-level description of the code functionality, or [get started](/docs/getting-started/) with it directly! + + +## What is in the box + +### Selector tools + +The main functionality Apache Annotator offers is to map a [Web Annotation Selector](https://www.w3.org/TR/2017/REC-annotation-model-20170223/#selector) to the segment of a document it corresponds to, sometimes called ‘anchoring’ a Selector; and, vice versa, to create a Selector that describes a given selection in the document precisely and unambiguously, such that other Web Annotation software knows exactly where it points to. The purpose of Selectors is to point at any part of a docume [...] + +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) | + + +### Web Annotation JSON validator + +The source code also includes a script for validating Web Annotation Data Model JSON documents against the data model schema. Having [installed from source](/docs/develop/#install-from-source), one can run: + +```sh +$ yarn validate --url https://raw.githubusercontent.com/w3c/web-annotation-tests/master/tools/samples/correct/anno1.json +``` + +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 + +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 [...]
