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 
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:
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:
annot.index: Associates URLs with the files containing the
metadata of the annotations.index + random suffix: Stores the metadata of the
annotations related to a given URL. The metadata is specified in RDF. annot + random suffix.html: Contains the body of an
annotation, stored as XHTML.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.
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.
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 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.
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.
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.
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.
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.
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.
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 |
 |
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 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 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 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.
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 IDs from the Links menu.