# Programmera &appname;

I enlighet med avsikten hos fri programvara, är du välkommen att programmera &appname; så mycket du vill. Du bör enkelt kunna skriva skript för att importera, exportera eller ändra data. Det här kapitlet ger dig mer information om hur man gör det.

## Filformat

&appname;s standarddatafil är ett zip-arkiv, normalt med filändelsen `.tc`. Inne i arkivet finns toppnivåfilen `tellico.xml`. Bilder kan inkluderas i katalogen `images/` i arkivet, eller kan inkluderas direkt i &XML;-data kodade med base64. I detta fall finns de inte alls i datafilen. &appname; kan också ladda &XML;-filen själv, utan komprimering.

### &XML;-data

#### Samling

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

Filen börjar med den nödvändiga &XML;-deklarationen och kodningen, följt av dokumenttypen. När en ny fälttyp läggs till eller ytterligare egenskaper läggs till i standardfälten, inkrementeras dokumenttypens DTD-version. &appname; kan alltid öppna och läsa alla tidigare DTD-versioner, men sparar filer med den nuvarande versionen. DTD-platsen pekar på en verklig DTD-fil.

Toppnivåelementet är elementet `<tellico>`, som innehåller deklarationen av standardnamnrymden och filens syntaxversion, som alltid ska stämma med DTD:n.

Elementet `<tellico>` innehåller ett element: `<collection>` (samling). Flera samlingar ignoreras för närvarande. Attributet `title` innehåller samlingens titel. medan `type` anger vilka typer av poster som finns i samlingen. De tillåtna typerna listas i ett senare avsnitt. Den valfria egenskapen `entryTitle` kan användas för att ange posternas titel i en egen samling, och ska vara pluralis.

#### Fält

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

Alla fälten definieras inne i elementet `<fields>`, som det bara får finnas ett av. All information i ett fält, förutom eventuella egenskaper, ingår som attribut i elementet `<field>`. De tillåtna värdena för attributen `flags`, `format` och `type` anges i ett senare avsnitt.

Fältegenskaper används för att ställa in förvalda fältvärden, intervall för betygsvärde, mallar för beroende värden, etc. Exemplen ovan inkluderar ett förvalt värde, ett maximalt betygsvärde, och en mall för ett beroende identifikationsfält.

#### Poster

      <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
    >Fakta</genre>
       </genres>
       <keywords>
        <keyword
    >Programmering</keyword>
        <keyword
    >Datorer</keyword>
       </keywords>
       <cover
    >cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

För varje fält i samlingen, kan en `<entry>` innehålla ett element vars namn är identiskt med fältnamnet.Om flera värden tillåts för fältet, läggs bokstaven s till i fältnamnet för att skapa ett element, och varje värde läggs till som ett underliggande objekt till elementet, som är fallet för fälten author (författare), genre och keyword (nyckelord) ovan.

Som ett resultat, om ytterligare fält läggs till i samlingen, följer inte datafilen längre DTD:n. Dock använder &appname; en &XML;-tolk som inte validerar, alltså orsakar inte ytterligare fält några problem.

#### Bilder

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

Inne i elementet `<images>` listas varje bild som refereras till av en post, tillsammans med attribut som beskriver bildens storlek, format och identifierare. Om en bild finns inne i zip-filen, är elementet tomt. Annars kan bilddata finnas i &XML; data som text kodad med base64.

## Samlingstypsvärden

Samlingstypen anges i samlingselementets typattribut. Värdet är lika med uppräkningsvärdet `Type` i `src/collection.h`.

## Samlingstypsvärden

Samlingstyp | Värde
Egen samling | 1
Boksamling | 2
Videosamling | 3
Musiksamling | 4
Bibliografi | 5
Seriesamling | 6
Vinsamling | 7
Myntsamling | 8
Frimärkssamling | 9
Kortsamling | 10
Videospelsamling | 11
Filkatalog | 12
Spelsamling | 13

## Fälttypvärden

&appname; inkluderar de förvalda fälten för en samling om det första fältelementet har namnet _default. För fälten Paragraph (stycke), Table (tabell) eller Image (bild), ska fältkategorierna vara identiska med fälttiteln.

Fältets typ anges i fältelementets typattribut. Värdet är lika med uppräkningsvärdet `FieldType` i `src/field.h`.

