<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 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>
]]>
</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="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>
]]>
</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
>Um elemento <markup
>&lt;field&gt;</markup
>, com um atributo de nome igual a <emphasis
>_default</emphasis
>, diz ao &appname; para incluir todos os campos padrão para esse tipo de coleção. </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>
</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
>. </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 256. </para>
</sect3>

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Max Icon Size=128</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>

<sect2 id="hidden-export-options-pilotdb">
<title
>[Export Options - PilotDB]</title>

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

<sect3>
<title
>Codificação de caracteres</title>

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

<sect3>
<title
>Exemplo</title>
<informalexample>
<para
><userinput
>Charset=Windows-1250</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>
