- ¿Qué es una Anotación?
- Anotaciones Locales y Remotas
- El Menú Anotaciones
- Preparando la Configuración para las Anotaciones
- Creando una Anotación
- Borrando una Anotación
- Cargando y Presentando Anotaciones
- Navegando entre Anotaciones
- Moviendo Anotaciones
- Problemas con Anotaciones y Documentos Modificados

## Anotaciones en Amaya

### ¿Qué es una Anotación?

La anotaciones son comentarios, notas, explicaciones, u otro tipo de observaciones que pueden adjuntarse a un documento Web o a una parte seleccionada del documento. Como son externas es posible anotar cualquier documento Web de manera independiente, sin necesidad de editar ese documento. Desde el punto de vista técnico, las anotaciones normalmente son vistas como metadatos, ya que dan información adicional sobre una porción existente de datos. En este proyecto, para describir las anotaciones usamos un RDF annotation schema especial.

Las anotaciones pueden guardarse localmente o en uno o más servidores de anotaciones. Cuando un documento es hojeado, Amaya llama a cada uno de esos servidores, solicitando las anotaciones relacionadas con el documento. Actualmente Amaya presenta las anotaciones con los iconos de anotación ( ) que están visualmente incrustados en el documento, como se muestra en la figura de abajo. Si el usuario hace un único clic sobre un icono de anotación, el texto que ha sido anotado se resalta. Si el usuario hace doble clic sobre este icono, el texto de la anotación y otros metadatos se presentan en una ventana aparte.

Una anotación tiene muchas propiedades, incluyendo:

- Localización física: ¿La anotación está almacenada en un archivo local o en una servidor de anotaciones?
- Alcance: ¿Está la anotación asociada a todo el documento o sólo a un fragmento de ese documento?
- Tipo de anotación: 'Anotación', 'Comentario', 'Consulta', ...

### Anotaciones locales y remotas

Amaya puede guardar datos de anotaciones en un sistema de archivo local (llamado "anotaciones locales") o en la Web (llamado "anotaciones remotas"). Anotaciones remotas son las almacenadas en servidores de anotaciones y pueden ser descargadas y almacenadas por cualquiera que tenga los apropiados derechos de acceso, tal como en el caso de otros documentos HTML. También nos referimos a anotaciones remotas como anotaciones públicas o compartidas, ya que pueden ser vistas por otras personas. Si deseas instalar tu propio servidor de anotaciones, por favor, ve a Annotation-Server-HOWTO.

El usuario no necesita un servidor para hacer una anotación local. Las anotaciones locales se almacenan en el directorio de preferencias de usuario, en un directorio especial llamado "`annotations`", y sólo puede ser visto por el dueño (de acuerdo a cómo esté organizado el sistema de derechos de acceso). Este directorio está conformado por tres tipos de ficheros:

annot.index
  asocia URLs con los archivos en los que se almacenan los metadatos de las anotaciones.
index + random suffix
  un fichero que almacena el metadato de las anotaciones relacionadas con una URL dada. El metadato se especifica con RDF.
annot + random suffix.html
  contiene el cuerpo de una anotación, almacenado como XHTML.

Un usuario puede, en cualquier momento, convertir una anotación local en una compartida usando la opción de menú Anotaciones/Post anotación. Si esta operación tiene éxito, la anotación local será borrada ya que será movida a un servidor de anotacion. La siguiente sección describe cómo indicar el nombre del servidor en el que deberían colocarse las anotaciones.

### Menú Anotaciones

La mayoría de los comandos necesarios para manejar anotaciones se encuentran en el menú Anotaciones mostrado abajo. Los comandos se explican más adelante en este documento, en el contexto de las metas del usuario cuando maneja anotaciones.

### Preparando la Configuración para las Anotaciones

El menú de configuración de anotaciones se encuentra bajo la opción de menú Anotaciones/Configurar. La siguiente figura muestra la versión Windows de este menú. La versión Unix tiene una interfaz de usuario un tanto diferente, pero las mismas funcionalidades.

Anotación de usuario
  Un campo que está asociado con cada nueva anotación como el autor de la anotación. Amaya utiliza, por defecto, el identificador de usuario de la persona, cuando crea el campo de metadato autor. La selección de la anotación de usuario le permite a un usuario cambiar este nombre por uno más significativo, por ejemplo, en vez de `u1723242` (que hace felíz a mi administrador de sistema) `marja` (que es el que usan otras personas normalmente cuando hablan conmigo).
