Known Issues with Annotations and Modified Documents

When you use annotations with live documents (documents whose contents can be modified), you may encounter two kinds of problems: orphan annotations and misleading annotations. To explain these problems, we must first describe how Amaya attaches annotations to documents.

Amaya uses XPointer to indicate where an annotation should be attached to a document. XPointers are based in the structure of the document. To build an XPointer for a selection, for example, Amaya starts from the first point of the selection and walk backwards through the document's structure, until it finds the root of the document. If an element has an ID attribute, Amaya stops building the XPointer and considers the element with the ID attribute value to be the beginning of that XPointer.

For example, if you look at the HTML source for this document, you'll notice that this section is enclosed within a DIV element that has an ID attribute with the value "Issues" Here's an extract of the source code:

  <div id="Issues">
  <h1>Issues with ....</h1>
  <p>If you are using...</p>
  <p>Amaya uses <strong>XPointer</strong>...</p>
  ...
  </div>

This XPointer points to the second paragraph: xpointer(id("Issues")/p[2])

The above XPointer points to the second p element, from the element parent having an ID attribute with value "Issues".

Note that the use of the ID attribute enables the document author to move the entire reference by the XPointer to another location within the document, without needing to update the XPointer. The XPointer does not depend on the elements that precede it.

Orphan Annotations

An annotation becomes an "orphan" when it can no longer be attached to a document, that is, when the XPointer does not resolve to any element in the structure. This happens when a document's structure is modified. Amaya displays a warning if it detects any orphan annotations while downloading a set of annotations from an annotation server. All orphan annotations are visible from the Links view and are associated with an icon that shows a question mark superimposed on the annotation pencil .

Misleading Annotations

An annotation becomes "misleading" when it points to a wrong piece of information. This problem is common when you annotate a portion of text that may change. In the first release, Amaya does not warn the user if an annotation is misleading. A future release may notify users of the potential for an annotation to be misleading.

What can you do to avoid this?

As the author of a document, try to use the ID attribute in strategic places, for example, inside <DIV> and p elements. For example:

  <p id="Amaya">Amaya uses...</p>

An XPointer that points to this paragraph is: xpointer(id("Amaya"))

Thus, the Xpointer will point to the same paragraph, regardless of its position in the document's structure.

Amaya enables you to automatically associate with or remove an ID attribute to/from a set of elements by choosing Add/Remove ID from the Links menu.