# Hacking del &appname;

En l'esperit del programari lliure, us convidem a fer hacking del &appname; tant com vulgueu. Haureu de ser capaç d'escriure scripts per a importar, exportar o modificar les dades amb molta facilitat. Aquest capítol us donarà més informació sobre com fer-ho.

## Format de fitxer

El fitxer de dades predeterminat del &appname; és un arxiu zip, normalment amb una extensió de fitxer `.tc`. Dins del fitxer hi haurà un fitxer `tellico.xml` de nivell superior. Les imatges es poden incloure dins de la carpeta `images/` a l'arxiu, o es poden incloure directament a les dades &XML; en una codificació base64. Les imatges també es poden desar dins de la carpeta de dades de l'aplicació, en aquest cas, no restaran al fitxer de dades. El &appname; també pot carregar el fitxer &XML;, sense comprimir.

### Dades &XML;

#### Col·lecció

    <?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="Els meus llibres" type="2">
     </collection>
    </tellico>

El fitxer comença amb la declaració i la codificació &XML; requerides, seguides pel tipus de document. Quan s'afegeix un tipus de camp nou o s'estableixen propietats addicionals en els camps predeterminats, s'incrementarà la versió del tipus de document DTD. El &appname; sempre és capaç d'obrir i llegir qualsevol versió anterior de DTD, però desarà els fitxers en la versió actual. La ubicació de DTD apunta a un fitxer DTD real.

L'element de nivell superior és un element `<tellico>`, que conté la declaració predeterminada d'espai de noms i la versió de la sintaxi del fitxer, el qual sempre haurà de coincidir amb el DTD.

L'element `<tellico>` conté un element `<collection>`. Les col·leccions múltiples seran ignorades, per ara. L'atribut `title` conté el títol de la col·lecció, mentre que `type` especifica quin tipus d'entrades es troben a la col·lecció. Els tipus permesos estan llistats en una secció posterior. Un atribut opcional `entryTitle` es pot utilitzar per a especificar el títol de les entrades per a una col·lecció personalitzada, i hauria de ser plural.

#### Camps

      <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"
    >Revista</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>

Tots els camps es defineixen dins d'un element `<fields>`, del qual sols n'hi pot haver un. Tota la informació per a un camp, a excepció de les propietats, s'inclou com a atributs de l'element `<field>`. Els valors permesos per als atributs `flags`, `format` i `type` es donen en una secció següent.

Les propietats del camp s'utilitzen per a establir els valors predeterminats per al camp, els intervals dels valors de puntuació, plantilles dels valors derivats, &etc; Els exemples anteriors inclouen un valor predeterminat, un valor de puntuació màxim, i una plantilla per a un camp ID derivat.

#### Entrades

      <entry>
       <title
    >El llenguatge de programació C++</title>
       <authors>
        <author
    >Stroustrup, Bjarne</author>
       </authors>
       <publisher
    >Addison-Wesley Pub Co</publisher>
       <edition
    >3a</edition>
       <pub_year
    >1997</pub_year>
       <isbn
    >0-201-88954-4</isbn>
       <genres>
        <genre
    >No ficció</genre>
       </genres>
       <keywords>
        <keyword
    >Programming</keyword>
        <keyword
    >Computers</keyword>
       </keywords>
       <cover
    >cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

Per a cada camp a la col·lecció, una `<entrada>` pot contenir un element que el seu nom és idèntic al nom del camp. Si es permeten múltiples valors per al camp, llavors la lletra s serà afegida al nom del camp per a crear un element, i cada valor serà afegit com un fill de l'element, com en el cas dels camps autor, gènere i paraules clau anteriors.

Com a resultat, si s'afegeixen camps addicionals a la col·lecció, el fitxer de dades ja no restarà conforme al DTD. No obstant això, el &appname;utilitza un analitzador &XML; sense validar, de manera que els camps addicionals no causaran problemes.

#### Imatges

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

Dins de l'element `<images>`, cada imatge farà referència a una entrada a la llista, juntament amb els atributs que descriuen la mida, format, i ID de la imatge. Si la imatge està continguda dins del fitxer Zip, l'element restarà buit. En cas contrari, les dades d'imatge podran estar contingudes a l'XML com a text codificat en base64.

## Els valors de Tipus de col·lecció

El tipus de col·lecció ve donat en l'atribut «type» de l'element de la col·lecció. El valor és igual que el valor d'enumeració de `Type` a `src/collection.h`.

## Els valors de Tipus de col·lecció

Tipus de col·lecció | Valor
Col·lecció personalitzada | 1
Col·lecció de llibres | 2
Col·lecció de vídeos | 3
Col·lecció de música | 4
Bibliografia | 5
Col·lecció de còmics | 6
Col·lecció de vins | 7
Col·lecció de monedes | 8
Col·lecció de segells | 9
Col·lecció de targetes comercials | 10
Col·lecció de videojocs | 11
Catàleg de fitxers | 12
Col·lecció de jocs de taula | 13

## Els valors de Tipus de camp

El &appname; inclourà tots els camps predeterminats per a una col·lecció si el primer element del camp s'anomena _default. Per als camps Paràgraf, Taula o Imatge, la categoria de camp haurà de ser idèntica al títol del camp.

