# Haquejar &appname;

En l'esperit del programari lliure, us convidem a haquejar &appname; tant com vulgueu. Haureu de ser capaç d'escriure scripts per 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 per omissió de &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. &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 nou tipus de camp o s'estableixen propietats addicionals en els camps per omissió, s'incrementarà la versió del tipus de document DTD. &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ó per omissió d'espai de noms i la versió de la sintaxi del fitxer, que 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 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, amb 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 establir els valors per omissió per al camp, els intervals dels valors de puntuació, plantilles dels valors derivats, &etc; Els exemples anteriors inclouen un valor per omissió, 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
    >3era</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 en el que el 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, &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ídeo | 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

&appname; inclourà tots els camps per omissió 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 dóna 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 d'una sola columna | 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 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 dóna 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
--- | ---
Sols capitalització | 0
Format del títol | 1
Format del nom | 2
Format de la data | 3
Sense format | 4

## Opcions ocultes de la configuració

&appname; té algunes opcions de configuració addicionals que no són visibles en el diàleg de configuració. No són prou importants com 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ó.

Els ajustaments per a &appname; es desen en un fitxer a la carpeta d'inici de l'usuari, anomenada `$`KDEHOME`/share/config/tellicorc`. Dins d'aquest fitxer, els ajustaments es posen en grups, que apareixen amb els noms entre claudàtors, com [General Options]. Per afegir un ajustament 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'ajustament a sota del nom de grup.

### [General Options]

Aquests ajustaments 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 aquest ajustament. 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 aquest ajustament. Per omissió és 1000.

#### Exemple

`Icon Cache Size=100`

#### Exemple

`Max Icon Size=128`

#### 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 aquest ajustament. El valor per omissió és 67108864.

#### Exemple

`Image Cache Size=256000000`

### [Options - bibtex]

Aquests ajustaments s'han de col·locar al grup Options - bibtex.

#### lyxpipe

Aquest ajustament é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`

### [Export Options - PilotDB]

Aquests ajustaments s'han de col·locar al grup Export Options - PilotDB.

#### Joc de caràcters

La codificació de les dades exportades al fitxer PilotDB es pot canviar amb aquest ajustament. El valor per omissió és el joc de caràcters per a la configuració regional de l'usuari.

#### Exemple

`Charset=Windows-1250`

## 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, que podran ser una combinació d'un-a-molts. La primera serà la que s'utilitzi per exportar a «bibtex».

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

## Consells XSLT

Aquests són alguns consells per escriure XSLT per analitzar dades &XML; de &appname;: (encara s'ha d'escriure).