Краткое описание пакета 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) 
            Кодировка атрибута на выходе из конвертера:

        language_code (str)
            Языковой код: фразы, вставляемые в текст, будут на указаном
            языке;

        embed_stylesheet (bool)
            Если флаг установлен, то в сгенерированную станицу будет
            вставлено определение стиля, иначе будет вставлена ссылка на
            ресурс, указанный в параметре stylesheet_path;
                
        stylesheet_path (str) 
            URL ресурса, содержащего определение стиля (используется только
            если флаг embed_stylesheet сброшен);


        field_name_limit (int) 
            Указывает максимальную ширину в (в символах) для одноколоночных имен полей.
            Более длинные имена полей будут распростанены на всю строку таблицы, используемой
            для отрисовки списка полей. Установите значение 0, если ширина не ограничена;

        option_limit (int)
            Указывает максимальную ширину в (в символах) для названий опций в списках опций.
            Более длинные имена опций будут распростанены на всю строку таблицы, используемой
            для отрисовки списка. Установите значение 0, если ширина не ограничена;

        footnote_references (choice)
            Формат для ссылок на сноски, может использоваться "superscript" (верхний индекс)
            или "brackets" (квадратные скобки);
            
        attribution (choice)
            Формат для атрибутов блока цитирования: может быть 'dash',
            'parenthesis', 'parens' или 'none';

        compact_lists (bool)
            Если флаг устанавлен, то будет уменьшен межстрочный интервал между элементами простых и нумерованных
            списков;

        compact_field_lists
            Если флаг установлен, то будет уменьшкн межстрочный интервал между элементами
            списка полей;

        xml_declaration 
            Если флаг установлен, то выходной код будет содержать XML-декларацию, сбрасывать этот флаг не
            рекомендуется;

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


converterlightrest
..................

Конвертер позволяет отформатировать текст в формате "Упрощенного
ReStructured Text". Этот формат примерно соответствует синтаксису ReST, но
использует от него лишь следующие конструкции:

- Разбивку на параграфы;

- Создание нумерованных и ненумерованных списков, без возможности вложения;

- Выделение жирным и наклонным шрифтом.

В отличие от ReST, на выходе конвертера получается фрагмент html-кода, а не
полная, валидная страница. Конвертер ориентирован на форматирования
небольших фрагментов кода, возможно, введенного подозрительными
пользователями.

    ng.app.converter.converter.converterrest.interfaces.IConverterLightReST
        Интерфейс конвертера содержит атрибуты:
        
        use_html_filter (bool)
            Использовать для входного текста фильтр html-конструкций: все
            коды html будут переписаны таким образом, чтобы избежать их
            интерпретации браузером как html-кода.

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. Его использование позволяет создавать веб-приложения с низкой
ресурсоемкостью, несмотря на сложность преобразований, который могут быть
использованы на представления текстовых атрибутов объектов.
[name:недописано]