## Fälttypvärden

Fälttyp | Värde
Enkel text | 1
Stycke | 2
Val | 3
Kryssruta | 4
Nummer | 6
Webbadress | 7
Tabell med en kolumn | 8
Bild | 10
Datum | 12
Betyg | 14

Fältet kan ha olika flaggor satta, givna som ett bitbaserat värde kombinerat med ELLER i fältelementets attribut flags. Flaggan för att förhindra användaren från att ta bort ett fält är avsett för sådana saker som hänvisningsnyckeln i bibliografiska poster.

## Fältflaggornas värden

Fältflaggor | Värde
Tillåt flera värden | `0x01`
Tillåt gruppering | `0x02`
Tillåt komplettering | `0x04`
Tillåt inte borttagning | `0x08`
Tillåt inte redigering | `0x10`
Beroende värde | `0x20`

Fältets format anges i fältelementets formatattribut. Date Formatting används för närvarande inte. Gruppering enligt personer med People använder alla fält som har Name Formatting (namnformatering). Att ange flaggan Derived Value (beroende värde) innebär att fältets värde skapas från mallegenskapen från andra fältvärden.

## Fältformatvärden

Fältformat | Värde
Bara kapitalisering | 0
Titelformatering | 1
Namnformatering | 2
Datumformatering | 3
Ingen formatering | 4

## Dolda inställningsalternativ

&appname; har några ytterligare inställningsalternativ som inte är synliga i inställningsdialogrutan. De är inte viktiga nog för att motivera att dialogrutan stökas till med fler inställningar, men eftersom de representerar alternativ som kan tilltala diverse användare, läser programmet dem från inställningsfilen.

&appname;s inställningar sparas i en fil i användarens hemkatalog, nämligen `$`KDEHOME`/share/config/tellicorc`. Inne i filen placeras inställningar i grupper, som visas med namn inom hakparenteser, såsom [General Options]. För att lägga till en inställning i gruppen [General Options], leta rätt på raden i inställningsfilen med det gruppnamnet. Om den inte finns, skapa den själv genom att lägga till en rad som lyder [General Options]. Därefter kan inställningen läggas till under gruppnamnet.

### [General Options]

Inställningarna ska placeras i gruppen General Options.

#### Max Icon Size

Den maximala storleken av ikonerna i ikonvyn kan ändras med den här inställningen. Förvalt värde är 96. Storleken måste vara i intervallet 32 till 512.

#### Exempel

`Max Icon Size=128`

#### Icon Cache Size

Det maximala antalet ikoner lagrade i minnet kan ändras med den här inställningen. Förvalt värde är 1000.

#### Exempel

`Icon Cache Size=100`

#### Exempel

`Max Icon Size=128`

#### Image Cache Size

Det maximala minnesstorleken i byte använd för att lagra alla bilder kan ändras med den här inställningen. Förvalt värde är 67108864.

#### Exempel

`Image Cache Size=256000000`

### [Options - bibtex]

Inställningarna ska placeras i gruppen Options - bibtex.

#### lyxpipe

Den här inställningen anger platsen för lyxpipe för att skicka bibliografiska hänvisningar. Den ska inte inkludera filändelsen `.in`.

#### Exempel

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Export Options - PilotDB]

Inställningarna ska placeras i gruppen Export Options - PilotDB.

#### Charset

Kodningen av exporterad data i PilotDB-filen kan ändras med den här inställningen.Förvalt värde är teckenuppsättningen i användarens landsinställning.

#### Exempel

`Charset=Windows-1250`

## Bibtex teckenöversättning

När Bibtex-filer importeras eller exporteras, översätts vissa tecken mellan sina motsvarande värden i Tex och tecken i Unicode. Dessa teckenavbildningar finnd i filen `bibtex-translation.xml`, som finns i installationens datakatalog. Avbildningarna kan ändras som önskas. Nyckelelementet innehåller tecknet i Unicode, och strängelementen inuti innehåller motsvarigheten i Tex, vilket kan vara en avbildning av ett värde till flera. Det första är det som används vid export till Bibtex.

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

## Trick med XSLT

Här är några tips för att skriva XSLT för att tolka &XML;-data från &appname;: (TBD).