# Использование файла HTML.trans

Этот документ является введением в механизм структурного преобразования предоставляемый Amaya. Он описывает синтаксис языка преобразования и то, каким образом выполняются эти преобразования с помощью редактора.

Файл `amaya/HTML.trans` содержит описания доступных преобразований. Этот файл может редактироваться во время работы Amaya. Во время вызова процедуры преобразования, редактор может динамично выполнять синтаксический анализ на предмет добавления новых преборазований в течении текущего сеанса редактирования.

Внимание: Так как содержание файла описания преобразований может содержать тэги, не редактируйте файл `HTML.trans` с помощью Amaya. Используйте любой текстовый редактор.

## Синтаксис языка преобразований Amaya

Комментарии начинаются символом`!`и продолжаются до конца линии.

Файл содержит список описаний преобразований. Каждое преобразование описывается тремя частями :

- имя заканчивается двоеточием `:`
- исходный образец заканчивается точкой с запятой`;`
- и список правил заключённый между фигурными скобками `{ }` , каждое правило заканчивается точкой с запятой `;`

Для удобства конечного пользователя имена появляются в меню Преобразовать для идентификации самого преобразования.

### Образец

Образец описывает определенную организацию элементов преобразования. Он работает как дополнительный фильтр к HTML dtd. Целью образца является идентификация специфической комбинации элементов, применяемого преобразования. В образце возможно указать условия на последовательность тэгов, на содержании тэга, на существование и значения атрибутов.

Формально, образец содержит HTML тэги (возможно с атрибутами) и некоторых операторов композиции:

`|` для выбора

`,`для потомков

`+` для последовательности

`?` для опций

`( )` для группируемых узлов

Фигурные с:обки `{` `}` определяют содержание узла.

Символ `*` является маркером, соответствующий любому типу элемента.

Имеется возможность переименовывать тэг предшествующий имеющемуся, имя сопровождается двоеточием (`:`).

Тэг может иметь атрибуты. Если для атрибута величина не определена, то элемент будет согласован, если присутствует сам атрибут. Если для атрибута величина определена, то элемент будет согласован, если атрибут присутствует и имеет указанное значение.

Примеры образцов приведены в конце этого документа.

### Правила

Правило показывает, как некоторые элементы, идентифицированные в образце, будут преобразованы. Правило имеет две части, разделённые символом `>`:

- исходный тэг или имя определённое в образце,
- целевой список тэгов предоставляет генерируемые тэги и место, куда они будут вставлены при преобразовании исходного элемента.

Целевой список тэгов сам разделен на две части, разделённый двоеточием (`:`):

- генерируемый путь местоположения (идентифицирует место куда будут вставляться новые тэги)
- список генерируемых тэгов

Генерируемый путь местоположения выполняет поиск в крайнем левом ответвлении дерева документа, начиная с родительского элемента, который соответствует самому верхнему символу образца.

В целевом списке тэгов, символ точка (`.`) используется для понижения в структуре дерева.

Если генерируемый список тэгов завершает специальный символ звездочка (`*`), исходный тэг элемента не изменяется, но он может быть перемещён в другое место в месте назначения.

Если исходный тэг или имя в левой части правил имеется в образце в количестве более одного экземпляра, правило преобразовывает все элементы, соответствующие местонахождению тэга в образце.

## Процесс преобразования

Когда пользователь выбирает команду Преобразовать из меню Правка, Amaya выполняет анализ файлов `HTML.trans` (или `MathML.trans`, и прочих). Затем выбирает элементы, сравнивая их с образцами для каждого преобразования. Названия сравниваемых преобразований должны быть предложены пользователю во всплывающем меню.

Если выбранным элементам соответствует несколько преобразований с одним и тем же именем, пользователю будет предложено преобразование с более высоким уровнем. Если на одном и том же уровне имеется несколько преобразований, то первым будет предлагаться преобразование объявленное первым в файле в HTML.trans. Как следствие, при большом количестве преобразований, рекомендуется определять (связывать) преобразования с определенными образцами.

Как только пользователь выберет преобразование, структура места назначения будет построена согласно правилам, в то время как выбранные элементы пересекаются.

И в заключении, содержание исходных элементов (текст и изображения, но только структурированные элементы) будет перемещено в сгенерированные элементы.

Процесс преобразования HTML документов полностью описан в Интерактивная реструктуризация HTML документов, представленный на пятой международной WWW конференции в Париже, в мае 1996 года, Cйcile Roisin и Stйphane Bonhomme.

## Примеры

- Первый пример объединяет несколько последовательных ненумерованных списков (UL) в уникальный список.

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

  Образец соответствует последовательности ненумерованных списков (UL), содержащих последовательность пунктов (LI).

  Правило гласит, что при проходе по согласованным элементам, пункт будет всякий раз выпадать, когда в пределах нового UL будет создаваться тэг LI. Когда правило применяется в первый раз, результирующая структура будет пуста, так что не будет существовать никакого UL элемента, в котором эти LI могут быть созданы. Поэтому, правило может применяться только тогда, когда будет создан UL.

- Второй пример преобразовывает список определения в таблицу.

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

  Образец соответствует любому элементу списка определения (dl).

  Правила объясняют, как выполняется строительство таблицы путём приращения, при прохождении структуры выбранного списка определения:

  - Каждый dt включает в себя создание новой строки (tr) в теле таблицы.
  - Каждый dd включает в себя создание новой ячейки (td) в последней (предыдущей) существующей строке таблицы.

- Третий пример удаляет элемент таблицы, сохраняя её содержание неизмённым, но извлекая его из таблицы.

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

  Образец соответствует любой таблице и идентифицирует содержание каждой ячейки таблицы (cell_content).

  Второе правило гласит, что содержание каждой ячейки должно быть перемещено в место первоначальной таблицы.

- Для более подробных примеров смотрите файл `amaya/HTML.trans`.