# Улучшение &appname;

Как и в случае других свободных программ, &appname; полностью открыта для улучшения. Написание сценариев для импорта, экспорта или изменения данных не представляет особой сложности. В этой главе рассказывается о том, как это сделать.

## Формат файла

По умолчанию файл данных &appname; представляет собой zip-архив, обычно с расширением `.tc`. Внутри архива находится файл верхнего уровня `tellico.xml`. Изображения могут либо содержаться в папке `images/` архива, либо включаться в данные &XML; напрямую в кодировке Base64. Изображения также могут храниться внутри папки данных приложения: в этом случае они отсутствуют в файле данных. &appname; также позволяет загрузить отдельно сам файл &XML; в несжатом виде.

### Данные &XML;

#### Коллекция

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE tellico PUBLIC "-//Robby Stephenson/DTD Tellico V11.0//EN" "http://periapsis.org/tellico/dtd/v11/tellico.dtd">
    <tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="11">
     <collection title="My Books" type="2">
     </collection>
    </tellico>

Файл начинается с обязательного объявления &XML; и кодировки, за которыми следует описание типа документа (doctype). DТD-версия типа документа увеличивается при добавлении нового типа поля или указании дополнительных свойств для полей по умолчанию. &appname; позволяет открыть и прочитать любые предыдущие DTD-версии, но сохранение файлов выполняется в текущей версии. Расположение DTD указывает на сам файл DTD.

Элемент верхнего уровня — `<tellico>`. Он содержит объявление пространства имён и версию синтаксиса файла по умолчанию (они всегда должны соответствовать DTD).

Элемент `<tellico>` содержит один элемент `<collection>`. Указание нескольких коллекций будет проигнорировано. Атрибут `title` содержит название коллекции, а `type` определяет содержащиеся в коллекции типы записей. Допустимые типы перечислены в следующем разделе. Необязательный атрибут `entryTitle` позволяет указать название записей для пользовательской коллекции и является множественным.

#### Поля

      <fields>
       <field flags="8" title="Title" category="General" format="1" type="1" name="title" />
       <field flags="7" title="Author" category="General" format="2" type="1" name="author" />
       <field flags="2" title="Binding" category="General" allowed="Hardback;Paperback;Trade Paperback;E-Book;Magazine;Journal" format="4" type="3" name="binding" >
        <prop name="default"
    >Мягкий переплёт</prop>
       </field>
       <field flags="6" title="Publisher" category="Publishing" format="0" type="1" name="publisher" />
       <field flags="4" title="Edition" category="Publishing" format="0" type="1" name="edition" />
       <field flags="3" title="Copyright Year" category="Publishing" format="4" type="6" name="cr_year" />
       <field flags="2" title="Publication Year" category="Publishing" format="4" type="6" name="pub_year" />
       <field flags="0" title="ISBN#" category="Publishing" format="4" type="1" name="isbn" description="International Standard Book Number" />
       <field flags="7" title="Genre" category="Classification" format="0" type="1" name="genre" />
       <field flags="7" title="Keywords" category="Classification" format="0" type="1" name="keyword" />
       <field flags="0" title="Front Cover" category="Front Cover" format="4" type="10" name="cover" />
       <field flags="0" title="Comments" category="Personal" format="4" type="1" name="comments" />
       <field title="Rating" flags="2" category="Personal" format="4" type="14" name="rating">
        <prop name="maximum"
    >5</prop>
        <prop name="minimum"
    >1</prop>
       </field>
       <field title="ID" flags="32" category="Personal" format="4" type="6" name="id">
        <prop name="template"
    >%{@id}</prop>
       </field>

      </fields>

Все поля определяются внутри элемента `<fields>` (допустимо указывать только один такой элемент). Все сведения о поле, за исключением свойств, указываются в виде атрибутов элемента `<field>`. Допустимые значения атрибутов `flags`, `format` и `type` указаны в следующем разделе.

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

#### Записи

      <entry>
       <title
    >C++ Programming Language, The</title>
       <authors>
        <author
    >Stroustrup, Bjarne</author>
       </authors>
       <publisher
    >Addison-Wesley Pub Co</publisher>
       <edition
    >3rd</edition>
       <pub_year
    >1997</pub_year>
       <isbn
    >0-201-88954-4</isbn>
       <genres>
        <genre
    >Non-Fiction</genre>
       </genres>
       <keywords>
        <keyword
    >Programming</keyword>
        <keyword
    >Computers</keyword>
       </keywords>
       <cover
    >cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

Элемент, название которого совпадает с названием поля, возможно указать в `<entry>`. Если поле позволяет указывать несколько значений, для создания элемента к названию поля добавляется буква s, и каждое значение добавляется как потомок этого элемента (как в приведённом выше примере с полями автора, жанра и ключевого слова).

Когда в коллекцию будут добавлены дополнительные поля, файл данных перестанет соответствовать DTD. Но в &appname; используется обработчик &XML;, который не выполняет проверку, поэтому проблем в работе приложения не возникнет.

