<chapter id="hacking">
<title
>Bidouiller &appname;</title>

<para
>Dans l'esprit du logiciel libre, vous êtes les bienvenues pour bidouiller &appname; comme vous le souhaitez. Vous devez pouvoir écrire des scripts pour importer, exporter ou modifier les données très facilement. Ce chapitre vous donne plus d'informations sur ce qui est possible de faire. </para>

<sect1 id="file-format">
<title
>Format de fichier</title>

<para
>Le fichier de données par défaut est une archive zip, avec normalement l'extension <literal role="extension"
>.tc</literal
>. À l'intérieur de l'archive se trouve un fichier <filename
>tellico.xml</filename
>, les images peuvent être incluses dans le dossier <filename
>images/</filename
> de l'archive, ou elles doivent être incluses dans le dossier &XML; directement dans un encodage base64. Les images peuvent aussi être enregistrées dans le dossier de données de l'application, auquel cas, elles ne sont pas du tout dans le fichier de données. &appname; peut aussi charger un fichier &XML;, lui-même, non compressé. </para>

<sect2 id="xml-format">
<title
>Donnés &XML;</title>

 

<sect3 id="coll-xml-data">
<title
>Collection</title>
<programlisting
><![CDATA[
<?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>
]]>
</programlisting>

<para
>Le fichier commence avec la déclaration et l'encodage &XML; requis suivi du doctype. Quand un nouveau type de champ est ajouté ou que des propriétés additionnelles sont définies sur les champs par défaut, la version du doctype DTD est incrémentée. &appname; peut toujours ouvrir et lire n'importe quelles versions DTD précédentes, mais enregistrera les fichiers dans la version courante. L'emplacement DTD est lié au fichier DTD actuel. </para>

<para
>L'élément de haut niveau est un élément <markup
>&lt;tellico&gt;</markup
>, contenant la déclaration de l'espace de nom par défaut et la version de syntaxe du fichier qui doit toujours correspondre au fichier DTD. </para>

<para
>L'élément <markup
>&lt;tellico&gt;</markup
> contient un élément <markup
>&lt;collection&gt;</markup
>. Plusieurs collections sont ignorées pour l'instant. L'attribut <markup
>title</markup
> contient le titre de la collection, tandis que le <markup
>type</markup
> spécifie quelles sortes d'entrées sont contenues dans la collection. Les types autorisés sont <link linkend="collection-type-values"
>listés dans une section suivante</link
>. Un attribut optionnel <markup
>entryTitle</markup
> peut être utilisé pour spécifier le titre des entrées pour une collection personnalisée, et doit être au pluriel. </para>
</sect3>

<sect3 id="fields-xml-data">
<title
>Champs</title>

<programlisting
><![CDATA[
  <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>
]]>
</programlisting>

<para
>Tous les champs sont définis dans un élément <markup
>&lt;fields&gt;</markup
> où ils ne peuvent qu'être unique. Toutes les informations pour un champ, sauf pour les propriétés étendues, sont inclues comme des attributs de l'élément de <markup
>&lt;field&gt;</markup
>. Les valeurs autorisées pour <markup
>flags</markup
>, <markup
>format</markup
>, et <markup
>type</markup
> sont données dans la <link linkend="field-type-values"
>section suivante</link
>. </para>

<para
>Field properties are used for setting default field values, rating value ranges, derived value templates, etc. The examples above include a default value, a maximum rating value, and a template for a derived ID field. </para>

 

</sect3>

<sect3 id="entries-xml-data">
<title
>Entrées</title>

<programlisting
><![CDATA[
  <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>
]]>
</programlisting>

<para
>Pour tous les champs de la collection, <markup
>&lt;entry&gt;</markup
> peut contenir un élément dont le nom est identique au nom de champ. Si plusieurs valeurs sont permises pour le champ, la lettre <emphasis
>s</emphasis
> est ensuite ajoutée au nom de champ pour créer un élément, et chaque valeur est ajoutée comme un enfant de l'élément, comme dans le cas des champs 'auteur, genre et mots clés ci-dessus. </para>

<para
>Comme résultat, si des champs additionnels sont ajoutés à la collection, le fichier de données ne sera plus conforme au fichier DTD. Cependant, &appname; utilise un analyseur syntaxique &XML; non valable, les champs additionnels ne poseront donc aucun problèmes. </para>
</sect3>

<sect3 id="images-xml-data">
<title
>Images</title>
<programlisting
><![CDATA[
  <images>
   <image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" />
  </images>
]]>
</programlisting>

<para
>Dans l'élément <markup
>&lt;images&gt;</markup
>, chaque image référencée par une entrée est listée, avec des attributs décrivant la taille de l'image, le format et l'ID. Si l'image est contenu dans le fichier zip, l'élément est vide. Sinon, l'image peut être contenue dans le flux &XML; comme texte d'encodage base64. </para>
</sect3>

</sect2>

