Annotations are comments, notes, explanations, or other types of external remarks that can be attached to a Web document or a selected part of the document. As they are external, it is possible to annotate any Web document independently, without needing to edit that document. From the technical point of view, annotations are usually seen as metadata, as they give additional information about an existing piece of data. In this project, we use 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. Currently Amaya
presents annotations with pencil annotation icons ( 
)that are visually
embedded in the document, as shown in the figure below. If the user
single-clicks on an annotation icon, the text that was annotated is
highlighted. If the user double-clicks on this icon, the annotation text and
other metadata are presented in a separate window.
An annotation has many properties including:
Amaya can store annotation data in a local file system (often called "local annotations") or it can store annotations remotely, accessed through the World Wide Web (called "remote annotations").
You do not need a server to create local annotations. Local annotations are stored under the user preferences directory, in a special directory called annotations, and 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 annotation from the Annotations menu. Once this is completed, the local annotation is deleted because it has been moved to an annotation server.
Amaya can store annotation data in a local file system (often called "local annotations") or it can store annotations remotely, in Annotations Servers accessed through the World Wide Web (called "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.
Most of the commands needed for handling annotations can be found from the Annotations menu shown below. The commands are explained later in this document in the context of users' goals when handling annotations.
This version of Amaya supports two kinds of annotations: annotations that apply to a whole document and annotations that apply to a specific point or selection in a document.
After any of these options are performed, an annotation dialog displays the annotation metadata and the body of the annotation.
Currently, the metadata consists of the author's name, title of the annotated document, annotation type, creation date, and 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.
Saving an annotation is the same as saving any other document with Amaya: choose Savefrom the File menu (or use its equivalent shortcut or button).
Local annotations are saved to the annotations directory and remote annotations are saved to the annotation post server, where they are stored if the user has write access.
To convert a local annotation into a shared one, choose Post Annotation from the 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.
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.
The Delete command on the Annotation menu enables you to delete an annotation. You can invoke this command from an open annotation window.
To delete an annotation from a document:
The Load Annotations 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 the Configuration for annotations dialog, and ask for any relevant annotation.
Annotations can also be loaded automatically whenever a new page is viewed by selecting the Autoload Annotations check box in the Configuration for annotations dialog.
In this version of Amaya, querying an annotation server will return all the annotations that are associated with a document. In a future version, it may be possible to use a customized query menu to refine the query string that is sent to the servers.
Choose Local filter from the Annotations menu to show or hide the annotation icons in the document window. You can show or hide annotations by three types of metadata: the name of the annotation's author, the type of annotation, and the annotation server name.
To apply any of these filters:
Note:
The Annotation Local Filter Menu dialog only shows you the
annotations it knows about at the moment it is opened. If new annotations are
added, you will need to reload the menu again.
The annotation author shows the author's name added to the name of the annotation server where the annotation is stored.
Annotations can be navigated by choosing Show Links from the Views menu. The Link window opens and displays a list of annotations. Annotations in the Link and Document windows are marked with a pencil annotation icon.
The Link window shows all the annotations, without taking into account whether they have been hidden with Local filter on the Annotations menu. As with the document window, a single-click on the annotation selects the annotated text in the document window and a double-click opens the annotation. This is an example of how to navigate from one annotation link to another, even if the annotation cannot be seen by the user because of disabilities or because of the characteristics of the used device.
You can move an annotation to any other part of the same document. This can be used, for example, to handle orphan and misleading annotations. You can move an annotation to either the current selection or to the value of a stored XPointer. It is only possible to move annotations in the same document where they were created.
To move an annotation to a current selection:
To make this change effective, must save the annotation or you will loose the change. You can also move an annotation to the current position of the cursor, without having to make a selection.
You can store the position where you want to move an annotation to, and then move it there. This feature is useful for moving multiple annotations to the same position or for scrolling elsewhere in the document before doing the move.
To move multiple annotations:
Annotations can be seen as comments to pages. The Annotation / Replies feature enhances the collaborative workspace by allowing users to reply to annotations or to other replies.
The Annotations / Reply to annotation menu command lets you to 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 reply window opens. The fields in a reply window can be edited just like in an annotation window as explained under Creating an annotation.
When the reply is ready, you can post it to a server with Annotations / Post to Server menu command or save it locally using the File / Save menu command. To delete a reply, you can use the Annotations / Delete menu command.
Replies can also be annotated like any other document, as explained in Creating an annotation.
In the current user interface, 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 will be highlighted and presented in a reply window. When another selection is made the same reply window is used.
There is no control yet for controlling 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 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.
As of Release 6.2, the icon used to mark the location of an annotation within an annotated document may be changed by the user.
In release 6.2 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 that is shipped with release 6.2 associates the following icons:
 |
Advice |
 |
Change |
 |
Comment |
 |
Example |
 |
Explanation |
 |
Question |
 |
SeeAlso |
The property name for adding annotation icons is http://www.w3.org/2001/10/typeIcon#usesIcon. For instance, to specify an icon named file:///home/question-icon.jpg for annotations that have type http://www.w3.org/2000/10/annotationType#Question you would enter the following RDF/XML into a file that Amaya reads at startup is:
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:i = "http://www.w3.org/2001/10/typeIcon#"> <rdf:Description rdf:about="http://www.w3.org/2000/10/annotationType#Question"> <i:usesIcon rdf:resource="file:///home/question-icon.jpg" /> </rdf:Description> </rdf:RDF>
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 Amaya home directory; ~/.amaya/annot.schemas (on Unix systems) or /winnt/profiles/<username>/amaya/annot.schemas (on Microsoft Windows systems). 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.
Release 6.2 includes a sample file named "typeIcon.rdf" that declares unique icons for each annotation type declared in the http://www.w3.org/2000/10/annotationType# 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 Amaya home directory and change the line near the end to point to your revised icon definition file.
To revert to the previous behavior prior to release 6.2, edit the config/annot.schemas in the Amaya installation directory and add a comment character ("#") at the beginning of the line near the end that refers to typeIcon.rdf:
#user-defined icons #http://www.w3.org/2001/10/typeIcon# $THOTDIR/config/typeIcon.rdf
Amaya supports JPEG, PNG, and GIF bitmap graphics formats for icon images. In release 6.2 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.
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.
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 
.
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.
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.