Servidores de Anotaciones
  Este campo le dice a Amaya qué servidores debe contactar cuando busque anotaciones. Se pueden especificar uno o más servidores. Hemos reservado el nombre de servidor localhost para decirle a Amaya que queremos buscar anotaciones locales. Esto no significa que estemos poniendo en marcha un servidor local de anotaciones. Si este fuera el caso, necesitaríamos indicar la URL completa. Bajo Unix, los servidores de anotación se especifican como una lista separada por espacios. Bajo Windows, son añadidos uno tras otro tecleando sus nombres directamente en el cuadro de diálogo, utilizando la tecla `Enter` para añadir uno nuevo. Por defecto, el campo para servidores de anotaciones indica un `localhost`.

  Truco: Si quieres deshabilitar temporalmente un servidor de anotación, añade el carácter "-" antes de su URL. Amaya lo ignorará.

Autocargar anotaciones locales/Autocargar anotaciones remotas
  Esta opción le dice a Amaya si solicita o no anotaciones, automáticamente (esto es, consultar a los servidores de anotaciones) cada vez que una URL es navegada. Si no está seleccionada, entonces el usuario tiene que invocar manualmente la función Cargar anotaciones desde el menú Anotaciones. Nótese que si se selecciona la opción `autocargar anotaciones remotas`, puede haber un retraso mientras Amaya resuelve el nombre de DNS de los servidores de anotación. Por defecto ambas opciones aparecen sin seleccionar.
Deshabilitar autocarga remota en cada inicio
  Si esta opción está seleccionada, Amaya restablecerá la opción `autocargar anotaciones remotas` cada vez que se inicie. Esta opción puede ser útil si estás trabajando desconectado a ratos, pero seguirá queriendo autocargar las anotaciones locales, y las remotas de vez en cuando, por ejemplo, cuando te conectas durante un rato.
Servidor de publicación

  Este campo define el servidor en el que serán publicadas las anotaciones. Las anotaciones locales se guardan siempre en una base de datos local, independientemente del valor de este campo. Por defecto este campo está vacío. Advierte que el servidor de publicación no está incluido automáticamente en la lista de servidores a ser consultados, se debe indicar el nombre del servidor de publicación en ambos campos, en cualquier orden que tú elijas.

### Creando una anotación

Esta versión de Amaya soporta dos tipos de anotaciones: anotaciones que se refieren a un documento completo y anotaciones que se refieren a un punto específico o selección en un documento.

Para anotar un documento completo, tan solo selecciona la opción de menú

##

Anotaciones/Anotar documento. Para anotar un punto, pon el cursor en cualquier punto en el documento y selecciona la opción de menú Anotaciones/Seleccionar anotación. Para anotar una selección, selecciona algo en el documento, y luego usa la opción de menú Anotaciones/Anotar selección. En todos estos casos aparecerá una ventana de anotación (ver la figura siguiente). El contenido de esta ventana muestra el metadato de la anotación, dentro de un recuadro, y el cuerpo de la anotación.

Normalmente, el metadato consiste en el nombre del autor, el título del documento anotado, el tipo de anotación, la fecha de creación, y la fecha de última modificación. Algunos de los campos de metadatos tienen propiedades especiales. El campo documento fuente es también un enlace que apunta de vuelta al texto anotado. Si el usuario hace doble clic sobre él, al igual que se sigue cualquier otro enlace en Amaya, el documento anotado será obtenido y el texto anotado aparecerá resaltado. El campo tipos de anotación permite al usuario clasificar la anotación y cambiar su tipo. Haz doble clic sobre el texto "tipo de anotación" para ver la lista de tipos disponibles. Describiremos más abajo cómo pueden los usuarios definir también, sus propios tipos de anotaciones. Finalmente, el campo Última modificación se actualiza automáticamente cada vez que se guarda una anotación.

Debajo, el área principal es el área del cuerpo de anotación. Muestra el contenido actual y puede ser editada como si estuviéramos editando cualquier otro documento HTML, .N.B., aunque todavía no se pueden incluir imágenes en el cuerpo. Algunas de las características pueden no estar listas en la versión inicial, tales como la vista Estructura.

Guardar una anotación es equivalente a guardar cualquier otro documento en Amaya. El usuario sólo necesita seleccionar el comando Archivo/Guardar (o utilizar su equivalente atajo de teclado o botón del menú). Las anotaciones locales se guardan en el directorio "annotations" y las anotaciones remotas se guardan en el servidor de publicación de anotaciones donde son almacenadas si el usuario ha escrito el acceso. Para convertir una anotación local en una compartida, el usuario necesita usar el comando Anotaciones/Publicar anotación y la anotación será guardada en el Servidor de publicación que esté definido en el menú de configuración. Si esta operación tiene éxito, la anotación local será borrada y las futuras operaciones de guardado irán directamente al servidor de anotaciones. En la versión inicial, Amaya no soporta una operación de guardado de una copia de una anotación remota en el directorio local de anotaciones.