</sect1>

<sect1 id="collection-type-values">
<title
>Valeurs du type de collection</title>

<para
>Le type de collection est donné dans l'attribut type de l'élément de la collection. La valeur est identique à la valeur <type
>Type</type
> dans <filename
> src/collection.h</filename
>. </para>

<table>
<title
>Valeurs du type de collection</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Type de collection</entry>
<entry
>Valeur</entry>
</row>
</thead>
<tbody>
<row
><entry
>Collection personnalisée</entry
><entry
>1</entry
></row>
<row
><entry
>Collection de livres</entry
><entry
>2</entry
></row>
<row
><entry
>Collection de films</entry
><entry
>3</entry
></row>
<row
><entry
>Collection de musique</entry
><entry
>4</entry
></row>
<row
><entry
>Bibliographie</entry
><entry
>5</entry
></row>
<row
><entry
>Collection de BD</entry
><entry
>6</entry
></row>
<row
><entry
>Collection de vins</entry
><entry
>7</entry
></row>
<row
><entry
>Collection de pièces</entry
><entry
>8</entry
></row>
<row
><entry
>Collection de timbres</entry
><entry
>9</entry
></row>
<row
><entry
>Collection de cartes</entry
><entry
>10</entry
></row>
<row
><entry
>Collection de jeux vidéo</entry
><entry
>11</entry
></row>
<row
><entry
>Catalogue de fichiers</entry
><entry
>12</entry
></row>
<row
><entry
>Collection de jeux de plateau</entry
><entry
>13</entry
></row>
</tbody>
</tgroup>
</table>


</sect1>

<sect1 id="field-type-values">
<title
>Valeurs de type de champ</title>

<para
>&appname; inclura tous les champs par défaut pour une collection si le premier élément de champ a le nom <emphasis
>_default</emphasis
>. Pour les champs <emphasis
>Paragraphe</emphasis
>, <emphasis
>Tableau</emphasis
>, ou <emphasis
>Image</emphasis
>, la catégorie de champ doit être identique au titre de champ. </para>

<para
>Le type d'un champ est donné dans l'attribut type de l'élément champ. La valeur est identique à la valeur enum <type
>FieldType</type
> dans <filename
>src/field.h</filename
>. </para>

<table>
<title
>Valeurs de type de champ</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Type de champ</entry>
<entry
>Valeur</entry>
</row>
</thead>
<tbody>
<row
><entry
>Texte simple</entry
><entry
>1</entry
></row>
<row
><entry
>Paragraphe</entry
><entry
>2</entry
></row>
<row
><entry
>Choix</entry
><entry
>3</entry
></row>
<row
><entry
>Case à cocher</entry
><entry
>4</entry
></row>
<row
><entry
>Nombre</entry
><entry
>6</entry
></row>
<row
><entry
>&URL;</entry
><entry
>7</entry
></row>
<row
><entry
>Tableau en colonnes simples</entry
><entry
>8</entry
></row>
<row
><entry
>Image</entry
><entry
>10</entry
></row>
<row
><entry
>Date</entry
><entry
>12</entry
></row>
<row
><entry
>Note</entry
><entry
>14</entry
></row>
</tbody>
</tgroup>
</table>

<para
>Le champ peut avoir différents jeux de drapeaux, donnés comme une valeur OR 'd bitewise dans l'attribut du drapeau sur l'élément de champ. Le drapeau, pour prévenir l'utilisateur d'une suppression d'un champ est voulue pour certaines choses comme la clé de citation pour les entrées bibliographiques. </para>

<table>
<title
>Valeur du drapeau de champ</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Drapeaux de champ</entry>
<entry
>Valeur</entry>
</row>
</thead>
<tbody>
<row
><entry
>Autoriser des valeurs multiples</entry
><entry
><constant
>0x01</constant
></entry
></row>
<row
><entry
>Autoriser le regroupement</entry
><entry
><constant
>0x02</constant
></entry
></row>
<row
><entry
>Autoriser le complètement</entry
><entry
><constant
>0x04</constant
></entry
></row>
<row
><entry
><emphasis
>Ne pas autoriser la suppression</emphasis
></entry
><entry
><constant
>0x08</constant
></entry
></row>
<row
><entry
><emphasis
>Disallow Editing</emphasis
></entry
><entry
><constant
>0x10</constant
></entry
></row>
<row
><entry
>Derived Value</entry
><entry
><constant
>0x20</constant
></entry
></row>
</tbody>
</tgroup>
</table>

<para
>The format of the field is given in the format attribute on the field element. <emphasis
>Date Formatting</emphasis
> is not currently used. Grouping by <emphasis
>People</emphasis
> uses all the fields which use <emphasis
>Name Formatting</emphasis
>. Setting the <emphasis
>Derived Value</emphasis
> flag implies the value for the field is generated from the template property from other field values. </para>

