# &appname; varjatumad võimalused

Vaba tarkvara vaimus oled kutsutud &appname;t just sel moel muutma, nagu sa seda ise soovid. Väga lihtne on kirjutada skripte andmete importimiseks, eksportimiseks või muutmiseks. Käesolevas peatükis seda ja muud tutvustataksegi.

## Failivorming

&appname; vaikimisi andmefail on zip-arhiiv, tavaliselt faililaiendiga `.tc`. Arhiivis asub tipptasemel fail `tellico.xml`. Pildid võib panna arhiivi kataloogi `images/`, kuid need võib ka lisada base64 kodeeringus otse &XML;-andmetesse. Samuti võib pildid salvestada rakenduse andmekataloogi, millisel juhul neid ei leidu üldse andmefailis. &appname; võib laadida ka tihendamata &XML;-faili.

### &XML;-andmed

#### Kogu

    <?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="Minu raamatud" type="2">
     </collection>
    </tellico>

Fail algab nõutava &XML;-deklaratsiooni ja kodeeringuga, millele järgneb doctype. Kui lisatakse uus väljatüüp või vaikeväljadele määratakse lisaomadusi, suurendatakse doctype DTD versiooni. &appname; võib alati avada ja lugeda varasemaid DTD versioone, kuid salvestab failid aktiivsesse versiooni. DTD asukoht viitab tegelikule DTD-failile.

Tipptaseme element on <tellico>, mis sisaldab vaikimisi nimeruumi deklaratsiooni ja faili süntaksi versiooni, mis peab alati klappima DTD-ga.

Element <tellico> sisaldab üht elementi <collection>. Praegu eiratakse mitut kogu. Atribuut title sisaldab kogu pealkirja, type aga määrab, millist laadi kirjed sisalduvad kogus. Lubatud tüübid on ära toodud allpool. Atribuuti entryTitle võib soovi korral kasutada kohandatud kogu kirjete pealkirja määramiseks ning see peab olema mitmuses.

#### Väljad

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

Kõik väljad on defineeritud elemendis <fields>, mida tohib olla ainult üks. Kogu välja teave, välja arvatud omadused, sisaldub atribuutidena elemendis <fields>. Atribuutide flags, format ja type lubatud väärtused on ära toodud allpool.

Väljade omadustega määratakse kndlaks vaikimisi väljade väärtused, hinnanguväärtuste vahemikud, tuletatud väärtustega mallid jms. Ülal toodud näidetes leiab vaikeväärtuse, maksimaalne hindamisväärtuse ja malli tuletatud ID väljale.

#### Kirjed

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

Kogu iga välja puhul võib <entry> sisaldada elementi, mille nimi langeb kokku välja nimega. Kui välja puhul on lubatud mitu väärtust, lisatakse elemendi loomiseks välja nimele täht s ning iga väärtus lisatakse elemendi järglasna, nagu ülal toodud näites autori, žanri ja võtmesõna väljad.

Kui kogusse lisatakse täiendavaid välju, ei vasta andmefail enam DTD-le. Kuid &appname; kasutab mittevalideerivat &XML;-o parserit, mistõttu lisaväljad ei tekita probleeme.

#### Pildid

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

Elemendis <images> on kirjas kõik kirjes mainitud pildid koos atribuutidega, mis kirjeldavad pildi suurust, vormingut ja ID-d. Kui pilt sisaldub zip-failis, on element tühi. Vastasel juhul võib pildiandmed lisada &XML;-voogu base64 kodeeringus tekstina.

## Kogutüüpide väärtused

Kogu tüüpi näitab kogu elemendis tüübi atribuut. Väärtus võrdub Type loendi väärtusega päisefailis `src/collection.h`.

### Kogutüüpide väärtused

Kogu tüüp | Väärtus
--- | ---
Kohandatud kogu | 1
Raamatute kogu | 2
Videokogu | 3
Muusikakogu | 4
Bibliograafia | 5
Koomiksikogu | 6
Veinikogu | 7
Mündikogu | 8
Margikogu | 9
Kogumiskaartide kogu | 10
Videomängude kogu | 11
Failikataloog | 12
Lauamängude kogu | 13

## Väljatüüpide väärtused

&appname; lisab kõik kogu vaikimisi väljad, kui esimese väljaelemendi nimi on _default. Väljade Lõik, Tabel ja Pilt puhul peab välja kategooria kattuma välja pealkirjaga.

Välja tüübi määrab elemendis field antud välja atribuut. Väärtus on võrdne FieldType loendi väärtusega päisefailis `src/field.h`.

### Väljatüüpide väärtused

