# Utilizar el archivo HTML.trans

Este documento es una introducción al mecanismo de transformaciónestructural incluido en Amaya. Describe la sintaxis del lenguaje de transformación y la manera en que esas transformaciones se efectúan en el editor.

El archivo `amaya/HTML.trans` contiene la descripción de las transformaciones disponibles. Puedes editar este archivo mientras estás utilizando Amaya. El archivo se analiza cada vez que solicitas una transformación, así que puedes añadir transformaciones mientras estás editando un documento.

Atención: Puesto que la descripción de las transformaciones puede incluir etiquetas, no edites el archivo `HTML.trans` con Amaya. Puedes utilizar cualqueir otro editor de texto.

## Sintáxis del lenguaje de transformación de Amaya

Los comentarios comienzan por `!` y continúan hasta el final de la línea.

El archivo consiste en un lista de descripciones de tranformaciones. Cada transformación se describe en tres partes:

- un nombre terminado con dos puntos`:`
- un patrón origen terminado con punto y coma `;`
- y una lista de reglas entre llaves `{ }` en la que cada regla se termina por un punto y coma `;`

El nombre aparece en el menú Transformar e identifica la transformación de cara al usuario.

### El patrón

El patrón describe la organización específica de los elementos a transformar. Actúa como filtro de la DTD HTML. El patrón identifica la combinación de elementos a la que puede aplicarse la transformación. El patrón puede incluir condiciones sobre la secuencia de etiquetas, sobre el contenido de una etiqueta y sobre la existencia y valor de los atributos.

Formalmente un patrón contiene etiquetas HTML (en su caso, con atributos) y algunos operadores:

`|` indica elección

`,` indica hermano

`+` indica secuencia

`?` indica elección

`( )` indica agrupación de nodos

Las llaves `{` `}` definen el contenido de un nodo.

El símbolo `*` inidca que se seleccionará cualquier tipo de elemento.

Puedes renombrar una etiqueta escribiendo antes de ella un nombre seguido de dos puntos (`:`).

La etiqueta puede tener atributos. Si no se especifica ningún valor para un atributo, se seleccionará cualquier elemento que tenga el atributo. Si se especifica un valor para un atributo, tan sólo se seleccionarán los elementos que contengan el atributo y el valor especificado.

Al final del documento puedes consultar ejemplos de patrones.

### Las reglas

Una regla expresa cómo se transformarán los elementos identificados por el patrón. Una regla tiene dos partes separadas por el símbolo `>`:

- una etiqueta origen o un nombre definido en el patrón,
- una lista de etiquetas destino, que indica las etiquetas que deben generarse y el lugar en que se insertan al transformar el elemento origen.

La lista de etiquetas destino se divide a su vez en dos partes separadas por dos puntos (`:`):

- el camino de generación (que identifica el lugar en que se insertan las nuevas etiquetas)
- la lista de etiquetas a generar

El camino de generación se recorre a partir de la rama situada más a la izquierda en el árbol del documento, comenzando en el padre del elemento que coincide con el símbolo más alto del patrón.

En la lista de etiquetas destino, el símbolo punto (`.`) se emplea para bajar en la estructura del árbol.

Si el símbolo especial asterisco (`*`) completa la lista de etiquetas a generar, la etiqueta origen no cambia, pero puede situarse en otro lugar en el destino.

Si la etiqueta origen o el nombre situado en la parte izquierda de una regla aparece más de una vez en el patrón, la regla transforma todos los elementos del patrón que coincidan.

## Proceso de transformación

Cuando el usuario elige el comando Transformar del menú Editar, Amaya analiza el archivo `HTML.trans`. A continuación, los elementos seleccionados se comparan con el patrón de cada transformación. Los nombres de las trasnformaciones coincidentes se proponen al usuario en un menú emergente.

Si se pueden aplicar varias transformaciones con el mismo nombre a los elementos seleccionados, se propone al usuario la transformación que coincide al nivel más alto. Si se pueden aplicar varias transformaciones del mismo nivel, se propone la que aparezca primero en el archivo `HTML.trans`. En consecuencia, se recomienda especificar antes las transformaciones específicas que las generales.

Una vez que el usuario ha elegido un transformación, la estructura de destino se construye siguiendo las reglas mientras se recorren los elementos seleccionados.

Finalmente, el contenido de los elementos origen (texto e imágenes, pero también contenido estructurado) se sitúa en los elementos generados.

Este proceso de transformación de los documentos HTML se describe en detalle en el artículo Reestructurar interactivamente documentos HTML, presentado en la 5ª conferencia internacional WWW en Paris, Mayo 1996, por Cécile Roisin y Stéphane Bonhomme.

## Ejemplos

- El primer ejemplo une varias listas no ordenadas (ul) consecutivas en una única lista.

      Merge Lists: (ul{li+})+;
          {
          li > ul:li;
          }

  El patrón coincide con una secuencia de listas no ordenadas (ul), que contengan items (li).

  La regla significa que cada vez que se encuentra un item al recorrer los elementos seleccionados, se crea una nueva etiqueta li dentro de un ul. Cuando se aplica la regla por primera vez, la estructura resultante está vacía, por lo que no existe elemento ul en el que crear el li. Una vez se ha cereado el ul, se puede aplicar la regla.

- El segundo ejemplo transforma una lista de definición en una tabla.

      Table: dl{(dt|dd)+};
         {
         dt > <table border=1>.tbody:tr.td;
         dd > <table border=1>.tbody.tr:td;
         }

  El patrón coincide con cualquier elemento lista definición (dl).

  Las reglas explican cómo se crea la tabla al recorrer la estructura de las listas de definición seleccionadas.

  - Cada dt implica la creación de una nueva fila (TR) en el cuerpo de la tabla.
  - Cada dd implica la creación de una nueva celda (TD) en la última fila de la tabla.
- El tercer ejemplo elimina una tabla, manteniendo su contenido sin cambios, pero fuera de la tabla.

      Remove Table:
      table{?caption,?(body:*{(tr{(td{(?cell_content:*)+}|
                                   th{(?cell_content:*)+}
                                 )})+})+};
           {
           caption>h3;
           cell_content>:*;
           }

  El patrón coincide con cualqueir tabla e identifica el contenido de cada celda de la tabla (cell_content).

  La segunda regla significa que el contenido de cada celda se situará en el lugar donde se encontraba la tabla original.

- Ver el archivo `amaya/HTML.trans` para consultar otros ejemplos de transformaciones.