El tipus de camp es dona en l'atribut «type» de l'element del camp. El valor serà igual que el valor d'enumeració `FieldType` a `src/field.h`.

## Els valors de Tipus de camp

Tipus de camp | Valor
Text pla | 1
Paràgraf | 2
Opció | 3
Casella de selecció | 4
Número | 6
&URL; | 7
Taula | 8
Imatge | 10
Data | 12
Puntuació | 14

El camp pot tenir establertes diferents etiquetes, donades com a un valor de bit amb OR a l'atribut «flags» en l'element «field». L'etiqueta per a prevenir que l'usuari suprimeixi un camp està destinada a coses com la clau de cita per a registres bibliogràfics.

## Els valors de l'etiqueta de camp

Etiquetes de camp | Valor
Permet múltiples valors | `0x01`
Permet agrupament | `0x02`
Permet compleció | `0x04`
No permetre eliminar | `0x08`
No permetre editar | `0x10`
Valor derivat | `0x20`

El format del camp es dona en l'atribut «format» en l'element «field». El format de la data no s'utilitza actualment. Agrupar per persones utilitza tots els camps que utilitzen el format del nom. Establir l'etiqueta Valor derivat implica que el valor per al camp és generat a partir de la propietat de la plantilla a partir d'altres valors de camp.

## Els valors de Format del camp

Format del camp | Valor
Només posar en majúscula la primera lletra | 0
Format del títol | 1
Format del nom | 2
Format de la data | 3
Sense format | 4

## Opcions ocultes de la configuració

El &appname; té algunes opcions de configuració addicionals que no són visibles en el diàleg de configuració. No són prou importants per a justificar que saturin el diàleg amb més opcions, però ja que representen opcions que poden resultar interessants per a diversos usuaris, l'aplicació les llegeix des del fitxer de configuració.

Les opcions del &appname; es desen en un fitxer a la carpeta d'inici de l'usuari, anomenada `~/.config/tellicorc`. Dins d'aquest fitxer, les opcions es posen en grups, els quals apareixen amb els noms entre claudàtors, com [General Options]. Per a afegir una opció al grup General Options, trobeu la línia al fitxer de configuració amb aquest nom de grup. Si no apareix, llavors creu-la afegint una línia que digui [General Options]. Llavors, podreu afegir l'opció a sota del nom de grup.

### [General Options]

Aquestes opcions s'han de col·locar al grup General Options.

#### Mida màxima de les icones

La mida màxima de les icones en la Vista d'icones es poden canviar amb aquesta opció. El valor per omissió és 96. La mida haurà d'estar a l'interval de 32 a 512.

#### Exemple

`Max Icon Size=128`

#### Mida de la memòria cau de les icones

El nombre màxim d'icones en la memòria cau es pot canviar amb aquesta opció. Per omissió és 1000.

#### Exemple

`Icon Cache Size=100`

#### Mida de la memòria cau de les imatges

La quantitat màxima de memòria en bytes utilitzada per a emmagatzemar en memòria cau totes les imatges es pot canviar amb aquesta opció. El valor per omissió és 512 MiB.

#### Exemple

`Image Cache Size=256000000`

### [Options - bibtex]

Aquestes opcions s'han de col·locar al grup Options - bibtex.

#### lyxpipe

Aquesta opció és per a la ubicació de la lyxpipe per a l'enviament de cites bibliogràfiques. No ha d'incloure el sufix `.in`.

#### Exemple

`lyxpipe=$HOME/.lyx/lyxpipe`

### [File Reader Options]

Aquestes opcions s'han de col·locar al grup File Reader Options.

#### Mida de la vista prèvia

Aquesta opció és per a la mida màxima de la vista prèvia de fitxer generada.

#### Exemple

`Preview Size=523`

### Opcions multidisc

Les fonts de dades MusicBrainz, Discogs i iTunes poden obtenir informació d'àlbums multidisc, especificant quines pistes conté cada disc. De manera predeterminada, les llistes de pistes s'insereixen en camps separats, un a cada disc. Abans de la versió 4.0, les llistes de pistes es combinaven. Aquesta opció proporciona el comportament pre-4.0 a un nivell de font de dades individual. Afegeix-ho a cada secció Data Source on es desitgi.

#### Divideix pistes per disc

Establint això a false es reverteix al comportament pre-4.0 on les pistes es redueixen a una llista de pistes única.

#### Exemple

`Split Tracks By Disc=false`

## Traducció de caràcters «bibtex»

Quan s'importin o exportin els fitxers de «bibtex», alguns caràcters es traduiran entre els seus equivalents TeX i els caràcters Unicode. Aquestes assignacions de caràcters estan contingudes en el fitxer `bibtex-translation.xml`, ubicat al directori d'instal·lació de les dades. Les assignacions es poden modificar, com vulgueu. L'element «key» contindrà el caràcter Unicode, i els elements «string» contindran els equivalents TeX, els quals podran ser una combinació d'un-a-molts. La primera serà la que s'utilitzi per a exportar a «bibtex».

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