# Додаткове налаштування &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; і визначення кодування, за яким має бути вказано тип документа. Після додавання нових полів або додаткових властивостей до типових полів номер версії типу документів DTD збільшується. Програма &appname; зможе відкрити і прочитати будь-яку з попередніх версій DTD, але зберігатиме файли лише у форматі поточної версії. Адреса DTD не вказує на справжній файл DTD.

Елементом найвищого рівня є елемент <tellico>, цей елемент містить типове оголошення простору назв і версії синтаксису файла, ця версія завжди має збігатися з версією DTD.

Елемент <tellico> містить один елемент <collection>. У поточній версії програми кратне визначення збірок (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"
    >Paperback</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), окрім властивостей, має бути включено як атрибути до елемента <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 текст.

## Значення типів збірки

Тип збірки слід вказувати у атрибуті типу елемента збірки. Значення має бути еквівалентним значенню переліку (enum) Type у `src/collection.h`.

### Значення типів збірки

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

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

&appname; включить всі типові поля для збірки, якщо першим елементом поля буде назва _default. Для полів Paragraph, Table і Image категорія поля має збігатися з заголовком поля.

Тип поля слід вказувати у атрибуті типу елемента поля. Значення має бути відповідним значенню переліку (enum) 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.

#### Max Icon Size

За допомогою цього параметра можна змінити розмір піктограм у режимі перегляду піктограм. Типовим значенням є 96. Ви можете вказати розмір у діапазоні від 32 до 512.

#### Приклад

`Max Icon Size=128`

#### Icon Cache Size

За допомогою цього параметра можна змінити максимальну кількість піктограм, які зберігатимуться у кеші. Типовим значенням є 1000.

#### Приклад

`Icon Cache Size=100`

#### Приклад

`Max Icon Size=128`

#### Image Cache Size

За допомогою цього параметра можна змінити об’єм пам’яті у байтах, який використовуватиметься для кешування всіх зображень. Типовим значенням параметра є 67108864.

#### Приклад

`Image Cache Size=256000000`

### [Options - bibtex]

Ці параметри слід вказати у групі Options - bibtex.

#### lyxpipe

Цей параметр призначено для визначення адреси lyxpipe для надсилання бібліографічних посилань. Суфікс `.in` вказувати не потрібно.

#### Приклад

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Export Options - PilotDB]

Ці параметри слід вказати у групі Export Options - PilotDB.

#### Набір символів

За допомогою цього параметра можна змінити кодування експортованих даних у файлі PilotDB. Типовим значенням є набір символів локалі користувача.

#### Приклад

`Charset=Windows-1250`

## Трансляція символів Bibtex

Під час імпортування або експортування файлів bibtex деякі символи буде перетворено з комбінацій символів TeX на символи Unicode і навпаки. Перелік транслювання символів міститься у файлі `bibtex-translation.xml`, який зберігаються у каталозі встановлених даних пакунка програми. За бажання, ви можете змінити параметри цієї трансляції. Елементи цього файла містять символи Unicode і відповідні рядки еквівалентних комбінацій символів TeX, трансляція може бути неоднозначною. Перший з можливих декількох рядків буде використано під час експорту до bibtex.

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

## Трюки з XSLT

Тут наведено декілька підказок щодо написання XSLT призначеного для обробки даних &XML; програми &appname;: (TBD).