# Hacking &appname;

Suivant l'esprit du Logiciel Libre, vous pouvez modifier &appname; autant que vous le désirez. Il devrait être très simple d'écrire des scripts pour importer, exporter ou modifier des données. Ce chapitre vous donne plus d'informations sur ce sujet.

## Format de fichiers

Le format de fichier par défaut de &appname; est une archive zip, normallement avec une extension de fichier en `.tc`. A l'intérieur de l'archive se trouve un fichier `tellico.xml`. Les images peuvent être placées dans le répertoire `images/` dans l'archive, ou être incluses directement dans le flux &xml; encodées au format base64. Les images peuvent également être enregistrées dqns le repertoire de données de l'application ; auquel cas elles ne sont pas du tout présentes dans le fichier de données. &appname; peut également charger le fichier &xml; directement; non compressé.

### Données &xml;

#### Collection

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE tellico PUBLIC "-//Robby Stephenson/DTD Tellico V9.0//EN" "http://periapsis.org/tellico/dtd/v9/tellico.dtd">
    <tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="9">
     <collection title="My Books" type="2">
     </collection>
    </tellico>

Le fichier commence par la déclaration et l'encodage &xml; requis, suivis par le type de document ("doctype"). Quand un nouveau champs est ajouté ou une propriété aditionelle attribuée aux champs par défaut, la version de DTD du doctype est incrémentée. &appname; est toujours capable d'ouvrir et lire les versions de DTD précédentes, mais sauvegarde les fichiers dans la version courante. La localisation DTD pointe vers le ficher DTD lui-même.

L'élément racine est un élément <tellico>, contenant la déclaration de l'espace de nommage par défaut et la version de la syntaxe du fichier, qui devraient toujours etre identiques à ceux de la DTD.

L'élément <tellico> contient un élément <collection>. Les collections multiples sont ignorées pour le moment. L'attribut title contient le nom de la collection, alors que l'attribut type specifie quel type d'entrées est contenu dans la collection. La liste des types disponibles est disponible dans une autre section. Un attribut optionnel entryTitle peut être utilisé pour spécifier le nom des entrées dans une collection personnalisée, et devrait être au pluriel.

#### Champs

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

Tous les champs sont définis dans un élément <fields>, qui doit être unique. Toutes les informations d'un champ, à l'exception des propriétés étendues, sont incluses dans l'élément <field>. Les valeurs possibles pour les attributs flags, format, et type sont données dans une section suivante.

Un élément <field> avec un attribut "name" égal à _default indique à &appname; d'inclure tous les champs par défaut de ce type de collection.

#### Entrées

      <entry>
       <title>Le langage C++, édition revue et corrigée</title>
       <authors>
        <author>Stroustrup, Bjarne</author>
       </authors>
       <publisher>Pearson Education</publisher>
       <edition>3rd</edition>
       <pub_year>2003</pub_year>
       <isbn>2-7440-7003-3</isbn>
       <genres>
        <genre>Non-Fiction</genre>
       </genres>
       <keywords>
        <keyword>Programmation et langages</keyword>
        <keyword>Informatique et Internet</keyword>
       </keywords>
       <cover>cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

Pour chaque champs de la collection, un élément <entry> peut contenir un élément dont le nom est identique à celui du champs. Si des valeurs multiples sont possibles pour ce champ, la lettre s est ajoutée au nom du champ pour créer un élément. Chaque valeur est ajoutée en tant que descendant de cet élément, comme c'est le cas pour les champs author, genre et keyword ci-dessus.

En conséquence, si de nouveaux champs sont ajoutés à la collection, le fichier de données ne sera plus conforme à la DTD. Cependant, &appname; utilise un analyseur &xml; ne vérifiant pas la validité des champs, ceux-ci ne posent donc pas problème.

#### Images

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

A l'intérieur de chaque élément <images> apparait chaque image référencée par une entrée, ainsi que les attributs décrivant la taille de l'image, son format et son numéro d'identification. Si l'image est contenue dans le fichier Zip, l'élément est vide. Dans le cas contraire les données de l'image peuvent être contenues dans le flux &xml; sous forme de text encodé au format base64.

## Valeurs des types de collections

Le type de collection est donné dans l'attribut "type" de l'élément "collection". La valeur est égale à celle de l'enum Type défini dans `src/collection.h`.

### Valeurs des types de collections

