PC World 2001 April

home *** CD-ROM | disk | FTP | other *** search

/ PC World 2001 April / PCWorld_2001-04_cd.bin / Komunik / Amaya / WinNT2000 / amaya-WindowsNT-4.3.exe / _SETUP.1 / Annotations.html < prev next >

Wrap

Extensible Markup Language | 2001-02-22 | 20.8 KB | 399 lines

<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Annotations in Amaya</title> <meta name="GENERATOR" content="amaya V4.2.2" /> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> </head> <body> <table border="0" width="100%" summary="toc"> <tbody> <tr> <td><img border="0" alt="W3C" src="../../Icons/WWW/w3c_home" /> <img border="0" alt="Amaya" src="../Icons/amaya.gif" /></td> <td><a href="MakeBook.html" accesskey="p"><img alt="previous" border="0" src="../Icons/left.gif" /></a> <a href="Manual.html" accesskey="t"><img alt="top" border="0" src="../Icons/up.gif" /></a> <a href="Configure.html" accesskey="n"><img alt="next" border="0" src="../Icons/right.gif" /></a> </td> </tr> </tbody> </table> <ul> <li><a href="#What">What is an Annotation</a></li> <li><a href="#Local">Local and Remote Annotations</a></li> <li><a href="#Annotation">Annotations Menu</a></li> <li><a href="#Configurat">Configuration Settings for Annotations</a></li> <li><a href="#Creating1">Creating an Annotation</a></li> <li><a href="#Deleting">Deleting an Annotation</a></li> <li><a href="#Loading">Loading and Presenting Annotations</a></li> <li><a href="#Navigating">Navigating Annotations</a></li> <li><a href="#Issues1">Issues with Annotations and Modified Documents</a></li> </ul> <div id="Annotations"> <h2>Annotations in Amaya</h2> <h3><a name="What">What is an Annotation?</a></h3> 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 <a href="http://www.w3.org/RDF/">RDF</a> <a href="http://www.w3.org/2000/10/annotation-ns">annotation schema</a> 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 ( <img src="../Icons/annot.png" alt="Annotation pencil icon" /> )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. <img src="../Icons/annotationicon.png" alt="annotation icon (= pencil)" /> An annotation has many properties including: <ul> <li>Physical location: is the annotation stored in a local file system or in an annotation server</li> <li>Scope: is the annotation associated to a whole document or just to a fragment of this document</li> <li>Annotation type: 'Annotation', 'Comment', 'Query', ...</li> </ul> <h3 id="Local">Local and remote annotations</h3> Amaya can store annotation data in a local file system (called "local annotations") or in the Web (called "remote annotations"). Remote annotations are stored in annotation servers and can be downloaded and stored by anyone having the correct access rights, such as is the case of other HTML documents. We also refer to remote annotations as shared or public annotations, as they can be seen by other people. If you wish to install your own annotation server, please refer to <a href="http://www.w3.org/1999/02/26-modules/User/Annotations-HOWTO.html">Annotation-Server-HOWTO</a>. The user doesn't need a server to make local annotations. Local annotations are stored under the <a href="/home/kahan/Amaya/doc/amaya/Configure.html">user preferences directory</a>, in a special directory called <code>annotations</code>, and can be seen only by their owner (according to the system access right setup). This directory is made of three kinds of files: <dl> <dt>annot.index</dt> <dd>associates URLs with the files where the metadata of the annotations are stored.</dd> <dt>index + random suffix</dt> <dd>a file that stores the metadata of the annotations related to a given URL. The metadata is specified with RDF.</dd> <dt>annot + random suffix.html</dt> <dd>contains the body of an annotation, stored as XHTML.</dd> </dl> At any time, a user can convert a local annotation to a shared one, by using the Annotations/Post annotation menu entry. If this operation is succesful, the local annotation will be deleted, as it will have been moved to an annotation server. The following section describes how to set up the name of the server to which annotations should be posted. <h3 id="Annotation">Annotations Menu</h3> 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. <img src="../Icons/annotationsmenu.png" alt="Annotations menu" /> <h3 id="Configurat">Configuration Settings for Annotations</h3> The annotations configuration menu is found under theAnnotations/Configure menu entry. The following figure shows the Windows version of this menu. The Unix version has a slightly different user interface, but the same functionalities. <img src="../Icons/configurebox.png" alt="configuration dialog box" /> <dl> <dt>Annotation user</dt> <dd>A field that is associated with each new annotation as the author of the annotation. By default, Amaya uses the login name of the user when building the author metadata field. The annotation user setting allows a user to change this name to a more significant one, for example, from <code>u1723242</code> (which makes happy my system administrator) to <code>marja</code> (which other people normally use when talking with me)<code>.</code></dd> <dt>Annotation servers</dt> <dd>This setting tells Amaya what servers it should contact when looking for annotations. You can specify one or more servers. We use the reserved server name localhost to tell Amaya we want to search the local annotations. It doesn't mean we're running a local annotation server. If that were the case, we would need to give its complete URL. Under Unix, the annotation servers are specified as a space separated list. Under Windows, they are added one after the other by directly typing their names in the dialog box, using the <code>Return</code> key to add a new one. By default, the annotation servers field is initialized to <code>localhost</code>. TIP: If you want to temporarily disable an annotation server, add a "-" char before its URL. Amaya will ignore it. </dd> <dt>Autoload local annotations/Autoload remote annotations</dt> <dd>These setting tells Amaya whether or not to request annotations automatically (that is, query the annotation servers ) every time that a URL is browsed. If it's not checked, then the user has to manually invoke the Load annotations function from the Annotations menu. Note that the if you check the <code>autoload remote annotations</code>option, there may be a delay when Amaya resolves the DNS name of the annotation servers. By default, both these options are turned off.</dd> <dt>Disable remote autoload at each startup</dt> <dd>If this option is checked, Amaya will reset the <code>autoload remote annotations</code> option at launch time. This option can be useful if you're working offline from time to time, but still want to autoload the local annotations, and the remote ones from time to time, for example, when going on-line for a while.</dd> <dt>Annotation post server</dt> <dd>This setting defines the server to which the annotations are posted. Local annotations are always saved to the local repository, regardless of the value of this setting. By default, this setting is empty. Note that the post server is not automatically included in the list of servers to be queried; you must enter the post server name in both places, in whatever order you choose. </dd> </dl> <h3 id="Creating1">Creating an Annotation</h3> This version of Amaya support two kinds of annotations: annotations that apply to a whole document and annotations that apply to a specific point or selection in a document. To annotate a whole document, just select the Annotations/Annotate document menu entry. To annotate a point, put the caret in any point in the document and select the Annotations/Annotate selection menu entry. To annotate a selection, make a selection in the document, and then use the Annotations/Annotate selection menu entry. In all of these cases, an annotation window will appear (see following figure). The content of this window shows the metadata of the annotation, inside a box, and the body of the annotation. <img src="../Icons/annotationwindow.png" alt="annotation window" /> Currently, the metadata consists of the author's name, the title of the annotated document, the type of the annotation, the date of creation, and the date of the last modification . Some of the metadata fields have special properties. The source document field is also a link that points back to the annotated text. If the user double-clicks on it, as when following any other link with Amaya, the annotated document will be raised and the annotated text will be highlighted. The annotation types field allows the user to classify the annotation and change its type. Double-click on the text "annotation type" to see the list of types available. We'll describe later how users can also define their own annotation types. Finally, the Last modified field is updated automatically each time that an annotation is saved. Below the header area is the annotation body area. It shows the current content, and it can be edited as if we were editing any other HTML document,. N.B., we don't support yet the use of images inside the body. Some of the features may not be ready in the initial release, such as the Structure view. Saving an annotation is equivalent to saving any other document with Amaya. The user just needs to select the File/Save command (or use its equivalent shortcut or button menu). 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, the user needs to use the Annotations/Post annotation command and the annotation will be saved to the Post server as defined in the configuration menu. If this operation is succesful, the local annotation will be removed and further save operations will go directly to that annotation server. In the initial release, Amaya does not support an operation to save a copy of a remote annotation in the local annotations directory. Some commands applied to the document in the Amaya Document window will be applied to annotation document in the Annotation window. For instance, the body of an annotation can be printed with File/Print command, or reloaded with File/Reload document command. (Note: some of these may not be implemented yet.) <h3 id="Deleting">Deleting an Annotation</h3> The Annotations/Delete annotation menu command lets you delete an annotation. You can invoke this command from an open annotation window. You can also delete an annotation from the annotated document by first selecting the annotation by doing a simple click on the annotation icon, and then calling this menu command. <h3 id="Loading">Loading and Presenting Annotations</h3> The Load annotations command tells amaya to load the annotations that are associated to the URL of the document that is being browsed in that window. Amaya will query the annotations servers, as set up in the Annotations/Configure dialogue, asking for any relevant annotation. The annotations can also be loaded automatically whenever a new page is loaded by selecting the Autoload annotations checkbox in the Annotations/Configure dialogue. Note that in this version of Amaya, querying an annotation server will return all the the annotations that are associated to to 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. The Annotations/Local filter menu allows a user to show or hide the annotation icons from the document window, for example, to concentrate on those that really interest him, or, to make it easier to read a heavily annotated document. The user can show or hide annotations by three types of metadata: by the name of the annotation's author, by the type of annotation, and by the annotation server name. To apply any of these filters, you need to click on the text box to select a given type of annotations, and then on the corresponding action button. The Show all and Hide all commands apply to all the annotations.A small and uncomfortable prefix charater shows the status of a given entry. This character can be either a space (' '), a star ('*') or a signet ('-') to say that tje annotations belonging to this given entrty are all visible, all hidden, or partially visible, respectively. Note that the filter menus only show you the annotations it knows about at the moment of its invocation. If you add new annotations in the meantime, you'll need to destroy this menu and invoke it again to see them. Note that for each annotation, the annotation user is shown by concatenating the author's name to the name of the annotation server where the annotation is stored, as shown in the following figure. <img src="../Icons/localfilter.png" alt="local filter dialog box" /> <h3 id="Navigating">Navigating Annotations</h3> Annotations appear as links in the Link window whih can be activated by the Views/ Show links command. Annotations in this window are marked with the same pencil icon as the annotations in the document window. The Link window shows all the annotations, without taking into account whether they have been hidden with the Annotation Local Filter menu. As with the document window, a single-click on the annotation will select the annotated text in the document window and a double click will open 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. <img src="../Icons/linkwindow.png" alt="Link window shows annotations" /> </div> <div id="Issues"> <h3 id="Issues1">Issues with Annotations and Modified Documents</h3> If you are using annotations with live documents (documents whose contents can be modified), you may encounter two kinds of problems: orphan annotations and misleading annotations. Let's first describe a bit more in detail how Amaya attaches annotations to documents. Amaya uses <a href="http://www.w3.org/XML/Linking">XPointer</a> to describe where an annotation should be attached to a document. XPointers are based in the structure of the document. To build an XPointer, for example for a selection, we start from the first point of the selection and walk backwards through the document's structure, until we find the root of the document. If an element has an ID attribute, we stop building the XPointer and we consider that the beginning of this XPointer is the element that has this ID attribute value. For example,. if you look at the HTML source for this document, you'll notice that this section (Issues with annotations...) is enclosed within a DIV element that has an ID attribute with the value "Issues". Here's an extract of the source code: <pre> <div id="Issues"> <h3>>Issues with ....</h3>> If you are using... Amaya uses XPointer... ... </div></pre> And here's the XPointer that points to the second paragraph:: <code>xpointer(id("Issues")/p[2])</code> The above XPointer points to the second <code>p</code> element, from the element parent having an ID attribute with value "Issues". (In order to select a whole paragraph, we put the cursor in the paragraph and pressed the Escape (Unix) or F2 (Windows) key). Note that the use of the ID attribute allows the document author to move this whole section elsewhere on the document, without needing to update the XPointer. The XPointer doesn't depend on the elements that precede this particular DIV element. We say that an annotation becomes an orphan when it cannot be attached anymore to a document, that is, when the XPointer doesn't resolve anymore to any element in the strucutre. This happens when a document's structure is modified. For example, the above XPointer wouldn't resolve anymore if we destroyed the ID attribute "Issues". Amaya will warn you if it detects any orphan annotation 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 <img src="../Icons/annotorp.png" alt="Orphan annotation icon" />. We say that an annotation is misleading when it points to a wrong piece of information. Coming back to our example, we can create a misleading annotation if we exchange the first and second paragraph. The XPointer will continue to point to the second paragraph, although we would have liked it to point now to the first paragraph. This problem is even more 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. How can you protect yourself? If you're the author of a document, try to use the ID attribute in strategic places, for example, in the DIV elements. Amaya allows you to automatically associate or remove an ID attribute to/from a set of elements by means of the Special/Make Add/Remove ID menu command. In the above example, we could have avoided the problem of misleading annotations if we had added an ID attribute to the second paragraph: <pre> Amaya uses...</pre> An XPointer that points to this paragraph is <code>xpointer(id("Amaya"))</code> Thus, the Xpointer will point to the same paragraph, regardless of its position in the document's structure. </div> <a href="MakeBook.html"><img alt="previous" border="0" src="../Icons/left.gif" /></a> <a href="Manual.html"><img alt="top" border="0" src="../Icons/up.gif" /></a> <a href="Configure.html"><img alt="next" border="0" src="../Icons/right.gif" /></a> <hr /> </body> </html>