path: root/tde-i18n-pt_BR/docs/tdewebdev/quanta/extending-quanta.docbook

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

<chapter id="extending-quanta-3-2">
<chapterinfo>
<title>Extendendo o &quantaplus;</title>
<authorgroup>
<author><firstname>Christopher</firstname> <surname>Hornbaker</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>
<author><firstname>Andr&#225;s</firstname> <surname>Mantia</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>

<othercredit role="translator"><firstname>Marcus</firstname><surname>Gama</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Tradução</contrib></othercredit> 

</authorgroup>
</chapterinfo>

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

<para>Este capítulo descreve como personalizar o &quantaplus; para suas necessidades particulares e como você pode ajudar o &quantaplus; a ficar ainda 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 de Tipo de Documento (&DTEP;)</title>

<para>Os Pacotes de Edição de Tipo de Documento (&DTEP;) são usados no &quantaplus; para adicionar suporte para marcação, linguagens de scripting e &CSS;. Eles permitem que o &quantaplus; forneça recursos de auto-complementação e nós de árvores. Sua simplicidade e flexibilidade são o que faz o &quantaplus; uma &IDE; rápida e amigável para desenvolvedores web. Eles são o que torna o &quantaplus; um ambiente produtivo e fácil de usar. </para>

<para>Os &DTEP;s vem em dois sabores: Família 1, que são para marcação, e Família 2 que são para scripting e &CSS;. Os &DTEP; são feitos de duas partes: a Pasta Marcas e as Barras de Ferramentas. Pastas de Marcas são compostas de dois tipos de arquivos: o &descriptionrc; e os arquivos TagXML, que carregam a extensão .tag. Barras de ferramentas são abas de botões orientadas à ícones e acessíveis (acima da janela de edição) que colocam texto em um documento mais rápido do que o usuário pode digitar. </para>

<para>Os &DTEP;s podem ser criados manualmente (veja abaixo), <link linkend="download-resources">obtidos da Internet</link> ou criados automaticamente a partir de uma DTD existente. Veja em <xref linkend="converting-dtd"/> os detalhes da conversão. </para>

<para>Este documento descreve como criar arquivos TagXML, o &descriptionrc; e as barras de ferramentas. Em resumo, um &DTEP;. </para>

<para>Arquivos TagXML (.tag) definem tanto os atributos específicos de uma marca como a disposição e conteúdo do diálogo de propriedades que o &quantaplus; mostra para a marca. O arquivo &descriptionrc; fornece regras e informações sobre o &DTEP; propriamente dito. Barras de ferramentas fornecem uma maneira rápida de adicionar marcas ao documento sem se preocupar com erros tais como de sintaxe. </para>

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

<para>Pastas de Marcas são somente isto: pastas. Elas são compostas somente do &descriptionrc; e arquivos TagXML. Pastas de Marcas carregam o nome da linguagem de marcação e versão, se aplicável. (Por exemplo, html-4.01-strict) </para>
</sect2>

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

<para>A tabela abaixo lista os elementos definidos na TagXML e declara se eles são necessários ou não. Apesar de nem todos serem necessários, é recomendável que você use o máximo que puder de modo que outros usuários possam ter uma experiência melhor e mais informações sobre como trabalhar com eles. </para>

<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Elemento</entry>
<entry>Uso Padrão</entry>
<entry>Uso da Caixa</entry>
</row>
</thead>
<tbody>
<row>
<entry>MARCAS</entry>
<entry>necessário</entry>
<entry>sempre</entry>
</row>
<row>
<entry>marca</entry>
<entry>necessário</entry>
<entry>sempre</entry>
</row>
<row>
<entry>label</entry>
<entry>opcional</entry>
<entry>necessário para criar um diálogo 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 o diálogo de propriedades exiba uma dica</entry>
</row>
<row>
<entry>whatsthis</entry>
<entry>opcional</entry>
<entry>necessário que que o diálogo de propriedades exiba um <quote>O que é Isto</quote></entry>
</row>
<row>
<entry>list</entry>
<entry>opcional</entry>
<entry>necessário que um atributo é do tipo <quote>lista</quote></entry>
</row>
<row>
<entry>item</entry>
<entry>opcional</entry>
<entry>necessário que &lt;lista> é 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 um rótulo é usado</entry>
</row>
<row>
<entry>text</entry>
<entry>opcional</entry>
<entry>necessário quando um rótulo é usado</entry>
</row>
<row>
<entry>children</entry>
<entry>opcional</entry>
<entry>lista de marcas que podem aparecer dentro de uma marca sendo definida</entry>
</row>
<row>
<entry>child</entry>
<entry>necessário</entry>
<entry>uma entrada filha</entry>
</row>
<row>
<entry>stoppingtags</entry>
<entry>opcional</entry>
<entry>lista de marcas que envia outra marca para o fim</entry>
</row>
<row>
<entry>stoppingtag</entry>
<entry>necessário</entry>
<entry>uma entrada stoppingtags</entry>
</row>
</tbody>
</tgroup>
</informaltable>


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

<para>As seções a seguir descreverão, em detalhes, cada elemento. Tudo sobre onde eles podem ir, o que eles fazem lá, e apresentados de uma maneira fácil de seguir. </para>

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

<para>Este é o elemento raiz de um documento TagXML. Ele deve aparecer em um documento somente uma vez. Ele pode conter a definição de múltiplas marcas. Isto é um elemento tipo elemento-somente. </para>

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

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

