<?xml version="1.0" encoding="UTF-8" ?>

<chapter id="extending-quanta-3-2">
<chapterinfo>
<title
>Extender o &quantaplus;</title>
<authorgroup>
<author
><firstname
>Christopher</firstname
> <surname
>Hornbaker</surname
> <affiliation
> <address
><email
>chrishornbaker@earthlink.net</email
></address>
</affiliation>
</author>

<othercredit role="translator"
><firstname
>Pedro</firstname
><surname
>Morais</surname
><affiliation
><address
><email
>morais@kde.org</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 

</authorgroup>
</chapterinfo>

<title
>Extender o &quantaplus;</title>

<para
>Este capítulo descreve como personalizar o &quantaplus; de acordo com as suas necessidades particulares e como pode ajudar o &quantaplus; a tornar-se melhor. </para>

<!--<sect1 id="kommander-3-2">
<title
>Using Kommander With &quantaplus;</title>

<para>
Kommander, by Marc Britton.
</para>
</sect1
> -->

<sect1 id="dtep-intro-3-2">
<title
>Pacote de Edição do Tipo de Documento (&DTEP;)</title>

<para
>Os Pacotes de Edição do Tipo de Documentos (&DTEP;s) são usados no &quantaplus; para adicionar o suporte para as linguagens de formatação e de 'scripting', bem como para o &CSS;. Estas permitem ao &quantaplus; oferecer as funcionalidades como a auto-completação e as árvores de nós. A sua simplicidade e flexibilidade são o que tornam o &quantaplus; um &IDE; rápido e amigável para os programadores Web. São também o que fazem do &quantaplus; um ambiente produtivo e simples de utilizar. </para>

<para
>Os &DTEP;s vêm em dois formatos: a Família 1, que corresponde às linguagens de formatação e a Família 2, que corresponde ao 'scripting' e ao &CSS;. Os &DTEP;s são compostos por duas partes, a Pasta de Marcas e as Barras de Ferramentas. As Pastas de Marcas são compostas por dois tipos de ficheiros, o 'description.rc' e os ficheiros de TagXML, os quais contêm a extensão '.tag'. As barras de ferramentas são as páginas de botões úteis e orientados por ícones (por cima da janela de edição) que colocam o texto num documento de forma mais rápida do que o utilizador consegue escrever. </para>

<para
>Este documento descreve como é possível criar ficheiros TagXML, o 'description.rc' e as barras de ferramentas. Em resumo, como criar um &DTEP;. </para>

<para
>Os ficheiros TagXML (.tag) definem tanto os atributos específicos para uma marca como a disposição e o conteúdo da janela de propriedades que o &quantaplus; irá mostrar para a marca. O ficheiro 'description.rc' contém as regras e a informação para o próprio &DTEP;. As barras de ferramentas oferecem uma forma rápida de adicionar marcas num documento, sem haver a preocupação com erros de escrita e outros erros do género. </para>

<sect2 id="dtep-packaging-3-2">
<title
>Empacotamento</title>

<para
>As Pastas de Marcas são isso mesmo - pastas. Estas são compostas apenas pelos ficheiros 'description.rc' e TagXML. As Pastas de Marcas contêm o nome da linguagem de formatação e a versão, se tal se aplicar. (Por exemplo, html-4.01-strict) </para>
</sect2>

<sect2 id="tagxml-3-2">
<title
>TagXML</title>

<para
>A tabela em baixo enumera os elementos que são definidos no TagXML e refere se estes são obrigatórios ou não. Embora nem todos sejam necessários, recomenda-se que você use tantos quantos possíveis para que os outros utilizadores possam ter uma melhor experiência e mais informação com que lidar. </para>

<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry
>Elemento</entry>
<entry
>Utilização Predefinida</entry>
<entry
>Caso de Utilização</entry>
</row>
</thead>
<tbody>
<row>
<entry
>TAGS</entry>
<entry
>necessário</entry>
<entry
>sempre</entry>
</row>
<row>
<entry
>tag</entry>
<entry
>necessário</entry>
<entry
>sempre</entry>
</row>
<row>
<entry
>label</entry>
<entry
>opcional</entry>
<entry
>necessário para criar uma janela de propriedades</entry>
</row>
<row>
<entry
>attr</entry>
<entry
>opcional</entry>
<entry
>necessário para definir um atributo</entry>
</row>
<row>
<entry
>tooltip</entry>
<entry
>opcional</entry>
<entry
>necessário para que a janela de propriedades mostre uma dica</entry>
</row>
<row>
<entry
>whatsthis</entry>
<entry
>opcional</entry>
<entry
>necessário para que a janela de propriedades mostre um <quote
>O Que é Isto?</quote
></entry>
</row>
<row>
<entry
>list</entry>
<entry
>opcional</entry>
<entry
>necessário quando um determinado atributo é do tipo <quote
>list</quote
> (lista)</entry>
</row>
<row>
<entry
>item</entry>
<entry
>opcional</entry>
<entry
>necessário quando o &lt;list
> é usado</entry>
</row>
<row>
<entry
>textlocation</entry>
<entry
>opcional</entry>
<entry
>sempre</entry>
</row>
<row>
<entry
>location</entry>
<entry
>opcional</entry>
<entry
>necessário quando é usada uma legenda</entry>
</row>
<row>
<entry
>text</entry>
<entry
>opcional</entry>
<entry
>necessário quando é usada uma legenda</entry>
</row>
<row>
<entry
>children</entry>
<entry
>opcional</entry>
<entry
>uma lista das marcas que poderão aparecer dentro da marca que está a ser definida</entry>
</row>
<row>
<entry
>child</entry>
<entry
>necessário</entry>
<entry
>um item-filho</entry>
</row>
<row>
<entry
>stoppingtags</entry>
<entry
>opcional</entry>
<entry
>uma lista das marcas que indicam o fim para outra marca</entry>
</row>
<row>
<entry
>stoppingtag</entry>
<entry
>necessário</entry>
<entry
>um item de interrupção da marca</entry>
</row>
</tbody>
</tgroup>
</informaltable>


