This is an automated email from the ASF dual-hosted git repository.

bigbluehat pushed a commit to branch asf-site
in repository 
https://gitbox.apache.org/repos/asf/incubator-annotator-website.git

commit 72ddb44f9007203f3970a526141996067e950237
Author: BigBlueHat <byo...@bigbluehat.com>
AuthorDate: Sun Oct 1 16:28:14 2023 -0400

    Publish website (update `content/`)
---
 content/docs/develop/index.html         | 20 ++++++------
 content/docs/getting-started/index.html | 57 +++++++++++++++++++++++++++------
 content/docs/index.html                 | 15 +++++----
 3 files changed, 67 insertions(+), 25 deletions(-)

diff --git a/content/docs/develop/index.html b/content/docs/develop/index.html
index 0420d2c..ae143e3 100644
--- a/content/docs/develop/index.html
+++ b/content/docs/develop/index.html
@@ -75,30 +75,31 @@
   <h1 style="margin-bottom: 2rem">Develop Apache Annotator</h1>
   <div class="ui mobile reversed stackable grid">
     <div class="twelve wide column">
-      <h2 id="install-from-source">Install from source</h2>
+      <h2 id="install-from-source" tabindex="-1">Install from source</h2>
 <p>This project’s source code is available directly <a 
href="https://gitbox.apache.org/repos/asf?p=incubator-annotator.git";>from the 
ASF</a> or <a href="https://github.com/apache/incubator-annotator";>via 
GitHub</a>.</p>
-<h3 id="requirements">Requirements</h3>
+<h3 id="requirements" tabindex="-1">Requirements</h3>
 <p>If you’d like to code on the project, you will need the following:</p>
 <ul>
 <li><a href="https://git-scm.com/";>git</a></li>
 <li><a href="https://nodejs.org";>node</a> version ^12.20 || ^14.15 || ^15.4 || 
^16.0</li>
 <li><a href="https://www.yarnpkg.com/";>yarn</a> version ^1.5</li>
 </ul>
-<h3 id="install">Install</h3>
+<h3 id="install" tabindex="-1">Install</h3>
 <p>To retrieve the code using git:</p>
 <pre class="language-shell"><code class="language-shell">$ <span class="token 
function">git</span> clone 
https://gitbox.apache.org/repos/asf/incubator-annotator.git 
apache-annotator</code></pre>
 <p>Then install dependencies using yarn:</p>
-<pre class="language-shell"><code class="language-shell">$ <span class="token 
builtin class-name">cd</span> apache-annotator<br>$ <span class="token 
function">yarn</span> <span class="token function">install</span></code></pre>
-<h2 id="build">Build</h2>
+<pre class="language-shell"><code class="language-shell">$ <span class="token 
builtin class-name">cd</span> apache-annotator
+$ <span class="token function">yarn</span> <span class="token 
function">install</span></code></pre>
+<h2 id="build" tabindex="-1">Build</h2>
 <p>To compile (‘transpile’) the code:</p>
 <pre class="language-shell"><code class="language-shell">$ <span class="token 
function">yarn</span> build</code></pre>
 <p>For each module, the TypeScript source code is in 
<code>packages/…/src</code> and the Javascript is output in 
<code>packages/…/lib</code>.</p>
 <p>To use your local build of the code in an application that depends on 
annotator, have a look at the <a href="https://yarnpkg.com/cli/link";><code>yarn 
link</code></a> or <a 
href="https://docs.npmjs.com/cli/v7/commands/npm-link";><code>npm 
link</code></a> command.</p>
-<h2 id="play">Play</h2>
+<h2 id="play" tabindex="-1">Play</h2>
 <p>To run a webserver running <a href="https://annotator.apache.org/demo/";>the 
demo</a>:</p>
 <pre class="language-shell"><code class="language-shell">$ <span class="token 
function">yarn</span> start</code></pre>
 <p>Now open <code>http://localhost:8080/</code> (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.</p>
