Amaya

## Annoter des documents

### Qu'est-ce qu'une annotation ?

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 schéma RDF pour décrire les annotations.

Les annotations peuvent être enregistrées localement ou sur un ou plusieurs serveur(s) d'annotations. 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 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.

Une annotation possède plusieurs propriétés :

- Point de stockage: dans le système de fichiers de l'utilisateur ou sur un serveur d'annotations.
- Etendue : l'annotation est associée à un document entier ou à une fragment de celui-ci.
- Type de l'annotation: remarque, commentaire, question, ...

### Annotations locales et distantes

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

Les annotations locales ne nécessitent pas l'utilisation de serveur. Elles sont enregistrées sous le répertoire AmayaHome, dans un répertoire spécifique appelé `annotations` et peuvent être visualisées uniquement par leur auteur (selon les droits d'accès en fonction).

Ce répertoire comporte trois sortes de fichiers :

- `annot.index` : les URL associées aux fichiers dans lesquels les méta-données des annotations sont sauvegardées.
- `index + random suffix` : 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.
- `annot + random suffix.html` : contient le corps de l'annotation enregistrée en XHTML.

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

#### Annotations distantes

Les annotations distantes 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.

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 "Annotation-Server HOWTO".

### Créer une annotation

Avant de créer une annotation il est recommandé de fixer certains paramètres dans les Préférences (voir la section Configuration des annotations)

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.

- Pour annoter un document entier, sélectionnez l'entrée Annoter le document du sous-menu Outils/Annotations.
- Pour annoter une position, placez le point d'insertion à cette position et sélectionnez l'entrée Annoter la sélection.
- Pour annoter une partie, faire la sélection désirée et sélectionnez l'entrée Annoter la sélection.

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

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

Certaines de ces méta-données ont des propriétés spécifiques.

- Le champ Document source 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.
- La méta-donnée Type de l'annotation 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.
- Enfin, la méta-donnée Date de dernière modification est automatiquement mise à jour lorsque l'annotation est sauvegardée.

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

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

### Enregister une annotation

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

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.

Pour transformer une annotation locale en une annotation publique (distante), l'utilisateur doit utiliser l'entrée Enregistrer sur le serveur. 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.

La sauvegarde des annotations se fera alors directement sur le serveur d'annotations.

### Détruire une annotation

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

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é.

### Charger et présenter les annotations

La commande Outils/Annotations/Charger annotations 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 Préférences/Annotations.

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

### Les annotations dans la vue Liens

Les annotations apparaissent dans la vue Liens 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.

### Répondre aux annotations / fils de discussion

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

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 Créer une annotation).

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

Les réponses peuvent également être annotées comme n'importe quel document, comme expliqué dans la section Créer une annotation.

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.

### Problèmes connus: fils incomplets

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.

### Problèmes relatifs aux annotations et aux documents modifiés

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

Pour cela, Amaya utilise le mécanisme XPointer. 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:

      <div id="Issues">
      <h3>Problèmes sur ....</h3>
      <p>Si vous utilisez ...</p>
      <p>Pour cela, Amaya utilise le mécanisme <strong>XPointer</strong>...</p>
      ...
      </div>

Et voici le XPointer qui pointe sur le second paragraphe:

`xpointer(id("Issues")/p[2])`

Le XPointer ci-dessus pointe sur le second élément `p` à 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.

Une annotation est dite orpheline 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 Liens du document et sont symbolisées par l'icône des annotations sur laquelle est superposé un point d'interrogation .

Une annotation est dite trompeuse 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.

Comment éviter ces problèmes ?

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 Ajouter/Retirer des attributs ID du menu Liens. Dans notre exemple, on peut éviter le problème des annotations trompeuses en ajoutant un attribut ID au second paragraphe:

      <p id="Amaya">Pour cela, Amaya utilise...</p>

Un XPointer qui pointe sur ce paragraphe est alors

`xpointer(id("Amaya"))`

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