<?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>Annoter des documents</title>
  <meta name="GENERATOR" content="amaya 9.4, see http://www.w3.org/Amaya/" />
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <link href="style.css" rel="stylesheet" type="text/css" />
</head>

<body xml:lang="fr" lang="fr">

<div class="PageHead">
Amaya<img alt="logo" src="../../resources/icons/22x22/logo.png" class="logo"
/> 

<p class="nav"><a href="MakeBook.html.fr" accesskey="p"><img alt="previous"
src="../../resources/icons/misc/left.png" /></a> <a href="Manual.html.fr"
accesskey="t"><img alt="top" src="../../resources/icons/misc/up.png" /></a>
<a href="Configure.html.fr" accesskey="n"><img alt="next"
src="../../resources/icons/misc/right.png" /></a></p>
</div>

<div class="PageBody" id="Annotations">
<h2 id="annotation">Annoter des documents</h2>

<h3 id="def">Qu'est-ce qu'une annotation ?</h3>

<p>Une annotation est un commentaire, une note, une explication ou tout autre
remarque externe qui peut être attachée à un document web ou à une partie
d'un document. Comme les annotations dans Amaya sont externes au document, il
est possible d'annoter n'importe quel document du web, même sans avoir le
droit de le modifier. D'un point de vue technique, une annotation peut être
vue comme une méta-donnée puisqu'elle fournit une information supplémentaire
sur une donnée existante. Amaya utilise un <a
href="http://www.w3.org/2000/10/annotation-ns">schéma</a> <a
href="http://www.w3.org/RDF/">RDF</a> pour décrire les annotations.</p>

<p>Les annotations peuvent être enregistrées localement ou sur un ou
plusieurs <em>serveur(s) d'annotations</em>. Lorsqu'un document est chargé,
Amaya interroge chacun de ces serveurs et recherche les annotations relatives
à ce document. Chaque annotation est ensuite représentée par l'icône suivante
<img src="../images/annot.png" alt="Crayon representant une annotation" />
qui est ajoutée au document. Lorsque vous cliquez sur l'icône, le passage
annoté est mis en évidence. Si vous double-cliquez sur l'icône alors le
contenu de l'annotation ainsi que les autres méta-données sont présentées
dans une fenêtre séparée.</p>

<p>Une annotation possède plusieurs propriétés :</p>
<ul>
  <li>Point de stockage: dans le système de fichiers de l'utilisateur ou sur
    un serveur d'annotations.</li>
  <li>Etendue : l'annotation est associée à un document entier ou à une
    fragment de celui-ci.</li>
  <li>Type de l'annotation: remarque, commentaire, question, ...</li>
</ul>

<h3 id="Local">Annotations locales et distantes</h3>

<p>Amaya peut enregistrer les annotations dans un fichier local (annotations
locales) ou sur le Web (annotations distantes).</p>

