# Hacking di &appname;

Nello spirito del software libero chiunque è autorizzato a modificare &appname; come e quanto vuole. Non dovrebbe essere difficile scrivere script per importare, esportare o modificare i dati. Questo capitolo fornisce ulteriori informazioni su come farlo.

## Formato dei file

Il file dati tipico di &appname; è un archivio zip e di norma ha estensione `.tc`. Nell'archivio si trova un file guida `tellico.xml`. Le immagini possono stare nella cartella `images/` dell'archivio o essere incluse direttamente nel file &XML;, codificate come base64. Le immagini possono essere anche salvate nella cartella dell'applicazione e in questo caso non saranno affatto incluse nel file dati. &appname; può anche caricare il solo file &XML; non compresso.

### Dati &XML;

#### Collezione

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

Il file inizia con le necessarie dichiarazioni e codifiche &XML;, seguite dal tipo di documento. Quando un nuovo tipo di campo viene aggiunto o viene impostata una nuova proprietà per i campi predefiniti la versione di "doctype DTD" viene incrementata. &appname; sarà sempre in grado di leggere file di versioni DTD successive, ma salverà sempre i file nella versione corrente. Il percorso DTD deve puntare ad un file DTD esistente.

L'elemento top-level è del tipo <tellico>. Esso contiene la dichiarazione namespace predefinita e la versione di sintassi del file, che deve sempre corrispondere al DTD.

L'elemento <tellico> contiene l'elemento <collection>. Al momento più collezioni sono ignorate. L'attributo title contiene il titolo della collezione mentre type specifica quali tipi di elementi vi sono contenuti. I tipi di campo disponibili sono elencati successivamente. Un attributo opzionale entryTitle può essere usato per specificare il titolo degli elementi in una collezione personalizzata. Il nome dovrebbe essere al plurale.

#### Campi

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

Tutti i campi sono definiti entro un unico elemento <fields>. Tutte le informazioni su uno specifico campo, tranne le sue proprietà, sono incluse come attributi dell'elemento <field>. I valori ammessi per gli attributi flags, format, e type sono elencati in una successiva sezione.

Le proprietà dei campi sono utilizzate per definire i loro valori predefiniti, le valutazioni possibili, i modelli per i valori derivati, etc. Gli esempi seguenti mostrano come assegnare un valore predefinito, un massimo per le valutazioni e un modello per un campo ID derivato.

#### Elementi

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

Per ogni campo nella collezione, <entry> dovrebbe contenere un elemento il cui nome è identico al nome del campo. Se sono stati impostati valori multipli per quel campo allora la lettera s viene aggiunta al nome del campo per creare l'elemento, e ogni valore è aggiunto come un "child" di quell'elemento, come nel caso dei campi author, genre e keyword qui sopra.

Come risultato se vengono aggiunti campi alla collezione il file dati non sarà più conforme al DTD. Tuttavia &appname; utilizza un parser &XML; di tipo non-validating, quindi i campi addizionali non dovrebbero causare problemi.

#### Immagini

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

All'interno dell'elemento <images> vengono elencate tutte le immagini collegate ad un oggetto con gli attributi che ne descrivono le dimensioni e il suo ID. Se l'immagine è contenuta in un file zip l'elemento è vuoto. Altrimenti l'immagine può essere inserita nel file &XML; codificandola come testo base64.

## Valori per Tipo di collezione

Il tipo di collezione è definito dall'attributo tipo dell'elemento collezione. Il valore corrisponde a quello Type enum nel file `src/collection.h`.

### Valori per Tipo di collezione

Tipi di collezione | Valore
--- | ---
Collezione personalizzata | 1
Collezione di libri | 2
Collezione video | 3
Collezione di musica | 4
Bibliografia | 5
Collezione di fumetti | 6
Collezione di vini | 7
Collezione di monete | 8
Collezione di francobolli | 9
Collezione di figurine o carte | 10
Collezione di videogiochi | 11
Catalogo di file | 12
Collezione di giochi da tavolo | 13

## Valori per Tipo di campo

Se il primo campo di una collezione ha il nome _default &appname; includerà tutti i campi predefiniti di quel tipo di collezione. Per i campi Paragraph, Table, o Image la categoria del campo deve essere identica al titolo.