#### Изображения

      <images>
       <image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" />
      </images>

Внутри элемента `<images>` перечислены все изображения, на которые ссылается запись, а также указаны атрибуты, которые описывают размер, формат и идентификатор изображения. Если изображение содержится в файле ZIP, элемент будет пустым. Если элемент не пуст, данные изображения могут содержаться в &XML;-потоке в виде текста в кодировке Base64.

## Значения типов коллекций

Тип коллекции указывается в атрибуте типа элемента коллекции. Значение совпадает со значением перечисления `Type` в файле `src/collection.h`.

## Значения типов коллекций

Тип коллекции | Значение
Пользовательская коллекция | 1
Коллекция книг | 2
Коллекция фильмов | 3
Коллекция музыки | 4
Библиография | 5
Коллекция комиксов | 6
Коллекция вин | 7
Коллекция монет | 8
Коллекция марок | 9
Коллекция карточек | 10
Коллекция видеоигр | 11
Каталог файлов | 12
Коллекция настольных игр | 13

## Значения типов полей

&appname; включит в коллекцию все поля по умолчанию, если первый элемент поля называется _default. Для полей типа Большой текст, Таблица и Изображение категория поля должна совпадать с названием поля.

Тип поля указывается в атрибуте типа элемента поля. Значение совпадает со значением перечисления `FieldType` в файле `src/field.h`.

## Значения типов полей

Тип поля | Значение
Простой текст | 1
Большой текст | 2
Выбор | 3
Выбор да/нет | 4
Номер | 6
&URL;-адрес | 7
Таблица | 8
Изображение | 10
Дата | 12
Рейтинг | 14

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

## Значения флагов полей

Флаги полей | Значение
Разрешить несколько значений | `0x01`
Разрешить группировку | `0x02`
Разрешить дополнение | `0x04`
Запретить удаление | `0x08`
Запретить редактирование | `0x10`
Зависимое значение | `0x20`

Формат поля указывается в атрибуте формата элемента поля. Форматирование дат в настоящее время не используется. При группировке по Людям используются все поля с Форматированием имён. Установка флага Зависимое значение означает, что значение этого поля создаётся из значений других полей с помощью шаблона.

## Значения формата поля

Формат поля | Значение
Только повышение регистра | 0
Форматирование названия | 1
Форматирование имени | 2
Форматирование даты | 3
Без форматирования | 4

## Скрытые параметры настройки

В &appname; имеется несколько дополнительных параметров настройки, которые не отображаются в диалоге конфигурации. Они не настолько важны, чтобы их стоило включать в этот диалог, но, тем не менее, могут быть прочитаны приложением из файла конфигурации (так как эти параметры могут быть полезны некоторым пользователям).

Параметры &appname; сохраняются в файле, который находится в домашней папке пользователя, а именно: `$`KDEHOME`/share/config/tellicorc`. В этом файле параметры распределены по группам. Названия групп заключены в квадратные скобки, например: [General Options]. Чтобы добавить параметр в группу General Options, найдите в файле параметров строку с названием этой группы. Если такой строки нет, создайте её, добавив строку с текстом [General Options]. После этого под названием группы будет возможно добавить параметр.

### [General Options]

Эти параметры следует поместить в группу General Options.

#### Максимальный размер значка

Этот параметр позволяет изменить максимальный размер значков, которые отображаются в режиме представления значков. Значение по умолчанию: 96. Размер должен находиться в диапазоне от 32 до 512.

#### Пример

`Max Icon Size=128`

#### Размер кэша значков

Этот параметр позволяет изменить максимальное количество значков для кэширования в памяти. Значение по умолчанию: 1000.

#### Пример

`Icon Cache Size=100`

#### Пример

`Max Icon Size=128`

#### Размер кэша изображений

Этот параметр позволяет изменить максимальное количество памяти (в байтах), которое используется для кэширования всех изображений. Значение по умолчанию: 67108864.

#### Пример

`Image Cache Size=256000000`

### [Options - bibtex]

Эти параметры следует поместить в группу Options - bibtex.

#### lyxpipe

Этот параметр позволяет указать расположение lyxpipe для отправки библиографических цитат. Оно не должно содержать суффикс `.in`.

#### Пример

`lyxpipe=$HOME/.lyx/lyxpipe`

## Преобразование символов BibTeX

При импорте или экспорте файлов BibTeX выполняется преобразование определённых символов из формата TeX в Юникод и обратно. Эти соответствия символов содержатся в файле `bibtex-translation.xml`, который расположен в каталоге установочных данных. Соответствия возможно изменить любым необходимым образом. Элемент ключа содержит символ Юникода, а находящиеся внутри элементы строк содержат эквиваленты TeX (соответствие может быть типа «один-ко-многим»). Первый из них используется при экспорте в BibTeX.

      <key char="À">
        <string
    >{\`A}</string>
        <string
    >\`{A}</string>
      </key>

## Советы по работе с XSLT

Далее приводятся советы по написанию XSLT для обработки данных &XML; &appname;: (появятся позднее).