Annotating documents

What is an annotation?

Annotations are comments, notes, explanations, or other types of external remarks that can be attached to a Web document or to a selected part of a document. As they are external, it is possible to annotate any Web document independently, without needing to edit the document itself. From a technical point of view, annotations are usually seen as metadata, as they give additional information about an existing piece of data. Amaya uses a special RDF annotation schema for describing annotations.

Annotations can be stored locally or in one or more annotation servers. When a document is browsed, Amaya queries each of these servers, requesting the annotations related to that document. Amaya presents an annotation with an icon Pencil representing an annotation that is visually embedded in the document. If you single-click this icon, the text that was annotated is highlighted. If you double-clicks the icon, the annotation text and other metadata are presented in a separate window.

An annotation has many properties including:

Local and remote annotations

Amaya can store annotation data in a local file system (local annotations) or it can store annotations remotely, on annotations servers accessed through the Web (remote annotations).

You do not need a server to create local annotations. Local annotations are stored under your AmayaHome directory, in a special directory called annotations, and they can be seen only by their owner (according to the system access right setup).

This directory contains three kinds of files:

At any time, you can convert a local annotation to a shared one by choosing Post to server from the Tools/Annotations submenu. Once this is completed, the local annotation is deleted because it has been moved to an annotation server.

Remote annotations

You can store remote annotations in annotation servers so that the annotations can be downloaded by anyone having the correct access rights, such as is the case of other HTML documents.

Remote annotations are referred to as shared or public annotations, because they can be seen by other people. If you wish to install your own annotation server, please refer to Annotation-Server-HOWTO.

Creating an annotation

Before creating an annotation, it is recommended to set some parameters in the Preferences (see section Configuring annotations).

Amaya supports two kinds of annotations: annotations that apply to a whole document and annotations that apply to a specific position or a selection in a document.

After these operations, an annotation document  is displayed, with some inital metadata and an empty body.

The metadata consists of the title of the annotation, the author's name, the title of the annotated document, the annotation type, the creation date, and the last modification date.

Some of the metadata fields have special properties:

Below the header area is the annotation body area. It shows the current content and can be edited like any other HTML document.

Some commands that can be applied to a document in the Amaya document window also can be applied to an annotation document in the Annotation window. For example, the body of an annotation can be printed by choosing Print from the File menu, or reloaded by choosing Reload document from the File menu.

Saving an annotation

Saving an annotation is the same as saving any other document with Amaya: choose Save from the File menu (or use its equivalent shortcut or button) or press the Save button.

Local annotations are saved to the annotations directory and remote annotations are saved to the annotation post server, if the user has write access.

To convert a local annotation into a shared one, choose Post to server from the Tools/Annotations menu to save the annotation to the Post server as defined in the Configuration for Annotations dialog. If this operation is successful, the local annotation will be removed and future Save operations will go directly to that annotation server.

Deleting an annotation

The Delete command on the Tools/Annotations submenu enables you to delete the current annotation. You can invoke this command from an annotation window.

You can also delete an annotation from the annotated document. Select the icon of the annotation and call the same command from the Tools menu in the annotated document window.

Loading and presenting annotations

The Tools/Annotations/Load command tells Amaya to load the annotations that are associated with the URL of the current document. Amaya will query the annotation servers, using the settings from Preferences/Annotations, and ask for any relevant annotation.

Annotations may also be loaded automatically whenever a new page is viewed by selecting the Autoload remote annotations check box in Preferences/Annotations.

Querying an annotation server returns all the annotations that are associated with a document.

Annotations in the Links window

The link view of the annotated document shows all the annotations.

As with the document window, annotations are identified by a pencil icon. A single-click on the icon selects the annotated text in the document window and a double-click opens the annotation.

Replying to annotations / discussion thread

Annotations can be seen as comments to web pages. The Tools/Annotations/Reply to annotation command enhances the collaborative workspace by allowing users to reply to annotations or to other replies.

The Reply to annotation command of the Tools/Annotations submenu lets you create a reply to an existing annotation or to a reply. You can invoke this command from an open annotation or a reply window.

As a result a new annotation document opens. The fields in a reply annotation can be edited just like in any other annotation as explained under Creating an annotation.

When the reply is ready, you can post it to a server with the Tools/Annotations/Post to server command or you can save it locally using the File/Save command. To delete a reply, you can use the Tools/Annotations/Delete command.

Replies can also be annotated like any other document, as explained in Creating an annotation.

All replies related to an annotation are shown at the bottom of this annotation, in a thread section. Each item in the thread gives the date of the reply, the author, and the title of the reply.

The content of any of these replies can be retrieved by double clicking the replies in the thread. The selected reply is highlighted and presented in a reply tab. When another selection is made the same reply tab is used.

Known issues: incomplete thread

There is no way to control which replies should be posted. In an ideal world, it should not be possible to save a reply to a reply if the previous reply was not saved in the same server. Likewise, if you delete a reply, you should delete all replies to this annotation. Not doing that leads to having fragments of threads that cannot be correctly attached in the thread.

For example, let R1 be the reply to annotation A1 and R2 a reply to R1. If you post R1, and let R2 be stored locally, then when you browse A1 and only download its local annotations, you will only see R2.

At this point, Amaya does not know that R1 exists, so it assumes that R2 has lost its parent. We identify these "orphan" threads by putting a question mark symbol ? in front of them. If later one, Amaya finds new thread items, for example, if you download R1, Amaya will then sort the thread view, inserting the threads as appropriately. In our example, R2 will become a child of R1, as expected.

Configuring annotation icons

User-definable icons by Annotation type (aka "dynamic icons")

The icon used to mark the location of an annotation within an annotated document may be changed by the user. The icon that denotes an annotation is chosen as a property of the annotation type. By including an RDF property of each annotation type you wish to use, you select the icon associated with annotations of that type.

The sample configuration associates the following icons:

Advice Advice
Change Change
Comment Comment
Example Example
Explanation Explanation
Question Question
SeeAlso SeeAlso

The property name for adding annotation icons is For instance, to specify an icon named file:///home/question-icon.jpg for annotations that have type you would enter the following RDF/XML into a file that Amaya reads at startup is:

   xmlns:i = "">
<rdf:Description rdf:about="">
  <i:usesIcon rdf:resource="file:///home/question-icon.jpg" />

The simplest way to get such RDF loaded into Amaya at startup is to include the file in the config/annot.schemas file in the Amaya program directory. In order to preserve this file so that it will not be overwritten when you install a new version of Amaya, you should copy the config/annot.schemas file into your personal AmayaHome directory.

You may list as many RDF files as you want in annot.schemas. See the comments in the file included in the Amaya kit for more details.

A sample file named typeIcon.rdf declares unique icons for each annotation type declared in the namespace. To experiment with user-defined icons, it may be easiest to copy this typeIcon.rdf into another directory and modify it. Copy annot.schemas to your AmayaHome directory and change the line near the end to point to your revised icon definition file.

Amaya supports JPEG, PNG, and GIF bitmap graphics formats for icon images. The icon URI may only be a file: URI; that is, the icon must appear in a local or mounted directory to Amaya. Two special forms of non-file: URIs are supported. If the file path name starts with $THOTDIR or $APP_HOME then the corresponding Amaya installation directory or personal Amaya home directory is substituted into the pathname.

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>

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 Orphan annotation icon .

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 IDs from the Links menu.