-<h2 id="run-tests">Run tests</h2>
+<h2 id="run-tests" tabindex="-1">Run tests</h2>
 <p>This runs the tests for all packages and reports their code coverage:</p>
 <pre class="language-shell"><code class="language-shell">$ <span class="token 
function">yarn</span> <span class="token builtin 
class-name">test</span></code></pre>
 
@@ -114,8 +115,9 @@
         }
       </style>
       <h1 class="ui small dividing header" style="margin: 0;">Contents</h1>
-      <nav class="toc">
-        <ol><li><a href="#install-from-source">Install from 
source</a><ol><li><a href="#requirements">Requirements</a></li><li><a 
href="#install">Install</a></li></ol></li><li><a 
href="#build">Build</a></li><li><a href="#play">Play</a></li><li><a 
href="#run-tests">Run tests</a></li></ol></nav>
+      <nav class="toc" >
+        <ol><li><a href="#install-from-source">Install from 
source</a><ol><li><a href="#requirements">Requirements</a></li><li><a 
href="#install">Install</a></li></ol></li><li><a 
href="#build">Build</a></li><li><a href="#play">Play</a></li><li><a 
href="#run-tests">Run tests</a></li></ol>
+      </nav>
     </aside>
   </div>
 </main>
diff --git a/content/docs/getting-started/index.html 
b/content/docs/getting-started/index.html
index b7c0c0b..0ec6b63 100644
--- a/content/docs/getting-started/index.html
+++ b/content/docs/getting-started/index.html
@@ -75,7 +75,7 @@
   <h1 style="margin-bottom: 2rem">Getting Started</h1>
   <div class="ui mobile reversed stackable grid">
     <div class="twelve wide column">
-      <h2 id="install-via-npm">Install via NPM</h2>
+      <h2 id="install-via-npm" tabindex="-1">Install via NPM</h2>
 <p>Currently we only support installation through NPM packages. You will need 
to use a bundler (such as <a href="https://webpack.js.org/";>webpack</a>) to use 
the modules in a web browser.</p>
 <p>The project is made up of multiple modules. Each module is <a 
href="https://www.npmjs.com/org/apache-annotator";>available on the NPM 
registry</a> as individual packages in the <code>@apache-annotator</code> 
scope, and all of them together in the <a 
href="https://www.npmjs.com/package/apache-annotator";><code>apache-annotator</code></a>
 ‘meta-package’. You can install either and then import packages in your code 
as <code>@apache-annotator/package</code> or <code>apache-annotator/package 
[...]
 <p>For example, for the latest official release:</p>
@@ -84,20 +84,58 @@
 <pre class="language-shell"><code class="language-shell">$ <span class="token 
function">yarn</span> <span class="token function">add</span> 
@apache-annotator/dom@dev</code></pre>
 <p>And in your code import what you need:</p>
 <pre class="language-js"><code class="language-js"><span class="token 
keyword">import</span> <span class="token punctuation">{</span> highlightText 
<span class="token punctuation">}</span> <span class="token 
keyword">from</span> <span class="token 
string">'@apache-annotator/dom'</span><span class="token 
punctuation">;</span></code></pre>
-<h2 id="install-from-source">Install from source</h2>
+<h2 id="install-from-source" tabindex="-1">Install from source</h2>
 <p>See <a href="/docs/develop/">Develop</a>.</p>
-<h2 id="usage-example%3A-a-text-quote-highlighter">Usage example: a text quote 
highlighter</h2>
+<h2 id="usage-example%3A-a-text-quote-highlighter" tabindex="-1">Usage 
example: a text quote highlighter</h2>
 <p>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).</p>
 <p>First, we define the way to describe the user’s selection as a <a 
