# 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 V9.0//EN" "http://periapsis.org/tellico/dtd/v9/tellico.dtd">
    <tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="9">
     <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="title" />
       <field flags="7" title="Autor" category="Geral" format="2" type="1" name="author" />
       <field flags="2" title="Encadernamento" category="Geral" allowed="Capa Dura;Capa de Papel;Capa de Papel Comercial;E-Book;Revista;Jornal" format="4" type="3" name="binding" />
       <field flags="6" title="Publicação" category="Publicação" format="0" type="1" name="publisher" />
       <field flags="4" title="Edição" category="Publicação" format="0" type="1" name="edition" />
       <field flags="3" title="Ano de Copyright" category="Publicação" format="4" type="6" name="cr_year" />
       <field flags="2" title="Ano de Publicação" category="Publicação" format="4" type="6" name="pub_year" />
       <field flags="0" title="ISBN#" category="Publicação" format="4" type="1" name="isbn" description="Número-Padrão Internacional para Livros" />
       <field flags="7" title="Gênero" category="Classificação" format="0" type="1" name="genre" />
       <field flags="7" title="Palavras-Chave" category="Classificação" format="0" type="1" name="keyword" />
       <field flags="0" title="Capa Frontal" category="Capa Frontal" format="4" type="10" name="cover" />
       <field flags="0" title="Comentários" category="Pessoal" format="4" type="1" name="comments" />
      </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.

Um elemento <field>, com um atributo de nome igual a _default, diz ao &appname; para incluir todos os campos padrão para esse tipo de coleção.

#### 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 de Coluna Única | 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`

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.

### 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 128.

#### Exemplo

`Max Icon Size=72`

### [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`

### [Export Options - PilotDB]

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

#### Charset

Você poderá alterar a codificação dos dados exportados dentro do arquivo do PilotDB file, graças a esta opção. O valor padrão é a codificação de caracteres da região do usuário.

#### Exemplo

`Charset=Windows-1250`

## 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).