home *** CD-ROM | disk | FTP | other *** search
/ GameStar 2005 May / Gamestar_73_2005-05_dvd.iso / Programy / amaya / amaya-Win98-8.7.3.exe / _SETUP.1 / annotation_issues.html < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-01  |  4.6 KB  |  108 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.   <title>Known Issues with Annotations and Modified Documents</title>
  8.   <style type="text/css">
  9.   </style>
  10.   <meta name="GENERATOR" content="amaya 8.6, see http://www.w3.org/Amaya/" />
  11.   <link href="../style.css" rel="stylesheet" type="text/css" />
  12. </head>
  13.  
  14. <body xml:lang="en" lang="en">
  15.  
  16. <table border="0" width="100%" summary="toc">
  17.   <tbody>
  18.     <tr>
  19.       <td><img alt="W3C" src="../../images/w3c_home" /> <img alt="Amaya"
  20.         src="../../images/amaya.gif" /></td>
  21.       <td><p align="right"><a href="configuring_icons.html"
  22.         accesskey="p"><img alt="previous" src="../../images/left.gif" /></a>
  23.         <a href="../Annotations.html" accesskey="t"><img alt="top"
  24.         src="../../images/up.gif" /></a></p>
  25.       </td>
  26.     </tr>
  27.   </tbody>
  28. </table>
  29.  
  30. <div id="page_body">
  31. <h1>Known Issues with Annotations and Modified Documents</h1>
  32.  
  33. <p>When you use annotations with live documents (documents whose contents can
  34. be modified), you may encounter two kinds of problems: <strong>orphan
  35. annotations</strong> and <strong>misleading annotations</strong>. To explain
  36. these problems, we must first describe how Amaya attaches annotations to
  37. documents.</p>
  38.  
  39. <p>Amaya uses <strong><a
  40. href="http://www.w3.org/XML/Linking">XPointer</a></strong> to indicate where
  41. an annotation should be attached to a document. XPointers are based in the
  42. structure of the document. To build an XPointer for a selection, for example,
  43. Amaya starts from the first point of the selection and walk backwards through
  44. the document's structure, until it finds the root of the document. If an
  45. element has an ID attribute, Amaya stops building the XPointer and considers
  46. the element with the ID attribute value to be the beginning of that
  47. XPointer.</p>
  48.  
  49. <p>For example, if you look at the HTML source for this document, you'll
  50. notice that this section is enclosed within a DIV element that has an ID
  51. attribute with the value "Issues" Here's an extract of the source code:</p>
  52. <pre>  <div id="Issues">
  53.   <h1>Issues with ....</h1>
  54.   <p>If you are using...</p>
  55.   <p>Amaya uses <strong>XPointer</strong>...</p>
  56.   ...
  57.   </div></pre>
  58.  
  59. <p>This XPointer points to the second paragraph:
  60. <code>xpointer(id("Issues")/p[2])</code></p>
  61.  
  62. <p>The above XPointer points to the second <code>p</code> element, from the
  63. element parent having an ID attribute with value "Issues".</p>
  64.  
  65. <p>Note that the use of the ID attribute enables the document author to move
  66. the entire reference by the XPointer to another location within the document,
  67. without needing to update the XPointer. The XPointer does not depend on the
  68. elements that precede it.</p>
  69.  
  70. <h2>Orphan Annotations</h2>
  71.  
  72. <p>An annotation becomes an "orphan" when it can no longer be attached to a
  73. document, that is, when the XPointer does not resolve to any element in the
  74. structure. This happens when a document's structure is modified. Amaya
  75. displays a warning if it detects any orphan annotations while downloading a
  76. set of annotations from an annotation server. All orphan annotations are
  77. visible from the Links view and are associated with an icon that shows a
  78. question mark superimposed on the annotation pencil <img
  79. src="../../images/annotorp.png" alt="Orphan annotation icon" />.</p>
  80.  
  81. <h2>Misleading Annotations</h2>
  82.  
  83. <p>An annotation becomes "misleading" when it points to a wrong piece of
  84. information. This problem is common when you annotate a portion of text that
  85. may change. In the first release, Amaya does not warn the user if an
  86. annotation is misleading. A future release may notify users of the potential
  87. for an annotation to be misleading.</p>
  88.  
  89. <h2>What can you do to avoid this?</h2>
  90.  
  91. <p>As the author of a document, try to use the <code>ID</code> attribute in
  92. strategic places, for example, inside <code><DIV></code> and
  93. <code>p</code> elements. For example:</p>
  94. <pre>  <p id="Amaya">Amaya uses...</p></pre>
  95.  
  96. <p>An XPointer that points to this paragraph is:
  97. <code>xpointer(id("Amaya"))</code></p>
  98.  
  99. <p>Thus, the Xpointer will point to the same paragraph, regardless of its
  100. position in the document's structure.</p>
  101.  
  102. <p>Amaya enables you to automatically associate with or remove an
  103. <code>ID</code> attribute to/from a set of elements by choosing
  104. <strong>Add/Remove ID</strong> from the <strong>Links</strong> menu.</p>
  105. </div>
  106. </body>
  107. </html>
  108.