href="https://www.w3.org/TR/2017/REC-annotation-model-20170223/#text-quote-selector";>TextQuoteSelector</a>.</p>
-<pre class="language-js"><code class="language-js"><span class="token 
keyword">import</span> <span class="token punctuation">{</span> 
describeTextQuote <span class="token punctuation">}</span> <span class="token 
keyword">from</span> <span class="token 
string">'@apache-annotator/dom'</span><span class="token 
punctuation">;</span><br><br><span class="token keyword">async</span> <span 
class="token keyword">function</span> <span class="token 
function">describeCurrentSelection</span><span cla [...]
+<pre class="language-js"><code class="language-js"><span class="token 
keyword">import</span> <span class="token punctuation">{</span> 
describeTextQuote <span class="token punctuation">}</span> <span class="token 
keyword">from</span> <span class="token 
string">'@apache-annotator/dom'</span><span class="token punctuation">;</span>
+
+<span class="token keyword">async</span> <span class="token 
keyword">function</span> <span class="token 
function">describeCurrentSelection</span><span class="token 
punctuation">(</span><span class="token punctuation">)</span> <span 
class="token punctuation">{</span>
+  <span class="token keyword">const</span> userSelection <span class="token 
operator">=</span> window<span class="token punctuation">.</span><span 
class="token function">getSelection</span><span class="token 
punctuation">(</span><span class="token punctuation">)</span><span class="token 
operator">?.</span><span class="token function">getRangeAt</span><span 
class="token punctuation">(</span><span class="token number">0</span><span 
class="token punctuation">)</span><span class="token punct [...]
+  <span class="token keyword">if</span> <span class="token 
punctuation">(</span><span class="token operator">!</span>userSelection <span 
class="token operator">||</span> userSelection<span class="token 
punctuation">.</span>isCollapsed<span class="token punctuation">)</span> <span 
class="token keyword">return</span><span class="token punctuation">;</span>
+  <span class="token keyword">return</span> <span class="token 
function">describeTextQuote</span><span class="token 
punctuation">(</span>userSelection<span class="token punctuation">)</span><span 
class="token punctuation">;</span>
+<span class="token punctuation">}</span></code></pre>
 <p>If the user had selected the word <em>“ipsum”</em> in the befamed 
<em>“Lorem ipsum dolor amet …”</em>, the return value of 
describeCurrentSelection() might resolve to this:</p>
-<pre class="language-json"><code class="language-json"><span class="token 
punctuation">{</span><br>  type<span class="token operator">:</span> 
'TextQuoteSelector'<span class="token punctuation">,</span><br>  exact<span 
class="token operator">:</span> 'ipsum'<span class="token 
punctuation">,</span><br>  prefix<span class="token operator">:</span> 'Lorem 
'<span class="token punctuation">,</span><br>  suffix<span class="token 
operator">:</span> ' dolor'<br><span class="token punctuation">}< [...]
+<pre class="language-json"><code class="language-json"><span class="token 
punctuation">{</span>
+  type<span class="token operator">:</span> 'TextQuoteSelector'<span 
class="token punctuation">,</span>
+  exact<span class="token operator">:</span> 'ipsum'<span class="token 
punctuation">,</span>
+  prefix<span class="token operator">:</span> 'Lorem '<span class="token 
punctuation">,</span>
+  suffix<span class="token operator">:</span> ' dolor'
+<span class="token punctuation">}</span></code></pre>
 <p>The <em>prefix</em> and <em>suffix</em> attributes are there to know which 
of multiple occurrences of <em>“ipsum”</em> the Selector points to. They will 
include just enough surrounding words to make the selector unambiguous.</p>
 <p>Next, we define roughly the inverse function: given a TextQuoteSelector, we 
