# Programar para &appname;

En el espíritu del Software Libre, se le anima a programar &appname; tanto como quiera. Debería poder escribir scripts para importar, exportar o modificar datos muy fácilmente. Este capítulo le da más información sobre cómo hacer eso.

## Formato de archivos

El archivo de datos por defecto de &appname; es un archivo zip, normalmente con una extensión de archivo `.tc`. Dentro del archivo hay un archivo de nivel superior `tellico.xml`. Las imágenes se pueden incluir dentro de la carpeta `images/` del archivo, o pueden incluirse en los datos &XML; directamente con una codificación base64. Las imágenes también pueden guardarse dentro de la carpeta de datos de la aplicación, en cuyo caso no estarán en el propio archivo de datos. &appname; puede también cargar el archivo &XML; tal cual, descomprimido.

### Datos &XML;

#### Colección

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

El archivo comienza con la declaración y la codificación &XML; requerida, seguida por el tipo de documento. Cuando se añade un nuevo tipo de campo o se establecen propiedades adicionales en los campos predeterminados, la versión DTD se incrementa. &appname; siempre puede abrir y leer cualquier versión anterior de DTD, pero guardará los archivos en la versión actual. La localización de DTD apunta a un archivo DTD real.

El elemento de nivel superior es un elemento `<tellico>` que contiene la declaración por defecto namespace y la versión de la sintaxis del archivo, que siempre debe coincidir con la de DTD.

El elemento `<tellico>` contiene un elemento de `<collection>`. Las colecciones múltiples son ignoradas por ahora. El atributo `title` contiene el título de la colección, mientras que `type` especifica qué tipo de entradas están contenidas en la colección. Los tipos permitidos se listan en una sección posterior. Un atributo opcional `entryTitle` se puede usar para especificar el título de las entradas para una colección personalizada, y debería ir en plural.

#### Campos

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

Todos los campos están definidos dentro de un elemento `<fields>`, del cual solo puede existir uno. toda la información sobre un campo, excepto de las propiedades, está incluida como atributos en el elemento `<field>`. Los valores permitidos para los atributos `flags`, `format`, y `type` vienen dados en la sección siguiente.

Las propiedades del campo se usan para establecer valores predeterminados para el campo, intervalos de valores de clasificación, plantillas de valores derivados, etc. Los ejemplos de arriba incluyen un valor por defecto, un valor máximo de clasificación y una plantilla por un campo ID derivado.

#### Entradas

      <entry>
       <title
    >Lenguaje de programación C++, El</title>
       <authors>
        <author
    >Stroustrup, Bjarne</author>
       </authors>
       <publisher
    >Addison-Wesley Pub Co</publisher>
       <edition
    >3ª</edition>
       <pub_year
    >1997</pub_year>
       <isbn
    >0-201-88954-4</isbn>
       <genres>
        <genre
    >No ficción</genre>
       </genres>
       <keywords>
        <keyword
    >Programación</keyword>
        <keyword
    >Informática</keyword>
       </keywords>
       <cover
    >cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

Para cada campo de la colección, una `<entrada>` puede contener un elemento cuyo nombre sea idéntico al nombre del campo. Si se permiten valores múltiples para ese campo, entonces se añade la letra s al nombre del campo para crear un elemento, y cada valor se añade como un hijo de ese elemento, como en el caso de los campos de autor, género y palabra clave de arriba.

Como resultado, si se añaden campos adicionales a la colección, el archivo de datos ya no se ajustará al DTD. Sin embargo, &appname; usa un analizador &XML; no validante, de forma que los campos adicionales no causen problemas.

#### Imágenes

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

Dentro del elemento `<imágenes>`, cada imagen referenciada por una entrada se lista junto con los atributos que describen el tamaño de la imagen, su formato y su id. Si la imagen está contenida dentro de un archivo Zip, el elemento estará vacío. De otro modo, los datos de la imagen pueden estar contenidos en el &XML; como un texto codificado en base64.

## Valores de tipo de colección

El tipo de la colección viene dado por el atributo tipo del elemento de la colección. El valor es igual al valor de enumeración de `Type` en `src/collection.h`.

## Valores de tipo de colección

Tipo de colección | Valor
Colección personalizada | 1
Colección de libros | 2
Colección de vídeo | 3
Colección de música | 4
Bibliografía | 5
Colección de comics | 6
Colección de vinos | 7
Colección de monedas | 8
Colección de sellos | 9
Colección de cromos | 10
Colección de videojuegos | 11
Catálogo de archivos | 12
Colección de juegos de tablero | 13

## Valores de tipo de campo