Välja tüüp | Väärtus
--- | ---
Tavaline tekst | 1
Lõik | 2
Valik | 3
Märkeruut | 4
Arv | 6
&URL; | 7
Üheveeruline tabel | 8
Pilt | 10
Kuupäev | 12
Hinnang | 14

Väljale võib määrata erinevaid lippe, mis on antud loogilise OR väärtusena elemendi field atribuudis flags. Lipp, mis takistab kasutajal välja kustutamast, on mõeldud näiteks viitevõtmele või bibliokirjele.

### Väljade lippude väärtused

Välja lipud | Väärtus
--- | ---
Mitme väärtuse lubamine | `0x01`
Rühmitamise lubamine | `0x02`
Sõnalõpetuse lubamine | `0x04`
Kustutamise keelamine | `0x08`
Muutmise keelamine | `0x10`
Tuletatud väärtus | `0x20`

Välja vorming on määratud elemendi field atribuudiga format. Kuupäevavormingut praegu ei kasutata. Rühmitamisel isikute järgi kasutatakse kõki välju, mille puhul on määratud Nimena vormindamine. Lipu Tuletatud väärtus määramisel genereeritakse välja väärtus teiste väljade väärtuste malli omadustest.

### Välja vormindamise väärtused

Välja vormindus | Väärtus
--- | ---
Ainult suurtäheliseks muutmine | 0
Pealkirjana vormindamine | 1
Nimena vormindamine | 2
Kuupäevana vormindamine | 3
Vormindus puudub | 4

## Peidetud seadistusvalikud

&appname;l on ka mõned seadistusvalikud, mida ei ole näha seadistustedialoogis. Need ei ole nii tähtsad, et muuta nendega niigi rohkete valikutega dialooge veel keerulisemaks, aga et nad võivad siiski olla teatavatele kasutajatele vajalikud või tulusad, annab rakendus võimaluse muuta neid otse seadistustefailis ja neid seejärel ka ära kasutada.

&appname; seadistused salvestatakse kasutaja kodukataloogi, täpsemalt faili `$`KDEHOME`/share/config/tellicorc`. Failis on seadistused jagatud rühmadesse, mille nimetused on nurksulgudes, näiteks [General Options]. Seadistuse lisamiseks mainitud üldiste valikute rühma otsi kõigepealt seadistusfailist üles vastava rühma nimega rida. Kui seda ei ole, lisa ise rida, millele seisab [General Options]. Seejärel saab vajaliku seadistuse lisada rühma nime alla.

### [General Options]

Järgnevad seadistused tuleks paigutada üldiste valikute rühma.

#### Max Icon Size (ikooni maksimumsuurus)

Selle seadistusega saab muuta ikoonivaate ikoonide maksimaalset suurust. Vaikeväärtus on 96. Suurus peab jääma vahemikku 32 kuni 512.

#### Näide

`Max Icon Size=128`

#### Icon Cache Size (ikoonipuhvri suurus)

Selle seadistusega saab muuta maksimaalset ikoonide arvu, mida hoitakse mälus. Vaikeväärtus on 1000.

#### Näide

`Icon Cache Size=100`

#### Näide

`Max Icon Size=128`

#### Image Cache Size (pildipuhvri suurus)

Selle seadistusega saab muuta mälu maksimaalset kogust baitides, mida kasutatakse kõigi piltide hoidmisel mälus. Vaikeväärtus on 67108864.

#### Näide

`Image Cache Size=256000000`

### [Options - bibtex]

Järgmised seadistused tuleks paigutada bibtexi valikute rühma.

#### lyxpipe

See seadistus määrab kindlaks lyxpipe'i asukoha, mida kasutatakse bibliograafiliste viidete saatmiseks. See ei tohi sisaldada faililaiendit `.in`.

#### Näide

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Export Options - PilotDB]

Järgmised seadistused tuleks paigutada PilotDB ekspordivalikute rühma.

#### Charset (kodeering)

Selle seadistusega saab muuta eksporditavate andmete kodeeringut PilotDB failis. Vaikeväärtuseks on kasutaja lokaadi kodeering.

#### Näide

`Charset=Windows-1250`

## Bibtexi märgiteisendus

Bibtex-failide importimisel või eksportimisel teisendatakse teatavad TeXi ja Unicode'i märgid. Vastavad seosed on kirjas failis `bibtex-translation.xml`, mis asub paigalduse andmekataloogis (data). Neid seoseid võib vastavalt vajadusele või soovile muuta. Element key sisaldab Unicode'i märki ning element string selle TeXi vasteid; tegemist võib olla ka üks-mitmele-seosega. Bibtexi eksportimisel kasutatakse esimest seost.

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

## XSLT nipid

Siin on mõned nipid XSLT kirjutamiseks, millega parsida &appname; &XML;-andmeid (veel kirjutamata).