Algunos comandos aplicados al documento en la ventana Documento Amaya se aplicarán al documento de anotación en la ventana Anotación. Por ejemplo, el cuerpo de una anotación puede imprimirse con el comando Archivo/Imprimir o recargado con el comando Archivo/Recargar documento. (Nota: Algunas de estas características pueden no estar incluídas aún).

### Borrando una Anotación

El comando del menú Anotaciones/Borrar anotación permite borrar una anotación. Se puede invocar este comando desde una ventana de anotación abierta. También se puede borrar una anotación desde el documento anotado seleccionando primero la anotación, haciendo un único clic sobre el icono de anotación, y luego llamando a este comando de menú.

### Cargando y Presentando Anotaciones

El comando Cargar Anotaciones le dice a Amaya que cargue las anotaciones asociadas a la URL del documento que está siendo navegado en esa ventana. Amaya consultará al servidor de anotaciones, que esté indicado en el cuadro de diálogo Anotaciones/Configurar, pidiéndole cualquier anotación relevante.

Las anotaciones pueden descargarse también automáticamente siempre que se carga una nueva página seleccionando la casilla de verificación Autocargar anotaciones en el cuadro de diálogo Anotaciones/Configurar.

Notese que en esta versión de Amaya, al interrogar a un servidor de anotaciones devolverá todas las anotaciones que están asociadas a un documento. En una versión futura será posible usar un menú personalizado para refinar la cadena de interrogantes que se envía a los servidores.

El menú Anotaciones/Filtro local permite al usuario mostrar o esconder los iconos de anotación desde la vista de documento, por ejemplo, para concentrarse en aquello que realmente le interesan o para hacer más fácil la lectura de un documento lleno de anotaciones. El usuario puede mostrar o esconder anotaciones por tres tipos de metadatos: por el nombre de autor de la anotación, por el tipo de anotación, y por el nombre de servidor de anotación. Para aplicar uno de estos filtros, necesitas hacer clic en el botón de opción para seleccionar un tipo de anotación dado y, luego en el correspondiente botón de acción. Los comandos Mostrar todo y Esconder todo se aplican a todas las anotaciones. Un pequeño e incómodo caracter a modo de prefijo señala el estado de una entrada dada. Este caracter puede ser tanto un espacio (' '), un asterisco ('*') o un guión ('-') para declarar que esas anotaciones que pertenecen a esa entrada dada están todas visibles, todas escondidas,o parcialmente visibles, respectivamente.

Ten en cuenta que el menú filtro sólo muestra las anotaciones que conoce que existen en el momento de su invocación. Si añades nuevas anotaciones entretanto, tendrás que destruir este menú e invocarlo de nuevo para verlas.

Advierte que para cada anotación, el usuario de anotación se muestra concatenando el nombre del autor con el nombre del servidor de anotación en el que está almacenada la anotación, tal como se muestra en la siguiente figura.

### Navegando entre Anotaciones

La anotaciones aparecen como enlaces en la ventana Enlaces que puede abrirse mediante el comando Vistas/Mostrar enlaces. En esta ventana las anotaciones aparecen marcadas con el mismo icono del lápiz, usado en las anotaciones en la ventana de documento. La ventana Enlace muestra todas las anotaciones, sin tener en cuenta si han sido escondidas con el menú Filtro Local de Anotaciones. Al igual que en la ventana de documento, un único clic sobre la anotación seleccionará el texto anotado en la ventana de documento y un doble clic abrirá la anotación. Este es un ejemplo de cómo navegar de un enlace de anotación a otro, incluso si la anotación no pude ser vista por el usuario debido a su discapacidad o debido a las características del dispositivo usado.

### Moviendo anotaciones

Amaya también te permite mover una anotación a cualquier otra parte del mismo documento. Esto es interesante, por ejemplo, para manejar anotaciones huérfanas y corruptas. Se puede mover una anotación a la selección actual o también a el valor de un XPointer almacenado. Por el momento sólo es posible mover anotaciones en el mismo documento en el que han sido creadas.

Para mover una anotación a la selección actual, primero hay que abrir la ventana de anotación. Entonces hay que hacer clic en el documento anotado y seleccionar algo en él. Luego, en la Ventana Anotación, invocar el menú Anotaciones/Mover a selección. Amaya moverá entonces el icono de anotación al texto seleccionado y marcará el documento de anotación como modificado. Para conseguir que este cambio se efectivo hay que guardar la anotación, de otra manera se perderán los cambios. Al igual que en la creación de anotaciones se puede mover una anotación a la posición actual del cursor, sin tener que hacer una selección.

