# Extender o &quanta;

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.

## Criar os Seus Próprios Documentos para o &quanta;

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.

Antes de começar a criar a sua própria documentação, poderá querer ver o repositório do &quanta; para ver se alguém já a criou.

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.

O formato geral do ficheiro 'docrc' é o seguinte:

    #Ficheiro de Configuração do KDE
    [Tree]
    Doc dir=<directoria relativa a este ficheiro onde estão os ficheiros de HTML da documentação> p.ex. php42/
    #elementos do nível de topo
    Top Element=<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

O ficheiro 'docrc' está partido em duas secções: Tree e Context.

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:

Relacionando isto com o descrito em cima, o meu ficheiro 'docrc' de PHP fica semelhante ao seguinte:

    #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
    ...

Repare no # antes da Introdução e Referência da Linguagem. 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 o Índice, irá reparar que este referencia directamente um ficheiro (e, como consequência, irá aparecer no fundo da árvore - com as directorias primeiro!).

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

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 &Ctrl;H 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.

ContextList

- 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).

Linhas de associação de ficheiros

- Estas estão no formato item de contexto=página de doc html. p.ex. acos=funcao.acos.html

Uma versão de exemplo da minha secção Context do 'docrc' encontra-se descrita de seguida:

    #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
    ...

Agora poderá gravar o seu ficheiro docrc, colocá-lo na directoria `$`HOME`/.kde/share/apps/quanta/doc` ou em `$`KDEDIR`/share/apps/quatna/doc` 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á.

Terá de reiniciar o &quanta; para poder então ver a sua documentação.

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 repositório do &quanta; 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.

Robert Nickel

## Criar Acções no &quanta;

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 html tidy nas nossas páginas Web.

Vamos começar: Configuração Configurar as Acções

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'.

Iremos criar uma nova acção, por isso vamos carregar no novo botão (em baixo à esquerda) e começar.

Agora foi-lhe apresentado um conjunto vazio de opções para preencher:

Texto

- Este é o nome da acção

Dica

- Não se sabe onde isto é mostrado. É opcional!

Texto de estado

- Não se sabe o que é ou onde é usado. É opcional!

Colocar esta acção em (opção)

- 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 Configuração Configurar as Barras de Ferramentas.

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'.

Vamos então agora ao cerne da questão. A definição da acção.

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 começar:

<tag >

- Isto é onde o utilizador indica o nome da 'tag', tal como irá aparecer no seu documento, p.ex., <div align=center>

</tag >

- Isto é onde indica a 'tag' de fecho, se existir, ou desligar a opção, se não existir, p.ex. </div>

Correr a janela Editar Tag se disponível

- Isto invoca o editor da janela se existir um ficheiro de 'tag' definido para este item. Veja a secção sobre os ficheiros de 'tags' para mais informações sobre os ficheiros de 'tags'.

E agora... De volta ao nosso programa agendado regularmente. A continuar a criação da acção 'html tidy'.

Carregue na página Script para revelar o seguinte:

O campo de texto no topo

- Isto é onde irá colocar o executável que procura. No nosso caso, será o /usr/local/bin/tidy porque é onde quero colocar o 'tidy'.

Agora, vamos às páginas de Entrada/Saída/Erros.

Página de Entrada

Nenhuma (opção exclusiva)

- 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'.

Texto seleccionado (opção exclusiva)

- 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.

Documento actual (botão de selecção)

- 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'.

Agora carregue na página Saída. Isto é para onde decidimos enviar a nossa redirecção para o resultado dos seus programas.

Nenhuma

- 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'.

Inserir na posição do cursor

- 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'.

Substituir o documento actual

- É 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'.

Criar um novo documento

- Enviar resultado para um novo documento na janela de edição. Esta é a melhor escolha par o tidy.

Janela de mensagens

- Manda para a janela de mensagens &Ctrl;M . 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 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.