<p>Les <em>annotations locales</em> ne nécessitent pas l'utilisation de
serveur. Elles sont enregistrées sous le répertoire <a
href="Configure.html.fr#pertoire1">AmayaHome</a>, dans un répertoire
spécifique appelé <code>annotations</code> et peuvent être visualisées
uniquement par leur auteur (selon les droits d'accès en fonction). </p>

<p>Ce répertoire comporte trois sortes de fichiers :</p>
<ul>
  <li><code>annot.index</code> : les URL associées aux fichiers dans lesquels
    les méta-données des annotations sont sauvegardées.</li>
  <li><code>index + random suffix</code> : un fichier contenant les
    méta-données d'une annotation relative à une URL. Les méta-données sont
    spécifiées en RDF.</li>
  <li><code>annot + random suffix.html</code> : contient le corps de
    l'annotation enregistrée en XHTML.</li>
</ul>

<p>Vous pouvez à tout moment transformer une annotation locale en une
annotation partagée en utilisant l'entrée <strong>Enregistrer sur le
serveur</strong> du sous-menu <strong>Outils/Annotations</strong>.
L'annotation est supprimée localement et transférée sur un serveur
d'annotations. </p>

<h4 id="Annotation">Annotations distantes</h4>

<p>Les <em>annotations distantes</em> sont enregistrées sur des serveurs
d'annotations et peuvent être chargées ou enregistrées par quiconque ayant
les droits d'accès correspondants, comme pour les autres documents HTML.</p>

<p>Les annotations distantes sont dites partagées ou publiques parce qu'elles
peuvent être vues par plusieurs personnes. Si vous désirez installer votre
propre serveur d'annotations, veuillez vous référer au document "<a
href="http://www.w3.org/1999/02/26-modules/User/Annotations-HOWTO.html">Annotation-Server
HOWTO</a>".</p>

<h3 id="Creating">Créer une annotation</h3>

<p>Avant de créer une annotation il est recommandé de fixer certains
paramètres dans les <strong>Préférences</strong> (voir la section <a
href="Configure.html.fr#Configurat">Configuration des annotations</a>)</p>

<p>Amaya supporte deux sortes d'annotations : celles qui s'appliquent au
document entier et celles qui s'appliquent à une position ou à une sélection
du document.</p>
<ul>
  <li>Pour annoter un document entier, sélectionnez l'entrée <strong>Annoter
    le document</strong> du sous-menu
  <strong>Outils/Annotations</strong>.</li>
  <li>Pour annoter une position, placez le point d'insertion à cette position
    et sélectionnez l'entrée <strong>Annoter la sélection</strong>.</li>
  <li>Pour annoter une partie, faire la sélection désirée et sélectionnez
    l'entrée <strong>Annoter la sélection</strong>.</li>
</ul>

<p>Dans tous les cas, un document d'annotation s'affiche, initialisé avec les
méta-données de l'annotation et un corps <strong>d</strong>'annotation
vide.</p>

<p>Les méta-données indiquent le <strong>titre</strong> de l'annotation, le
<strong>nom de son auteur</strong>, le <strong>titre du document
annoté</strong> (également appelé document source), le <strong>type de
l'annotation</strong>, sa <strong>date de création</strong> et la
<strong>date de sa dernière modification</strong>.</p>

<p>Certaines de ces méta-données ont des propriétés spécifiques. </p>
<ul>
  <li>Le champ <strong>Document source</strong> est un lien qui pointe sur le
    texte annoté. Si vous double-cliquez dessus (comme pour tout lien dans
    Amaya), le document annoté est affiché en premier plan et le texte annoté
    est mis en évidence.</li>
  <li>La méta-donnée <strong>Type de l'annotation</strong> vous permet de
    classer les annotations et de changer leur type. Un double-clic sur ce
    champ montre la liste des types disponibles. Voir plus loin comment
    définir son propre type d'annotation.</li>
  <li>Enfin, la méta-donnée <strong>Date de dernière modification</strong>
    est automatiquement mise à jour lorsque l'annotation est sauvegardée.</li>
</ul>

<p>Sous l'entête de l'annotation se trouve le <strong>corps</strong> de
celle-ci. Il montre son contenu courant et peut être édité comme n'importe
quel document HTML. </p>

<p>Certaines commandes accessibles dans la vue principale d'Amaya sont
également disponibles pour les annotations comme par exemple le commande
<strong>Imprimer</strong> qui imprime le corps de l'annotation ou la commande
<strong>Recharger</strong>.</p>

<h3 id="Enregister">Enregister une annotation</h3>

<p>L'enregistrement d'une annotation se fait comme l'enregistrement de
n'importe quel autre document. Sélectionnez l'entrée
<strong>Enregistrer</strong> du menu <strong>Fichier</strong> ou cliquez sur
le bouton équivalent ou bien activer le raccourci-clavier correspondant.</p>

<p>Les annotations locales sont sauvées sous le répertoire des annotations et
les annotations distantes sont sauvées sur le serveur d'annotation, si
l'utilisateur possède un droit d'écriture.</p>

<p>Pour transformer une annotation locale en une annotation publique
(distante), l'utilisateur doit utiliser l'entrée <strong>Enregistrer sur le
serveur</strong>. Elle sera alors enregistrée sous le serveur défini dans le
menu de Préférences puis, en cas de succès, supprimées du répertoire
local.</p>

<p>La sauvegarde des annotations se fera alors directement sur le serveur
d'annotations.</p>

<h3 id="Deleting1">Détruire une annotation</h3>

<p>Pour supprimer une annotation vous pouvez utiliser la commande
<strong>Annotations/Supprimer</strong> du menu <strong>Outils</strong> de la
fenêtre de l'annotation à supprimer.</p>

<p>Vous pouvez également supprimer une annotation à partir du document
annoté, en sélectionnant l'icône de celle-ci puis en appelant la même
commande dans le menu du document annoté.</p>

<h3 id="Loading">Charger et présenter les annotations</h3>

<p>La commande <strong>Outils/Annotations/Charger annotations</strong>
indique à Amaya de rechercher les annotations associées à l'URL du document
chargé dans la vue principale. Amaya va alors rechercher les annotations
correspondantes dans les serveurs d'annotations définis dans les
<strong>Préférences/Annotations</strong>.</p>

<p>Les annotations peuvent également être chargées automatiquement en
choisissant l'option <strong>Charger automatiquement les annotations</strong>
dans les <strong>Préférences/Annotations</strong>. La recherche sur un
serveur d'annotations retourne toutes les annotations associées à un
document.</p>

<h3 id="Navigating">Les annotations dans la vue Liens</h3>

<p>Les annotations apparaissent dans la vue <strong>Liens</strong> du
document annoté (avec les autres liens définis dans ce document) et sont
symbolisées par la même icône que dans la vue principale. Comme dans la vue
principale, un simple-clic sur l'icône met en évidence la partie annotée du
document et un double-clic ouvre l'annotation.</p>

<h3 id="Threads">Répondre aux annotations / fils de discussion</h3>

<p>Les annotations peuvent être considérées comme des commentaires sur des
documents. La commande <strong>Outils/Annotations/Répondre à
l'annotation</strong> élargit l'espace de travail collaboratif en permettant
aux utilisateurs de répondre aux annotations des autres utilisateurs ainsi
qu'aux autres réponses</p>

<p>Vous pouvez appeler cette commande depuis la fenêtre d'une annotation ou
depuis la fenêtre d'une réponse. Une nouvelle fenêtre de réponse est alors
ouverte. Les champs de cette fenêtre peuvent être édités de le même manière
que ceux d'une fenêtre d'annotation (voir <a href="#Creating">Créer une
annotation</a>).</p>

<p>Quand la réponse est terminée, vous pouvez la poster sur un serveur par la
commande <strong>Outils/Annotations/Enregistrer sur le serveur</strong> ou
l'enregistrer localement par la commande
<strong>Fichier/Enregistrer</strong>. La commande
<strong>Outils/Annotations/Supprimer</strong> supprime la réponse.</p>

<p>Les réponses peuvent également être annotées comme n'importe quel
document, comme expliqué dans la section <a href="#Creating">Créer une
annotation</a>.</p>

<p>Toutes les réponses relatives à une même annotation sont affichées en
dessous de celle-ci, dans une section "fil". Chaque élément du fil donne la
date de la réponse, son auteur et son titre. Le contenu de chacune des
réponses est accessible en double-cliquant sur la réponse dans le fil. La
réponse sélectionnée est mise en sur-brillance et présentée dans une nouvelle
fenêtre de réponse. Lorsqu'une autre réponse est sélectionnée, la même
fenêtre de réponse est utilisée.</p>

<h3 id="Probl">Problèmes connus: fils incomplets</h3>

<p>Il n'y a pas de contrôle pour déterminer quelle réponse devrait être
postée. Dans l'absolu, il ne devrait pas être possible de poster une réponse
à une réponse sur un autre serveur que la réponse elle-même. De même, si vous
supprimez une réponse vous devriez supprimer toutes les réponses se
rapportant à l'annotation. Sans cela, vous pouvez avoir des fragments du fil
qui ne peuvent être correctement rattachés à celui-ci. Par exemple, soit R1
une réponse à l'annotation A1 et R2 une réponse à R1. Si vous postez R1 et
sauvez localement R2 et si vous visualisez A1 en chargeant uniquement les
annotations locales, alors seule R2 sera visible. A ce niveau, Amaya ne sait
pas que R1 existe et suppose que R2 a perdu sa réponse "mère". On identifie
ces fils "orphelins" en plaçant devant un point d'interrogation. Si par la
suite Amaya trouve de nouveaux éléments du fil, par exemple en chargeant R1,
il les triera correctement. Dans notre exemple, la réponse R2 deviendra fille
de R1, comme attendu.</p>

<div id="Issues">
<h3 id="Issues1">Problèmes relatifs aux annotations et aux documents
modifiés</h3>

<p>Si vous utilisez les annotations sur des documents dont le contenu peut
être modifié, deux catégories de problèmes peuvent survenir: les
<strong>annotations orphelines</strong> et les <strong>annotations
trompeuses.</strong> Avant d'aller plus loin sur ces problèmes, nous allons
d'abord décrire comment Amaya relie les annotations aux documents annotés.</p>

<p>Pour cela, Amaya utilise le mécanisme <strong><a
href="http://www.w3.org/XML/Linking">XPointer</a></strong>. Les XPointers
reposent sur la structure du document. Pour construire un XPointer, par
exemple pour une sélection, on part du premier point de la sélection et on
remonte à travers la structure du document jusqu'à trouver la racine de
celui-ci. Si un élément possède un attribut ID, on arrête la recherche et on
considère que le début du XPointer est cet élément. Par exemple, en regardant
le source HTML de cette documentation, on s'aperçoit que la section courante
est à l'intérieur d'un élément DIV, lequel possède un attribut ID avec la
valeur "Issues". Voici un extrait du code source:</p>
<pre>  &lt;div id="Issues"&gt;
  &lt;h3&gt;Problèmes sur ....&lt;/h3&gt;
  &lt;p&gt;Si vous utilisez ...&lt;/p&gt;
  &lt;p&gt;Pour cela, Amaya utilise le mécanisme &lt;strong&gt;XPointer&lt;/strong&gt;...&lt;/p&gt;
  ...
  &lt;/div&gt;</pre>

<p>Et voici le XPointer qui pointe sur le second paragraphe:</p>

<p style="text-align: center"><code>xpointer(id("Issues")/p[2])</code></p>

<p>Le XPointer ci-dessus pointe sur le second élément <code>p</code> à partir
de l'élément parent qui possède l'attribut ID avec la valeur "Issues".
L'utilisation de l'attribut ID permet à l'auteur du document de déplacer la
totalité de cette section n'importe où dans le document sans avoir besoin de
remettre à jour le XPointer correspondant. Ce dernier de dépend pas des
éléments qui précèdent cette section.</p>

<p>Une annotation est dite <strong>orpheline</strong> lorsqu'elle ne peut
plus être rattachée au document, c'est à dire quand le XPointer ne trouve
plus l'élément correspondant dans la structure du document. Cela arrive
notamment quand la structure est modifiée. Par exemple, le XPointer précédent
ne pourrait plus retrouver l'élément correspondant si l'on supprimait
l'attribut ID de celui-ci. Amaya avertit l'utilisateur s'il détecte une
annotation orpheline au chargement. Les annotations orphelines sont visibles
dans la vue <strong>Liens</strong> du document et sont symbolisées par
l'icône des annotations sur laquelle est superposé un point d'interrogation
<img src="../images/annotorp.png" alt="Orphan annotation icon" />.</p>

<p>Une annotation est dite <strong>trompeuse</strong> lorsqu'elle ne pointe
pas sur la bonne partie du document. En reprenant notre exemple, nous pouvons
créer une annotation trompeuse en intervertissant le premier et le second
paragraphe. Le XPointer continuera de pointer vers le second paragraphe bien
qu'il devrait pointer désormais sur le premier. Ce problème est encore plus
fréquent lorsque vous annotez un texte qui peut changer. Dans sa version
actuelle, Amaya n'avertit pas l'utilisateur des annotations trompeuses. Une
prochaine version l'avertira de la possibilité d'une annotation d'être
trompeuse.</p>

<p>Comment éviter ces problèmes ?</p>

<p>Si vous êtes l'auteur du document, utilisez les attributs ID aux endroits
stratégiques, par exemple pour les éléments DIV. Amaya vous permet d'associer
ou de retirer automatiquement un attribut ID en sélectionnant l'entrée
<strong>Ajouter/Retirer des attributs ID</strong> du menu
<strong>Liens</strong>. Dans notre exemple, on peut éviter le problème des
annotations trompeuses en ajoutant un attribut ID au second paragraphe:</p>
<pre>  &lt;p id="Amaya"&gt;Pour cela, Amaya utilise...&lt;/p&gt;</pre>

<p>Un XPointer qui pointe sur ce paragraphe est alors</p>

<p style="text-align: center"><code>xpointer(id("Amaya"))</code></p>

<p>Ainsi, ce XPointer pointera toujours sur le même paragraphe, sans se
soucier de la position de celui-ci dans la structure du document.</p>
</div>

<p></p>
</div>
</body>
</html>