<para>Envoltório para marca que está sendo definida. Este é um elemento tipo elemento-somente. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</entry>
</row>
</thead>
<tbody>
<row>
<entry>MARCAS</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>Padrão</entry><entry>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>nome</entry><entry>string</entry><entry></entry><entry></entry>
<entry>necessário</entry><entry>Especifica o nome da marca que está sendo definida.</entry>
</row>
<row>
<entry>simples</entry><entry>booleano</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Especifica se a marca precisa ou não de um fechamento de marca &lt;/(nomemarca)>.</entry>
</row>
<row>
<entry>type</entry><entry>string</entry><entry></entry><entry>xmltag</entry>
<entry>opcional</entry><entry>Especifica o tipo da marca que está sendo definida.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>xmltag</entry><entry></entry>
<entry></entry><entry>Tipo de marca é baseado-XML. (Família 1 somente.)</entry>
</row>
<row>
  <entry></entry><entry></entry><entry>entity</entry><entry></entry>
  <entry></entry><entry>A marca descreve uma entidade. (Família 1 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>property</entry><entry></entry>
<entry></entry><entry>Tipo da marca é relacionado ao &CSS;. (Família 2 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>function</entry><entry></entry>
<entry></entry><entry>Tipo da marca é uma função de script. Quando usado &lt;attr> se torna argumentos da função. (Família 2 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>class</entry><entry></entry>
<entry></entry><entry>Tipo da marca é uma classe de script. (Família 2 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>method</entry><entry></entry>
<entry></entry><entry>Type of tag is a class method. (Family 2 only.)</entry>
</row>
<row>
<entry>returnType</entry><entry>string</entry><entry></entry><entry>void </entry>
<entry>opcional</entry><entry>Especifica o tipo de retorno da marca que está sendo definida. (Família 2 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>void</entry><entry></entry>
<entry></entry><entry>Tipo da marca retorna void.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>int</entry><entry></entry>
<entry></entry><entry>Tipo da marca retorna inteiro.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>float</entry><entry></entry>
<entry></entry><entry>Tipo da marca retorna flutuante.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>long</entry><entry></entry>
<entry></entry><entry>Tipo da marca retorna longo.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>string</entry><entry></entry>
<entry></entry><entry>Tipo da marca retorna string.</entry>
</row>
<row>
  <entry>version</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Indica a versão da linguagem para a qual esta marca é válida</entry>
</row>
<row>
  <entry>extends</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Valid only if the type of the tag is "class". The name of the base class for this class. (Family 2 only.)</entry>
</row>
<row>
  <entry>class</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Valid only if the type is "method". Specifies the name of the class to where this method belongs. (Family 2 only.)</entry>
</row>
<row>
  <entry>common</entry><entry>booleano</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Se for igual a "yes", a marca corresponde a um grupo de atributos comum e os atributos desta marca poderão ser anexados a qualquer outra marca. (Apenas na Família 1.)</entry>
</row>
<row>
  <entry>comment</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>o texto do comentário aparece perto do nome da marca na lista de completação</entry>
</row></tbody>
</tgroup>
</informaltable>
</sect4>

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

<para>Coloca um rótulo no diálogo. O texto especificado pela marca &lt;texto>. Este é um elemento tipo elemento-somente. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</entry>
</row>
</thead>
<tbody>
<row>
<entry>marca</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. Ele define o nome e tipo do atributo. Ele contém também marcas adicionais que especificam como este atributo deve ser exibido, etc. Este é um elemento tipo elemento-somente. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</entry>
</row>
</thead>
<tbody>
<row>
<entry>marca</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>Padrão</entry><entry>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>nome</entry><entry>string</entry><entry></entry><entry></entry>
<entry>necessário</entry><entry>Especifica o nome do atributo que está sendo definido.</entry>
</row>
<row>
<entry>type</entry><entry>string</entry><entry></entry><entry>input</entry>
<entry>necessário</entry><entry>Especifica o tipo de atributo que está sendo definido.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>input</entry><entry></entry>
<entry></entry><entry>Campo suporta entradas de texto livre (campo texto).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>check</entry><entry></entry>
<entry></entry><entry>O valor do campo é booleano (caixa de verificaçã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 é uma &URL;. (Arquivo local para referir-se.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>list</entry><entry></entry>
<entry></entry><entry>O valor do campo é um ítem de uma lista especificada.</entry>
</row>
<row>
<entry>status</entry><entry>string</entry><entry></entry><entry>opcional</entry>
<entry>necessário</entry><entry>Especifica se o argumento é ou não obrigatório. (Família 2 somente.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>opcional</entry><entry></entry>
<entry></entry><entry>Argumento é opcional.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>necessário</entry><entry></entry>
<entry></entry><entry>Argumento é obrigatório.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>implied</entry><entry></entry>
<entry></entry><entry>Argumento é implicado.</entry>
</row>
<row>
  <entry>source</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Indica as origens usadas para preencher o item do atributo no diálogo de edição da marca e na árvore de atributos</entry>
</row>
<row>
  <entry></entry><entry></entry><entry>selection</entry><entry></entry>
  <entry></entry><entry>O texto seleccionado será usado como origem</entry>
</row>
<row>
  <entry></entry><entry></entry><entry>dcop</entry><entry></entry>
  <entry></entry><entry>Será usado o resultado de um método de DCOP como origem</entry>
</row>
<row>
  <entry>interface</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Necessita do 'source="dcop"'. A interface de DCOP a partir da qual o &quantaplus; irá buscar os dados de origem.</entry>
</row>
<row>
  <entry>method</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Necessita do 'source="dcop"' e do nome de uma interface. O nome do método de DCOP a partir do qual o &quantaplus; irá buscar os dados de origem.</entry>
</row>
<row>
  <entry>arguments</entry><entry>string</entry><entry></entry><entry></entry>
  <entry>opcional</entry><entry>Necessita do 'source="dcop"', de uma interface e de um nome de um método. Os argumentos que são passados ao método. Poderá estar em branco ou aceitar o "%tagname%", que corresponde ao nome atual da marca.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

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

<para>Define a dica para o campo no diálogo. Este elemento é somente-texto. </para>

<note>
<para>Atualmente somente texto plano é suportado (você não pode usar qualquer marcação). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</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 é Isso' para um campo no diálogo. Este elemento é somente-texto. </para>

<note>
<para>Atualmente somente texto plano é suportado (você não pode usar qualquer marcação). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</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 de contenção que agrupa juntos os ítens em uma lista. Isto pode aparecer somente uma vez para cada descrição de atributo. Este é um elemento tipo somente-elemento. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</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 ítem em uma lista. Este elemento é somente-texto. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</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>Especifica a posição de um texto de atributo da marca dentro de um diálogo. Esta marca somente pode ocorrer uma vez para cada atibuto no diálogo (&ie; uma para cada marca &lt;attr>). Este elemento é vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filho</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>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>row</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Especifica a linha na disposição do diálogo de um campo ou rótulo.</entry>
</row>
<row>
<entry>col</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Especifica a coluna na disposição do diálogo de um campo ou rótulo.</entry>
</row>
<row>
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Especifica o número de linhas que um campo deve se extender.</entry>
</row>
<row>
<entry>colspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Especifica o número de colunas que um campo deve se extender.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

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

<para>Especifica a posição e tamanho do campo no diálogo. Esta marca somente pode ocorrer uma vez para cada campo no diálogo (&ie; uma para cada marca &lt;attr> e &lt;label>). Este elemento é vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filho</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>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>row</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Especifica a linha na disposição do diálogo de um campo ou rótulo.</entry>
</row>
<row>
<entry>col</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Especifica a coluna na disposição do diálogo de um campo ou rótulo.</entry>
</row>
<row>
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Especifica o número de linhas que um campo deve se extender.</entry>
</row>
<row>
<entry>colspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Especifica o número de colunas que um campo deve se extender.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

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

<para>Define o texto para um rótulo ou caixa de verificação. Este elemento é somente-texto. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filho</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 de elementos que podem aparecer dentro da marca que está sendo especificada. Este elemento é um elemento tipo elemento-somente. </para>

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

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

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

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filho</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>Valores</entry>
<entry>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>nome</entry><entry>string</entry><entry></entry>
<entry>necessário</entry><entry>Especifica uma marca que pode aparecer dentro de uma determinada marca.</entry>
</row>
<row>
<entry>usage</entry><entry>string</entry><entry></entry>
<entry>opcional</entry><entry>Specifies the relation with the parent.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>necessário</entry>
<entry></entry><entry>The parent must have at least one child with this name.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

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

<para>Define uma lista de elemento que forçam o fim da marca. Este elemento é um elemento tipo elemento-somente. </para>

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

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

<para>Define uma marca de parada. Este elemento é vazio. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filho</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>Uso</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>nome</entry><entry>string</entry>
<entry>necessário</entry><entry>Especifica que marcas forçam o fim de outra marca.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
</sect3>

<sect3 id="tagxml-usage-3-2">
<title>Uso do TagXML</title>

<para>Todos os arquivos TagXML devem iniciar com a declaração &XML;: &lt;?xml version="1.0" encoding="UTF-8"?> e devem estar corretamente aninhado e fechado. </para>

<important>
<para>Espaços não afetam nada, mas observe os caracteres &amp; e &lt;. Eles devem ser substituídos por &amp;amp; e &amp;lt; respectivamente em elementos como &lt;tooltip>, &lt;whatsthis>, e &lt;text>. Não fazer isto não causará travamentos, mas você terá pedaços do seu trabalho desaparecendo neste caso. </para>
</important>
</sect3>

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

<para>Para validar seus arquivos TagXML, simplesmente clique no menu <quote>Ferramentas</quote> do &quantaplus; e selecione <quote>Validar TagXML</quote>. Um diálogo será apresentado e você precisará somente seguir as orientações fornecidas. </para>

<note>
<para>Este recurso atualmente não está presente. Atualmente a validação ocorre quando os arquivos 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 exemplo a seguir mostrará um arquivo TagXML da Família 1 válido. Este arquivo procura descrever o elemento &lt;schema> do Esquema do &W3C; &XML;. O nome do arquivo para este arquivo TagXML será 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>Versão do esquema.&lt;/tooltip>
   &lt;whatsthis>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>Referência de &URI; do espaço de nomes para este esquema.&lt;/tooltip>
   &lt;whatsthis>Referência de &URI; do espaço de nomes para este 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>Referência de &URI; do espaço de nomes para uso neste esquema.
   Se nenhum prefixo é usado, então componentes deste espaço de nomes podem ser usados sem qualificação.&lt;/tooltip>
   &lt;whatsthis>Referência de &URI; do espaço de nomes para uso neste esquema.
   Se nenhum prefixo é usado, então componentes deste espaço de nomes podem ser usados sem qualificação.&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>Forma padrão para todos os atributos dentro deste esquema.&lt;/tooltip>
   &lt;whatsthis>Forma padrã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>Forma padrão para todos os atributos dentro deste esquema.&lt;/tooltip>
   &lt;whatsthis>Forma padrão para todos os atributos 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 exemplo a seguir mostrará um arquivo TagXML da Família 2 válido. Este arquivo procura descrever a função de sobrecarga do &PHP;. O nome do arquivo para este arquivo TagXML será 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>&descriptionrc;</title>

<para>O arquivo &descriptionrc; também é bastante simples e existe um editor para ele, acessível através da opção <menuchoice><guimenu>DTD</guimenu><guimenuitem>Editar a Configuração da DTD</guimenuitem></menuchoice>. Isto irá editar o &descriptionrc; de um &DTEP; que você poderá selecionar numa lista. Para editar o &descriptionrc; para um &DTEP; acabado de criar, você deverá criar um único &descriptionrc; com os seguintes itens: </para>
<para>
  <informalexample>
    <literallayout><markup>
        [General]
        Version = Use 1 para o &quantaplus; versão &lt;=3.1.2 e 2 para as versões posteriores.
        Name = Texto de definição da DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
        NickName = O nome bonito da DTD. (HTML 4.01 Transitional). Se não estiver definido, o Name é usado como NickName.
      </markup>
    </literallayout>
  </informalexample>
</para>
<para>Logo que o tenha criado e colocado junto com os arquivos de marcas, carregue o &DTEP; acabado de criar com a opção <menuchoice><guimenu>DTD</guimenu><guimenuitem>Carregar o Pacote de DTD (DTEP)</guimenuitem></menuchoice> e, depois de carregado, você poderá prosseguir com a edição da configuração do &DTEP;. Verifique as dicas e o texto 'o que é isto' no diálogo do editor para compreender o significado de cada item. Em alternativa, você poderá ler o arquivo <filename>quanta/data/dtep/dtd-description.txt</filename> do pacote de código, que contém uma descrição do formato. </para>
</sect2>
</sect1>

<sect1 id="user-actions">
<title>Ações Definidas pelo Usuário</title>
<para>Ações são muito comuns em qualquer aplicativo. Você irá valorizá-las ao usar qualquer aplicativo. Clicar em um ícone na barra de ferramentas, selecionar um item de menu ou usar um atalho de teclado normalmente executa uma ação. No &quantaplus; ações atingiram um próximo nível. Ao invés de ações de codificação difícil (que são criadas pelo programador do aplicativo a nível de código fonte) é possível para o usuário comum criar e modificar ações e deste modo adicionar novas funcionalidades ao &quantaplus;. Estas são as ações definidas pelo usuário, e muitas das ações padrão do &quantaplus; são definidas (e modificadas) pelo usuário também. </para>
<para>Existem três tipos de ações definíveis pelo usuário: <itemizedlist>
<listitem><para><link linkend="text-actions">Ações de texto</link></para></listitem>
<listitem><para><link linkend="tag-actions">Ações de marca</link></para></listitem>
<listitem><para><link linkend="script-actions">Ações de script</link></para></listitem>
</itemizedlist>
</para>
<sect2 id="creating-actions">
<title>Criando ações</title>
<para>Você pode criar uma ação indo para <menuchoice> <guimenu>Configurações</guimenu> <guimenuitem>Configurar Ações</guimenuitem> </menuchoice>. Clique em <guibutton>Nova Ação</guibutton> e você obterá um diálogo semelhante a isto: <mediaobject> <imageobject>
<imagedata fileref="dtep_doc_img7.png" format="PNG"/>
</imageobject>
</mediaobject>
<variablelist>
<varlistentry>
<term><guilabel>Tipo</guilabel></term>
<listitem><para>Especifica o tipo da ação (<link linkend="text-actions">Texto</link>, <link linkend="tag-actions">Marca</link>, <link linkend="script-actions">Script</link>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Texto</guilabel></term>
<listitem><para>O nome visível ao usuário da ação.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>O botão próximo ao rótulo <guilabel>Texto</guilabel></term>
<listitem><para>O ícone atribuído a esta ação. Clique nele para mudar o ícone atual.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dica da ferramenta</guilabel></term>
<listitem><para>Uma descrição curta do que a ação faz.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Atalho</guilabel></term>
<listitem><para>Um atalho atribuído a esta ação. Clique em <guilabel>Personalizado</guilabel> ou no botão próximo ao <guilabel>Personalizado</guilabel> para atribuir um atalho; clique em <guilabel>Nenhum</guilabel> para remover o atalho atualmente atribuído.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Barras de ferramentas recipiente</guilabel></term>
<listitem><para>A barra de ferramentas definida pelo usuário onde esta ação aparece. Veja <xref linkend="creating-toolbars-3-2"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Configurações Detalhadas</guilabel></term>
<listitem><para>Especifica configurações para os diferentes tipos de ação. Veja abaixo. </para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="text-actions">
<title>Ações de texto</title>
<para>
<mediaobject><imageobject>
<imagedata fileref="text-action.png" format="PNG"/>
</imageobject></mediaobject> As ações mais simples. Você pode inserir algum texto na área de <guilabel>Configurações Detalhadas</guilabel> e sempre que a ação é executada este texto será inserido em seu documento na posição atual do cursor. Veja o exemplo abaixo. </para>
</sect2>
<sect2 id="tag-actions">
<title>Ações de marca</title>
<para>Útil para inserir marcas XML, mas é claro você pode usá-las para outras finalidades também. <mediaobject><imageobject> <imagedata fileref="tag-actions.png" format="PNG"/> </imageobject></mediaobject> <variablelist> <varlistentry> <term><guilabel>&lt;marca&gt;</guilabel></term> <listitem><para>O nome da marca.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>&lt;/marca&gt;</guilabel></term> <listitem><para>Se habilitado quando a ação é executada este texto será inserido como uma marca fechada. Se existir uma área selecionada no documento antes de você executar a ação, o &lt;marca&gt; será inserido antes da área selecionada e o &lt;/marca&gt; após.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Executar diálogo "Editar marca" se disponível</guilabel></term> <listitem><para>Se habilitado e existir um arquivo tagXML para esta marca, um diálogo de definição de marca será mostrado antes de inserir a marca dentro do documento, de modo que você possa ajustar os atributos da marca.</para></listitem> </varlistentry> </variablelist> O &lt;marca&gt; e &lt;/marca&gt; serão inseridos como você digitá-los aqui. O &lt;, &gt; ou o sinal / não serão automaticamente adicionados. </para>
</sect2>
<sect2 id="script-actions">
<title>Ações de script</title>
<para>
<mediaobject><imageobject>
<imagedata fileref="script-action.png" format="PNG"/>
</imageobject></mediaobject> O mais poderoso tipo de ação. Com a ajuda desta ação você poderá executar aplicativos externos (normalmente scripts, mas isto não é limitado somente aos scripts), que podem alterar seu documento ou usar seu documento (ou parte dele) como entrada. Exemplos do próprio &quantaplus; são o diálogo <guibutton>Início Rápido</guibutton>, as várias ações <guilabel>Ver Em...</guilabel> para os DTEPs do (X)HTML. </para>
<para>Primeiro você deve inserir o nome do seu script com o interpretador que deverá ser usado com ele. Exemplo <command>sh /home/minhaCasa/meuScript.sh</command>. </para>
<para>Apesar de você poder usar caminhos completos, a maneira recomendada é usar a variável <command>%scriptdir</command> na linha de comando, como <command>sh %scriptdir/meuScript.sh</command>. Deste modo o &quantaplus; tentará localizar seu script nos seguintes locais: <itemizedlist> <listitem><para>pasta de script global: <filename><envar>$TDEDIR</envar>/share/apps/quanta/scripts</filename></para></listitem> <listitem><para>pasta de script local: <filename><envar>$TDEHOME</envar>/share/apps/quanta/scripts</filename></para></listitem> <listitem><para>seu caminho: <envar>$PATH</envar></para></listitem> </itemizedlist> Existem outras variáveis especiais que você pode usar na linha de comando: <itemizedlist>
<listitem><para><command>%f</command>: será substituída com a URL do documento atual. No caso de documentos locais, file:/ será retirado do documento.</para></listitem>
<listitem><para><command>%input</command>: será substituído com a entrada selecionada. Veja abaixo.</para></listitem>
<listitem><para><command>%projectbase</command>: será substituída com a URL do projeto atual. Isto é vazio se nenhum projeto está carregado.</para></listitem>
<listitem><para><command>%pid</command>: será substituída com o PID do processo do &quantaplus; em execução. Se o &quantaplus; estiver rodando em modo único, o texto "unique" prefixará o número PID. Útil ao usar o DCOP para controlar o &quantaplus; a partir de um script externo.</para></listitem>
<listitem><para><command>%userarguments</command>: útil no caso de eventos. Esta entrada será substituída pela propriedade do evento na seguinte ordem: <variablelist>
<varlistentry>
<term>Primeiro argumento</term>
<listitem><para>O identificador único do 'script'</para></listitem>
</varlistentry>
<varlistentry>
<term>Segundo argumento</term>
<listitem><para>o nome do evento</para></listitem>
</varlistentry>
<varlistentry>
<term>Terceiro argumento</term>
<listitem><para>os parâmetros do evento, sendo normalmente o nome do documento atual ou a localização do arquivo do projeto.</para></listitem>
</varlistentry>
</variablelist>
 </para></listitem>
</itemizedlist>
</para>
<para>Além dos métodos acima o script pode receber entrada a partir do &quantaplus; na entrada padrão. Na caixa combinada <guilabel>Entrada</guilabel> você pode selecionar o que enviar para a entrada padrão: As opções são: <itemizedlist>
<listitem><para><guilabel>Nada</guilabel>: nada é enviado para o script.</para></listitem>
<listitem><para><guilabel>Documento atual</guilabel>: todo o documento é enviado para o script.</para></listitem>
<listitem><para><guilabel>Texto selecionado</guilabel>: a área selecionada do documento é enviada para o script. Usar a variável <command>%input</command> normalmente faz sentido somente ao usar esta configuração.</para></listitem>
</itemizedlist>
</para>
<para>Semelhante à <guilabel>Entrada</guilabel> você pode obter a saída do aplicativo executado. Existem dois tipos de saída: <itemizedlist> <listitem><para>saída normal, impressa para a saída padrão;</para> </listitem> <listitem><para>mensagens de erro, impressa para a saída de erro padrão.</para> </listitem> </itemizedlist> Você pode especificar o que deve acontecer com o texto impresso na saída padrão. Isto pode ser feito modificando o valor da caixa combinada <guilabel>Saída</guilabel>: <itemizedlist>
<listitem><para><guilabel>Nada</guilabel>: a saída do aplicativo é ignorada.</para></listitem>
<listitem><para><guilabel>Inserir na posição do cursor</guilabel>: a saída será inserida no documento atual na posição do cursor.</para></listitem>
<listitem><para><guilabel>Substituir seleção</guilabel>: a área selecionada do documento será substituída com a saída.</para></listitem>
<listitem><para><guilabel>Substituir seleção</guilabel>: a área selecionada do documento será substituída com a saída.</para></listitem>
<listitem><para><guilabel>Criar um novo documento</guilabel>: um novo documento será criado e conterá toda a saída do script.</para></listitem>
<listitem><para><guilabel>Substituir documento atual</guilabel>: todo o documento será substituído com a saída.</para></listitem>
<listitem><para><guilabel>Janela de mensagem</guilabel>: a saída aparecerá na visão da ferramenta <guilabel>Mensagens</guilabel>.</para></listitem>
</itemizedlist>
</para>
<para>As opções para a saída de erro padrão (<guilabel>Erro</guilabel>) são as mesmas da saída normal.</para>
</sect2>
</sect1>

<sect1 id="creating-toolbars-3-2">
<title>Criando Barras de Ferramentas</title>

<para>O texto a seguir mostrará como criar barras de ferramentas para um &DTEP;. Barras de ferramentas são elementos gráficos que possuem ações atribuídas. Ações, no &quantaplus;, são a base para todas as outras extensões que o &quantaplus; possui e possuirá no futuro. O mesmo mecanismo que define uma ação no &quantaplus; habilita a auto-completamentação e diálogos de marca. Com ações, o limite do que você pode fazer é virtualmente infinito. Para entender através de um exemplo, nós usaremos <ulink url="http://tidy.sf.net">&HTML; arrumado</ulink> em nossas páginas web. </para>

<sect2 id="from-scratch-to-complete-3-2">
<title>Do Zero para o Completo</title>

<para>Para inciar, você precisará criar uma barra de ferramentas de usuário. Selecione <menuchoice><guimenu>Barras de Ferramentas</guimenu> <guimenuitem>Adicionar Barra de Ferramentas de Usuário</guimenuitem></menuchoice>. </para>

<para>Se existirem muitas marcas para a linguagem de marcação, é recomendável que você divida as marcas em grupos lógicos. Você precisará criar uma nova barra de ferramentas de usuário para cada grupo. Neste caso, não existem muitas, por isso nós iremos criar uma barra de ferramentas e nomeá-la com o nome da marcação. </para>

<para>Uma vez que todas as suas barras de ferramentas estejam criadas, você deve adicioná-as e configurar as ações. Para fazer isto, selecione <menuchoice> <guimenu>Configurações</guimenu> <guimenuitem>Configurar Ações</guimenuitem> </menuchoice> <emphasis> </emphasis>. </para>

<para>As partes desta janelas são bem objetivas. Pressione o botão <guibutton>Nova ação</guibutton> na base da janela para entrar no modo de edição. </para>

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

<para>Complete o resto e,se a marca tiver atributos e você planeja sempre usá-los, habilite a caixa <guilabel>Executar o diálogo "Editar marca" se disponível</guilabel> de modo que você seja questionado sempre que a ação é usada. </para>

<para>Você deve agora ter algo como o seguinte. </para>

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

<para>Pressione o botão <guibutton>Aplicar</guibutton> e você verá a ação adicionada à(s) barra(s) de ferramentas selecionada(s). </para>

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

<para>Opa! Este ícone é terrível. Como eu mesmo e os outros associarão este ícone com aquela ação? Vamos substituí-lo antes de surgirem problemas. </para>

<para>Para criar um ícone que descreva mais precisamente aquela ação, nós iremos usar o &kiconedit;. Selecione-o a partir do &kmenu;, <menuchoice> <guisubmenu>Gráficos</guisubmenu> <guisubmenu>Mais Programas</guisubmenu> </menuchoice> (ou onde a sua distribuição o tenha colocado). </para>

<para>O padrão do &kiconedit; é o tamanho de 32x32 pixéis, mas nós precisamos de 22x22. Para mudar isto, selecione <menuchoice> <guimenu>Editar</guimenu> <guimenuitem>Redimensionar</guimenuitem> </menuchoice>. </para>

<para>Tenha em mente que você está criando um ícone que ajudará não somente você a lembrar-se que ação ele faz, mas também outros usuários do &DTEP;. </para>

<para>Uma vez que a marca para qual eu estou criando o ícone é chamada <quote>iniciar</quote>, eu decidi criar um <quote>Sinal de iniciar</quote>. Use a cor verde (verde é frequentemente interpretado como <quote>ir</quote>, <quote>iniciar</quote>, ou <quote>proceder</quote>), ou, pelo menos, apresente um mensagem ara o usuário que clicar nesta ação colocará uma marca &lt;iniciar&gt; no documento atual. </para>

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

<para>Agora que eu terminei a criação do ícone, eu o salvarei. </para>

<para>Uma vez que você tenha terminado a criação do(s) ícone(s), você deve associá-lo com a ação. Para fazer isto, abra <menuchoice> <guimenu>Configurações</guimenu> <guimenuitem>Configurar Ações</guimenuitem> </menuchoice> novamente (no &quantaplus;) e selecione a ação a qual deseja associar o ícone. Ao lado do campo <guilabel>Texto</guilabel>, você verá um botão; clique-o. </para>

<para>Selecione <guilabel>Outros Ícones</guilabel> e então clique o botão <guibutton>Navegar</guibutton>. </para>

<para>Vá para a pasta na qual você salvou o ícone, selecione o ícone e clique <guibutton>OK</guibutton>. </para>

<para>Pressione o botão <guibutton>Aplicar</guibutton> e continue a fazer o mesmo com as outras marcas, se for o caso, ou clique em <guibutton>OK</guibutton> para terminar. </para>

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

<para>Vamos dizer que você deseje adicionar algumas funções comuns do &quantaplus; na sua barra de ferramentas ou talvez ache que sua barra de ferramentas poderia ser melhor organizada de uma maneira diferente, com alguns separadores para agrupar ações. Abra o diálogo <guilabel>Configurar Barras de Ferramentas</guilabel> acessando <menuchoice> <guimenu>Configurações</guimenu> <guimenuitem>Configurar Barras de Ferramentas</guimenuitem> </menuchoice>. Certifique-se de que sua barra de ferramentas está selecionada. </para>

<para>Eu irei escolher o separador (topo da coluna da esquerda) para a minha barra de ferramentas. Uma vez que você tenha selecionado o ítem que deseja adicionar a sua barra de ferramentas, pressione o botão de seta para direita. Isto adicionará o ítem a sua barra de ferramentas. </para>

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

<para>Eu acho que gostaria de ter uma maneira rápida de acessar a <guilabel>Previsão do Konqueror</guilabel>. Eu selecionarei este ítem e o adicionarei à barra de ferramentas. </para>

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

<para>Observe como o separador auxiliar no agrupamento. Alguém que não conheça minha barra de ferramentas poderá pensar que o botão do &konqueror; foi colocado como ou em oposição ao botão iniciar. </para>

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

<para>Aplique suas mudanças e, quando tiver concluído, pressione <guibutton>OK</guibutton> para terminar. </para>

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

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

<para>Lembre de testar sua barra de ferramentas, clicando em todos os butões, de modo que você saiba se a saída é correta. </para>

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

<para>Agora para salvar a barra de ferramentas, nós selecionaremos <menuchoice> <guimenu>Barras de Ferramentas</guimenu> <guisubmenu>Salvar Barras de Ferramentas</guisubmenu> <guimenuitem>Salvar como Barra de Ferramentas Local</guimenuitem> </menuchoice>. </para>

<para>Salve-a para a pasta correta. Uma vez que NeXML não existe, eu simplesmente a terei na pasta de nível superior, mas sua barra de ferramentas deve ser salva para a pasta correta. Certifique-se de ajustar seu &descriptionrc; para fazer com que ela seja carregada quando um novo arquivo do tipo especificado seja criado. </para>
</sect2>
</sect1>


<sect1 id="creating-quanta-docs-3-2">
<sect1info>
<title>Criando Sua Própria Documentação</title>
<authorgroup>
<author><firstname>Robert</firstname> <surname>Nickel</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>

<othercredit role="translator"><firstname>Marcus</firstname><surname>Gama</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Tradução</contrib></othercredit> 

</authorgroup>
</sect1info>

<title>Criando Sua Própria Documentação</title>

<para>Provavelmente as adições mais notáveis ao &quantaplus; para o usuário em geral serão as adições de documentação para linguagens de marcação ou script que você mais gosta. Para este fim, este capítulo explanará como eu criei a árvore de documentação do &PHP; para meu uso pessoal. </para>

<para>Antes de iniciar a criação de sua própria documentação, você pode desejar verificar o <ulink url="http://quanta.sf.net/main1.php?contfile=resource">repositório do &quantaplus;</ulink> para ver se alguém já fez isto para você. </para>

<para>Existem duas fases para este processo. Primeiro, você deve obter a documentação existente para a linguagem de marcação/script/&etc; que você deseja. Segundo, você deve criar o arquivo <filename>docrc</filename>. O primeiro depende de você, o segundo será abordado aqui. </para>

<para>A forma geral do arquivo docrc é a seguinte: </para>

<informalexample>
<literallayout>#KDE Config File
[Tree]
Doc dir=<replaceable>caminho, relativo a este arquivo, dos arquivos de documentação html</replaceable> &eg; php42/
#top level elements
Top Element=<replaceable>Sua descrição desyes documentos</replaceable>> &eg; documentação do &PHP; 4.2

Section 1=Section1.html
Section 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,marca1,marca2,marca3
func1=func1.html
func2=func2.html
marca1=marca1.html
marca2=marca2.html
marca3=marca3.html
</literallayout>
</informalexample>

<para>O <filename>docrc</filename> é dividido em duas seções: Tree e Context. </para>

<para>A seção Tree define o aspecto da apresentação da documentação na aba de documentação. Por exemplo, você verá que nos documentos  você terá algo como i&PHP;sto: </para>

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

<para>Relacionado com o mostrado acima, meu <filename>docrc</filename> do &PHP; se parece com isto: </para>

<informalexample>
<literallayout>#KDE Config File

[Tree]

Doc dir=php42/

#top level elements
Top Element=Documentação PHP 4.2

Documentação PHP 4.2=Índice,#Iniciando,#Referência de Linguagem

Índice=index.html

Iniciando=Introdução, ...
Introdução=introduction.html
...

Referência de Linguagem=Sintaxe básica, ...
Sintaxe básica=language.basic-syntax.html
...

</literallayout>
</informalexample>

<para>Observe o <literal>#</literal> na frente do <quote>Iniciando</quote> e <quote>Referência de Linguagem</quote>. Ele indica que estes são sub-recipientes na árvore e tem seu próprio conteúdo. Eu não acredito que existe um limite de profundidade aqui (isto deve ser feito de acordo com seu bom senso) &mdash; use seu julgamento. </para>

<para>Para o Índice, você observará que ele se referencia diretamente a um arquivo (e consequentemente mostra acima na base da visão de árvore &mdash; diretórios primeiro|). </para>

<important>
<para>Espaços não afetam nada, mas observe os caracteres &amp; e &lt;. Eles devem ser separados por &amp;amp; e &amp;lt; respectivamente em todos os arquivos de recursos do &quantaplus; baseados em &XML;. </para>
</important>

<para>A seção Context é a seção do arquivo docrc que é usada para facilitar a ajuda sensível ao contexto. Por exemplo, você esté escrevendo um script  e você gostaria de ve&PHP;r a documentação para a função <function>mysql_fecth_array</function>. Você simplesmente destaca a função e então pressiona <keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo> para ajuda de contexto. A documentação do <function>mysql_fetch_array</function> será imediatamente exibida. Existem apenas dois tipos de entrada aqui: a ContextList e as linhas de associação de arquivo. </para>

<variablelist>
<varlistentry>
<term>ContextList</term>
<listitem>
<para>Realmente simples, isto é apenas uma lista separada por vírgulas dos itens de contexto que você deseja tornar disponíveis (para o &PHP;, estes são as funções do &PHP;). </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Linhas de associação de arquivos</term>
<listitem>
<para>Estas seguem a forma item de contexto=página do doc html. &eg; acos=function.acos.html </para>
</listitem>
</varlistentry>
</variablelist>

<para>Um exemplo abaixo da versão da seção Context do meu <filename>docrc</filename> é o seguinte: </para>

<informalexample>
<literallayout>#Keywords for context help
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...

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

<para>Agora você pode salvar seu arquivo <filename>docrc</filename>, salve-o no <filename class="directory"> $<envar>HOME</envar>/.trinity/share/apps/quanta/doc</filename> ou <filename class="directory">$<envar>TDEDIR</envar>/share/apps/quanta/doc</filename> para uso local ou global respectivamente. Então crie uma pasta (a especificada em seu arquivo <filename>docrc</filename>) no mesmo diretório do seu <filename>docrc</filename> e copie suas páginas &HTML; nele. </para>

<para>Você precisará reiniciar o &quantaplus; e então você verá seus documentos. </para>

<para>Uma vez que você tenha certeza de que eles são bons e podem ser compartilhados, envie seu <filename>docrc</filename> com uma descrição de qualquer informação pertinente sobre que documentos você usou para o <ulink url="http://quanta.sf.net/main1.php?contfile=resource">repositório do &quantaplus;</ulink> para uso pela comunidade do &quantaplus;. Você não ficará rico, mas se sentirá bem em saber que contribuiu para a melhor plataforma de desenvolvimento web do mundo. </para>

</sect1>

<sect1 id="sharing-resources">
  <title>Compartilhar Recursos</title>
  <para>Com o &quantaplus;, você não está sozinho. É possível compartilhar os vários recursos (pacotes DTEP, barras de ferramentas com ações, programas, modelos) com outras pessoas. Existem duas formas de fazer isso: </para>
  <variablelist>
    <varlistentry>
      <term>Enviar por E-mail</term>
      <listitem><para>Os recursos poderão ser enviados por e-mail para os seus amigos, colegas ou para quem você quiser. Irá ver os itens de menu <guilabel>Enviar por E-mail</guilabel> em vários locais, como o <menuchoice><guimenu>DTD</guimenu><guimenuitem>Enviar o Pacote de DTD (DTEP) por E-mail</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramentas</guimenu><guimenuitem>Enviar a Barra de Ferramentas por E-mail</guimenuitem></menuchoice>, no menu de contexto dos arquivos e pastas dos e na árvore de <guilabel>Modelos</guilabel> e <guilabel>Scripts</guilabel>. </para></listitem>
    </varlistentry>
    <varlistentry>
      <term>Enviar para o servidor principal</term>
      <listitem><para>Os recursos podem ser remetidos para o nosso repositório principal, a partir do qual todos os outros usuários do &quantaplus; poderão obtê-los. Os envios são revistos e disponibilizados, se a nossa equipe considerar que estão corretos e são úteis. Para fazer um envio válido, sugere-se que assine os recursos, pelo que irá necessitar de uma chave de GPG/PGP. Esta informação é usada para verificar a origem dos recursos, tanto pela nossa equipe como por quem irá obter os recursos.</para>
        <para>Para saber como obter os recursos do servidor principal, veja em <xref linkend="download-resources"/>.</para>
      <para>Ao enviar, será pedido para inserir a senha da sua chave privada de GPG (a senha não será gravada) ou, no caso de ter mais chaves privadas, poderá escolher a que deseja usar. No diálogo para <guilabel>Compartilhar Coisas Novas</guilabel>, preencha os campos de entrada (o <guilabel>URL de Previsão</guilabel> poderá ficar em branco) e inicie o envio, clicando em <guilabel>OK</guilabel>.</para>
      <para>O envio poderá ser iniciado em <menuchoice><guimenu>DTD</guimenu><guimenuitem>Enviar o Pacote do DTD (DTEP)</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramentas</guimenu><guimenuitem>Enviar a Barra de Ferramentas</guimenuitem></menuchoice>, no menu de contexto dos arquivos e pastas na árvore de <guilabel>Modelos</guilabel> e <guilabel>Scripts</guilabel>. </para>
      </listitem>
    </varlistentry>
</variablelist>
</sect1>
<sect1 id="download-resources">
<title>Obtendo os Recursos</title>
<para>É possível atualizar o seu &quantaplus; sem obter uma versão nova, obtendo os recursos novos como os pacotes DTEP, as barras de ferramentas com ações, modelos, 'scripts' e documentação. Uma possibilidade será obter os recursos por e-mail ou a partir de um servidor Web; nesses casos, você terá que instalá-los manualmente. Se você teve sorte, você também obteve um programa de instalação no local de onde transferiu os recursos. Contudo, o &quantaplus; tem um servidor dedicado que mantém os recursos que não foram instalados na distribuição principal, devido aos seus tamanhos ou a uso pouco frequente ou que foram contribuídos posteriormente pelos usuários, sendo estes recursos instalados automaticamente. Para obter esses recursos, use os vários itens de menu para <guilabel>Obter</guilabel>. Você poderá encontrá-los em <menuchoice><guimenu>DTD</guimenu><guimenuitem>Obter o Pacote de DTD (DTEP)</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramenta</guimenu><guimenuitem>Obter Barra de Ferramentas</guimenuitem></menuchoice>, no menu de contexto ou numa área vazia ou num item de topo nas árvores de <guilabel>Modelos</guilabel>, <guilabel>Scripts</guilabel> e <guilabel>Documentação</guilabel>. </para>
<para>Depois de obter um recurso, mas antes de instalá-lo, o &quantaplus; verifica se o recurso é válido, verificando a integridade e a assinatura. No caso de ocorrerem problemas, ele irá avisá-lo e você poderá decidir se deseja continuar ou não. Por favor reveja os diálogos de avisos com cuidado. No caso da integridade ser correta e o recurso estar devidamente assinado, você irá obter ainda um diálogo de informação, para que possa ver quem criou o recurso. </para>
<para>
  <caution><para>Certifique-se de instalar os recursos, principalmente as barras de ferramentas e os scripts, apenas a partir de fontes de confiança!</para></caution>
</para>
</sect1>

<sect1 id="converting-dtd">
  <title>Convertendo uma DTD para um &DTEP;</title>
  <para>É possível trabalhar em linguagens de XML que não sejam suportadas atualmente pelo &quantaplus; se criar um pacote DTEP. Contudo, a criação poderá levar bastante tempo, uma vez que poderá ter que escrever centenas de arquivos de marcas no formato <link linkend="tagxml-3-2">tagXML</link>. Obviamente, existe uma forma melhor de fazer isso, convertendo a DTD automaticamente para um pacote DTEP. </para>
  <para>A conversão poderá ser iniciada a partir da opção do menu <menuchoice><guimenu>DTD</guimenu><guimenuitem>Carregar e Converter a DTD</guimenuitem></menuchoice>. Selecione o arquivo <filename>.dtd</filename> que define a DTD que deseja usar, onde irá ver o seguinte diálogo: <mediaobject> <imageobject>
        <imagedata fileref="dtd-conversion.png" format="PNG"/>
      </imageobject>
    </mediaobject>  
  </para>
<para>Os itens são:</para>
<itemizedlist>
  <listitem><para><guilabel>Nome da pasta-alvo:</guilabel>o &DTEP; recém criado irá parar, com este nome, na pasta <filename><envar>$TDEHOME</envar>/share/apps/quanta/dtep</filename>. </para>
  </listitem>
  <listitem><para><guilabel>Nome:</guilabel> o nome (texto de definição) do DTD</para></listitem>
  <listitem><para><guilabel>Apelido:</guilabel> o nome visto pelo usuário do &DTEP;</para></listitem>
  <listitem><para><guilabel>Linha de definição do !DOCTYPE:</guilabel> o texto que deverá aparecer na marca !DOCTYPE, como por exemplo HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"</para></listitem>
  <listitem><para><guilabel>URL do DTD:</guilabel> o URL apontando para o arquivo DTD</para></listitem>
  <listitem><para><guilabel>Extensão padrão:</guilabel> a extensão que será usada normalmente para os arquivos que foram escritos nesta DTD</para></listitem>
  <listitem><para><guilabel>Marcas e atributos sensíveis à cais:</guilabel> esta opção costuma estar assinalada para o caso das variantes da linguagem XML</para></listitem>
  <listitem><para><guilabel>Ajustar o DTEP após a conversão:</guilabel> se estiver assinalado, após a conversão, o &quantaplus; irá invocar o editor do &descriptionrc;, de modo a que você possa ajustar alguns detalhes do &DTEP; acabado de criar. Recomenda-se que deixe esta opção assinalada.</para></listitem>
</itemizedlist>

</sect1>
</chapter>