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