# Modificar o &appname;

Segundo o espírito do 'Software' Livre, você é bem-vindo para modificar o &appname; tanto quanto desejar. Você poderá criar programas para importar, exportar ou modificar os dados com muita facilidade. Este capítulo fornece mais informações sobre como fazer isso.

## Formato de arquivo

O arquivo de dados padrão do &appname; é um pacote ZIP, normalmente com uma extensão de arquivos `.tc`. Dentro do pacote, existe um arquivo de topo `tellico.xml`. As imagens poderão ser incluídas dentro da pasta `images/` do pacote, podendo também ser incluídas diretamente no &XML;, com uma codificação 'base64'. As imagens poderão também ser salvas dentro da pasta de dados da aplicação; nesse caso, não estarão no arquivo de dados. O &appname; também pode carregar o arquivo &XML; propriamente dito, no formato não-comprimido.

### Dados &XML;

#### Coleção

    <?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="Meus Livros" type="2">
     </collection>
    </tellico>

O arquivo começa com a declaração e codificação obrigatória do &XML;, seguida do tipo de documento. Quando for adicionado um novo tipo de campo ou forem definidas propriedades adicionais nos campos predefinidos, a versão da DTD para o tipo de documento será incrementada. O &appname; será sempre capaz de abrir e ler qualquer versão anterior da DTD, mas só irá salvar os arquivos na versão atual. A localização da DTD aponta de fato para um arquivo de DTD atual.

O elemento de topo é um <tellico>, que contém a declaração do espaço de nomes padrão e a versão da sintaxe do arquivo, que deverá corresponder sempre à DTD.

O elemento <tellico> contém um elemento <collection>. São ignoradas várias coleções, por enquanto. O atributo title contém o título da coleção, enquanto o type define os tipos de itens que estão contidos na coleção. Os tipos permitidos são apresentados numa seção posterior. Existe um atributo entryTitle opcional que poderá ser usado para definir o título dos itens numa coleção personalizada, devendo estar no plural.

#### Campos

      <fields>
       <field flags="8" title="Título" category="Geral" format="1" type="1" name="titulo" />
       <field flags="7" title="Autor" category="Geral" format="2" type="1" name="autor" />
       <field flags="2" title="Formato" category="Geral" allowed="Capa Dura;Capa de Papel;Capa de Papel Comercial;E-Book;Revista;Jornal" format="4" type="3" name="formato" >
        <prop name="default"
    >Revista</prop>
       </field>
       <field flags="6" title="Publicação" category="Publicação" format="0" type="1" name="publicacao" />
       <field flags="4" title="Edição" category="Publicação" format="0" type="1" name="edicao" />
       <field flags="3" title="Ano do 'Copyright'" category="Publicação" format="4" type="6" name="ano_copyright" />
       <field flags="2" title="Ano de Publicação" category="Publicação" format="4" type="6" name="ano_publicacao" />
       <field flags="0" title="ISBN#" category="Publicação" format="4" type="1" name="isbn" description="International Standard Book Number" />
       <field flags="7" title="Gênero" category="Classificação" format="0" type="1" name="genero" />
       <field flags="7" title="Palavras-Chave" category="Classificação" format="0" type="1" name="palavraschave" />
       <field flags="0" title="Capa" category="Capa" format="4" type="10" name="capa" />
       <field flags="0" title="Comentários" category="Pessoal" format="4" type="1" name="comentarios" />
       <field title="Classificação" flags="2" category="Pessoal" format="4" type="14" name="classificacao">
        <prop name="maximum"
    >5</prop>
        <prop name="minimum"
    >1</prop>
       </field>
       <field title="ID" flags="32" category="Pessoal" format="4" type="6" name="id">
        <prop name="template"
    >%{@id}</prop>
       </field>

      </fields>

Todos os campos são definidos dentro de um elemento <fields>, nos quais só poderá existir um. Toda a informação de um campo, exceto as propriedades estendidas, são incluídas como atributos do elemento <field>. Os valores permitidos para os atributos flags, format e type são fornecidos na seguinte seção.

As propriedades dos campos são usadas para definir os valores padrão para os campos, os intervalos dos valores de classificações, os modelos dos valores derivados, etc. Os exemplos acima incluem um valor padrão, um valor máximo de classificação e um modelo para um campo de ID derivado.

#### Elementos

      <entry>
       <title
    >A Linguagem de Programação C++</title>
       <authors>
        <author
    >Stroustrup, Bjarne</author>
       </authors>
       <publisher
    >Addison-Wesley Pub Co</publisher>
       <edition
    >3a</edition>
       <pub_year
    >1997</pub_year>
       <isbn
    >0-201-88954-4</isbn>
       <genres>
        <genre
    >Não-Ficção</genre>
       </genres>
       <keywords>
        <keyword
    >Programação</keyword>
        <keyword
    >Computadores</keyword>
       </keywords>
       <cover
    >cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
      </entry>

Para cada um dos campos da coleção, existe um <entry> que poderá conter um elemento, cujo nome é idêntico ao nome do campo. Se forem permitidos vários valores para o campo, então será adicionada a letra s ao nome do campo, ao criar um elemento, e cada um dos valores é adicionado como um filho do elemento, como acontece no caso dos campos 'author', 'genre' e 'keyword' acima.

Como resultado, se forem adicionados campos extras à coleção, o arquivo de dados já não ficará mais em conformidade com a DTD. Contudo, o &appname; usa um processador de &XML; sem validação, assim os campos adicionais não causam problemas.

#### Imagens

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