highlight the text it points to.</p>
-<pre class="language-js"><code class="language-js"><span class="token 
keyword">import</span> <span class="token punctuation">{</span> 
createTextQuoteSelectorMatcher<span class="token punctuation">,</span> 
highlightText <span class="token punctuation">}</span> <span class="token 
keyword">from</span> <span class="token 
string">'@apache-annotator/dom'</span><span class="token 
punctuation">;</span><br><br><span class="token keyword">async</span> <span 
class="token keyword">function</span> <s [...]
+<pre class="language-js"><code class="language-js"><span class="token 
keyword">import</span> <span class="token punctuation">{</span> 
createTextQuoteSelectorMatcher<span class="token punctuation">,</span> 
highlightText <span class="token punctuation">}</span> <span class="token 
keyword">from</span> <span class="token 
string">'@apache-annotator/dom'</span><span class="token punctuation">;</span>
+
+<span class="token keyword">async</span> <span class="token 
keyword">function</span> <span class="token 
function">highlightSelectorTarget</span><span class="token 
punctuation">(</span><span class="token 
parameter">textQuoteSelector</span><span class="token punctuation">)</span> 
<span class="token punctuation">{</span>
+  <span class="token keyword">const</span> matches <span class="token 
operator">=</span> <span class="token 
function">createTextQuoteSelectorMatcher</span><span class="token 
punctuation">(</span>textQuoteSelector<span class="token 
punctuation">)</span><span class="token punctuation">(</span>document<span 
class="token punctuation">.</span>body<span class="token 
punctuation">)</span><span class="token punctuation">;</span>
+
+  <span class="token comment">// Modifying the DOM while searching can mess 
up; see issue #112.</span>
+  <span class="token comment">// Therefore, we first collect all matches 
before highlighting them.</span>
+  <span class="token keyword">const</span> matchList <span class="token 
operator">=</span> <span class="token punctuation">[</span><span class="token 
punctuation">]</span><span class="token punctuation">;</span>
+  <span class="token keyword">for</span> <span class="token 
keyword">await</span> <span class="token punctuation">(</span><span 
class="token keyword">const</span> match <span class="token keyword">of</span> 
matches<span class="token punctuation">)</span> matchList<span class="token 
punctuation">.</span><span class="token function">push</span><span class="token 
punctuation">(</span>match<span class="token punctuation">)</span><span 
class="token punctuation">;</span>
+
+  <span class="token keyword">for</span> <span class="token 
punctuation">(</span><span class="token keyword">const</span> match <span 
class="token keyword">of</span> matchList<span class="token 
punctuation">)</span> <span class="token function">highlightText</span><span 
class="token punctuation">(</span>match<span class="token 
punctuation">)</span><span class="token punctuation">;</span>
+<span class="token punctuation">}</span></code></pre>
 <p>As the <a 
href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of";><code>for
 await … of</code></a> 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 &amp; suffix, perhaps the document changed!).</p>
 <p>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.</p>