Type de collection | Valeur
--- | ---
Custom Collection | 1
Book Collection | 2
Video Collection | 3
Music Collection | 4
Bibliography | 5
Comic Book Collection | 6
Wine Collection | 7
Coin Collection | 8
Stamp Collection | 9
Trading Card Collection | 10
Video Game Collection | 11
File Catalog | 12

## Valeurs des types de champs

&appname; inclut tous les champs par défaut de la collection si le premier élément est nommé _default. Pour les champs Paragraphe, Tableau ou Image, la catégorie du champ doit être identique au titre du champ.

Le type de champ est donné dans l'attribut type de l'élément. La valeur est égale à celle de l'enum FieldType défini dans `src/field.h`. Le type Lecture seule était prévu pour pour les champs devant être conservés ; mais ne pouvant pas être modifiés par l'utilisateur, tels que les champs ajoutés lors de l'import d'une collection dans une autre format. Il n'est pas utilisé.

### Valeurs des types de champs

Type de champ | Valeur
--- | ---
Texte simple | 1
Paragraphe | 2
Choix | 3
Case à cocher | 4
Lecture seule | 5
Nombre | 6
URL | 7
Tableau à une colonne | 8
Tableau à deux colonnes | 9
Image | 10
Dépendant | 11
Date | 12

Le champ peut avoir plusieurs options, données par la valeur d'un champ de bits dans l'attribut flags de l'élément du champ. L'option interdisant à l'utilisateur d'effacer un champ est prévue pour des données telles qu'une citation dans une entrée bibliographique.

### Valeurs des options de champ

Option de champ | Valeur
--- | ---
Autoriser des valeurs multiples | `0x01`
Autoriser le regroupement | `0x02`
Activer l'auto-complétion | `0x04`
Interdire l'effacement | `0x08`

La mise en forme du champ est donnée dans l'attribut format de l'élément. Date n'est pas utilisé pour le moment. Le regroupement par Personne utilise tous les champs ayant une mise en forme de Nom.

### Valeurs de mises en forme de champ

Format de champ | Valeur
--- | ---
Capitales | 0
Title | 1
Nom | 2
Date | 3
Pas de mise en forme | 4

## Options de configuration cachées

&appname; dispose de certaines options de configuration qui ne sont pas visibles dans la &config-dialog;. Elles ne sont pas suffisament importantes pour charger la boite de dialogue avec plus d'options, mais puisqu'elles peuvent être utiles à certains utilisateurs, l'application les lit dans le fichier de configuration.

Les paramètres de &appname; sont enregistrés dans un fichier du répertoire de l'utilisateur, `$`KDEHOME`/share/config/tellicorc`. Dans ce fichier; les paramètres sont rassemblés dans des groupes qui apparaissent avec un nom entre crochet, tel que [General Options]. Pour ajouter un paramètre au groupe General Options, trouvez la ligne dans le fichier de configuration avec ce nom de groupe. S'il n'apparait pas, créez-le vous-même en ajoutant une ligne [General Options]. Les paramètres peuvent alors être ajoutés sur les lignes suivantes.

### [General Options]

Ces paramètres doivent être placés dans le groupe General Options.

#### Max Icon Size

La taille maximum des icones dans la &icon-view; peut être changée avec cette option. La valeur par défaut est 96, et peut être modifiée entre 32 et 128.

#### Exemple

`Max Icon Size=72`

### [Options - bibtex]

Ces paramètres doivent être placés dans le groupe Options - bibtex.

#### lyxpipe

Ce paramètre indique l'adresse lyxpipe pour envoyer les citations bibliographiques. Il ne doit pas inclure le suffixe `.in`.

#### Exemple

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Export Options - PilotDB]

Ces paramètres doivent être placés dans le groupe Export Options - PilotDB.

#### Charset

L'encodage des données exportées dans le fichier PilotDB peut être changé avec ce paramètre. La valeur par défaut est le jeu de caractères de la locale de l'utilisateur.

#### Exemple

`Charset=Windows-1250`

## Conversion de cqrqctères BibTeX

Lorsque des fichiers BibTeX sont i,portés ou exportés, certains caractères sont convertis entre leur équivalent TeX et unicode. Ces tables de conversions sont contenues dans le fichier `bibtex-translation.xml`, se trouvant dans le repertoire de données installées par le logiciel. Ces tables de conversion peuvent être modifiée librement. L'élément clef contient le caractère Unicode, et les chaines contiennent les équivalents TeX, qui peuvent être multiples. Le premier est celui utilisé lors des exports qu format BibTeX.

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

## Astuces XSLT

Quelques astuces pour écrire du XSLT pour traiter les données &xml; de &appname; : (à écrire).