Dentro do elemento <images>, é enumerada cada uma das imagens referenciadas por um elemento, em conjunto com os atributos que descrevem o tamanho, o formato e o identificador da imagem. Se a imagem estiver contida dentro do arquivo ZIP, o elemento está em branco. Caso contrário, os dados da imagem poderão estar contidos na sequência de &XML;, sob o formato de texto codificado em base64.

## Valores do Tipo de Coleção

O tipo de coleção é fornecido no atributo 'type' do elemento 'collection'. O valor é igual ao valor enumerado Type em `src/collection.h`.

### Valores do Tipo de Coleção

Tipo de Coleção | Valor
--- | ---
Coleção Personalizada | 1
Coleção de Livros | 2
Coleção de Vídeos | 3
Coleção de Músicas | 4
Bibliografia | 5
Coleção de Revistas em Quadrinhos | 6
Coleção de Vinhos | 7
Coleção de Moedas | 8
Coleção de Selos | 9
Coleção de Cartões Comerciais | 10
Coleção de Jogos de Console | 11
Catálogo de Arquivos | 12
Coleção de jogos de tabuleiro | 13

## Valores do Tipo de Campo

O &appname; irá incluir todos os campos padrão de uma coleção, caso o elemento do primeiro campo tenha o nome _default. Para os campos de Parágrafo, Tabela ou Imagem, a categoria do campo deverá ser idêntica ao título do campo.

O tipo de campo é fornecido no atributo 'type' do elemento 'field'. O valor é igual ao valor enumerado FieldType em `src/field.h`.

### Valores do Tipo de Campo

Tipo do Campo | Valor
--- | ---
Texto simples | 1
Parágrafo | 2
Escolha | 3
Opção | 4
Número | 6
&URL; | 7
Tabela | 8
Imagem | 10
Data | 12
Classificação | 14

O campo poderá ter diferentes opções ativas, indicado como um valor em OR's do atributo 'flags' do elemento 'field'. A opção para impedir o usuário de apagar um campo é necessária para algumas coisas, como a chave de citação dos itens bibliográficos.

### Valores das Opções dos Campos

Opções do Campo | Valor
--- | ---
Permitir Valores Múltiplos | `0x01`
Permitir o Agrupamento | `0x02`
Permitir o Completamento | `0x04`
Proibir a Remoção | `0x08`
Proibir a edição | `0x10`
Valor derivado | `0x20`

O formato do campo é indicado no atributo 'format' do elemento 'field'. A Formatação de Datas não é usada no momento. O agrupamento por Pessoas usa todos os campos que usam a Formatação de Nomes. Atribuir a opção Valor derivado, implica que o valor do campo seja gerado a partir da propriedade do modelo e dos valores dos outros campos.

### Valores dos Formatos dos Campos

Formato do Campo | Valor
--- | ---
Apenas com Capitalização | 0
Formatação de Títulos | 1
Formatação de Nomes | 2
Formatação de Datas | 3
Sem Formatação | 4

## Opções Ocultas de Configuração

O &appname; tem algumas opções adicionais de configuração que não estão visíveis na Janela de Configuração. Não são importantes o suficiente para que tenham que encher a janela de configuração, mas representam opções que poderão apelar a vários usuários, sendo que a aplicação as lê do arquivo de configuração.

A configuração do &appname; é salva num arquivo da pasta pessoal do usuário, nomeadamente o `$`KDEHOME`/share/config/tellicorc`. Dentro desse arquivo, a configuração é distribuída por grupos, os quais aparecem entre colchetes, como em '[General Options]'. Para adicionar uma opção ao grupo General Options, descubra a linha no arquivo de configuração com esse nome de grupo. Se esta não existir, então adicione-a você mesmo, acrescentando uma linha que diga [General Options]. Depois, você poderá adicionar a opção abaixo do nome do grupo.

### [General Options]

Estas opções deverão ser colocadas no grupo General Options.

#### Max Icon Size

Você poderá alterar o tamanho máximo dos ícones na Área de Ícones com esta opção. O valor padrão é 96. O tamanho deverá estar no intervalo entre 32 e 512.

#### Exemplo

`Max Icon Size=128`

#### Icon Cache Size

O número máximo de ícones que serão guardados na memória pode ser mudado com esta opção. O valor padrão é 1000.

#### Exemplo

`Icon Cache Size=100`

#### Exemplo

`Max Icon Size=128`

#### Image Cache Size

A quantidade máxima de memória em bytes usada para guardar todas as imagens pode ser mudada com esta opção. O valor padrão é 67108864.

#### Exemplo

`Image Cache Size=256000000`

### [Options - bibtex]

Estas opções deverão ser colocadas no grupo Options - bibtex.

#### lyxpipe

Esta opção serve para a localização do 'pipe' do Lyx, para onde deverá enviar as citações bibliográficas. Não deverá incluir o sufixo `.in`.

#### Exemplo

`lyxpipe=$HOME/.lyx/lyxpipe`

## Bibtex Character Translation

Quando os arquivos 'bibtex' são importados ou exportados, certos caracteres são traduzidos entre os seus equivalentes em TeX e os caracteres em Unicode. Esses mapeamentos de caracteres constam no arquivo `bibtex-translation.xml`, que se localiza na pasta de dados de instalação. Os mapeamentos poderão ser modificados como desejar. O elemento 'key' contém o caracter Unicode, enquanto os elementos 'string' dentro dele contêm os equivalentes em TeX, os quais poderão ser uma associação de um-para-muitos. O primeiro deles será usado na exportação para o 'bibtex'.

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

## Truques de XSLT

Aqui estão algumas sugestões de programação em XSLT para processar os dados em &XML; do &appname;: (POR FAZER).