# Hacking &appname;

In de geest van Vrije Software bent u welkom om &appname; te hacken zoveel u wilt. U zou in staat moeten zijn om scripts te schrijven om gegevens gemakkelijk te importeren, te exporteren of te wijzigen. Dit hoofdstuk geeft u meer informatie over hoe dat te doen.

## Bestandsformaat

Het standaard gegevensbestand van &appname; is een zip-archief, normaal met een `.tc` bestandsextensie. In het archief is een bestand op top-niveau `tellico.xml`. Afbeeldingen kunnen meegenomen worden in de map `images/` in het archief of ze kunnen direct ingevoegd zijn in de &XML;-gegevens in een base64-codering. Afbeeldingen kunnen ook opgeslagen worden in de gegevensmap van de toepassing, in welk geval, ze helemaal niet in het gegevensbestand zelf zitten. &appname; kan ook het &XML;-bestand, op zichzelf, laden, niet gecomprimeerd.

### &XML;-gegevens

#### Collectie

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

Het bestand begint met de vereiste &XML;-declaratie en codering, gevolgd door het doctype. Wanneer een nieuw veldtype is toegevoegd of extra eigenschappen zijn ingesteld op de standaard velden, the zal de versie van het doctype-DTD verhoogt worden. &appname; is altijd in staat om elke vorige DTD-versie te openen en te lezen, maar zal bestanden opslaan in de huidige versie. De DTD-locatie wijst naar een actueel DTD-bestand.

Het hoogste element is een `<tellico>` element, die de standaard naamruimte declaratie bevat en de syntaxisversie van het bestand, die altijd overeen zou moeten komen met de DTD.

Het element `<tellico>` bevat één element `<collection>`. Meerdere verzamelingen worden voor nu genegeerd. Het `title` attribuut bevat de verzamelingtitel, terwijl het `type` specificeert welk soort items de verzameling bevat. De toegestane typen staan in een lijst in een latere sectie. Een optioneel attribuut `entryTitle` kan gebruikt worden om de titel van de items te specificeren voor een aangepaste verzameling en zou een meervoud moeten zijn.

#### Velden

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

Alle velden worden binnen een `<fields>` element gedefinieerd, waarvan er slechts één kan zijn. Alle informatie voor een veld, behalve voor eigenschappen, zijn meegenomen als attributen van het `<field>` element. De toegestane waarden voor de attributen `flags`, `format` en `type` zijn gegeven in een volgende sectie.

Veldeigenschappen worden gebruikt voor instelling van standaard veldwaarden, reeksen waarderingswaarden, afgeleide waardesjablonen, etc. Het bovenstaande voorbeeld bevat een standaard waarde, een maximale waarderingswaarde en een sjabloon voor een afleid ID-veld.

#### Items

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

Voor elk veld in de verzameling kan een `<item>` een element bevatten wiens naam identiek is aan de veldnaam. Als meerdere waarden voor het veld zijn toegestaan, zal de letter s toegevoegd moeten worden aan de veldnaam om een element aam te maken en elke waarde wordt toegevoegd als een kind van het element, zoals bovenstaand in het geval van de velden auteur, genre en keyword.

Als resultaat, als extra velden zijn toegevoegd aan de verzameling, zal het gegevensbestand niet langer overeenstemmen met de DTD. &appname; gebruikt echter een niet-validerende &XML;-parser, dus extra velden veroorzaken geen problemen.

#### Afbeeldingen

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

Binnen het element `<images>` wordt elke afbeelding waarnaar verwezen wordt door een item in een lijst gezet, samen met attributen die de grootte, formaat en id van de afbeelding beschrijven. Als de afbeelding zich in het zip-bestand bevindt, is het element leeg. Anders kunnen de afbeeldingsgegevens zich bevinden in de &XML;-stream als base64 gecodeerde tekst.

## Waarden van typen van verzamelingen

Het type verzameling is gegeven in het type-attribuut van het verzamelingselement. De waarde is gelijk aan het `Type` enum-waarde in `src/collection.h`.

## Waarden van typen van verzamelingen

Type collectie | Waarde
Eigen verzameling | 1
Boekenverzameling | 2
Filmverzameling | 3
Muziekverzameling | 4
Bibliografie | 5
Stripverzameling | 6
Wijnverzameling | 7
Muntverzameling | 8
Postverzameling | 9
Ruilkaartenverzameling | 10
Videospellenverzameling | 11
Bestandencatalogus | 12
Bordspellenverzameling | 13

## Waarden van typen velden

&appname; zal alle standaard velden bevatten voor een verzameling als het eerste veldelement de naam _default heeft. Voor velden Paragraaf, Tabel of Afbeelding zou de veldcategorie identiek moeten zijn aan de veldtitel.

Het type veld is gegeven in het type-attribuut van het veldelement. De waarde is gelijk aan het `FieldType` enum-waarde in `src/field.h`.

## Waarden van typen velden

Veldtype | Waarde
Eenvoudige tekst | 1
Paragraaf | 2
Keuze | 3
Keuzevakje | 4
Cijfers | 6
&URL; | 7
Tabel | 8
Afbeelding | 10
Datum | 12
Waardering | 14