También se puede memorizar la posición a la que se quiere mover la anotación y, entonces, moverla ahí. Esto es útil, por ejemplo, si se quieren mover varias anotaciones a la misma posición o si se quiere desplazarse a cualquier parte del documento antes de moverlas. Para hacer esto, haz una selección (o sólo posiciona el cursor) en el lugar en el que quieres mover la anotación. Entonces utiliza el menú Enlace/Almacenar enlace como XPointer para almacenar internamente un XPointer que represente la selección. Finalmente, en la ventana Anotaciones, utiliza el menú Anotaciones/Mover para almacenar XPointer para mover la anotación a su nueva localización. Al igual que antes deberás guardar la anotación para hacer efectivo el cambio.

### Problemas con Anotaciones y Documentos Modificados

Si se está usando anotaciones con documentos en vivo (documentos cuyos contenidos pueden ser modificados) puedes encontrar dos tipos de problemas: anotaciones huérfanas y anotaciones corruptas. Déjanos antes describir un poco más en detalle cómo Amaya añade anotaciones a los documentos.

Amaya utiliza XPointer para describir dónde debe añadirse una anotación a un documento. XPointer está basado en la estructura del documento. Para construir un XPointer, por ejemplo para una selección, comenzamos desde el primer punto de la selección y vamos regresando a través de la estructura del documento hasta encontrar la ruta del documento. Si un elemento tiene un atributo ID, paramos de construir el XPointer y consideramos que el comienzo de ese XPointer es el elemento que tiene ese valor de atributo ID. Por ejemplo, si miras el código HTML de este documento, notarás que esta sección (Problemas con anotaciones...) está incluida dentro de un elemento DIV que tiene un atributo ID con el valor "Issues". Aquí hay un extracto del código fuente:

      <div id="Issues">
      <h3>Problemas con ....</h3>
      <p>Si se está usando...</p>
      <p>Amaya utiliza <strong>XPointer</strong>...</p>
      ...
      </div>

Y aquí el XPointer que apunta al segundo párrafo:

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

El XPointer de arriba apunta al segundo elemento p, desde el elemento padre que tiene un atributo ID con el valor "Issues". (Para seleccionar un párrafo completo, ponemos el cursor en el párrafo y presionamos la tecla escape [Unix] o F2 [Windows]). Nótese que el uso del atributo ID permite al autor del documento mover la selección completa, donde quiera en el documento, sin necesidad de actualizar el XPointer. El XPointer no depende del elemento que precede ese particular elemento DIV.

Decimos que una anotación se queda huérfana cuando ya no puede ser añadida a un documento, esto es, cuando el XPointer no determina nunca más ningún elemento en la estructura. Esto pasa cuando una estructura de documento se modifica. Por ejemplo, el XPointer de arriba no podría determinar nunca más si eliminamos el atributo ID "Issues". Amaya te advertirá si detecta cualquier anotación huérfana mientras descarga una serie de anotaciones desde un servidor de anotaciones. Todas las anotaciones huérfanas son visibles desde la vista Enlaces y están asociadas con un icono que muestra un signo de interrogación superpuesto al lápiz de anotaciones .

Decimos que una anotación es corrupta cuando apunta a una pieza de información errónea. Volviendo a nuestro ejemplo, podemos crear una anotación corrupta si intercambiamos el primer y segundo párrafo. El XPointer continuará apuntando al segundo párrafo, a pesar de que nos gustaría que apuntara al primer párrafo. Este problema se hace incluso más común cuando anotas una porción de texto que puede cambiar. En la primera versión, Amaya no advierte al usuario si una anotación está corrupta. Una futura versión puede avisar al usuario de la posibilidad de que una anotación pueda llegar a ser corrupta.

¿Cómo puedes protegerte a ti mismo?

Si eres el autor de un documento, intenta usar el atributo ID en lugares estratégicos, por ejemplo, en los elementos DIV. Amaya te permite asociar automáticamente o eliminar un atributo ID a/desde una serie de elementos por medio del comando de menú Especial/Crear/Suprimir atributos ID. En el ejemplo de arriba, nosotros podríamos haber evitado el problema de las anotaciones corruptas si hubiésemos añadido un atributo ID al segundo párrafo:

      <p id="Amaya">Amaya utiliza...</p>

Un XPointer que apunta a este párrafo es:

`xpointer(id("Amaya"))`

De esta manera, el XPointer apuntará al mismo párrafo, independientemente de su posición en la estructura del documento.