<chapter id="hacking">
<title
>Modificar o &appname;</title>

<para
>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. </para>

<sect1 id="file-format">
<title
>Formato de arquivo</title>

<para
>O arquivo de dados padrão do &appname; é um pacote ZIP, normalmente com uma extensão de arquivos <literal role="extension"
>.tc</literal
>. Dentro do pacote, existe um arquivo de topo <filename
>tellico.xml</filename
>. As imagens poderão ser incluídas dentro da pasta <filename
>images/</filename
> 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. </para>

<sect2 id="xml-format">
<title
>Dados &XML;</title>

 

<sect3 id="coll-xml-data">
<title
>Coleção</title>
<programlisting
><![CDATA[
<?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>
]]>
</programlisting>

<para
>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. </para>

<para
>O elemento de topo é um <markup
>&lt;tellico&gt;</markup
>, 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. </para>

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

<sect3 id="fields-xml-data">
<title
>Campos</title>

<programlisting
><![CDATA[
  <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>
]]>
</programlisting>

<para
>Todos os campos são definidos dentro de um elemento <markup
>&lt;fields&gt;</markup
>, 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 <markup
>&lt;field&gt;</markup
>. Os valores permitidos para os atributos <markup
>flags</markup
>, <markup
>format</markup
> e <markup
>type</markup
> são fornecidos na <link linkend="field-type-values"
>seguinte seção</link
>. </para>

<para
>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. </para>

 

</sect3>

<sect3 id="entries-xml-data">
<title
>Elementos</title>

<programlisting
><![CDATA[
  <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>
]]>
</programlisting>

<para
>Para cada um dos campos da coleção, existe um <markup
>&lt;entry&gt;</markup
> 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 <emphasis
>s</emphasis
> 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. </para>

<para
>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. </para>
</sect3>

<sect3 id="images-xml-data">
<title
>Imagens</title>
<programlisting
><![CDATA[
  <images>
   <image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" />
  </images>
]]>
</programlisting>

<para
>Dentro do elemento <markup
>&lt;images&gt;</markup
>, é 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. </para>
</sect3>

</sect2>

</sect1>

<sect1 id="collection-type-values">
<title
>Valores do Tipo de Coleção</title>

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

<table>
<title
>Valores do Tipo de Coleção</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Tipo de Coleção</entry>
<entry
>Valor</entry>
</row>
</thead>
<tbody>
<row
><entry
>Coleção Personalizada</entry
><entry
>1</entry
></row>
<row
><entry
>Coleção de Livros</entry
><entry
>2</entry
></row>
<row
><entry
>Coleção de Vídeos</entry
><entry
>3</entry
></row>
<row
><entry
>Coleção de Músicas</entry
><entry
>4</entry
></row>
<row
><entry
>Bibliografia</entry
><entry
>5</entry
></row>
<row
><entry
>Coleção de Revistas em Quadrinhos</entry
><entry
>6</entry
></row>
<row
><entry
>Coleção de Vinhos</entry
><entry
>7</entry
></row>
<row
><entry
>Coleção de Moedas</entry
><entry
>8</entry
></row>
<row
><entry
>Coleção de Selos</entry
><entry
>9</entry
></row>
<row
><entry
>Coleção de Cartões Comerciais</entry
><entry
>10</entry
></row>
<row
><entry
>Coleção de Jogos de Console</entry
><entry
>11</entry
></row>
<row
><entry
>Catálogo de Arquivos</entry
><entry
>12</entry
></row>
<row
><entry
>Coleção de jogos de tabuleiro</entry
><entry
>13</entry
></row>
</tbody>
</tgroup>
</table>


</sect1>

<sect1 id="field-type-values">
<title
>Valores do Tipo de Campo</title>

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

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

<table>
<title
>Valores do Tipo de Campo</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Tipo do Campo</entry>
<entry
>Valor</entry>
</row>
</thead>
<tbody>
<row
><entry
>Texto simples</entry
><entry
>1</entry
></row>
<row
><entry
>Parágrafo</entry
><entry
>2</entry
></row>
<row
><entry
>Escolha</entry
><entry
>3</entry
></row>
<row
><entry
>Opção</entry
><entry
>4</entry
></row>
<row
><entry
>Número</entry
><entry
>6</entry
></row>
<row
><entry
>&URL;</entry
><entry
>7</entry
></row>
<row
><entry
>Tabela de Coluna Única</entry
><entry
>8</entry
></row>
<row
><entry
>Imagem</entry
><entry
>10</entry
></row>
<row
><entry
>Data</entry
><entry
>12</entry
></row>
<row
><entry
>Classificação</entry
><entry
>14</entry
></row>
</tbody>
</tgroup>
</table>

