Краткое описание пакета ng.app.converter
========================================

Пакет разработан для поддержки преобразования содержимого объектов,
выполняемого при помощи настраиваемых независимых конвертеров. Конвертеры
настраиваются через веб-интерфейс и могут разрабатываться независимо от
пакета. Результат конверсии кешируется, содержимое кеша обновляется при
устаревании по сравнению с настройками конвертера или содержимым объекта.

Настройка пакета включает в себя установку кеша, утилиты настройки
отображения атрибутов и конвертеров.

Настройка кеша
--------------

В качестве кеша используется объект
ng.app.converter.cachestore.cachestore.Cachestore с интерфейсом
ng.app.converter.cachestore.interfaces.ICachestore. Он должен быть создан и
зарегистрирован с этим интефейсом и пустым именем. При внесении серьезных
изменений в настройки конвертеров рекомендуется стереть содержимое кеша.
Настройка кеша производится при помощи следующих параметров:

    eventdelta (int) 
        Погрешность времени допустимая при установлении факта
        устаревания элемента кеша, рекомендуется ставить порядка двух
        секунд;
        
    max_caching_time (int) 
        Максимальное время жизни элемента кеша, обращение по истечении этого
        времени приведет к регенерации элемента. Рекомендуемое значение
        не менее 864000 секунд (10 дней).

Настройка утилиты отображения атрибутов
---------------------------------------


Конвертеры
----------

Конвертеры должны создаваться и регистрироваться под интефейсом
ng.app.converter.converter.interfaces.IConverter или производным от него.
Имя конвертера при регистрации должно позволять легко идентифицировать
конвертер при дальнейшей настройке.

converterhead  
.............

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

    ng.app.converter.converter.converterhead.interfaces.IConverterHead
        Интерфейс конвертера, содержит атрибуты:
        
        bytes  (int)
            Количество байт от начала атрибута которое
            будет использовано (не более этого значения),

        lines (int)
            Количество строк от начала атрибута которое
            будет использовано (не более этого значения),

        regexp (unicode)
            Регулярное выражение которое будет использовано для
            разбора, результат разбора преобразуется в словарь,
            
        format (тип: unicode)
            Формат, используемый для формирования значения, форматирование
            использует словарь полученный регулярным выражением.

converterannotator  
..................

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

(в настоящее время работоспособность конвертера под вопросом)


converterregexp  
...............

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

    ng.app.converter.converter.converterregexp.interfaces.IConverterRegexp
        Интерфейс конвертера, содержит атрибуты:
        
        regexp (unicode)
            Регулярное выражение которое будет использовано для
            разбора, результат разбора преобразуется в словарь,
            
        format (тип: unicode)
            Формат, используемый для формирования значения, форматирование
            использует словарь полученный регулярным выражением.
            
converterst    
...........

Конвертер позволяет отформатировать текст в формате "Structured Text". Если
результыты форматирования неудовлетворительны, рекомендуется объединять
конвертер с конвертерами converterregexp и converterxslt, для
дополнительного форматирования.

    ng.app.converter.converter.converterst.interfaces.IConverterST
        Интерфейс конвертера, не содержит никаких настроечных атрибутов.

converterrest   
.............

Конвертер позволяет отформатировать текст в формате "ReStructured Text".
Если результыты форматирования неудовлетворительны, рекомендуется объединять
конвертер с конвертерами converterregexp и converterxslt, для
дополнительного форматирования.

    ng.app.converter.converter.converterrest.interfaces.IConverterReST
        Интерфейс конвертера, содержит атрибуты:
        
        halt_level (int) 
            Максимально допустимый уровень заголовка;
            
        initial_header_level (int) 
            Начальный уровень заголвка;
            
        input_encoding (str) 
            Ожидаемая кодировка атрибута;
            
        output_encoding (type:  str) 
            Кодировка атрибута на выходе из конвертера:

converterxslt  
.............

Конвертер позволяет применить к входному тексту xslt-преобразования.
Предполагаемое применение - обработка документов в XML-форматах. В настоящее
время конвертер сделан под преобразоване HTML-документов.

    ng.app.converter.converter.converterxslt.interfaces.IConverterXSLT
        Интефейс конвертера, содержит атрибуты:
        
        html_charset (str) 
            Кодировка, которая будет использована, если кодировку входного
            текста нельзя определить по его содержимому.

Текст xslt-преобразования загружается в конвертер через специальную страницу
загрузки (как файл).

converterchain      
..............

Конвертер позволяет строить цепочки из зарегистрированных конвертеров. Очень
удобен при формировании конвертеров на основе converterregexp.

    ng.app.converter.converter.converterchain.interfaces.IConverterChain
        Интефейс конвертера, содержит атрибуты:
        
        chain (tuple of str) 
            Кортеж строк, идентифицирующиз зарегистрированные конвертеры.

convertercontainer  
..................

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

    ng.app.converter.converter.convertercontainer.interfaces.IConverterContainer
        Интерфейс конвертера, не содержит никаких настроечных атрибутов.
        
converterselect  
...............

Экспериментальный конвертер, позволяющий выделить из текста HTML-страницы
значимый текст и обрезать оформление. Эксперимент пока неудачный :).

converterwiki
.............

Конвертер, форматирующий страницу как WIKI. Разработка конвертера
приостановлена, так как необходимый конвертер удалось собрать средствами
converterchain, converterregexp.


Заключение
----------

Идея этого пакета прошла хорошую проверку временем в продукте, реализованном
в Zope2. Его использование позволяет создавать веб-приложения с низкой
ресурсоемкостью, несмотря на сложность преобразований, который могут быть
использованы на представления текстовых атрибутов объектов.