Het veld kan verschillende vlaggen hebben ingesteld, gegeven als een bitsgewijs met OF behandelde waarde in het attribuut vlaggen op het veldelement. De vlag om te voorkomen dat de gebruiker een veld verwijdert is bedoeld voor zulke dingen als de citatiesleutel voor bibliografische items.

## Waarden van veldvlaggen

Veldvlaggen | Waarde
Meerdere waarden toestaan | `0x01`
Groepering toestaan | `0x02`
Aanvulling toestaan | `0x04`
Verwijderen weigeren | `0x08`
Bewerken weigeren | `0x10`
Afgeleide waarde | `0x20`

Het formaat van het veld is gegeven in het formaatattribuut op het veldelement. Datumformattering wordt nu niet gebruikt. Groepering door Mensen gebruikt alle velden die Naamformattering gebruiken. Zetten van de vlag Afgeleide waarde impliceert de waarde voor het veld is gegenereerd uit de sjablooneigenschap uit andere veldwaarden.

## Waarden van veldformaten

Veldformaat | Waarde
Alleen hoofdletters | 0
Opmaak van titel | 1
Naamformattering | 2
Datumformattering | 3
Geen opmaak | 4

## Verborgen configuratieopties

&appname; heeft enige extra configuratieopties die niet zichtbaar zijn in de Configuratiedialoog. Ze zijn niet belangrijk genoeg om de dialoog met meer instellingen te overvoeren, maar omdat ze opties representeren die verschillende gebruikers aanspreken, leest de toepassing ze uit het configuratiebestand.

De instellingen voor &appname; worden opgeslagen in een bestand in de hoofdmap van de gebruiker, namenlijk `~/.config/tellicorc`. Binnen dat bestand worden instellingen in groepen gezet, die van in haakjes gezette namen zijn voorzien, zoals [General Options]. Om een instellting toe te voegen aan de groep General Options, zoek de regel in het instellingenbestand met die groepsnaam. Als deze niet aanwezig is, maak deze dan zelf door een regel met [General Options] toe te voegen. Daarna kan de instelling toegevoegd worden onder de groepsnaam.

### [Algemene opties]

Deze instellingen kunnen geplaatst worden in de groe General Options.

#### Max Icon Size

De maximum grootte van de pictogrammen in de Pictogramweergave kan gewijzigd worden met deze instelling. De standaard waarde is 96. De grootte moet in de reeks 32 tot 512 liggen.

#### Voorbeeld

`Max Icon Size=128`

#### Icon Cache Size

Het maximum aantal pictogrammen gebufferd in geheugen kan gewijzigd worden met deze instelling. De standaard waarde is 1000.

#### Voorbeeld

`Icon Cache Size=100`

#### Image Cache Size

De maximum hoeveelheid geheugen in bytes gebruikt voor buffering van alle afbeeldingen kan gewijzigd worden met deze instelling. De standaard waarde is 512 MiB.

#### Voorbeeld

`Image Cache Size=256000000`

### [Options - bibtex]

Deze instellingen zouden geplaatst kunnen worden in de groep Options - bibtex.

#### lyxpipe

Deze instelling is voor de locatie van de lyxpipe voor verzenden van bibliografische citaten. Het zou niet het achtervoegsel `.in` moeten bevatten.

#### Voorbeeld

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Opties voor bestand lezen]

Deze instellingen kunnen geplaatst worden in de groep Opties voor bestand lezen.

#### Voorbeeldgrootte

Deze instelling is voor de maximum grootte van het gegenereerde bestandsvoorbeeld.

#### Voorbeeld

`Voorbeeldgrootte=523`

### Opties voor meerdere schijven

De gegevensbronnen MusicBrainz, Discogs en iTunes kunnen informatie over albums met meerdere schijven ophalen, waarbij wordt gespecificeerd welke nummers elke schijf bevat. Standaard worden de tracklijsten in aparte velden ingevoegd, één voor elke schijf. Vóór versie 4.0 werden de tracklijsten gecombineerd. Deze optie biedt het gedrag van vóór versie 4.0 op het niveau van een individuele gegevensbron. Voeg deze optie toe aan elke Gegevensbron-sectie waar dit gewenst is.

#### Tracks per schijf splitsen

Als dit op false wordt gezet, keert het terug naar het gedrag van vóór versie 4.0, waarbij de nummers werden samengevoegd tot één enkele lijst met nummers.

#### Voorbeeld

`Tracks per schijf splitsen=onwaar`

## Bibtex Character Translation

Wanneer bibtex-bestanden geïmporteerd of geëxporteerd worden, worden bepaalde tekens vertaald tussen hun TeX-equivalenten en de Unicode tekens. Deze koppelingen tussen tekens zitten in het bestand `bibtex-translation.xml`, gelokaliseerd in de gegevens voor installatie. De koppelingen kunnen, indien gewenst, gewijzigd worden. Het sleutelelement bevat het Unicode-teken en de tekenreekselementen erin bevatten de TeX-equivalenten, die een een-naar-meer koppeling kunnen hebben. De eerste is degene die wordt gebruikt bij exporteren naar bibtex.

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