- Définition
- Annotations locales et distantes
- Menu des annotations
- Menu de configuration pour les annotations
- Créer une annotation
- Supprimer une annotation
- Charger et afficher une annotations
- Activer des annotations
- Problèmes relatifs aux annotations et aux documents modifiés

## Les annotations dans Amaya

### Définition

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 de celui-ci. 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. Dans Amaya, nous utilisons 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 (voir figure ci-dessous). Lorsque l'utilisateur clique sur l'icône d'annotation, le passage annoté est mis en évidence. Si l'utilisateur double-clique sur l'icône alors le contenu de l'annotation ainsi que les autres méta-données lui sont présentées dans une nouvelle fenêtre.

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: 'Annotation', 'Comment', 'Query', ...

### Annotations locales et distantes

Amaya peut sauver les annotations dans un fichier local (annotations locales) ou sur le Web (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".

Les annotations locales ne nécessitent pas l'utilisation de serveur. Elles sont enregistrées sous le repértoire de configuration d'Amaya, 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 meta-données d'une annotation relative à une URL. Les meta-données sont spécifiées avec RDF.
annot + random suffix.html
  contient le corps de l'annotation enregistrée en XHTML.

Un utilisateur peut à tout moment transformer une annotation locale en une annotation partagée en utilisant l'entrée Enregistrer une annotation du menu Annotations. Si cette commande réussit, l'annotation est supprimée localement et transférée sur un serveur d'annotations. La section suivante décrit comment définir le nom du serveur d'annotations sur lequel les annotations distantes sont enregistrées.

### Menu des annotations

La plupart des commandes utilisées pour la gestion des annotations se trouvent dans le menu d'annotations représenté ci dessous.

### Menu de configuration pour les annotations

Ce menu est appelé à partir de l'entrée Configuration. La figure suivante montre la version Windows de ce menu. La version Unix a une interface utilisateur légèrement différente mais offre les mêmes fonctionnalités.

Nom de l'utilisateur (Annotation user)
  Ce champ est associé à chaque nouvelle annotation et définit l'auteur de l'annotation. Par défaut, Amaya utilise le nom de connexion pour construire la méta-donnée auteur. Le champ "Annotation user" permet à un utilisateur de remplacer ce nom par un nom plus significatif comme par exemple, changer le nom `u1723242` en `marja`.
Serveurs d'Annotations (Annotation servers)
  Ce champ définit les serveurs d'annotations à interroger lorsque Amaya cherche une annotation. Vous pouvez spécifier un ou plusieurs serveurs. Le nom de serveur localhost est réservé, il indique à Amaya de chercher localement les annotations. Cela ne signifie pas que l'on utilise un serveur pour les annotations locale, pour cela il faudrait donner l'URL complète de celui-ci. Sous Unix, les serveurs d'annotations sont spécifiés à la suite, séparés par un espace. Sous Windows, ils sont spécifiés les uns après les autres et séparés par la touche `Return`. Par défaut, ce champ est initialisé avec `localhost`.

  ASTUCE: Vous pouvez inhiber la consultation d'un serveur d'annotations en préfixant l'URL du serveur avec le caractère '-'.

Chargement automatique des annotations locales et distantes (Autoload annotations)
  Ces options indiquent à Amaya de rechercher automatiquement ou non les annotations lorsqu'une nouvelle URL est chargée. Si elles ne sont pas positionnées alors l'utilisateur doit explicitement sélectionner l'entrée Charger les annotations pour visualiser celles-ci. Il peut y avoir un certain délai lorsque Amaya charge les annotations distantes, ce délai étant du à la résolution du nom DNS des serveurs d'annotations. Par défaut, ces options sont désactivées.
Désactiver le chargement automatique des annotations distantes
  Lorsque cette option est activée, Amaya réinitialise l'option `Chargement automatique des annotations distantes` au démarrage. Cela est très utile si vous travaillez en mode déconnecté de temps en temps et que vous voulez continuer à charger automatiquement les annotations locales tout en rechargeant les annotations distantes lorsque vous êtes connectés.
Serveur de publication des annotations (Annotation Post Server)
  Ce champ définit le serveur sur lequel les annotations sont enregistrées. Les annotations locales sont toujours sauvegardées dans un répertoire local, sans tenir compte de ce champ. Par défaut, il est vide. Il est à noter que le serveur sur lequel les annotations distantes sont enregistrées n'est pas nécessairement inclus dans la liste des serveurs interrogés; pour cela, vous devez rentrer son nom dans chacun des deux champs, dans l'ordre que vous voulez.

### Créer une annotation

La version courante d'Amaya supporte deux sortes d'annotations: celles qui s'appliquent sur le document entier et celles qui s'appliquent sur une partie ou une sélection du document. Pour annoter un document entier, sélectionnez l'entrée Annoter le document du menu Annotations. Pour annoter une partie, placez le curseur sur la partie désirée et sélectionnez l'entrée Annoter la sélection. Pour annoter la sélection, utilisez la même entrée après avoir fait la sélection désirée. Dans tous les cas, une fenêtre d'annotation s'affichera (figure suivante). Le contenu de cette fenêtre montre les méta-données de l'annotation à l'intérieur d'un cadre et le corps de l'annotation à l'extérieur.

Les méta-données actuellement définies pour une annotation indiquent 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. Ainsi, le champ document source est également un lien qui pointe sur le texte annoté. Si l'utilisateur double-clique dessus (comme pour tout lien dans Amaya) alors 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 permet à l'utilisateur de classer les annotations et de changer leur type. Un double-clic sur ce champ montre la liste des types disponibles. Nous préciserons plus loin comment un utilisateur peut 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. Il est à noter que la version courante d'Amaya ne supporte pas les images dans le corps des annotations et que certaines des fonctionnalités de celles-ci ne sont pas encore disponibles, comme la vue structure par exemple.

Sauver une annotation revient à sauver n'importe quel autre document, l'utilisateur doit juste sélectionner l'entrée Sauver du menu Fichier ou cliquer 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 sous le serveur d'annotation correspondant, si l'utilisateur possède un droit d'écriture dessus. Pour transformer une annotation locale en une annotation publique (distante), l'utilisateur doit utiliser l'entrée Enregistrer les annotations, elles seront alors enregistrées sous le serveur défini dans le menu de configuration 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. Dans la version initiale des annotations, l'opération inverse (transfert d'une annotation distante dans le répertoire local) n'est pas supportée .

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

