| <!DOCTYPE html> |
| <html prefix="og: http://ogp.me/ns#" class="default"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1"> |
| <title>Apache Annotator (incubating)</title> |
| |
| <meta property="og:title" content="Apache Annotator" /> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="https://annotator.apache.org/" /> |
| <meta property="og:image:url" content="https://annotator.apache.org/images/annotator-logo.svg" /> |
| <meta property="og:image:alt" content="Apache Annotator (incubating) logo" /> |
| |
| <link rel="apple-touch-icon" sizes="180x180" href="/images/apple-touch-icon.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/images/favicon-32x32.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/images/favicon-16x16.png"> |
| <link rel="manifest" href="/site.webmanifest"> |
| <link rel="mask-icon" href="/images/safari-pinned-tab.svg" color="#5bbad5"> |
| <meta name="msapplication-TileColor" content="#da532c"> |
| <meta name="theme-color" content="#ffffff"> |
| |
| <link rel="alternate" title="DOAP" href="doap.rdf" type="application/rdf+xml" /> |
| |
| |
| <link rel="stylesheet" href="//semantic-ui.com/dist/semantic.min.css" /> |
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/prism-themes/themes/prism-vs.css" /> |
| <style> |
| html { |
| font-size: 17px; |
| } |
| |
| p, pre[class*="language-"] { |
| margin: .8em 0 1.25em; |
| } |
| </style> |
| </head> |
| |
| <body> |
| <div class="ui borderless stackable top attached main menu"> |
| <div class="ui container"> |
| <a class="item" href="/" style="color: rgba(0,0,0,.87);"> |
| <img class="ui small image" src="/images/annotator-logo.svg" alt="Apache Annotator (incubating)" /> |
| </a> |
| |
| <nav class="right menu"> |
| <a class="item" href="/">Home</a> |
| <a class="item" href="/demo/"><span class="ui positive button">Demo!</span></a> |
| <a class="active item" href="/docs/">Documentation</a> |
| <a class="item" rel="external" href="https://github.com/apache/incubator-annotator">Code <i class="small external icon"></i></a> |
| <a class="item" rel="external" href="https://github.com/apache/incubator-annotator/issues">Issue tracker <i class="small external icon"></i></a> |
| </nav> |
| </div> |
| </div> |
| <div class="ui basic segment container"> |
| |
| <nav class="ui secondary stackable pointing menu" style="justify-content: center;"> |
| <span class="item" style="background: #ff08">This documentation is for v0.2 (in development)</span> |
| <span class="item"></span> |
| <a href="/docs/" class="active item">Overview</a> |
| <a href="/docs/getting-started/" class="item">Getting Started</a> |
| <a href="/docs/develop/" class="item">Develop</a> |
| <a href="/docs/api/" class="item">API reference</a> |
| </nav> |
| |
| <main class="ui basic segment container"> |
| <h1 style="margin-bottom: 2rem">Overview</h1> |
| <div class="ui mobile reversed stackable grid"> |
| <div class="twelve wide column"> |
| <p>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.</p> |
| <p>The modules are written in <a href="https://www.typescriptlang.org/">TypeScript</a>, and distributed as Javascript/ECMAScript modules <a href="https://www.npmjs.com/org/apache-annotator">on NPM</a>. Read further for a high-level description of the code functionality, or <a href="/docs/getting-started/">get started</a> with it directly!</p> |
| <h2 id="what-is-in-the-box">What is in the box</h2> |
| <h3 id="selector-tools">Selector tools</h3> |
| <p>The main functionality Apache Annotator offers is to map a <a href="https://www.w3.org/TR/2017/REC-annotation-model-20170223/#selector">Web Annotation Selector</a> 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 document without requiring any modification of the document itself.</p> |
| <p>The <a href="https://www.w3.org/TR/annotation-model">W3C Web Annotation Data Model</a> 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.</p> |
| <table> |
| <thead> |
| <tr> |
| <th>Selector</th> |
| <th>Description</th> |
| <th>Implemented?</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#fragment-selector">Fragment</a></td> |
| <td>Uses the fragment part of an IRI defined by the representation’s media type.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#css-selector">CSS</a></td> |
| <td>CSS Selectors allow for a wide variety of well supported ways to describe the path to an element in a web page.</td> |
| <td>Yes (<a href="/docs/api/modules/dom.html#createcssselectormatcher">for DOM</a>)</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#xpath-selector">XPath</a></td> |
| <td>Implements an XPath based selection.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#text-quote-selector">Text Quote</a></td> |
| <td>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.</td> |
| <td>Yes (<a href="/docs/api/modules/dom.html#createtextquoteselectormatcher">for DOM</a> and <a href="/docs/api/modules/selector.html#textquoteselectormatcher">on any text</a>)</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#text-position-selector">Text Position</a></td> |
| <td>This Selector describes a range of text by recording the start and end positions of the selection in the stream.</td> |
| <td>Yes (<a href="/docs/api/modules/dom.html#createtextpositionselectormatcher">for DOM</a> and <a href="/docs/api/modules/selector.html#textpositionselectormatcher">on any text</a>)</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#data-position-selector">Data Position</a></td> |
| <td>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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#svg-selector">SVG</a></td> |
| <td>An SvgSelector defines an area through the use of the Scalable Vector Graphics standard.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#range-selector">Range</a></td> |
| <td>A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors.</td> |
| <td>Yes (<a href="/docs/api/modules/dom.html#makecreaterangeselectormatcher">for DOM</a>)</td> |
| </tr> |
| <tr> |
| <td><a href="https://www.w3.org/TR/annotation-model/#refinement-of-selection">Refinement</a></td> |
| <td>Select a part of a selection, rather than as a selection of the complete resource.</td> |
| <td><a href="/docs/api/modules/selector.html#makerefinable">Yes</a></td> |
| </tr> |
| </tbody> |
| </table> |
| <h3 id="web-annotation-json-validator">Web Annotation JSON validator</h3> |
| <p>The source code also includes a script for validating Web Annotation Data Model JSON documents against the data model schema. Having <a href="/docs/develop/#install-from-source">installed from source</a>, one can run:</p> |
| <pre class="language-shell"><code class="language-shell">$ <span class="token function">yarn</span> validate --url https://raw.githubusercontent.com/w3c/web-annotation-tests/master/tools/samples/correct/anno1.json</code></pre> |
| <p>With the <code>--url</code> option you can pass in a URL or a local path to a JSON file.</p> |
| <p>See some <a href="https://github.com/w3c/web-annotation-tests/tree/master/tools/samples">example JSON files</a> from the W3C. Note that this validator only tests the data model is followed, and not e.g. whether its target actually exists.</p> |
| <h2 id="what-apache-annotator-is-not">What Apache Annotator is not</h2> |
| <p>Apache Annotator is <strong>not an all-in-one annotation tool</strong>; rather, it <em>helps others create</em> 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.</p> |
| |
| </div> |
| <aside class="ui four wide column"> |
| <style> |
| .toc ol { |
| list-style-type: none; |
| padding-left: 1em; |
| } |
| .toc ol li { |
| margin: 0.25em 0; |
| } |
| </style> |
| <h1 class="ui small dividing header" style="margin: 0;">Contents</h1> |
| <nav class="toc"> |
| <ol><li><a href="#what-is-in-the-box">What is in the box</a><ol><li><a href="#selector-tools">Selector tools</a></li><li><a href="#web-annotation-json-validator">Web Annotation JSON validator</a></li></ol></li><li><a href="#what-apache-annotator-is-not">What Apache Annotator is not</a></li></ol></nav> |
| </aside> |
| </div> |
| </main> |
| |
| </div> |
| <footer class="ui bottom attached segment"> |
| <div class="ui container"> |
| <div class="ui equal height divided stackable grid"> |
| <div class="four wide column"> |
| <a class="ui left floated medium image" href="https://apache.org/" target="_blank"> |
| <img src="https://incubator.apache.org/images/incubator_feather_egg_logo_sm.png" alt="logo of the Apache Incubator" /> |
| </a> |
| <p> |
| <em>Copyright © 2016-2018 The Apache Software Foundation, Licensed under |
| the <a href="https://www.apache.org/licenses/LICENSE-2.0" rel="license external">Apache License, Version 2.0</a>. |
| | |
| <a rel="external" href="https://www.apache.org/foundation/policies/privacy">Privacy Policy</a> |
| </em> |
| </p> |
| </div> |
| <div class="nine wide column"> |
| <p> |
| <em>Apache Annotator is an effort undergoing incubation at <a target="_blank" href="https://apache.org/">The Apache Software Foundation (ASF)</a> sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.</em></p> |
| <p><em>Apache®, the names of Apache projects, and the feather logo are either <a rel="external" href="https://www.apache.org/foundation/marks/list/">registered trademarks or trademarks</a> of the Apache Software Foundation in the United States and/or other countries.</em></p> |
| </div> |
| <div class="three wide column"> |
| <h4 class="header">The <abbr title="Apache Software Foundation">ASF</abbr></h4> |
| <div class="ui link list"> |
| <a class="item" rel="external" href="https://incubator.apache.org/">Apache Incubator</a> |
| <a class="item" rel="external" href="https://www.apache.org/">About the ASF</a> |
| <a class="item" rel="external" href="https://www.apache.org/events/current-event">Events</a> |
| <a class="item" rel="external" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <a class="item" rel="external" href="https://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> |
| <a class="item" rel="external" href="https://www.apache.org/security/">Security</a> |
| <a class="item" rel="external" href="https://www.apache.org/licenses/">License</a> |
| </div> |
| </div> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
