home *** CD-ROM | disk | FTP | other *** search
/ GameStar 2005 May / Gamestar_73_2005-05_dvd.iso / Programy / amaya / amaya-WinXP-9.1.exe / doc / WX / Annotations.html < prev    next >
Encoding:
Extensible Markup Language  |  2005-02-23  |  24.6 KB  |  549 lines
  1. <?xml version="1.0" encoding="iso-8859-1"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  3.        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  4. <html xmlns="http://www.w3.org/1999/xhtml">
  5. <head>
  6.   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  7.   <meta name="GENERATOR" content="amaya 9.1, see http://www.w3.org/Amaya/" />
  8.   <title>Annotations in Amaya</title>
  9.   <style type="text/css">
  10.   </style>
  11.   <link href="style.css" rel="stylesheet" type="text/css" />
  12. </head>
  13.  
  14. <body xml:lang="en" lang="en">
  15.  
  16. <div>
  17. <img alt="Amaya" src="../../resources/icons/22x22/logo.png" class="logo" />
  18.  
  19. <p class="nav"><a href="MakeBook.html" accesskey="p"><img alt="previous"
  20. src="../../resources/icons/misc/left.png" /></a> <a href="Manual.html"
  21. accesskey="t"><img alt="top" src="../../resources/icons/misc/up.png" /></a>
  22. <a href="bookmarks.html" accesskey="n"><img alt="next"
  23. src="../../resources/icons/misc/right.png" /></a></p>
  24. </div>
  25.  
  26. <div id="page_body">
  27. <h2>Annotations in Amaya</h2>
  28.  
  29. <h3>What is an annotation?</h3>
  30.  
  31. <p>Annotations are comments, notes, explanations, or other types of external
  32. remarks that can be attached to a Web document or a selected part of the
  33. document. As they are external, it is possible to annotate any Web document
  34. independently, without needing to edit that document. From the technical
  35. point of view, annotations are usually seen as <strong>metadata,</strong> as
  36. they give additional information about an existing piece of data. In this
  37. project, we use a special <strong><a
  38. href="http://www.w3.org/RDF/">RDF</a></strong> <a
  39. href="http://www.w3.org/2000/10/annotation-ns">annotation schema</a> for
  40. describing annotations.</p>
  41.  
  42. <p>Annotations can be stored locally or in one or more <strong>annotation
  43. servers</strong>. When a document is browsed, Amaya queries each of these
  44. servers, requesting the annotations related to that document. Currently Amaya
  45. presents annotations with pencil annotation icons ( <img
  46. src="../images/annot.png" alt="Annotation pencil icon" /> )that are visually
  47. embedded in the document, as shown in the figure below. If the user
  48. single-clicks on an annotation icon, the text that was annotated is
  49. highlighted. If the user double-clicks on this icon, the annotation text and
  50. other metadata are presented in a separate window.</p>
  51.  
  52. <p style="text-align: center"><img src="../images/annotationicon.png"
  53. alt="annotation icon (= pencil)" /></p>
  54.  
  55. <p>An annotation has many properties including:</p>
  56. <ul>
  57.   <li>Physical location: is the annotation stored in a local file system or
  58.     in an annotation server</li>
  59.   <li>Scope: is the annotation associated to a whole document or just to a
  60.     fragment of this document</li>
  61.   <li>Annotation type: 'Annotation', 'Comment', 'Query', ...</li>
  62. </ul>
  63.  
  64. <h3>About Local Annotations</h3>
  65.  
  66. <p>Amaya can store annotation data in a local file system (often called
  67. "local annotations") or it can store annotations <span style="color:blue"><a
  68. href="../html/attaching_annotations/about_storing_remote_annotations.html">remotely</a></span>,
  69. accessed through the World Wide Web (called "remote annotations").</p>
  70.  
  71. <p>You do not need a server to create local annotations. Local annotations
  72. are stored under the user preferences directory, in a special directory
  73. called <strong>annotations</strong>, and can be seen only by their owner
  74. (according to the system access right setup). This directory contains three
  75. kinds of files:</p>
  76. <ul>
  77.   <li><strong>annot.index:</strong> Associates URLs with the files containing
  78.     the metadata of the annotations.</li>
  79.   <li><strong>index + random suffix:</strong> Stores the metadata of the
  80.     annotations related to a given URL. The metadata is specified with RDF.
  81.     <br />
  82.   </li>
  83.   <li><strong>annot + random suffix.html:</strong> Contains the body of an
  84.     annotation, stored as XHTML.</li>
  85. </ul>
  86.  
  87. <p>At any time, you can convert a local annotation to a shared one by
  88. choosing <strong>Post annotation</strong> from the
  89. <strong>Annotations</strong> menu. Once this is completed, the local
  90. annotation is deleted because it has been moved to an annotation server.</p>
  91.  
  92. <h3>About Remote Annotations</h3>
  93.  
  94. <p>Amaya can store annotation data in a <span style="color: blue"><a
  95. href="../html/attaching_annotations/about_storing_local_annotations.html">local
  96. file system</a></span> (often called "local annotations") or it can store
  97. annotations remotely, in Annotations Servers accessed through the World Wide
  98. Web (called "remote annotations").</p>
  99.  
  100. <p>You can store remote annotations in annotation servers so that the
  101. annotations can be downloaded by anyone having the correct access rights,
  102. such as is the case of other HTML documents.</p>
  103.  
  104. <p>Remote annotations are referred to as shared or public annotations,
  105. because they can be seen by other people. If you wish to install your own
  106. annotation server, please refer to <span style="color:blue"><a
  107. href="http://www.w3.org/1999/02/26-modules/User/Annotations-HOWTO.html">Annotation-Server-HOWTO</a></span>.</p>
  108.  
  109. <h3 id="Annotation">Annotations Menu</h3>
  110.  
  111. <p>Most of the commands needed for handling annotations can be found from the
  112. Annotations menu shown below. The commands are explained later in this
  113. document in the context of users' goals when handling annotations.</p>
  114.  
  115. <h3>Creating an Annotation</h3>
  116.  
  117. <p>This version of Amaya supports two kinds of annotations: annotations that
  118. apply to a whole document and annotations that apply to a specific point or
  119. selection in a document.</p>
  120. <ul>
  121.   <li>To annotate an entire document, choose <strong>Annotate
  122.     document</strong> from the <strong>Annotations</strong> menu.
  123.     <p></p>
  124.   </li>
  125.   <li>To annotate a point, put the insertion point at any place in the
  126.     document and choose <strong>Annotate selection</strong> from the
  127.     <strong>Annotations</strong> menu.
  128.     <p></p>
  129.   </li>
  130.   <li>To annotate a selection, make a selection in the document and choose
  131.     <strong>Annotate selection</strong> from the <strong>Annotations</strong>
  132.     menu.</li>
  133. </ul>
  134.  
  135. <p>After any of these options are performed, an annotation dialog displays
  136. the annotation metadata and the body of the annotation.</p>
  137.  
  138. <p><img src="../images/annotationwindow.png" alt="annotation window" /></p>
  139.  
  140. <h3>Annotation Metadata</h3>
  141.  
  142. <p>Currently, the metadata consists of the author's name, title of the
  143. annotated document, annotation type, creation date, and last modification
  144. date. Some of the metadata fields have special properties:</p>
  145. <ul>
  146.   <li>The <strong>Source Document</strong> field is also a link that points
  147.     back to the annotated text. If the user double-clicks it, as when
  148.     following any other link with Amaya, the annotated document will be
  149.     displayed with the annotated text highlighted.
  150.     <p></p>
  151.   </li>
  152.   <li>The <strong>Annotation Types</strong>field lets you classify the
  153.     annotation and change its type. Double-click on the text "annotation
  154.     type" to see the list of types available.
  155.     <p></p>
  156.   </li>
  157.   <li>The <strong>Last Modified</strong>field is updated automatically each
  158.     time that an annotation is saved.</li>
  159. </ul>
  160.  
  161. <p>Below the header area is the annotation body area. It shows the current
  162. content and can be edited like any other HTML document.</p>
  163.  
  164. <h3>Saving an Annotation</h3>
  165.  
  166. <p>Saving an annotation is the same as saving any other document with Amaya:
  167. choose <span class="Link"><strong>Save</strong></span>from the
  168. <strong>File</strong> menu (or use its equivalent shortcut or button).</p>
  169.  
  170. <p>Local annotations are saved to the annotations directory and remote
  171. annotations are saved to the annotation post server, where they are stored if
  172. the user has write access.</p>
  173.  
  174. <p>To convert a local annotation into a shared one, choose <strong>Post
  175. Annotation</strong> from the <strong>Annotations</strong> menu to save the
  176. annotation to the Post server as defined in the <span
  177. class="Link"><strong>Configuration for Annotations</strong> dialog</span>. If
  178. this operation is successful, the local annotation will be removed and future
  179. <strong>Save</strong> operations will go directly to that annotation
  180. server.</p>
  181.  
  182. <p>Some commands that can be applied to a document in the Amaya document
  183. window also can be applied to an annotation document in the Annotation
  184. window. For example, the body of an annotation can be printed by choosing
  185. <strong>Print</strong> from the <strong>File</strong> menu, or reloaded by
  186. choosing <strong>Reload document</strong> from the <strong>File</strong>
  187. menu.</p>
  188.  
  189. <h3>Deleting an Annotation</h3>
  190.  
  191. <p>The <strong>Delete</strong> command on the <strong>Annotation</strong>
  192. menu enables you to delete an annotation. You can invoke this command from an
  193. open annotation window.</p>
  194.  
  195. <p class="ProcedureCaption">To delete an annotation from a document:</p>
  196. <ol>
  197.   <li>Select the annotation by clicking the annotation icon.
  198.     <p></p>
  199.   </li>
  200.   <li>Choose <strong>Delete</strong> from the <strong>Annotations</strong>
  201.     menu.</li>
  202. </ol>
  203.  
  204. <h3>Loading and Presenting Annotations</h3>
  205.  
  206. <p>The <strong>Load Annotations</strong> command tells Amaya to load the
  207. annotations that are associated with the URL of the current document. Amaya
  208. will query the annotation servers, using the settings from the
  209. <strong>Configuration for annotations</strong> dialog, and ask for any
  210. relevant annotation.</p>
  211.  
  212. <p>Annotations can also be loaded automatically whenever a new page is viewed
  213. by selecting the <strong>Autoload Annotations</strong> check box in the
  214. <strong>Configuration for annotations</strong> dialog.</p>
  215.  
  216. <p>In this version of Amaya, querying an annotation server will return all
  217. the annotations that are associated with a document. In a future version, it
  218. may be possible to use a customized query menu to refine the query string
  219. that is sent to the servers.</p>
  220.  
  221. <h3>The Annotation Local Filter Menu</h3>
  222.  
  223. <p>Choose <strong>Local filter</strong> from the <strong>Annotations</strong>
  224. menu to show or hide the annotation icons in the document window. You can
  225. show or hide annotations by three types of metadata: the name of the
  226. annotation's author, the type of annotation, and the annotation server
  227. name.</p>
  228.  
  229. <p class="ProcedureCaption">To apply any of these filters:</p>
  230. <ol>
  231.   <li>Click the text box to select an annotation type.
  232.     <p></p>
  233.   </li>
  234.   <li>Click the corresponding action button. The <strong>Show all</strong>
  235.     and <strong>Hide all</strong> buttons apply to all the annotations.
  236.     <p></p>
  237.   </li>
  238.   <li>A small prefix character indicates the status of a given entry. This
  239.     character can be a space (' '), a star ('*'), or a signet ('-') to
  240.     indicate that the annotations belonging to this given entry are all
  241.     visible, all hidden, or partially visible, respectively.</li>
  242. </ol>
  243.  
  244. <p class="Note"><strong>Note:</strong><br />
  245. The <strong>Annotation Local Filter Menu</strong> dialog only shows you the
  246. annotations it knows about at the moment it is opened. If new annotations are
  247. added, you will need to reload the menu again.</p>
  248.  
  249. <p>The annotation author shows the author's name added to the name of the
  250. annotation server where the annotation is stored.</p>
  251.  
  252. <h3>Navigating Annotations</h3>
  253.  
  254. <p>Annotations can be navigated by choosing <strong>Show Links</strong> from
  255. the <span class="Link"><strong>Views</strong> menu</span>. The Link window
  256. opens and displays a list of annotations. Annotations in the Link and
  257. Document windows are marked with a pencil annotation icon.</p>
  258.  
  259. <h3>Annotations in the Link window</h3>
  260.  
  261. <p>The Link window shows all the annotations, without taking into account
  262. whether they have been hidden with <strong>Local filter</strong> on the
  263. <strong>Annotations</strong> menu. As with the document window, a
  264. single-click on the annotation selects the annotated text in the document
  265. window and a double-click opens the annotation. This is an example of how to
  266. navigate from one annotation link to another, even if the annotation cannot
  267. be seen by the user because of disabilities or because of the characteristics
  268. of the used device.</p>
  269.  
  270. <h3>Moving Annotations</h3>
  271.  
  272. <p>You can move an annotation to any other part of the same document. This
  273. can be used, for example, to handle <a
  274. href="../html/attaching_annotations/annotation_issues.html">orphan and
  275. misleading annotations</a>. You can move an annotation to either the current
  276. selection or to the value of a stored <span class="Link">XPointer</span>. It
  277. is only possible to move annotations in the same document where they were
  278. created.</p>
  279.  
  280. <p>To move an annotation to a current selection:</p>
  281. <ol>
  282.   <li>Open the <strong>Annotations</strong> menu and select <strong>Annotate
  283.     document</strong>. The <strong>annotation</strong> window opens.</li>
  284.   <li>Click the annotated document and select something on it.</li>
  285.   <li>In the <strong>annotation</strong> window, choose <strong>Move to
  286.     selection</strong> from the <strong>Annotations</strong> menu.</li>
  287.   <li>Amaya moves the annotation icon to the text you selected and will mark
  288.     the annotation document as modified.</li>
  289. </ol>
  290.  
  291. <p>To make this change effective, must save the annotation or you will loose
  292. the change. You can also move an annotation to the current position of the
  293. cursor, without having to make a selection.</p>
  294.  
  295. <h3>Moving Annotations to a Previously Memorized Location</h3>
  296.  
  297. <p>You can store the position where you want to move an annotation to, and
  298. then move it there. This feature is useful for moving multiple annotations to
  299. the same position or for scrolling elsewhere in the document before doing the
  300. move.</p>
  301.  
  302. <p>To move multiple annotations:</p>
  303. <ol>
  304.   <li>Make a selection (or just place the cursor) in the location where you
  305.     want to move the annotation.
  306.     <p></p>
  307.   </li>
  308.   <li>Choose <strong>Store selection as XPointer</strong> from the
  309.     <strong>Annotations</strong> menu to store an XPointer representing that
  310.     selection.
  311.     <p></p>
  312.   </li>
  313.   <li>In the <strong>Annotations</strong> window, choose <strong>Move to
  314.     stored XPointer</strong> from the <strong>Annotations</strong> menu to
  315.     move the annotation to its new location.
  316.     <p></p>
  317.   </li>
  318.   <li>Save the annotation to make this change effective.</li>
  319. </ol>
  320.  
  321. <h3>Replying to Annotations / Discussion Threads</h3>
  322.  
  323. <p>Annotations can be seen as comments to pages. The <strong>Annotation /
  324. Replies</strong> feature enhances the collaborative workspace by allowing
  325. users to reply to annotations or to other replies.</p>
  326.  
  327. <p>The <strong>Annotations / Reply to annotation</strong> menu command lets
  328. you to create a reply to an existing annotation or to a reply. You can invoke
  329. this command from an open annotation or a reply window. As a result a new
  330. reply window opens. The fields in a reply window can be edited just like in
  331. an annotation window as explained under <strong>Creating an
  332. annotation</strong>.</p>
  333.  
  334. <p>When the reply is ready, you can post it to a server with
  335. <strong>Annotations / Post to Server</strong> menu command or save it locally
  336. using the <strong>File / Save</strong> menu command. To delete a reply, you
  337. can use the <strong>Annotations / Delete</strong> menu command.</p>
  338.  
  339. <p>Replies can also be annotated like any other document, as explained in <a
  340. href="../html/attaching_annotations/creating_an_annotation.html">Creating an
  341. annotation</a>.</p>
  342.  
  343. <h3>The user interface</h3>
  344.  
  345. <p><img alt="An annotation with a discussion thread"
  346. src="../images/threads.png" /></p>
  347.  
  348. <p>In the current user interface, all replies related to an annotation are
  349. shown at the bottom of this annotation, in a thread section. Each item in the
  350. thread gives the date of the reply, the author, and the title of the reply.
  351. The content of any of these replies can be retrieved by double clicking the
  352. replies in the thread. The selected reply will be highlighted and presented
  353. in a reply window. When another selection is made the same reply window is
  354. used.</p>
  355.  
  356. <h3>Known issues: Incomplete threads</h3>
  357.  
  358. <p>There is no control yet for controlling which replies should be posted. In
  359. an ideal world, it should not be possible to save a reply to a reply if the
  360. previous reply was not saved in the same server. Likewise, if you delete a
  361. reply, you should delete all replies to this annotation. Not doing leads to
  362. having fragments of threads that cannot be correctly attached in the thread.
  363. For example, let R1 be the reply to annotation A1 and R2 a reply to R1. If
  364. you post R1, and let R2 be stored locally, then when you browse A1 and only
  365. download its local annotations, you will only see R2. At this point, Amaya
  366. does not know that R1 exists, so it assumes that R2 has lost its parent. We
  367. identify these "orphan" threads by putting a question mark symbol
  368. <strong>?</strong> in front of them. If later one, Amaya finds new thread
  369. items, for example, if you download R1, Amaya will then sort the thread view,
  370. inserting the threads as appropriately. In our example, R2 will become a
  371. child of R1, as expected.</p>
  372.  
  373. <h3>Configuring Annotation Icons</h3>
  374.  
  375. <h4>User-definable icons by Annotation type (aka "dynamic icons")</h4>
  376.  
  377. <p>As of Release 6.2, the icon used to mark the location of an annotation
  378. within an annotated document may be changed by the user.</p>
  379.  
  380. <p>In release 6.2 the icon that denotes an annotation is chosen as a property
  381. of the annotation type. By including an RDF property of each annotation type
  382. you wish to use, you select the icon associated with annotations of that
  383. type.</p>
  384.  
  385. <p>The sample configuration that is shipped with release 6.2 associates the
  386. following icons:</p>
  387.  
  388. <table>
  389.   <tbody>
  390.     <tr>
  391.       <td width="35"><img src="../../amaya/advice.png" alt="Advice" /></td>
  392.       <td>Advice</td>
  393.     </tr>
  394.     <tr>
  395.       <td width="35"><img src="../../amaya/change.png" alt="Change" /></td>
  396.       <td>Change</td>
  397.     </tr>
  398.     <tr>
  399.       <td width="35"><img src="../../amaya/annot.png" alt="Comment" /></td>
  400.       <td>Comment</td>
  401.     </tr>
  402.     <tr>
  403.       <td width="35"><img src="../../amaya/example.png" alt="Example" /></td>
  404.       <td>Example</td>
  405.     </tr>
  406.     <tr>
  407.       <td width="35"><img src="../../amaya/explanation.png" alt="Explanation"
  408.         /></td>
  409.       <td>Explanation</td>
  410.     </tr>
  411.     <tr>
  412.       <td width="35"><img src="../../amaya/question.png" alt="Question"
  413.       /></td>
  414.       <td>Question</td>
  415.     </tr>
  416.     <tr>
  417.       <td width="35"><img src="../../amaya/seealso.png" alt="SeeAlso" /></td>
  418.       <td>SeeAlso</td>
  419.     </tr>
  420.   </tbody>
  421. </table>
  422.  
  423. <p>The property name for adding annotation icons is <a
  424. href="http://www.w3.org/2001/10/typeIcon#usesIcon">http://www.w3.org/2001/10/typeIcon#usesIcon</a>.
  425. For instance, to specify an icon named file:///home/question-icon.jpg for
  426. annotations that have type <a
  427. href="http://www.w3.org/2000/10/annotationType#Question">http://www.w3.org/2000/10/annotationType#Question</a>
  428. you would enter the following RDF/XML into a file that Amaya reads at startup
  429. is:</p>
  430. <pre><rdf:RDF
  431.    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  432.    xmlns:i = "http://www.w3.org/2001/10/typeIcon#">
  433. <rdf:Description rdf:about="http://www.w3.org/2000/10/annotationType#Question">
  434.   <i:usesIcon rdf:resource="file:///home/question-icon.jpg" />
  435. </rdf:Description>
  436. </rdf:RDF></pre>
  437.  
  438. <p>The simplest way to get such RDF loaded into Amaya at startup is to
  439. include the file in the config/annot.schemas file in the Amaya program
  440. directory. In order to preserve this file so that it will not be overwritten
  441. when you install a new version of Amaya, you should copy the
  442. config/annot.schemas file into your personal Amaya home directory;
  443. ~/.amaya/annot.schemas (on Unix systems) or
  444. /winnt/profiles/<username>/amaya/annot.schemas (on Microsoft Windows
  445. systems). You may list as many RDF files as you want in annot.schemas. See
  446. the comments in the file included in the Amaya kit for more details.</p>
  447.  
  448. <p>Release 6.2 includes a sample file named "typeIcon.rdf" that declares
  449. unique icons for each annotation type declared in the <a
  450. href="http://www.w3.org/2000/10/annotationType#">http://www.w3.org/2000/10/annotationType#</a>
  451. namespace. To experiment with user-defined icons, it may be easiest to copy
  452. this typeIcon.rdf into another directory and modify it. Copy annot.schemas to
  453. your Amaya home directory and change the line near the end to point to your
  454. revised icon definition file.</p>
  455.  
  456. <p>To revert to the previous behavior prior to release 6.2, edit the
  457. config/annot.schemas in the Amaya installation directory and add a comment
  458. character ("#") at the beginning of the line near the end that refers to
  459. typeIcon.rdf:</p>
  460. <pre>#user-defined icons
  461. #http://www.w3.org/2001/10/typeIcon# $THOTDIR/config/typeIcon.rdf</pre>
  462.  
  463. <p>Amaya supports JPEG, PNG, and GIF bitmap graphics formats for icon images.
  464. In release 6.2 the icon URI may only be a file: URI; that is, the icon must
  465. appear in a local or mounted directory to Amaya. Two special forms of
  466. non-file: URIs are supported. If the file path name starts with "$THOTDIR" or
  467. "$APP_HOME" then the corresponding Amaya installation directory or personal
  468. Amaya home directory is substituted into the pathname.</p>
  469.  
  470. <h3>Known Issues with Annotations and Modified Documents</h3>
  471.  
  472. <p>When you use annotations with live documents (documents whose contents can
  473. be modified), you may encounter two kinds of problems: <strong>orphan
  474. annotations</strong> and <strong>misleading annotations</strong>. To explain
  475. these problems, we must first describe how Amaya attaches annotations to
  476. documents.</p>
  477.  
  478. <p>Amaya uses <strong><a
  479. href="http://www.w3.org/XML/Linking">XPointer</a></strong> to indicate where
  480. an annotation should be attached to a document. XPointers are based in the
  481. structure of the document. To build an XPointer for a selection, for example,
  482. Amaya starts from the first point of the selection and walk backwards through
  483. the document's structure, until it finds the root of the document. If an
  484. element has an ID attribute, Amaya stops building the XPointer and considers
  485. the element with the ID attribute value to be the beginning of that
  486. XPointer.</p>
  487.  
  488. <p>For example, if you look at the HTML source for this document, you'll
  489. notice that this section is enclosed within a DIV element that has an ID
  490. attribute with the value "Issues" Here's an extract of the source code:</p>
  491. <pre>  <div id="Issues">
  492.   <h1>Issues with ....</h1>
  493.   <p>If you are using...</p>
  494.   <p>Amaya uses <strong>XPointer</strong>...</p>
  495.   ...
  496.   </div></pre>
  497.  
  498. <p>This XPointer points to the second paragraph:
  499. <code>xpointer(id("Issues")/p[2])</code></p>
  500.  
  501. <p>The above XPointer points to the second <code>p</code> element, from the
  502. element parent having an ID attribute with value "Issues".</p>
  503.  
  504. <p>Note that the use of the ID attribute enables the document author to move
  505. the entire reference by the XPointer to another location within the document,
  506. without needing to update the XPointer. The XPointer does not depend on the
  507. elements that precede it.</p>
  508.  
  509. <h4>Orphan Annotations</h4>
  510.  
  511. <p>An annotation becomes an "orphan" when it can no longer be attached to a
  512. document, that is, when the XPointer does not resolve to any element in the
  513. structure. This happens when a document's structure is modified. Amaya
  514. displays a warning if it detects any orphan annotations while downloading a
  515. set of annotations from an annotation server. All orphan annotations are
  516. visible from the Links view and are associated with an icon that shows a
  517. question mark superimposed on the annotation pencil <img
  518. src="../images/annotorp.png" alt="Orphan annotation icon" />.</p>
  519.  
  520. <h4>Misleading Annotations</h4>
  521.  
  522. <p>An annotation becomes "misleading" when it points to a wrong piece of
  523. information. This problem is common when you annotate a portion of text that
  524. may change. In the first release, Amaya does not warn the user if an
  525. annotation is misleading. A future release may notify users of the potential
  526. for an annotation to be misleading.</p>
  527.  
  528. <h4>What can you do to avoid this?</h4>
  529.  
  530. <p>As the author of a document, try to use the <code>ID</code> attribute in
  531. strategic places, for example, inside <code><DIV></code> and
  532. <code>p</code> elements. For example:</p>
  533. <pre>  <p id="Amaya">Amaya uses...</p></pre>
  534.  
  535. <p>An XPointer that points to this paragraph is:
  536. <code>xpointer(id("Amaya"))</code></p>
  537.  
  538. <p>Thus, the Xpointer will point to the same paragraph, regardless of its
  539. position in the document's structure.</p>
  540.  
  541. <p>Amaya enables you to automatically associate with or remove an
  542. <code>ID</code> attribute to/from a set of elements by choosing
  543. <strong>Add/Remove ID</strong> from the <strong>Links</strong> menu.</p>
  544.  
  545. <p></p>
  546. </div>
  547. </body>
  548. </html>
  549.