# Hacking &appname;

In the spirit of Free Software, you are welcome to hack on &appname; as much as you like. You should be able to write scripts to import, export, or modify data very easily. This chapter gives you more information about doing that.

## File Format

The default &appname; data file is a zip archive, normally with a `.tc` file extension. Inside the archive is a top-level `tellico.xml` file. Images may be included inside the `images/` folder in the archive, or they may be included in the &XML; data directly in a base64 encoding. Images may also be saved inside the application data folder, in which case, they are not in the data file at all. &appname; can also load the &XML; file, by itself, uncompressed.

### &XML; Data

#### Collection

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

The file begins with the required &XML; declaration and encoding, followed by the doctype. When a new field type is added or additional properties are set on the default fields, the doctype DTD version is incremented. &appname; is always able to open and read any previous DTD version, but will save files in the current version. The DTD location does point to an actual DTD file.

The top-level element is a <tellico> element, containing the default namespace declaration and the syntax version of the file, which should always match the DTD.

The <tellico> element contains one <collection> element. Multiple collections are ignored, for now. The title attribute contains the collection title, while the type specifies what kinds of entries are contained in the collection. The allowable types are in listed in a later section. An optional entryTitle attribute may be used to specify the title of the entries for a custom collection, and should be plural.

#### Fields

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

All of the fields are defined inside a <fields> element, of which there can be only one. All of the information for a field, except for any properties, are included as attributes of the <field> element. The allowable values for the flags, format, and type attributes are given in a following section.

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.

#### Entries

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

For every field in the collection, an <entry> may contain an element whose name is identical to the field name. If multiple values are allowed for the field, then the letter s is added to the field name to create an element, and each value is added as a child of the element, as in the case of the author, genre, and keyword fields above.

As a result, if additional fields are added to the collection, the data file will no longer conform to the DTD. However, &appname; uses a non-validating &XML; parser, so additional fields do not cause problems.

#### Images

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

Inside the <images> element, each image referenced by an entry is listed, along with attributes describing the image's size, format, and id. If the image is contained inside the Zip file, the element is empty. Otherwise, the image data may be contained in the &XML; stream as base64-encoded text.

## Collection Type Values

The type of collection is given in the type attribute of the collection element. The value is equal to the Type enum value in `src/collection.h`.

### Collection Type Values

Collection Type | Value
--- | ---
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
Board Game Collection | 13

## Field Type Values

&appname; will include all the default fields for a collection if the first field element has the name _default. For Paragraph, Table, or Image fields, the field category should be identical to the field title.

The type of field is given in the type attribute of the field element. The value is equal to the FieldType enum value in `src/field.h`.

### Field Type Values

Field Type | Value
--- | ---
Simple Text | 1
Paragraph | 2
Choice | 3
Checkbox | 4
Number | 6
&URL; | 7
Table | 8
Image | 10
Date | 12
Rating | 14

The field may have different flags set, given as a bitwise OR'd value in the flags attribute on the field element. The flag for preventing the user from deleting a field is intended for such things as the citation key for bibliographic entries.

### Field Flag Values

Field Flags | Value
--- | ---
Allow Multiple Values | `0x01`
Allow Grouping | `0x02`
Allow Completion | `0x04`
Disallow Deleting | `0x08`
Disallow Editing | `0x10`
Derived Value | `0x20`

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

### Field Format Values

Field Format | Value
--- | ---
Capitalization Only | 0
Title Formatting | 1
Name Formatting | 2
Date Formatting | 3
No Formatting | 4

## Hidden Configuration Options

&appname; has some additional configuration options that are not visible in the Configuration Dialog. They are not important enough to warrant cluttering the dialog with more settings, but as they represent options which may appeal to various users, the application does read them from the configuration file.

The settings for &appname; are saved in a file in the user's home folder, namely `$`KDEHOME`/share/config/tellicorc`. Within that file, settings are put in groups, which appear with bracketed names, such as [General Options]. To add a setting to the General Options group, find the line in the settings file with that group name. If it does not appear, then create it yourself by adding a line saying [General Options]. Then, the setting can be added underneath the group name.

### [General Options]

These settings should be placed in the General Options group.

#### Max Icon Size

The maximum size of the icons in the Icon View may be changed with this setting. The default value is 96. The size must be in the range of 32 to 512.

#### Example

`Max Icon Size=128`

#### Icon Cache Size

The maximum numbers of icons cached in memory may be changed with this setting. The default value is 1000.

#### Example

`Icon Cache Size=100`

#### Example

`Max Icon Size=128`

#### Image Cache Size

The maximum amount of memory in bytes used for caching all the images may be changed with this setting. The default value is 67108864.

#### Example

`Image Cache Size=256000000`

### [Options - bibtex]

These settings should be placed in the Options - bibtex group.

#### lyxpipe

This setting is for the location of the lyxpipe for sending bibliographic citations. It should not include the `.in` suffix.

#### Example

`lyxpipe=$HOME/.lyx/lyxpipe`

## Bibtex Character Translation

When bibtex files are imported or exported, certain characters are translated between their TeX equivalents and the Unicode characters. Those character mappings are contained in the `bibtex-translation.xml` file, located in the installation data directory. The mappings can be modified, as desired. The key element contains the Unicode character, and the string elements within contain the TeX equivalents, which may be a one-to-many mapping. The first one is the one used when exporting to bibtex.

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

## XSLT Tricks

Here are some tips for writing XSLT to parse &appname; &XML; data: (TBD).