Il tipo di un campo è definito dal corrispondente attributo di un suo elemento. Il valore corrisponde all'enum FieldType nel file `src/field.h`.

### Valori per Tipo di campo

Tipi di campo | Valore
--- | ---
Testo semplice | 1
Paragrafo | 2
Scelta | 3
Spunta | 4
Numero | 6
&URL; | 7
Tabella a Colonna singola | 8
Immagine | 10
Data | 12
Voto | 14

I campi possono avere alcune flag impostate, e sono date come valori bitwise OR negli attributi flag del elemento field. La flag per impedire all'utente di cancellare il campo serve per cose come la citation key delle entrate bibliografiche.

### Valori di flag in field

Field Flags | Valore
--- | ---
Permetti valori multipli | `0x01`
Permetti raggruppamento | `0x02`
Permetti completamento automatico | `0x04`
Disabilita la cancellazione | `0x08`
Disabilita le modifiche | `0x10`
Valori derivati | `0x20`

La formattazione del campo è stabilita nell'attributo format degli elementi del campo. Date Formatting non è al momento usato. Il raggruppamento in Persone usa tutti i campi che usano Formatta come nome. Impostare la flag Derived Value comporta che il valore del campo è generato a partire dai valori degli altri campi in base alle regole del modello.

### Valori di formattazione dei campi

Formattazione campo | Valore
--- | ---
Solo maiuscole | 0
Formatta come titolo | 1
Formatta come nome | 2
Date Formatting | 3
Nessuna formattazione | 4

## Opzioni di configurazione nascoste

&appname; ha alcune opzioni di configurazione aggiuntive che non sono visibili nella finestra di configurazione. Non sono così importanti da essere messe nella finestra ma, poiché potrebbero far piacere a diversi utenti, l'applicazione può leggerle direttamente dal file di configurazione.

Le impostazioni di &appname; sono salvate in un file nella cartella home dell'utente chiamato `$`KDEHOME`/share/config/tellicorc`. In questo file le opzioni di configurazione sono raggruppate sotto nomi posti tra parentesi come [General Options]. Per aggiungere impostazioni al gruppo General Options cercare la linea che contiene questa dicitura, e se non esiste crearla aggiungendo una linea con scritto [General Options]. Successivamente si possono aggiungere impostazioni sotto il nome del gruppo.

### [General Options]

Queste impostazioni possono essere scritte nel gruppo General Options.

#### Max Icon Size

La dimensione massima delle icone nella vista a icone può essere cambiata agendo su questa impostazione. Il valore predefinito è 96. La dimensione dev'essere compresa tra 32 e 128.

#### Esempio

`Max Icon Size=128`

#### Icon Cache Size

Il numero massimo di icone conservate nella cache può essere cambiato agendo su questa impostazione. Il valore predefinito è 1000.

#### Esempio

`Icon Cache Size=100`

#### Esempio

`Max Icon Size=128`

#### Image Cache Size

Lo spazio massimo utilizzato per mantenere in cache tutte le immagini può essere cambiato agendo su questa impostazione. Il valore predefinito è 67108864.

#### Esempio

`Image Cache Size=256000000`

### [Options - bibtex]

Queste impostazioni rientrano nel gruppo Options - bibtex.

#### lyxpipe

Questa impostazione è il percorso del lyxpipe per inviare citazioni bibliografiche. Non deve includere il suffisso `.in`.

#### Esempio

`lyxpipe=$HOME/.lyx/lyxpipe`

## Traduzione dei caratteri bibtex

Quando vengono importati od esportati file bibtex alcuni caratteri sono tradotti da caratteri Unicode e gli equivalenti TeX, e viceversa. La mappatura di questa conversione è contenuta nel file `bibtex-translation.xml`, nella cartella d'installazione del programma. La mappatura può essere modificata a proprio piacimento. Le chiavi contengono i caratteri Unicode, e le stringhe gli equivalenti TeX, che possono essere mappati come uno-a-molti. Solo il primo viene usato quando si esporta in bibtex.

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

## Trucchi XSLT

Ecco alcuni suggerimenti per scrivere XSLT per analizzare i dati &XML; di &appname; (TBD).