# Додаткове налаштування &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 V9.0//EN" "http://periapsis.org/tellico/dtd/v9/tellico.dtd">
    <tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="9">
     <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" />
       <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" />
      </fields>

Всі поля визначаються всередині елемента <fields>, цей елемент не можна вказувати декілька разів. Всі дані для поля (field), окрім властивостей, має бути включено як атрибути до елемента <field>. Можливі значення для атрибутів flags, format і type наведено у наступному розділі.

Визначення елемента <field> з назвою атрибута рівною _default наказує &appname; включити всі типові поля для цього типу збірки.

#### Записи

      <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`

Формат поля визначається атрибутом формату у елементі поля. У поточній версії форматування дати не використовується. Інструмент групування за іменами людей бере до уваги всі поля, які використовують форматування імені.

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

Формат поля | Значення
--- | ---
Лише зміна регістру символів | 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 до 128.

#### Приклад

`Max Icon Size=72`

### [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).