A(N) Is an Annotation That the Author or a Reviewer Adds to the Document

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 certificate. As they are external, it is possible to comment any Web certificate independently, without needing to edit the document itself. From a technical bespeak of view, annotations are usually seen every bit metadata, as they give boosted information nigh an existing piece of data. Amaya uses a special RDF annotation schema for describing annotations.

Annotations can exist stored locally or in 1 or more note 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 yous double-clicks the icon, the annotation text and other metadata are presented in a separate window.

An annotation has many properties including:

• Physical location: is the notation stored in the local file system or in an annotation server
• Telescopic: is the note associated to a whole document or simply to a fragment.
• Annotation type: 'Note', 'Annotate', 'Query', ...

Local and remote annotations

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

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

This directory contains three kinds of files:

• annot.alphabetize: 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 torso of an annotation, stored as XHTML.

At whatsoever time, you lot can convert a local note to a shared 1 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 shop remote annotations in annotation servers and then that the annotations tin can be downloaded past anyone having the correct access rights, such as is the case of other HTML documents.

Remote annotations are referred to equally shared or public annotations, because they can be seen past other people. If you wish to install your own notation server, delight refer to Notation-Server-HOWTO.

Creating an annotation

Before creating an annotation, information technology is recommended to set up some parameters in the Preferences (run into section Configuring annotations).

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

• To annotate an entire document, cull Annotate certificate from the Tools/Annotations menu.
• To comment a position, put the insertion indicate at that position in the document and cull Annotate selection from the Tools/Annotations menu.
• To annotate a selection, make a option in the document and choose Comment pick from the Tools/Annotations card.

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

The metadata consists of the title of the annotation, the author'southward proper noun, the championship of the annotated document, the note blazon, the creation engagement, and the last modification engagement.

Some of the metadata fields have special properties:

• The Source document field is a link that points back to the annotated text. If the user double-clicks it, as when following any other link with Amaya, the annotated document volition exist displayed with the annotated text highlighted.
• The Annotation types field lets you allocate the annotation and change its blazon. Double-click on the text Annotation type to see the list of types bachelor.
• The Final modified field is updated automatically each fourth dimension that an annotation is saved.

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

Some commands that can exist applied to a certificate in the Amaya document window also can be applied to an notation document in the Annotation window. For example, the trunk of an annotation can be printed by choosing Impress from the File menu, or reloaded by choosing Reload document from the File bill of fare.

Saving an annotation

Saving an annotation is the same every bit saving whatsoever other certificate with Amaya: choose Save from the File card (or use its equivalent shortcut or button) or press the Save push.

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

To convert a local notation into a shared one, choose Post to server from the Tools/Annotations menu to relieve the annotation to the Post server as defined in the Configuration for Annotations dialog. If this performance 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. Yous can invoke this command from an annotation window.

You can as well 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 certificate. Amaya will query the annotation servers, using the settings from Preferences/Annotations, and ask for any relevant annotation.

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

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

Annotations in the Links window

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

Equally with the document window, annotations are identified past a pencil icon. A unmarried-click on the icon selects the annotated text in the document window and a double-click opens the notation.

Replying to annotations / discussion thread

Annotations can exist seen every bit comments to web pages. The Tools/Annotations/Answer to note control enhances the collaborative workspace by allowing users to reply to annotations or to other replies.

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

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

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

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

All replies related to an note are shown at the lesser of this notation, in a thread section. Each detail 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 exist retrieved by double clicking the replies in the thread. The selected reply is highlighted and presented in a answer tab. When another pick is made the same reply tab is used.

Known problems: incomplete thread

In that location is no way to control which replies should be posted. In an platonic world, it should not be possible to salve a answer to a reply if the previous answer was not saved in the same server. Also, 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 case, let R1 be the answer to note A1 and R2 a respond to R1. If you postal service R1, and permit R2 be stored locally, and then when you scan A1 and only download its local annotations, you will merely see R2.

At this bespeak, 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 i, Amaya finds new thread items, for case, if y'all download R1, Amaya will then sort the thread view, inserting the threads every bit accordingly. In our instance, 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 certificate may be changed by the user. The icon that denotes an notation is called equally a property of the notation type. Past including an RDF property of each annotation blazon you wish to utilize, you lot select the icon associated with annotations of that blazon.

The sample configuration associates the following icons:

	Advice
	Change
	Comment
	Example
	Explanation
	Question
	SeeAlso

The holding name for calculation notation 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 blazon 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/x/typeIcon#"> <rdf:Description rdf:about="http://www.w3.org/2000/10/annotationType#Question">   <i:usesIcon rdf:resource="file:///dwelling house/question-icon.jpg" /> </rdf:Clarification> </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 and then that it volition not be overwritten when you lot install a new version of Amaya, y'all should re-create the config/annot.schemas file into your personal AmayaHome directory.

You may list as many RDF files equally you desire in annot.schemas. See the comments in the file included in the Amaya kit for more than 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 change it. Re-create annot.schemas to your AmayaHome directory and change the line most the cease 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 announced 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 so the corresponding Amaya installation directory or personal Amaya domicile directory is substituted into the pathname.

Known bug with annotations and modified documents

When you use annotations with live documents (documents whose contents can be modified), yous may run into 2 kinds of problems: orphan annotations and misleading annotations. To explain these problems, we must get-go describe how Amaya attaches annotations to documents.

Amaya uses XPointer to signal where an notation should be attached to a document. XPointers are based in the structure of the document. To build an XPointer for a pick, for instance, Amaya starts from the first point of the selection and walk backwards through the document's structure, until information technology finds the root of the certificate. If an element has an id attribute, Amaya stops building the XPointer and considers the chemical element with the id attribute value to be the showtime of that XPointer.

For case, if you look at the HTML source for this document, you'll observe that this section is enclosed within a div element that has an id attribute with the value "Problems" Hither's an extract of the source lawmaking:

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

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

The to a higher place XPointer points to the second p element, from the element parent having an id aspect with value "Problems".

Note that the use of the id attribute enables the document author to move the entire reference past the XPointer to another location inside 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 whatsoever element in the construction. This happens when a document's construction is modified. Amaya displays a warning if it detects any orphan annotations while downloading a set up 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 notation pencil .

Misleading annotations

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

What can you do to avert this?

As the author of a document, try to apply the ID aspect 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 volition point to the same paragraph, regardless of its position in the document'south construction.

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

garnerourty1983.blogspot.com

Source: https://www.w3.org/Amaya/User/doc/Annotations.html