&appname; incluirá todos los campos predeterminados para una colección si el primer elemento del campo tiene el nombre _default. Para los campos Párrafo, Tabla, o Imagen, la categoría del campo debería ser idéntica al título del campo.

El tipo de campo viene dado por el atributo tipo del elemento del campo. El valor es igual al valor de enumeración de `FieldType`

## Valores de tipo de campo

Tipo de campo | Valor
Texto sencillo | 1
Párrafo | 2
Elección | 3
Casilla de verificación | 4
Número | 6
&URL; | 7
Tabla | 8
Imagen | 10
Fecha | 12
Clasificación | 14

El campo puede tener establecidos diferentes indicadores, dados como un valor de bit con OR en el atributo «indicador» del elemento del campo. El indicador para evitar que el usuario borre un campo está dirigido a esas cosas como la clave de cita para las entradas bibliográficas.

## Valores del indicador de campo

Indicadores de campo | Valor
Permitir múltiples valores | `0x01`
Permitir agrupamiento | `0x02`
Permitir completado | `0x04`
No permitir el borrado | `0x08`
No permitir la edición | `0x10`
Valor derivado | `0x20`

El formato del campo viene dado por el atributo «formato» del elemento del campo. El formato de fecha no se usa actualmente. Agrupar por personas usa todos los campos que utilizan formateo de nombres. Establecer el marcador de Valor derivado implica que el valor de ese campo se genera desde la propiedad de plantilla de otros valores de campo.

## Valores del formato de campo

Formato de campo | Valor
Solo capitalización | 0
Formateo de título | 1
Formateo de nombres | 2
Formateo de fecha | 3
Sin formateo | 4

## Opciones ocultas de configuración

&appname; tiene algunas opciones de configuración adicionales que no son visibles en el Diálogo de configuración. No son lo suficientemente importantes para garantizar masificar el diálogo con más opciones, pero como representan opciones que pueden ser interesantes para varios usuarios, la aplicación las lee desde el archivo de configuración.

Los ajustes para &appname; se guardan en un archivo del directorio local del usuario, normalmente `~/.config/tellicorc`. Dentro de ese archivo, los ajustes se ponen en grupos, que aparecen con nombres entre corchetes, como en [Opciones generales]. Para añadir un ajuste al grupo Opciones generales, encuentre la línea en el archivo de ajustes que contenga el nombre del grupo. Si no aparece, créelo usted mismo añadiendo una línea que diga [Opciones generales]. Entonces, el ajuste se puede añadir bajo el nombre del grupo.

### [Opciones generales]

Estos ajustes deberían colocarse en el grupo Opciones generales.

#### Máx. tamaño de icono

El tamaño máximo de los iconos en la Vista de iconos se puede cambiar mediante este ajuste. El valor por defecto es de 96. El tamaño debe estar entre 32 y 256.

#### Ejemplo

`Max Icon Size=128`

#### Tamaño de la caché de iconos

El número máximo de iconos almacenados en la memoria se puede cambiar mediante este ajuste. El valor por defecto es 1000.

#### Ejemplo

`Icon Cache Size=100`

#### Tamaño de la caché de imágenes

La cantidad máxima de memoria en bytes usada para almacenar todas las imágenes se puede cambiar con este ajuste. El valor por defecto es 512 MiB.

#### Ejemplo

`Image Cache Size=256000000`

### [Opciones - bibtex]

Estos ajustes deberían colocarse en el grupo Opciones - bibtex.

#### lyxpipe

Este ajuste es para la localización de lyxpipe para enviar citas bibliográficas. No debería incluir el sufijo `.in`

#### Ejemplo

`lyxpipe=$HOME/.lyx/lyxpipe`

### [Opciones del lector de archivos]

Estos ajustes deberían colocarse en el grupo Opciones del lector de archivos.

#### Tamaño de la vista previa

Este ajuste es para el tamaño máximo de la vista previa del archivo.

#### Ejemplo

`Tamaño de la vista previa=523`

### Opciones multidisco

Las fuentes de datos MusicBrainz, Discogs e iTunes pueden extraer información de álbumes multidisco, especificando las pistas que contiene cada álbum. De forma predeterminada, las listas de pistas se insertan en un campo separado (uno para cada disco). Antes de la versión 4.0, las listas de pistas se combinaban. Esta opción proporciona el comportamiento previo a la versión 4.0 a nivel de fuente de datos individual. Añádala a cada sección Fuente de datos donde la necesite.

#### Dividir pistas por disco

Si define esta opción a falso se revierte el comportamiento previo a la versión 4.0, donde las pistas se compactan en una única lista de pistas.

#### Ejemplo

`Dividir pistas por disco=falso`

## Traducción de caracteres Bibtex

Cuando se importan o exportan archivos de bibtex, ciertos caracteres

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