<para
>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. </para>

<table>
<title
>Valores das Opções dos Campos</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Opções do Campo</entry>
<entry
>Valor</entry>
</row>
</thead>
<tbody>
<row
><entry
>Permitir Valores Múltiplos</entry
><entry
><constant
>0x01</constant
></entry
></row>
<row
><entry
>Permitir o Agrupamento</entry
><entry
><constant
>0x02</constant
></entry
></row>
<row
><entry
>Permitir o Completamento</entry
><entry
><constant
>0x04</constant
></entry
></row>
<row
><entry
><emphasis
>Proibir a Remoção</emphasis
></entry
><entry
><constant
>0x08</constant
></entry
></row>
<row
><entry
><emphasis
>Proibir a edição</emphasis
></entry
><entry
><constant
>0x10</constant
></entry
></row>
<row
><entry
>Valor derivado</entry
><entry
><constant
>0x20</constant
></entry
></row>
</tbody>
</tgroup>
</table>

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

<table>
<title
>Valores dos Formatos dos Campos</title>
<tgroup cols="2">
<thead>
<row>
<entry
>Formato do Campo</entry>
<entry
>Valor</entry>
</row>
</thead>
<tbody>
<row
><entry
>Apenas com Capitalização</entry
><entry
>0</entry
></row>
<row
><entry
>Formatação de Títulos</entry
><entry
>1</entry
></row>
<row
><entry
>Formatação de Nomes</entry
><entry
>2</entry
></row>
<row
><entry
><emphasis
>Formatação de Datas</emphasis
></entry
><entry
>3</entry
></row>
<row
><entry
>Sem Formatação</entry
><entry
>4</entry
></row>
</tbody>
</tgroup>
</table>

</sect1>

<sect1 id="hidden-options">
<title
>Opções Ocultas de Configuração</title>

<para
>O &appname; tem algumas opções adicionais de configuração que não estão visíveis na <interface
>Janela de Configuração</interface
>. 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. </para>

<para
>A configuração do &appname; é salva num arquivo da pasta pessoal do usuário, nomeadamente o <filename
>$<envar
>KDEHOME</envar
>/share/config/tellicorc</filename
>. 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 <emphasis
>General Options</emphasis
>, 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. </para>

<sect2 id="hidden-general-options">
<title
>[General Options]</title>

<para
>Estas opções deverão ser colocadas no grupo <emphasis
>General Options</emphasis
>. </para>

<sect3>
<title
>Max Icon Size</title>

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

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Max Icon Size=128</userinput
></para>
</informalexample>
</sect3>

<sect3>
<title
>Icon Cache Size</title>

<para
>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. </para>
</sect3>

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Icon Cache Size=100</userinput
></para>
</informalexample>
</sect3>

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Max Icon Size=128</userinput
></para>
</informalexample>
</sect3>

<sect3>
<title
>Image Cache Size</title>

<para
>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. </para>
</sect3>

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Image Cache Size=256000000</userinput
></para>
</informalexample>
</sect3>

</sect2>

<sect2 id="hidden-bibtex-options">
<title
>[Options - bibtex]</title>

<para
>Estas opções deverão ser colocadas no grupo <emphasis
>Options - bibtex</emphasis
>. </para>

<sect3>
<title
>lyxpipe</title>

<para
>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 <literal role="extension"
>.in</literal
>. </para>
</sect3>

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>lyxpipe=$HOME/.lyx/lyxpipe</userinput
></para>
</informalexample>
</sect3>
</sect2>

</sect1>

<sect1 id="bibtex-translation">
<title
>Bibtex Character Translation</title>

<para
>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 <filename
>bibtex-translation.xml</filename
>, 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'. </para>

<programlisting
><![CDATA[
  <key char="À">
    <string
>{\`A}</string>
    <string
>\`{A}</string>
  </key>
]]>
</programlisting>

</sect1>

<sect1 id="xslt-tricks">
<title
>Truques de XSLT</title>

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

</chapter>