<chapter id="extending-quanta">
<title
>Extender o &quanta;</title>
<para
>Este capítulo descreve como personalizar o &quanta; de acordo com as suas necessidades particulares e como pode ajudar o &quanta; a tornar-se melhor.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>
<title
>Criar os Seus Próprios Documentos para o &quanta;</title>
<para
>Provavelmente as adições mais notáveis ao &quanta; 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.sourceforge.net/main1.php?contfile=resource"
>repositório do &quanta;</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 'docrc'. O primeiro é segundo o seu critério, enquanto o último passo será debatido aqui.</para>

<para
>O formato geral do ficheiro 'docrc' é o seguinte: <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
> O ficheiro 'docrc' está partido em duas secções: Tree e Context. </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>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para
><para
>Relacionando isto com o descrito em cima, o meu ficheiro 'docrc' de PHP fica semelhante ao seguinte: <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
> Repare no # 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 - com as directorias 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 &quanta;.</para
> </important>
<para
>A secção Context é a secção do ficheiro 'docrc' que é usada para facilitar a ajuda dependente do contexto. Por exemplo, se estiver a fazer um programa em PHP e quiser ver a documentação para a função mysql_fetch_array function. Basta seleccionar a função e carregar então em <menuchoice
> <shortcut
> <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
> </shortcut
> <guimenu
></guimenu
> </menuchoice
> para obter uma ajuda de contexto. Neste momento, passou a ver a documentação sobre o mysql_fetch_array. Existem apenas dois tipos de registos: as linhas do ContextList e as de associação de ficheiros. <variablelist
> <varlistentry
> <term
>ContextList</term
> <listitem
> <para
>Não é mais do que uma lista separada por vírgulas dos itens de contexto que deseja disponibilizar (no caso do PHP, são as funções do mesmo). </para
></listitem
> </varlistentry
> <varlistentry
> <term
>Linhas de associação de ficheiros</term
> <listitem
><para
>Estas estão no formato item de contexto=página de doc html. p.ex. acos=funcao.acos.html</para
></listitem
> </varlistentry
> </variablelist
> Uma versão de exemplo da minha secção Context do 'docrc' encontra-se descrita de seguida: <informalexample
> <literallayout>
#Palavras-chave para a ajuda de contexto
[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>
<para
>Agora poderá gravar o seu ficheiro docrc, colocá-lo na directoria <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 directoria (a especificada no seu ficheiro 'docrc') na mesma directoria que no seu ficheiro 'docrc' e copie as suas páginas de documentação em HTML para lá.</para>
<para
>Terá de reiniciar o &quanta; 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 'docrc' em conjunto com uma descrição com todas as informações pertinentes da documentação que usou no <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>repositório do &quanta;</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>

<sect1 id="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Criar Acções no &quanta;</title>
<para
>As acções no &quanta; 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://www.w3c.org/People/Raggett/tidy/"
>html tidy</ulink
> nas nossas páginas Web.</para>

<para
>Vamos começar: <menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Configurar as Acções</guimenuitem
></menuchoice
> </para>
<para
> Logo que tenha iniciado a janela de acções irá ver esta janela. À esquerda encontra-se a lista das acções conhecidas no momento. Poderá seleccionar uma delas e efectuar as mesmas acções para uma acção existente, da mesma forma que iremos fazer com a nossa acção 'html tidy'. </para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Iremos criar uma nova acção, por isso vamos carregar no novo botão (em baixo à esquerda) e começar.</para>

<para
>Agora foi-lhe apresentado um conjunto vazio de opções para preencher:  <variablelist
> <varlistentry
> <term
>Texto</term
> <listitem
><para
>Este é o nome da acção</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Dica</term
> <listitem
><para
>Não se sabe onde isto é mostrado. É opcional!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Texto de estado</term
> <listitem
><para
>Não se sabe o que é ou onde é usado. É opcional!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Colocar esta acção em (opção)</term
> <listitem
><para
>Isto activa a lista para seleccionar a barra de ferramentas onde colocar esta acção. Se não quiser escolher agora, poderá sempre fazê-lo posteriormente em <menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Configurar as Barras de Ferramentas</guimenuitem
></menuchoice
>.</para
></listitem
> </varlistentry
> </variablelist
> Depois de preencher os campos básicos, poderá seleccionar um ícone para a acção ao carregar no botão de ícones à esquerda do campo 'Texto'. </para>

<para
>Vamos então agora ao cerne da questão. A definição da acção.</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Se estivéssemos a definir uma 'tag' de formatação, poderíamos usar a página da 'tag' para indicar os parâmetros das 'tags'.</para>
<para
> Para começar: <variablelist
> <varlistentry
> <term
>&lt;tag
></term
> <listitem
><para
>Isto é onde o utilizador indica o nome da 'tag', tal como irá aparecer no seu documento, p.ex., &lt;div align=center&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>&lt;/tag
></term
> <listitem
><para
>Isto é onde indica a 'tag' de fecho, se existir, ou desligar a opção, se não existir, p.ex. &lt;/div&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Correr a janela <quote
>Editar Tag</quote
> se disponível</term
> <listitem
><para
>Isto invoca o editor da janela se existir um ficheiro de 'tag' definido para este item. Veja a secção sobre os <link linkend="tag-files"
>ficheiros de 'tags'</link
> para mais informações sobre os ficheiros de 'tags'.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>E agora... De volta ao nosso programa agendado regularmente. A continuar a criação da acção 'html tidy'.</para>
<para
>Carregue na página Script para revelar o seguinte:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject
></para>
<para
> <variablelist
> <varlistentry
> <term
>O campo de texto no topo</term
> <listitem
><para
>Isto é onde irá colocar o executável que procura. No nosso caso, será o /usr/local/bin/tidy porque é onde quero colocar o 'tidy'.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Agora, vamos às páginas de Entrada/Saída/Erros.</para>
<para
><emphasis
>Página de Entrada</emphasis
> <variablelist
> <varlistentry
> <term
>Nenhuma (opção exclusiva)</term
> <listitem
><para
>Não aceitar nenhuma entrada para este programa. Isto poderá ser útil se estiver a chamar um progrma em Tcl/Tk que fez aparecer uma janela para interagir com o utilizador e que devolveu os seus resultados. Iremos seleccionar algo para o 'tidy'.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Texto seleccionado (opção exclusiva)</term
> <listitem
><para
>Tal como indica, envia uma cópia do texto seleccionado no momento para o 'standard in' do programa no campo de texto em cima. Poderemos usar isto para o 'tidy', mas não tem piada seleccionar tudo num documento grande.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Documento actual (botão de selecção)</term
> <listitem
><para
>Encaminha o conteúdo da versão do editor do ficheiro para o 'standard in' do programa no campo de texto em cima. Isto é o que irá ser usado para o 'tidy'.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Agora carregue na página <emphasis
>Saída</emphasis
>. Isto é para onde decidimos enviar a nossa redirecção para o resultado dos seus programas. <variablelist
> <varlistentry
> <term
>Nenhuma</term
> <listitem
><para
>Isto será útil se estiver a lançar uma aplicação externa que só aceita dados de entrada mas não devolve nenhum resultado. Isto não tem uso real no 'tidy'.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Inserir na posição do cursor</term
> <listitem
><para
>Tal como indica, coloca o texto na posição onde o cursor se encontra. Verifique se é este o sítio onde quer introduzir o texto. Não é útil no caso do 'tidy'.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Substituir o documento actual</term
> <listitem
><para
>É feita uma substituição total do ficheiro aqui. Não irá substituir o ficheiro no disco, mas irá defazer a sua sessão de edição actual, por isso use com cuidado. Não iremos usar isto com o 'tidy'.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Criar um novo documento</term
> <listitem
><para
>Enviar resultado para um novo documento na janela de edição. Esta é a melhor escolha par o tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Janela de mensagens</term
> <listitem
><para
>Manda para a janela de mensagens <menuchoice
><shortcut
><keycombo action="simul"
>&Ctrl;<keycap
>M</keycap
> </keycombo
></shortcut
><guimenu
></guimenu
></menuchoice
>. Isto é útil para fins de depuração e para a janela de Erros, mas não para a Saída. Não é usado no 'tidy'.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
> Para a página de Edição, as opções são as mesmas que para a página de Saída. Normalmente, irá usar a janela de mensagens para ajudar na depuração.</para>
</sect1>
</chapter>