-<pre class="language-js"><code class="language-js">document<span class="token 
punctuation">.</span><span class="token function">addEventListener</span><span 
class="token punctuation">(</span><span class="token 
string">'mouseup'</span><span class="token punctuation">,</span> <span 
class="token keyword">async</span> <span class="token 
punctuation">(</span><span class="token punctuation">)</span> <span 
class="token operator">=></span> <span class="token punctuation">{</span><br>  
<span clas [...]
+<pre class="language-js"><code class="language-js">document<span class="token 
punctuation">.</span><span class="token function">addEventListener</span><span 
class="token punctuation">(</span><span class="token 
string">'mouseup'</span><span class="token punctuation">,</span> <span 
class="token keyword">async</span> <span class="token 
punctuation">(</span><span class="token punctuation">)</span> <span 
class="token operator">=></span> <span class="token punctuation">{</span>
+  <span class="token keyword">const</span> selector <span class="token 
operator">=</span> <span class="token keyword">await</span> <span class="token 
function">describeCurrentSelection</span><span class="token 
punctuation">(</span><span class="token punctuation">)</span><span class="token 
punctuation">;</span>
+  <span class="token keyword">const</span> existingSelectors <span 
class="token operator">=</span> <span class="token constant">JSON</span><span 
class="token punctuation">.</span><span class="token 
function">parse</span><span class="token punctuation">(</span>localStorage<span 
class="token punctuation">[</span>document<span class="token 
punctuation">.</span><span class="token constant">URL</span><span class="token 
punctuation">]</span> <span class="token operator">||</span> <span class=" [...]
+  localStorage<span class="token punctuation">[</span>document<span 
class="token punctuation">.</span><span class="token constant">URL</span><span 
class="token punctuation">]</span> <span class="token operator">=</span> <span 
class="token constant">JSON</span><span class="token punctuation">.</span><span 
class="token function">stringify</span><span class="token 
punctuation">(</span><span class="token punctuation">[</span><span class="token 
operator">...</span>existingSelectors<span class [...]
+  <span class="token keyword">await</span> <span class="token 
function">highlightSelectorTarget</span><span class="token 
punctuation">(</span>selector<span class="token punctuation">)</span><span 
class="token punctuation">;</span>
+<span class="token punctuation">}</span><span class="token 
punctuation">)</span><span class="token punctuation">;</span>
+
+<span class="token comment">// Highlight the last selection that was stored, 
if any.</span>
+<span class="token keyword">async</span> <span class="token 
keyword">function</span> <span class="token 
function">highlightStoredSelectors</span><span class="token 
punctuation">(</span><span class="token punctuation">)</span> <span 
class="token punctuation">{</span>
+  <span class="token keyword">if</span> <span class="token 
punctuation">(</span>localStorage<span class="token 
punctuation">[</span>document<span class="token punctuation">.</span><span 
class="token constant">URL</span><span class="token punctuation">]</span><span 
class="token punctuation">)</span> <span class="token punctuation">{</span>
+    <span class="token keyword">const</span> selectors <span class="token 
operator">=</span> <span class="token constant">JSON</span><span class="token 
punctuation">.</span><span class="token function">parse</span><span 
class="token punctuation">(</span>localStorage<span class="token 
punctuation">[</span>document<span class="token punctuation">.</span><span 
class="token constant">URL</span><span class="token punctuation">]</span><span 
class="token punctuation">)</span><span class="token  [...]
+    <span class="token keyword">for</span> <span class="token 
punctuation">(</span><span class="token keyword">const</span> selector <span 
class="token keyword">of</span> selectors<span class="token 
punctuation">)</span> <span class="token punctuation">{</span>
+      <span class="token keyword">await</span> <span class="token 
function">highlightSelectorTarget</span><span class="token 
punctuation">(</span>selector<span class="token punctuation">)</span><span 
class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+  <span class="token punctuation">}</span>
+<span class="token punctuation">}</span>
+<span class="token function">highlightStoredSelectors</span><span class="token 
punctuation">(</span><span class="token punctuation">)</span><span class="token 
punctuation">;</span></code></pre>
 <p>To see similar pieces of code in action, have a look at <a 
href="/demo/">the demo</a>.</p>
 
     </div>
@@ -112,8 +150,9 @@
         }
       </style>
       <h1 class="ui small dividing header" style="margin: 0;">Contents</h1>
-      <nav class="toc">
-        <ol><li><a href="#install-via-npm">Install via NPM</a></li><li><a 
href="#install-from-source">Install from source</a></li><li><a 
href="#usage-example%3A-a-text-quote-highlighter">Usage example: a text quote 
highlighter</a></li></ol></nav>
+      <nav class="toc" >
+        <ol><li><a href="#install-via-npm">Install via NPM</a></li><li><a 
href="#install-from-source">Install from source</a></li><li><a 
href="#usage-example%3A-a-text-quote-highlighter">Usage example: a text quote 
highlighter</a></li></ol>
+      </nav>
     </aside>
   </div>
 </main>
diff --git a/content/docs/index.html b/content/docs/index.html
index ad485a8..363c35b 100644
--- a/content/docs/index.html
+++ b/content/docs/index.html
@@ -77,8 +77,8 @@
     <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>
+<h2 id="what-is-in-the-box" tabindex="-1">What is in the box</h2>
+<h3 id="selector-tools" tabindex="-1">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 pa [...]
 <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>
@@ -137,12 +137,12 @@
 </tr>
 </tbody>
 </table>
-<h3 id="web-annotation-json-validator">Web Annotation JSON validator</h3>
+<h3 id="web-annotation-json-validator" tabindex="-1">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>
+<pre class="language-shell"><code class="language-shell">$ <span class="token 
function">yarn</span> validate <span class="token parameter 
variable">--url</span> 
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>
+<h2 id="what-apache-annotator-is-not" tabindex="-1">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: find [...]
 
     </div>
@@ -157,8 +157,9 @@
         }
       </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>
+      <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>

Reply via email to