Add note&workaround for issue #112 in 'Getting Started'
diff --git a/content/docs/getting-started/index.html b/content/docs/getting-started/index.html
index 17dd36b..7cbc8da 100644
--- a/content/docs/getting-started/index.html
+++ b/content/docs/getting-started/index.html
@@ -86,7 +86,7 @@
<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">}</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> <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><br> <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><br> <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> <span class="token punctuation">{</span><br> <span class="token function">highlightText</span><span class="token punctuation">(</span>match<span class="token punctuation">)</span><span class="token punctuation">;</span><br> <span class="token punctuation">}</span><br><span class="token punctuation">}</span></code></pre>
+<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> <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><br> <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><br><br> <span class="token comment">// Modifying the DOM while searching can mess up; see issue #112.</span><br> <span class="token comment">// Therefore, we first collect all matches before highlighting them.</span><br> <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><br> <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><br><br> <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><br><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 & 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 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><br> <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="token string">'[]'</span><span class="token punctuation">)</span><span class="token punctuation">;</span><br> 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="token punctuation">,</span> selector<span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span><br> <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><br><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><br><br><span class="token comment">// Highlight the last selection that was stored, if any.</span><br><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><br> <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><br> <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 punctuation">;</span><br> <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><br> <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><br> <span class="token punctuation">}</span><br> <span class="token punctuation">}</span><br><span class="token punctuation">}</span><br><span class="token function">highlightStoredSelectors</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md
index cf4ff6b..53035fe 100644
--- a/src/docs/getting-started.md
+++ b/src/docs/getting-started.md
@@ -70,9 +70,13 @@
async function highlightSelectorTarget(textQuoteSelector) {
const matches = createTextQuoteSelectorMatcher(textQuoteSelector)(document.body);
- for await (const match of matches) {
- highlightText(match);
- }
+
+ // Modifying the DOM while searching can mess up; see issue #112.
+ // Therefore, we first collect all matches before highlighting them.
+ const matchList = [];
+ for await (const match of matches) matchList.push(match);
+
+ for (const match of matchList) highlightText(match);
}
```