<table>
<title
>Valeurs de format de champ</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Format de champ</entry>
<entry
>Valeur</entry>
</row>
</thead>
<tbody>
<row
><entry
>Mise en majuscule automatique seulement</entry
><entry
>0</entry
></row>
<row
><entry
>Formatage du titre</entry
><entry
>1</entry
></row>
<row
><entry
>Formatage du nom</entry
><entry
>2</entry
></row>
<row
><entry
><emphasis
>Formatage de la date</emphasis
></entry
><entry
>3</entry
></row>
<row
><entry
>Pas de formatage</entry
><entry
>4</entry
></row>
</tbody>
</tgroup>
</table>

</sect1>

<sect1 id="hidden-options">
<title
>Cacher les options de configuration</title>

<para
>&appname; a des options de configuration supplémentaires qui ne sont pas visibles dans la <interface
>Boîte de dialogue de configuration</interface
>. Ces options n'étaient pas assez importantes pour encombrer la boîte de dialogue avec plus de paramètres, mais comme elles représentent des options qui peuvent plaire à des utilisateurs, l'application les lit depuis le fichier de configuration. </para>

<para
>Les paramètres pour &appname; sont enregistrés dans un fichier dans le dossier personnel de l'utilisateur appelé <filename
>$<envar
>KDEHOME</envar
>/share/config/tellicorc</filename
>. Dans ce fichier, les paramètres sont rangés par groupes, qui apparaissent avec des noms entre crochets, tel que [General Options]. Pour ajouter un paramètre au groupe <emphasis
>General Options</emphasis
>, cherchez la ligne dans le fichier de configuration avec ce nom de groupe. Si il n'apparaît pas créez le vous même en ajoutant une ligne intitulée [General Options]. Le paramètre peut ensuite être ajouté sous le nom de groupe. </para>

<sect2 id="hidden-general-options">
<title
>[General Options]</title>

<para
>Ces paramètres doivent être placés dans le groupe <emphasis
>General Options</emphasis
>. </para>

<sect3>
<title
>Taille maximum des icônes</title>

<para
>La taille maximum des icônes dans la <interface
>Vue en icônes</interface
> peut être modifiée avec ce paramètre. La valeur par défaut est 96. La taille doit être comprise entre 32 et 256. </para>
</sect3>

<sect3>
<title
>Exemple</title>
<informalexample>
<para
><userinput
>Max Icon Size=128</userinput
></para>
</informalexample>
</sect3>

</sect2>

<sect2 id="hidden-bibtex-options">
<title
>[Options - BibTeX]</title>

<para
>Ces paramètres doivent être placés dans le groupe <emphasis
>Options - BibTeX</emphasis
>. </para>

<sect3>
<title
>lyxpipe</title>

<para
>Ce paramètre est pour l'emplacement de lyxpipe pour l'envoi de citations bibliographiques. Il ne doit pas inclure le suffixe <literal role="extension"
>.in</literal
>. </para>
</sect3>

<sect3>
<title
>Exemple</title>
<informalexample>
<para
><userinput
>lyxpipe=$HOME/.lyx/lyxpipe</userinput
></para>
</informalexample>
</sect3>
</sect2>

<sect2 id="hidden-export-options-pilotdb">
<title
>[Export Options - PilotDB]</title>

<para
>Ces paramètres doivent être placés dans le groupe <emphasis
>Export Options - PilotDB</emphasis
>. </para>

<sect3>
<title
>Jeu de caractères</title>

<para
>L'encodage de données exportées dans un fichier PilotDB peut être modifié avec ce paramètre. La valeur par défaut est la règle de jeu de caractères pour la locale de l'utilisateur. </para>
</sect3>

<sect3>
<title
>Exemple</title>
<informalexample>
<para
><userinput
>Charset=Windows-1250</userinput
></para>
</informalexample>
</sect3>
</sect2>

</sect1>

<sect1 id="bibtex-translation">
<title
>Traduction de caractères BibTeX</title>

<para
>Quand des fichiers BibTeX sont importés ou exportés, certains caractères sont traduits entre leur équivalent TeX et les caractères Unicode. Ces mapping de caractères sont contenus dans le fichier <filename
>BibTeX-translation.xml</filename
>, situés dans le dossier d'installation. Le mapping peut être modifié, comme désiré. L'élément clé contient les caractères Unicode, et les éléments de l'entrée qui contiennent les équivalents TeX, qui peuvent être un mapping un-vers-plusieurs. Le premier mapping est le premier utilisé à l'exportation vers BibTeX. </para>

<programlisting
><![CDATA[
  <key char="À">
    <string
>{\`A}</string>
    <string
>\`{A}</string>
  </key>
]]>
</programlisting>

</sect1>

<sect1 id="xslt-tricks">
<title
>Astuces XSLT</title>

<para
>Voici quelques astuces pour l'écriture XSLT pour analyser les données &XML; de &appname; (TBD). </para>
</sect1>

</chapter>