<sect3 id="dtep-element-descriptions-3-2">
<title
>Descrições do Elemento do TagXML</title>

<para
>As secções seguintes irão descrever, em detalhe, cada elemento. Tudo desde onde eles poderão estar até o que poderão conter é descrito aqui de uma forma simples de seguir. </para>

<sect4 id="TAGS-3-2">
<title
>TAGS</title>

<para
>Este é o elemento de raiz (topo) de um documento de TagXML. Só poderá aparecer num documento uma única vez. Poderá conter a definição de várias marcas. Este é um elemento do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
><emphasis
>NENHUM</emphasis
></entry>
<entry
>tag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="tag-3-2">
<title
>tag</title>

<para
>Uma cobertura para a marca a ser definida. Este é um elemento do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>TAGS</entry>
<entry
>label, attr, stoppingtags</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry
><entry
>Valores</entry>
<entry
>Predefinição</entry
><entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry
><entry
></entry
><entry
></entry>
<entry
>necessário</entry
><entry
>Indica o nome da marca a ser definida.</entry>
</row>
<row>
<entry
>single</entry
><entry
>boolean</entry
><entry
></entry
><entry
></entry>
<entry
>opcional</entry
><entry
>Indica se a marca necessita de uma 'tag' de fecho ou não (&lt;/(nome da marca)
>.</entry>
</row>
<row>
<entry
>type</entry
><entry
>string</entry
><entry
></entry
><entry
>xmltag</entry>
<entry
>opcional</entry
><entry
>Indica o tipo da marca a ser definida.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>xmltag</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca baseia-se em XML. (Apenas na Família 1.)</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>property</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca relaciona-se com a &CSS; (Apenas Família 2.)</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>function</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca é uma função de programação. Quando é usado, os elementos &lt;attr
> tornam-se os argumentos da função (apenas na Família 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>class</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca é uma classe de programação. (apenas na Família 2.)</entry>
</row>
<row>
<entry
>returnType</entry
><entry
>string</entry
><entry
></entry
><entry
>void </entry>
<entry
>opcional</entry
><entry
>Indica o tipo devolvido pela marca a ser definida. (apenas na Família 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>void</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca não devolve nada ('void').</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>int</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca devolve um inteiro.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>float</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca devolve um número de vírgula flutuante.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>long</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo da marca devolve um número longo.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>string</entry
><entry
></entry>
<entry
></entry
><entry
>O tipo de marca devolve uma cadeia de caracteres.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="label-3-2">
<title
>label</title>

<para
>Coloca uma legenda na janela. O texto é referido na marca &lt;text
>. Este é um elemento do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry>
<entry
>text, location</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="attr-3-2">
<title
>attr</title>

<para
>Define um atributo da marca. Este elemento ocorre uma vez para cada atributo. Define o nome e o tipo do atributo. Também contém as marcas adicionais que indicam como o atributo deverá ser mostrado, etc. Este é um elemento do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry>
<entry
>location, list, tooltip, whatsthis, textlocation</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry
><entry
>Valores</entry>
<entry
>Predefinição</entry
><entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry
><entry
></entry
><entry
></entry>
<entry
>necessário</entry
><entry
>Indica o nome do atributo a ser definido.</entry>
</row>
<row>
<entry
>type</entry
><entry
>string</entry
><entry
></entry
><entry
>input</entry>
<entry
>necessário</entry
><entry
>Indica o tipo do atributo a ser definido.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>input</entry
><entry
></entry>
<entry
></entry
><entry
>O campo suporta a introdução de texto livre (campo de texto).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>check</entry
><entry
></entry>
<entry
></entry
><entry
>O valor do campo é booleano (opção).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>color</entry
><entry
></entry>
<entry
></entry
><entry
>O valor do campo é uma cor.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>url</entry
><entry
></entry>
<entry
></entry
><entry
>O valor do campo é um &URL;. (Ficheiro local que referencia.)</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>list</entry
><entry
></entry>
<entry
></entry
><entry
>O valor do campo é um item de uma lista indicada.</entry>
</row>
<row>
<entry
>status</entry
><entry
>string</entry
><entry
></entry
><entry
>opcional</entry>
<entry
>necessário</entry
><entry
>Indica se o argumento é ou não obrigatório. (Apenas na Família 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>opcional</entry
><entry
></entry>
<entry
></entry
><entry
>O argumento é opcional.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>necessário</entry
><entry
></entry>
<entry
></entry
><entry
>O argumento é necessário.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>implied</entry
><entry
></entry>
<entry
></entry
><entry
>O argumento é implícito.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="tooltip-3-2">
<title
>tooltip</title>

<para
>Define a dica para um campo na janela. Este elemento é apenas de texto. </para>

<note>
<para
>De momento só é suportado texto simples (você não pode usar nenhuma formatação). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="whatsthis-3-2">
<title
>whatsthis</title>

<para
>Define a ajuda 'O Que É Isto?' para um campo da janela. Este elemento contém apenas texto. </para>

<note>
<para
>De momento só é suportado texto simples (você não pode usar nenhuma formatação). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="list-3-2">
<title
>list</title>

<para
>Uma marca que apenas agrupa os itens de uma lista. Só pode aparecer uma vez por cada descrição de um atributo. Este é um elemento do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
>item</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="item-3-2">
<title
>item</title>

<para
>Define um item da lista. Este elemento contém apenas texto. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>list</entry>
<entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="textlocation-3-2">
<title
>textlocation</title>

<para
>Indica a posição do atributo de uma marca dentro de uma janela. Esta marca só poderá ocorrer uma vez por cada atributo da janela (&ie; um por cada marca &lt;attr
>). Este elemento fica vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry>
<entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry>
<entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>row</entry
><entry
>nonNegativeInteger</entry>
<entry
>necessário</entry
><entry
>Indica a linha na disposição da janela de um campo ou legenda.</entry>
</row>
<row>
<entry
>col</entry
><entry
>nonNegativeInteger</entry>
<entry
>necessário</entry
><entry
>Indica a coluna na disposição da janela para um campo ou uma legenda.</entry>
</row>
<row>
<entry
>rowspan</entry
><entry
>nonNegativeInteger</entry>
<entry
>opcional</entry
><entry
>Indica o número de linhas que um campo poderá ocupar.</entry>
</row>
<row>
<entry
>colspan</entry
><entry
>nonNegativeInteger</entry>
<entry
>opcional</entry
><entry
>Indica o número de colunas que um campo poderá ocupar.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="location-3-2">
<title
>location</title>

<para
>Indica a posição e o tamanho de um campo na janela. Esta marca só deverá aparecer uma vez por cada campo da janela (&ie; um por cada marca de &lt;attr
> e &lt;label
>). Este elemento fica vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>label, attr</entry
><entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry>
<entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>row</entry
><entry
>nonNegativeInteger</entry>
<entry
>necessário</entry
><entry
>Indica a linha na disposição da janela de um campo ou legenda.</entry>
</row>
<row>
<entry
>col</entry
><entry
>nonNegativeInteger</entry>
<entry
>necessário</entry
><entry
>Indica a coluna na disposição da janela para um campo ou uma legenda.</entry>
</row>
<row>
<entry
>rowspan</entry
><entry
>nonNegativeInteger</entry>
<entry
>opcional</entry
><entry
>Indica o número de linhas que um campo poderá ocupar.</entry>
</row>
<row>
<entry
>colspan</entry
><entry
>nonNegativeInteger</entry>
<entry
>opcional</entry
><entry
>Indica o número de colunas que um campo poderá ocupar.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="text-3-2">
<title
>text</title>

<para
>Define o texto para uma legenda ou para uma opção. Este campo contém apenas texto. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>label, attr</entry
><entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="children-3-2">
<title
>children</title>

<para
>Define uma lista dos elementos que podem aparecer dentro da marca a ser criada. Este elemento é do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry
><entry
>child</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="child-3-2">
<title
>child</title>

<para
>Define uma marca-filha. Este elemento fica vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>children</entry
><entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry>
<entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry>
<entry
>necessário</entry
><entry
>Define uma marca que poderá aparecer dentro da marca indicada.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="stoppingtags-3-2">
<title
>stoppingtags</title>

<para
>Define uma lista dos elementos que obrigam a marca a terminar. Este elemento é do tipo apenas para elementos. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry
><entry
>stoppingtag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="stoppingtag-3-2">
<title
>stoppingtag</title>

<para
>Define uma marca de interrupção ou de fecho. Este elemento fica vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Pai(s)</entry
><entry
>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry
>stoppingtags</entry
><entry
><emphasis
>NENHUM</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Atributo</entry
><entry
>Tipo</entry>
<entry
>Utilização</entry
><entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry>
<entry
>necessário</entry
><entry
>Indica quais as marcas que obrigam ao fecho de outra marca.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
</sect3>

<sect3 id="tagxml-usage-3-2">
<title
>Utilização do TagXML</title>

<para
>Todos os ficheiros de TagXML deverão começar pela declaração de &XML;: &lt;?xml version="1.0" encoding="UTF-8"?> e deverão estar devidamente aninhados e fechados. </para>

<important>
<para
>Os espaços não afectam de facto em nada, mas tenha em atenção os caracteres &amp; e &lt;. Estes deverão ser substituídos provavelmente por &amp;amp; e por &amp;lt;, respectivamente, nos elementos como o &lt;tooltip
>, o &lt;whatsthis
> e o &lt;text
>. Se não o fizer não irá estoirar o programa, mas poderá fazer com que certos pedaços do seu trabalho desapareçam, nesse caso. </para>
</important>
</sect3>

<sect3 id="tagxml-validation-3-2">
<title
>Validação do TagXML</title>

<para
>Para validar os seus ficheiros TagXML, basta carregar na janela das <quote
>Ferramentas</quote
> no topo do &quantaplus; e seleccionar <quote
>Validar o TagXML.</quote
> Irá então aparecer uma janela na qual você terá apenas de seguir as indicações simples. </para>

<note>
<para
>Esta funcionalidade de momento não está presente. Actualmente a validação ocorre quando os ficheiros TagXML são carregados no &quantaplus;. </para>
</note>
</sect3>

<sect3 id="tagxml-examples-3-2">
<title
>Exemplos de TagXML</title>

<sect4 id="family-one-3-2">
<title
>Família 1</title>

<para
>O seguinte irá mostrar um ficheiro de TagXML da Família 1 válido. Este ficheiro descreve também o elemento &lt;schema
> do &XML; Schema da &W3C;. O nome do ficheiro para este ficheiro TagXML seria então schema.tag. Simples, não é? </para>

<informalexample>
<literallayout
><markup>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!DOCTYPE TAGS>
&lt;TAGS>
 &lt;tag name="schema">
  &lt;label>
   &lt;text
>id&lt;/text>
   &lt;location col="0" row="0"/>
  &lt;/label>
  &lt;attr name="id" type="input">
   &lt;tooltip
>Um ID único para o elemento.&lt;/tooltip>
   &lt;whatsthis
>Um ID único para o elemento.&lt;/whatsthis>
   &lt;location col="1" row="0"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>version&lt;/text>
   &lt;location col="0" row="1"/>
  &lt;/label>
  &lt;attr name="version" type="input">
   &lt;tooltip
>A versão do esquema.&lt;/tooltip>
   &lt;whatsthis
>A versão do esquema.&lt;/whatsthis>
   &lt;location col="1" row="1"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>targetNamespace&lt;/text>
   &lt;location col="0" row="2"/>
  &lt;/label>
  &lt;attr name="targetNamespace" type="input">
   &lt;tooltip
>Uma referência de &URI; para o espaço de nomes deste esquema.&lt;/tooltip>
   &lt;whatsthis
>Uma referência de &URI; para o espaço de nomes deste esquema.&lt;/whatsthis>
   &lt;location col="1" row="2"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>xmlns&lt;/text>
   &lt;location col="0" row="3"/>
  &lt;/label>
  &lt;attr name="xmlns" type="input">
   &lt;tooltip
>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema.
   Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.&lt;/tooltip>
   &lt;whatsthis
>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema.
   Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.&lt;/whatsthis>
   &lt;location col="1" row="3"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>attributeFormDefault&lt;/text>
   &lt;location col="0" row="4"/>
  &lt;/label>
  &lt;attr name="attributeFormDefault" type="list">
   &lt;items>
    &lt;item
>qualified&lt;/item>
    &lt;item
>unqualified&lt;/item>
   &lt;/items>
   &lt;tooltip
>O formato por omissão para todos os atributos dentro deste esquema.&lt;/tooltip>
   &lt;whatsthis
>O formato por omissão para todos os atributos dentro deste esquema.&lt;/whatsthis>
   &lt;location col="1" row="4"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>elementFormDefault&lt;/text>
   &lt;location col="0" row="5"/>
  &lt;/label>
  &lt;attr name="elementFormDefault" type="list">
   &lt;items>
    &lt;item
>qualified&lt;/item>
    &lt;item
>unqualified&lt;/item>
   &lt;/items>
   &lt;tooltip
>O formato por omissão para todos os elementos dentro deste esquema.&lt;/tooltip>
   &lt;whatsthis
>O formato por omissão para todos os elementos dentro deste esquema.&lt;/whatsthis>
   &lt;location col="1" row="5"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>blockDefault&lt;/text>
   &lt;location col="0" row="6"/>
  &lt;/label>
  &lt;attr name="blockDefault" type="input">
   &lt;location col="1" row="6"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>finalDefault&lt;/text>
   &lt;location col="0" row="7"/>
  &lt;/label>
  &lt;attr name="finalDefault" type="input">
   &lt;location col="1" row="7"/>
  &lt;/attr>
 &lt;/tag>
&lt;/TAGS>
</markup
>
</literallayout>
</informalexample>
</sect4>

<sect4 id="family-two-3-2">
<title
>Família 2</title>

<para
>O seguinte irá mostrar-lhe um ficheiro TagXML da Família 2 válido. Este ficheiro descreve a função 'overload' do &PHP;. O nome do ficheiro TagXML seria overload.tag. </para>

<informalexample>
<literallayout
><markup>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!DOCTYPE tags>
&lt;tags>
  &lt;tag name="overload" type="function" returnType="void">
&lt;attr name="class_name" type="string" status="optional"/>
  &lt;/tag>
&lt;/tags>
</markup
>
</literallayout>
</informalexample>
</sect4>
</sect3>
</sect2>

<sect2 id="descriptionrc-3-2">
<title
>description.rc</title>

<para
>O ficheiro 'description.rc' é também ele muito simples. Nem todos os itens seguintes serão necessariamente usados. A estrutura básica do ficheiro 'description.rc' é a seguinte. </para>

<sect3 id="family-one-structure-3-2">
<title
>Estrutura da Família 1</title>

<informalexample>
<literallayout
><markup>
[General] - Informação genérica
Version = Use 1 para o &quantaplus; versão &lt;=3.1.2 e 2 para qualquer versão posterior.
Name = Texto de definição do DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
NickName = O nome embelezado do DTD. (HTML 4.01 Transitional). Se não fore definido, o Name é usado como NickName.
&URL; = Um &URL; a apontar para a definição do DTD. (http://www.w3.org/TR/html4/loose.dtd)
DoctypeString = O texto que deveria aparecer na declaração do !DOCTYPE.
(HTML PUBLIC "-//&W3C;//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
Inherits = O nome do DTD do qual este DTD herda as suas marcas. (-//&W3C;//DTD HTML 4.01//EN)
DefaultExtension = Os ficheiros novos são criados com esta extensão. (html)
Groups = A lista dos grupos de atributos comuns, os quais poderão estar presentes em mais do que uma marca.
(Core, I18n, Script) Veja em baixo. (Grupo1, Grupo2...)
NumOfPages = Quantas páginas deve ter uma janela de marca, ao lado da página que contém os atributos definidos no ficheiro de marcas? Veja em baixo. (Pagina1,...)
CaseSensitive = Se o DTD distingue maiúsculas de minúsculas. (true|false)
Family = 1 Este tipo de DTEP é da família 1, dado que é de formatação.

[Toolbars] - Informação sobre as barras de ferramentas do DTEP.
Location = O nome da pasta dentro da $KDEDIR($KDEHOME)/share/apps/quanta/toolbars onde as barras de ferramentas deste DTEP estão.
Names = A lista dos nomes dos ficheiros das barras de ferramentas, retirando a extensão .toolbar.tgz, que são carregados para este DTEP na pasta acima.

[Grupo1] - Substitua por um dos grupos indicados em baixo.
Attributes = A lista com os atributos deste grupo. De momento, todos os atributos listados são tratados como texto.
Exemplo:
[Core]
Attributes = id, class, style, title

[Page1] - A descrição de uma página de edição de marcas.
Title = O título desta página na janela de edição de marcas.
Groups = Uma lista dos grupos que aparecem nesta página. (Core, I18n)

[Extra rules] - Algumas regras que não se encaixam noutros locais.
BooleanAttributes = (simple|complex)
Exemplo para o 'simple': &lt;marca atrBooleano
>.
Exemplo para o 'complex': &lt;marca atrBooleano="1"
> ou &lt;marca atrBooleano="true">
Single Tag Style = (html|XML)
Exemplo para o 'html': &lt;marca_unica>
Exemplo para o XML:  &lt;marca_unica />
StructGroupsCount = O número de grupos de estrutura. Veja em baixo.
MinusAllowedInWords = Se 'true' (verdadeiro), o "isto-e-uma-palavra" é tratado como uma palavra. Caso contrário, é tratado como 4 palavras.
TagAutoCompleteAfter = CARACTER. O campo de auto-completação aparece automaticamente logo que este CARACTER tenha sido introduzido ou o ESPAÇO é carregado a seguir a este CARACTER. Para o DTEP Família 1 é normalmente o "&lt;" O texto "none" em vez de um CARACTER indica que a lista de completação da marca não deverá aparecer automaticamente, mas sim apenas se o utilizador o desejar.
AttributeSeparator = CARACTER. Este CARACTER significa que o nome do atributo terminou. É o " para os DTEPs de XML.
TagSeparator = CARACTER. Semelhante ao anterior.

[StructGrupo_1] - Definição do grupo 1 de estrutura.
Name = O texto que aparece se existirem marcas que correspondam à configuração deste grupo.
No_Name = O texto que aparece se NÃO existirem marcas que correspondam à configuração deste grupo.
Icon = O nome do ícone que aparece antes dos textos descritos acima.
Tag = nomemarca(atributo1, atributo2, ...). As marcas com o nome 'nomemarca' irão aparecer sob este grupo. O texto do item será "valor_atributo1 | valor_atributos2 | ..."
De momento só uma marca poderá ser listada aqui.
HasFileName = (true|false) Verdadeiro, se o texto do item (por cima dos valores dos atributos) contém um nome de ficheiro.
FileNameRx = Uma expressão regular que é usada para remover os caracteres desnecessários para o texto do item.

[Parsing rules] - As regras que são usadas para analisar o documento.
SpecialAreas = O texto de início e de fim das áreas especiais, separado por uma vírgula.
As áreas especiais não são analisadas de acordo com as regras deste DTEP, mas com as suas próprias regras.
Uma área especial poderá ser um DTEP de outra família, um comentário, ou outra coisa com esse efeito.
P.ex. &lt;!-- -->
SpecialAreaNames = Uma lista separada por vírgulas dos nomes das áreas especiais. P.ex., comentário
SpecialTags = nomemarca(nomeatributo) - Indica uma marca que define o início de uma área especial.
MayContain = Uma lista separada por vírgulas de DTEPs de família 2 que poderão estar presentes no documento.
(php, css)
</markup
>
</literallayout>
</informalexample>
</sect3>

<sect3 id="family-two-structure-3-2">
<title
>Estrutura da Família 2</title>

<informalexample>
<literallayout
><markup>
[General] - Informação genérica.
Version = Use 1 para o &quantaplus; versão &lt;=3.1.2 e 2 para qualquer versão posterior.
Name = Um nome próprio
NickName = O que lhe chamam. Se não estiver definido, o Name é usado como NickName.
Inherits = O nome do DTEP do qual este herda marcas. (O Name, não o NickName)
DefaultExtension = Os ficheiros novos são criados com esta extensão. (php)
NumOfPages = 0 Sempre zero, porque não existe uma janela de edição de marcas para os DTEPs de Família 2.
CaseSensitive = Se há distinção de maiúsculas ou minúsculas no DTEP. (true|false)
Family = 2 Este tipo de DTEP é da família 2, dado que não é de formatação.

[Toolbars] - Informação sobre as barras de ferramentas do DTEP.
Location = O nome da pasta dentro da $KDEDIR($KDEHOME)/share/apps/quanta/toolbars onde estão as barras de ferramentas deste DTEP.
Names = A lista dos nomes dos ficheiros das barras de ferramentas, tirando a extensão .toolbar.tgz, que são carregados para este DTEP na pasta acima.

[Extra rules] - Algumas regras que não se encaixam noutros lugares.
BooleanAttributes = (simple|complex)
Exemplo para o 'simple': &lt;marca atrBooleano
>.
Exemplo para o 'complex': &lt;marca atrBooleano="1"
> ou &lt;marca atrBooleano="true">
StructGroupsCount = O número de grupos de estrutura. Ver em baixo.
MinusAllowedInWords = Se verdadeiro, o "isto-e-uma-palavra" é tratado como uma palavra só. Caso contrário, é visto como 4 palavras.
TagAutoCompleteAfter = CARACTER. O campo de auto-completação aparece automaticamente logo que este CARACTER tenha sido introduzido ou o ESPAÇO tenha sido carregado a seguir a este CARACTER. Para os DTEPs família 1, é normalmente o "&lt;". O texto "none" em vez de um CARACTER indica que a lista de completação da marca não deverá aparecer automaticamente, a menos que o utilizador o deseje.
AttributeSeparator = CARACTER. Este CARACTER significa que o nome do atributo terminou. É o " para os DTEPs de XML.
TagSeparator = CARACTER. Semelhante ao anterior.
AttributeAutoCompletionAfter = CARACTER. Semelhante ao TagAutoCompletionAfter, mas para os atributos das marcas. É igual a "(" por omissão e a ":" para o CSS.

[StructGrupo_1] - Definição do grupo de estrutura 1.
Name = O texto que aparece se existirem marcas que correspondam à configuração deste grupo.
No_Name = O texto que aparece se NÃO existirem marcas que correspondam à configuração deste grupo.
Icon = O nome do ícone que aparece antes dos textos descritos acima.
Tag = nomemarca(atributo1, atributo2, ...). As marcas com o nome 'nomemarca' irão aparecer sob este grupo. O texto do item será "valor_atributo1 | valor_atributos2 | ..."
De momento só uma marca poderá ser listada aqui.
HasFileName = (true|false) Verdadeiro, se o texto do item (por cima dos valores dos atributos) contém um nome de ficheiro.
FileNameRx = Uma expressão regular que é usada para remover os caracteres desnecessários para o texto do item.
SearchRx = Uma expressão regular que é usada para procurar as áreas de texto no DTEP da Família 2 que pertencerão a este grupo
ClearRx = Uma expressão regular que é usada para limpar o texto/caracteres indesejado do resultado da pesquisa anterior. O texto limpo irá aparecer na árvore de estrutura.

[Parsing rules] - As regras que são usadas para analisar o documento.
SpecialAreas = O texto de início e de fim das áreas especiais, separado por uma vírgula.
As áreas especiais não são analisadas de acordo com as regras deste DTEP, mas com as suas próprias regras.
Uma área especial poderá ser um DTEP de outra família, um comentário, ou outra coisa com esse efeito.
P.ex. &lt;!-- -->
SpecialAreaNames = Uma lista separada por vírgulas dos nomes das áreas especiais. P.ex., comentário
SpecialTags = nomemarca(nomeatributo) - Indica uma marca que define o início de uma área especial.
MayContain = Uma lista separada por vírgulas de DTEPs de família 2 que poderão estar presentes no documento.
AreaBorders = Uma lista separada por vírgulas dos contornos das áreas que encapsulam este DTEP da Família 2. No caso do PHP, é: &lt;? ?>, &lt;* *
>, &lt;% %>
Tags = nomemarca(atributo). Se o DTD-pai(real) tiver uma marca com o nome 'nomemarca' e o valor do atributo desta marca for igual ao do nome do DTD, a área da marca é analisada de acordo com as regras deste DTD.
Comments = comma separated list of area borders for comments. EOL means end-of-line.
Exemplo: // EOL, /* */
StructKeywords = Uma lista separada por ponto-e-vírgulas de palavras-chave de estruturas. As estruturas são tratadas como novos nós na árvore de estrutura.
StructBeginStr = Um texto que corresponde ao início de uma estrutura (como o {)
StructEndStr = Um texto que indica o fim de uma estrutura (como o })
StructRx = Uma expressão regular que contém o início ou o fim da área da estrutura. Por exemplo, \\{ | \\} (o contorno da área da estrutura pode ser o { ou o })
</markup
>
</literallayout>
</informalexample>
</sect3>
</sect2>
</sect1>

<sect1 id="creating-toolbars-3-2">
<title
>Criação de Barras de Ferramentas</title>

<para
>O seguinte irá mostrar como criar barras de ferramentas para um &DTEP;. As barras de ferramentas são elementos gráficos que se encontram associados a acções. As acções no &quantaplus; são a base para praticamente todas as extensões que o &quanta; tem e que irá adquirir no futuro. O mesmo mecanismo que define uma acção no &quanta; activa a auto-completação e as janelas de 'tags'. Com as acções, o limite do que poderá fazer é virtualmente nulo. Para poder ver um exemplo, iremos usar o <ulink url="http://tidy.sf.net"
>&HTML; tidy</ulink
> nas nossas páginas Web. </para>

<sect2 id="from-scratch-to-complete-3-2">
<title
>Do Zero Até uma Versão Completa</title>

<para
>Para começar, você irá precisar de criar uma barra de ferramentas do utilizador. Seleccione a opção <menuchoice
> <guimenu
>Barras de Ferramentas</guimenu
> <guimenuitem
>Adicionar uma Barra de Ferramentas do Utilizador</guimenuitem
> </menuchoice
>. </para>

<para
>Se existirem várias marcas para a linguagem de formatação, recomenda-se que você divida as marcas em grupos lógicos. Irá precisar de criar uma nova barra de ferramentas do utilizador para cada grupo. Neste caso, não existem muitas, por isso vamos criar apenas uma barra de ferramentas e dar-lhe o nome da formatação. </para>

<para
>Logo que todas as suas barras de ferramentas forem criadas, você precisa adicionar e configurar as acções. Para o fazer, seleccione <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar as Acções</guimenuitem
> </menuchoice
> <emphasis
> </emphasis
>. </para>

<para
>As componentes desta janela são relativamente intuitivas. Carregue no botão <guibutton
>Nova acção</guibutton
> no fundo da janela para entrar no modo de edição. </para>

<para
>Preencha todos os campos necessários e adicione a marca à(s) barra(s) de ferramentas apropriada(s). </para>

<para
>Complete o resto e, se a marca tiver atributos e planeia usá-los sempre, assinale a opção <guilabel
>Correr a janela "Editar a marca" se disponível </guilabel
> de modo a que não tenha de ser avisado de cada vez que a acção é usada. </para>

<para
>Agora você deverá ter algo muito semelhante ao seguinte. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img7.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Carregue no botão <guibutton
>Aplicar</guibutton
> para ver a acção adicionada à barra ou barras de ferramentas que seleccionou. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img8.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Ui! Este é um ícone horrível. Como é que você próprio e os outros irão recordar que aquele ícone corresponde a aquela acção? Vamos substitui-lo antes que haja problemas. </para>

<para
>Para criar um ícone que descreva de forma mais adequada essa acção, nós iremos usar o &kiconedit;. Seleccione-o no &kmenu;, <menuchoice
> <guisubmenu
>Gráficos</guisubmenu
> <guisubmenu
>Mais Programas</guisubmenu
> </menuchoice
> (ou onde quer qe a sua distribuição o tenha posto). </para>

<para
>O &kiconedit; usa por omissão o tamanho de 32x32 pixels, mas nós precisamos do tamanho 22x22. Para o alterar, seleccione <menuchoice
> <guimenu
>Editar</guimenu
> <guimenuitem
>Redimensionar</guimenuitem
> </menuchoice
>. </para>

<para
>Lembre-se que você está a criar um ícone que o irá ajudar não só a si a lembrar o objectivo daquela acção, mas também aos outros utilizadores do &DTEP;. </para>

<para
>Dado que a marca para a qual estou a criar o ícone se chama <quote
>iniciar,</quote
> decidi criar um ícone de <quote
>sinal de Iniciar.</quote
> Ao usar a cor verde (o verde é normalmente interpretado como <quote
>seguir,</quote
> <quote
>iniciar,</quote
> ou <quote
>prosseguir</quote
>) irá, ou pelo menos é suposto, fornecer ao utilizador uma mensagem de que, se carregar nesta acção, irá colocar a marca de &lt;inicio&gt; no documento actual. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img15.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Agora que terminei a criação do ícone, vou então gravá-lo. </para>

<para
>Logo que tenha acabado de criar o ícone ou ícones, você precisa associar o ícone à acção. Para o fazer, abra a <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar as Acções</guimenuitem
> </menuchoice
> de novo (no &quantaplus;) e seleccione a acção para a qual criou o ícone. Para além do campo de <guilabel
>Texto</guilabel
>, você irá ver um botão; neste momento, carregue no mesmo. </para>

<para
>Seleccione <guilabel
>Outros Ícones</guilabel
> e carregue então no botão <guibutton
>Escolher</guibutton
>. </para>

<para
>Vá para a pasta na qual gravou o ícone, seleccione o mesmo e carregue em <guibutton
>OK</guibutton
>. </para>

<para
>Carregue no botão <guibutton
>Aplicar</guibutton
> e poderá então continuar a fazer o mesmo com as outras marcas, se existirem, ou poderá então carregar em <guibutton
>OK</guibutton
> para terminar. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img18.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Digamos que você desejaria adicionar mais algumas funções comuns do &quantaplus; à sua barra de ferramentas ou então acharia que a barra de ferramentas ficaria melhor se ficasse arrumada com alguns separadores para agrupar as acções. Abra a janela de <guilabel
>Configurar as Barras de Ferramentas</guilabel
> indo à opção <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar as Barras de Ferramentas</guimenuitem
> </menuchoice
>. Certifique-se que a sua barra de ferramentas está seleccionada. </para>

<para
>Irei então escolher o separador (em cima na coluna da esquerda) para a minha barra de ferramentas. Logo que você tenha seleccionado o item que deseja adicionar à sua barra de ferramentas, carregue no botão com a seta para a direita. Isto irá adicioná-lo à sua barra de ferramentas. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img21.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Penso que gostaria de uma forma mais rápida de aceder à <guilabel
>Antevisão no  Konqueror</guilabel
>. Irei então seleccioná-la e adicioná-la à barra de ferramentas. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img22.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Repare como o separador ajuda a agrupar. Alguém que não conhecesse bem a minha barra de ferramentas poderia ter pensado que o botão do &konqueror; seria semelhante ou o oposto do botão de início. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img23.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Aplique as suas alterações e, quando tiver terminado, carregue em <guibutton
>OK</guibutton
> para terminar. </para>

<para
>Ah, veja a nova e fantástica barra de ferramentas! Muito mais útil agora. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img24.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Lembre-se de testar a sua barra de ferramentas, carregando em todos os botões, de modo a que saiba que o resultado é o correcto. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img25.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Agora, para gravar a barra de ferramentas, iremos seleccionar a opção <menuchoice
> <guimenu
>Barras de Ferramentas</guimenu
> <guisubmenu
>Gravar as Barras de Ferramentas</guisubmenu
> <guimenuitem
>Gravar como Barra de Ferramentas Local</guimenuitem
> </menuchoice
>. </para>

<para
>Grave-a na pasta correcta. Dado que a NeXML não existe, irei tê-la apenas na pasta de topo, mas as suas barras de ferramentas deverão ser gravadas na pasta correcta. Certifique-se que ajusta o seu 'description.rc' para que este carregue as mesmas barras de cada vez que um ficheiro desse tipo é criado. </para>
</sect2>
</sect1>


<sect1 id="creating-quanta-docs-3-2">
<sect1info>
<title
>Criar os Seus Próprios Documentos</title>
<authorgroup>
<author
><firstname
>Robert</firstname
> <surname
>Nickel</surname
> <affiliation
> <address
><email
>robert@artnickel.com</email
></address>
</affiliation>
</author>

<othercredit role="translator"
><firstname
>Pedro</firstname
><surname
>Morais</surname
><affiliation
><address
><email
>morais@kde.org</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 

</authorgroup>
</sect1info>

<title
>Criar os Seus Próprios Documentos</title>

<para
>Provavelmente as adições mais notáveis ao &quantaplus; para o utilizador geral serão a inclusão de documentação para a linguagem de formatação ou de 'scripting' que gostar mais. Para tal, este capítulo irá explicar como é que eu crio a árvore de documentação de &PHP; para o meu uso pessoal. </para>

<para
>Antes de começar a criar a sua própria documentação, poderá querer ver o <ulink url="http://quanta.sf.net/main1.php?contfile=resource"
>repositório do &quantaplus;</ulink
> para ver se alguém já a criou. </para>

<para
>Existem duas partes neste processo. Primeiro, deverá obter a documentação existente para a linguagem em questão que está à procura. Em segundo lugar, terá de criar o ficheiro <filename
>docrc</filename
>. O primeiro é segundo o seu critério, enquanto o último passo será debatido aqui. </para>

<para
>O formato geral do 'docrc' é o seguinte: </para>

<informalexample>
<literallayout
>#Ficheiro de Configuração do KDE
[Tree]
Doc dir=&lt;directoria relativa a este ficheiro onde estão os ficheiros de HTML da documentação&gt; p.ex. php42/
#elementos do nível de topo
Top Element=&lt;A sua descrição destes documentos
> p.ex. documentação do PHP 4.2

Secção 1=Secção1.html
Secção 2=#Sec2.1,#Sec2.2,#Sec2.3
Sec2.1=Sec2.1.html
Sec2.2=Sec2.2.html
Sec2.3=Sec2.3.html
...

[Context]
ContextList=func1,func2,tag1,tag2,tag3
func1=func1.html
func2=func2.html
tag1=tag1.html
tag2=tag2.html
tag3=tag3.html
</literallayout>
</informalexample>

<para
>O <filename
>docrc</filename
> está repartido em duas secções: Tree (árvore) e Context (contexto). </para>

<para
>A secção Tree define o aspecto da apresentação da documentação na página respectiva. Por exemplo, poderá ver na documentação de &PHP; que tem algo do género do seguinte: </para>

<mediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Relacionando isto com o descrito em cima, o meu ficheiro <filename
>docrc</filename
> de &PHP; fica semelhante ao seguinte: </para>

<informalexample>
<literallayout
>#Ficheiro de Configuração do KDE

[Tree]

Doc dir=php42/

#elementos do nível de topo
Top Element=Documentação do PHP 4.2

documentação do PHP 4.2=Índice,#Introdução,#Referência da Linguagem

Índice=index.html

Introdução=Introduction, ...
Apresentação=introduction.html
...

Referência da Linguagem=Sintaxe básica, ...
Sintaxe básica=linguagem.sintaxe-basica.html
...

</literallayout>
</informalexample>

<para
> Repare no <literal
>#</literal
> antes da <quote
>Introdução</quote
> e <quote
>Referência da Linguagem</quote
>. Isto indica que estes são sub-títulos na árvore e que tem conteúdo próprio. Não creio que haja um limite para a profundidade do conjunto (excepto a que é definida pela sanidade) - use segundo o seu critério. </para>

<para
>Para o Índice, irá reparar que este referencia directamente um ficheiro (e, como consequência, irá aparecer no fundo da árvore &mdash; com as pastas primeiro!). </para>

<important>
<para
>Os espaços não afectam de facto em nada, mas tenha em atenção os caracteres &amp; e &lt;. Estes deverão ser substituídos provavelmente por &amp;amp; e por &amp;lt;, respectivamente, em todos os ficheiros de recursos de &XML; do &quantaplus;. </para>
</important>

<para
>A secção Context é a secção do ficheiro 'docrc' que é usada para facilitar a ajuda dependente do contexto. Por exemplo, você está a fazer um programa em &PHP; e deseja ver a documentação para a função <function
>mysql_fetch_array</function
>. Basta você seleccionar a função e carregar então em <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
> para obter a ajuda de contexto. A documentação do <function
>mysql_fetch_array</function
> irá aparecer imediatamente. Existem apenas dois tipos de itens aqui: o ContextList e as linhas de associações de ficheiros. </para>

<variablelist>
<varlistentry>
<term
>ContextList</term>
<listitem>
<para
>Muito simplesmente, isto é apenas uma lista separada por vírgulas dos itens de contexto que você deseja ter disponíveis (para o &PHP;, estas serão as funções de &PHP;). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Linhas de associação de ficheiros</term>
<listitem>
<para
>Estas estão no formato de item de contexto=página HTML de documentação, &eg; acos=funcao.acos.html </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Uma versão muito resumida da minha secção Context do <filename
>docrc</filename
> encontra-se a seguir: </para>

<informalexample>
<literallayout
>#Palavras-chave para a ajuda de contexto
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...

abs=funcao.abs.html
acos=funcao.acos.html
acosh=funcao.acosh.html
addcslashes=funcao.addcslashes.html
addslashes=funcao.addslashes.html
...
</literallayout>
</informalexample>

<para
>Agora poderá gravar o seu ficheiro <filename
>docrc</filename
>, colocá-lo na pasta <filename class="directory"
> $<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
> ou em <filename class="directory"
> $<envar
>KDEDIR</envar
>/share/apps/quatna/doc</filename
> para o uso local ou global, respectivamente. Crie então uma pasta (a especificada no seu ficheiro 'docrc') na mesma pasta que no seu ficheiro 'docrc' e copie as suas páginas de documentação em HTML para lá. </para>

<para
>Terá de reiniciar o &quantaplus; para poder então ver a sua documentação. </para>

<para
>Logo que tenha a certeza que eles ficaram bem e que vale a pena serem partilhados, envie o ficheiro <filename
>docrc</filename
> em conjunto com uma descrição com todas as informações pertinentes da documentação que usou no <ulink url="http://quanta.sf.net/main1.php?contfile=resource"
>repositório do &quantaplus;</ulink
> para ser usado pela comunidade do &quanta;. Não irá ficar rico, mas ficará satisfeito de certeza em saber que contribuiu para a melhor plataforma de programação Web existente. </para>

</sect1>
</chapter>