### Détruire une annotation

La commande Détruire une annotation du menu de la fenêtre d'annotation vous permet de supprimer celle-ci. Vous pouvez également supprimer une annotation à partir du document annoté en sélectionnant l'icône de celle-ci puis en appelant cette commande dans le menu du document annoté.

### Charger et présenter les annotations

La commande Charger les 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 par le menu de Configuration. Les annotations peuvent également être chargées automatiquement en choisissant l'option Autoload annotations dans le menu de configuration. Dans la version actuelle des annotations, la recherche sur un serveur d'annotations retourne toutes les annotations associées à un document. Dans une prochaine version, il sera possible de mieux cibler la requête envoyée aux serveurs.

L'entrée Filtre local permet à l'utilisateur de montrer ou de cacher les icônes d'annotation dans un document annoté pour mieux se concentrer par exemple sur ce qui l'intéresse ou pour faciliter la lecture d'un document annoté. L'utilisateur peut filtrer ces icônes selon trois critères: le nom de l'auteur de l'annotation, le type de l'annotation et le nom du serveur d'annotations. Pour appliquer chacun de ces filtres, cliquez sur le texte correspondant pour sélectionner un type donné d'annotation puis sur le bouton correspondant à l'action. Les commandes Montrer Tout et Cacher Tout s'appliquent sur l'ensemble des annotations. On prefixe chaque entrée du menu d'un espace (' '), d'une étoile ('*') et d'un tiré ('-') pour indiquer que toutes les annotations appartenant à une catégorie donnée sont visibles, cachées ou partiellement cachées, respectivement.

Il est à noter que le menu Filtre vous montre l'état courant du document au moment où le filtre est invoqué. Si vous ajoutez des nouvelles annotations entre temps, le filtre ne les montrera pas. Il faudra appuyer sur le bouton terminer et le rappeler pour voir le nouvel état.

Pour chaque annotation, le nom de l'utilisateur est obtenu en concaténant le nom de l'auteur et le nom du serveur d'annotations sur lequel celle-ci est enregistrée, comme montré dans la figure suivante.

### Activer des annotations

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. La vue Liens montre toutes les annotations du document sans tenir compte du fait qu'elles aient été ou non cachées par le menu Filtrer. Comme dans la vue principale, un simple-clic sur l'icône met en évidence le partie annotée du document et un double-clic ouvre l'annotation. La figure ci-dessous montre un exemple de navigation d'un lien d'annotation vers un autre même si l'annotation ne peut être vue par tous les utilisateurs à cause d'une indisponibilité ou des caractéristiques du support utilisé.

### 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 Spécial. 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.