<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN"
"dtd/kdex.dtd"
> -->

<chapter id="extending-quanta">
<title
>Extendendo o &quanta;</title>

<para
>Este capítulo descreve como personalizar o &quanta; para suas necessidades particulares e como você pode ajudar o &quanta; a ficar ainda melhor.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>

<title
>Criando Seus Próprios Docs para o &quanta;</title>

<para
>Provavelmente as adições mais notáveis ao &quanta; para o usuário em geral serão as adições de documentação para linguagens de marcação e script que você mais gosta. Para este fim, este capítulo explanará como eu criei a árvore de documentação do <acronym
>PHP</acronym
> 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.sourceforge.net/main1.php?contfile=resource"
>repositório do &quanta;</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 <acronym
>PHP</acronym
> 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,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
> é 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 <acronym
>PHP</acronym
> você terá algo como isto:</para>

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

<para
>Relacionado com o mostrado acima, meu <filename
>docrc</filename
> do <acronym
>PHP</acronym
> 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-containers 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 &quanta; 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 <acronym
>PHP</acronym
> e você gostaria de ver 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 <acronym
>PHP</acronym
>, estes são as funções do <acronym
>PHP</acronym
>).</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
>/.kde/share/apps/quanta/doc</filename
> ou <filename class="directory"
> $<envar
>KDEDIR</envar
>/share/apps/quanta/doc</filename
> para uso local ou global respectivamente. Então crie um diretório (o especificado sem 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 &quanta; 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.sourceforge.net/main1.php?contfile=resource"
>repositório do &quanta;</ulink
> para uso pela comunidade do &quanta;. 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="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Criando Ações no &quanta;</title>

<para
>Ações no &quanta; são a base para todas as outras extensões que o &quanta; possui e possuirá no futuro. O mesmo mecanismo que define uma ação no &quanta; habilita o autocompletamento e diálogos de tag. 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://www.w3c.org/People/Raggett/tidy/"
>html arrumado</ulink
> em nossas páginas web.</para>

<para
>Vamos iniciar <menuchoice
><guimenu
>Configurações</guimenu
><guimenuitem
>Configurar Ações</guimenuitem
></menuchoice
></para>

<para
>Uma vez que você iniciou o diálogo de ação você verá esta janela. À esquerda está a lista das ações atualmente conhecidas. Você pode selecionar uma delas e realizar as mesmas ações para uma ação existente que nós estamos indo fazer com nossa ação html arrumado.</para>

<screenshot
> <screeninfo
></screeninfo
> <mediaobject
> <imageobject
> <imagedata fileref="conf-action.png" format="PNG" /> </imageobject
> <textobject
><phrase
></phrase
></textobject
> </mediaobject
> </screenshot>

<para
>Nós estamos criando uma nova ação, então vamos clicar no botão <guibutton
>Nova</guibutton
> (inferior esquerdo) e iniciar.</para>

<para
>Agora você será apresentado a um conjunto em branco de opções para preenchimento:</para>

<variablelist
> <varlistentry
> <term
><guilabel
>Texto</guilabel
></term
> <listitem
><para
>Este é o nome da ação</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Dica</guilabel
></term
> <listitem
><para
> Opcional</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Texto de estado</guilabel
></term
> <listitem
><para
> Opcional.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Coloca esta ação na</guilabel
> (caixa de checagem)</term
> <listitem
><para
>Isto habilita a caixa combinada para seleção de uma barra de ferramentas para colocar esta ação nela. Se você não escolher agora, você pode sempre adicioná-la mais tarde a partir do <menuchoice
><guimenu
>Configurações</guimenu
><guimenuitem
>Configurar Barras de Ferramentas</guimenuitem
></menuchoice
></para
></listitem
> </varlistentry
> </variablelist>

<para
>Após preencher estes parâmetros básicos, você pode selecionar um ícone para a ação clicando no botão de ícone à esquerda da caixa de entrada<guilabel
>Texto</guilabel
>.</para>

<para
>Agora vamos ao que interessa, a definição da ação.</para>

<screenshot
> <screeninfo
></screeninfo
> <mediaobject
> <imageobject
> <imagedata fileref="conf-action1.png" format="PNG" /> </imageobject
> <textobject
><phrase
></phrase
></textobject
> </mediaobject
> </screenshot>

<para
>Se nós estamos definindo uma tag de marcação, nós podemos usar a aba tag aqui para inserir os parâmetros da tag.</para>

<para
>Grafia:</para>

<variablelist
> <varlistentry
> <term
><guilabel
>&lt;tag&gt;</guilabel
></term
> <listitem
><para
>Aqui é onde você insere o nome da tag como aparecerá em seu documento. &eg; <userinput
>&lt;div align=center&gt;</userinput
></para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>&lt;/tag&gt;</guilabel
></term
> <listitem
><para
>Aqui é onde você insere a tag de fechamento, se existir, ou desabilita a caixa se não. &eg; <userinput
>&lt;/div&gt;</userinput
></para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Executar diálogo "Editar Tag" se disponível</guilabel
></term
> <listitem
><para
>Isto executa o editor de diálogo se existe um arquivo de tag definido para este item. Verifique a seção de <link linkend="tag-files"
>arquivos de tag</link
> para mais informações sobre arquivos de tag.</para
></listitem
> </varlistentry
> </variablelist>

<para
>E agora... Voltando para nosso programa agendado regularmente. Continuando a criação da ação html arrumado.</para>

<para
>Clique na aba <guilabel
>Script</guilabel
> para revelar o seguinte:</para>

<screenshot
> <screeninfo
></screeninfo
> <mediaobject
> <imageobject
> <imagedata fileref="conf-action2.png" format="PNG" /> </imageobject
> <textobject
> <phrase
></phrase
> </textobject
> </mediaobject
> </screenshot>

<variablelist
> <varlistentry
>  <listitem
> <para
>Aqui é onde você coloca o executável que você deseja. No nosso caso, ele deve ser <filename
>/usr/local/bin/tidy</filename
> porque ali é onde eu mantenho o <command
>tidy</command
>.</para
> </listitem
> </varlistentry
> </variablelist>

<para
>Agora na aba de Entrada/Saída/Erros.</para>

<variablelist
> <title
><guilabel
>Entrada</guilabel
></title
> <varlistentry
> <term
><guilabel
>Nenhuma</guilabel
> (botão de opção)</term
> <listitem
><para
>Não fornece nenhuma entrada para este script. Isto deve ser útil se você estiver chamando um script Tcl/Tk que exibe uma janela para interação com o usuário e então retorna seu resultado. Nós iremos escolher outra opção para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Texto selecionado</guilabel
> (botão de opção)</term
> <listitem
><para
>Envia uma cópia do texto atualmente selecionado para a entrada padrão do script da caixa de entrada acima. Nós podemos usar isto para o <command
>tidy</command
>, ams isto não tem graça selecionar tudo num documento grande.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Documento atual</guilabel
> (botão de opção)</term
> <listitem
><para
>Envia o conteúdo do arquivo em edição através da entrada padrão do script na caixa de entrada acima. Isto é o que nós queremos usar para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> </variablelist>

<para
>Agora clique na aba <guilabel
>Saída</guilabel
>. Aqui é onde nós decidiremos para onde redirecionar a saída de nosso script.</para>
 
<variablelist
> <varlistentry
> <term
><guilabel
>Nenhum</guilabel
></term
> <listitem
><para
>Isto será bom se você está lançando um aplicativo externo que somente recebe uma entrada mas não retorna nenhuma saída. Isto não tem nenhuma utilidade para nós com o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Inserir na posição do cursor</guilabel
></term
> <listitem
><para
>Apenas o que está dito. Tenha certeza que você está onde deseja que o texto seja inserido. Não é bom para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Substituir o documento atual</guilabel
></term
> <listitem
><para
>Substituição total do arquivo aqui. Isto não sobrescreve o arquivo no disco, mas isto destrói sua sessão de edição atual. Use com cautela. Nós não usaremos isto para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Cria novo documento</guilabel
></term
> <listitem
><para
>Saída para um novo documento na janela de edição. Esta é a melhor escolhar para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> <varlistentry
> <term
><guilabel
>Janela de mensagem</guilabel
></term
> <listitem
><para
>Saída para a janela de mensagem disponível pressionado <keycombo action="simul"
>&Ctrl;<keycap
>M</keycap
></keycombo
>. Isto é útil para depuração e a aba <guilabel
>Erro</guilabel
>, mas não muito para Saída. Não para o <command
>tidy</command
>.</para
></listitem
> </varlistentry
> </variablelist>

<para
>Para a aba <guilabel
>Editar</guilabel
>, as opções são as mesmas da aba <guilabel
>Saída</guilabel
>. Usualmente, você usara a janela de mensagem para auxiliar na depuração ou a opção <guilabel
>nenhum</guilabel
>.</para>

</sect1>
</chapter>

