# Extendendo o &quanta;

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

## Criando Seus Próprios Docs para o &quanta;

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 PHP para meu uso pessoal.

Antes de iniciar a criação de sua própria documentação, você pode desejar verificar o repositório do &quanta; para ver se alguém já fez isto para você.

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 `docrc`. O primeiro depende de você, o segundo será abordado aqui.

A forma geral do arquivo docrc é a seguinte:

    #KDE Config File
    [Tree]
    Doc dir=caminho, relativo a este arquivo, dos arquivos de documentação html ⪚ php42/
    #top level elements
    Top Element=Sua descrição desyes documentos
    > ⪚ 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,tag1,tag2,tag3
    func1=func1.html
    func2=func2.html
    tag1=tag1.html
    tag2=tag2.html
    tag3=tag3.html

O `docrc` é dividido em duas seções: Tree e Context.

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 PHP você terá algo como isto:

Relacionado com o mostrado acima, meu `docrc` do PHP se parece com isto:

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

Observe o `#` na frente do Iniciando e Referência de Linguagem. 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) — use seu julgamento.

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

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

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 PHP e você gostaria de ver a documentação para a função `mysql_fecth_array`. Você simplesmente destaca a função e então pressiona &Ctrl;H para ajuda de contexto. A documentação do `mysql_fetch_array` será imediatamente exibida. Existem apenas dois tipos de entrada aqui: a ContextList e as linhas de associação de arquivo.

ContextList

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

Linhas de associação de arquivos

- Estas seguem a forma item de contexto=página do doc html. ⪚ acos=function.acos.html

Um exemplo abaixo da versão da seção Context do meu `docrc` é o seguinte:

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

Agora você pode salvar seu arquivo `docrc`, salve-o no `$`HOME`/.kde/share/apps/quanta/doc` ou `$`KDEDIR`/share/apps/quanta/doc` para uso local ou global respectivamente. Então crie um diretório (o especificado sem seu arquivo `docrc`) no mesmo diretório do seu `docrc` e copie suas páginas &HTML; nele.

Você precisará reiniciar o &quanta; e então você verá seus documentos.

Uma vez que você tenha certeza de que eles são bons e podem ser compartilhados, envie seu `docrc` com uma descrição de qualquer informação pertinente sobre que documentos você usou para o repositório do &quanta; 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.

Robert Nickel

## Criando Ações no &quanta;

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 html arrumado em nossas páginas web.

Vamos iniciar Configurações Configurar Ações

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.

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

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

Texto

- Este é o nome da ação

Dica

- Opcional

Texto de estado

- Opcional.

Coloca esta ação na (caixa de checagem)

- 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 Configurações Configurar Barras de Ferramentas

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

Agora vamos ao que interessa, a definição da ação.

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.

Grafia:

<tag>

- Aqui é onde você insere o nome da tag como aparecerá em seu documento. ⪚ `<div align=center>`

</tag>

- Aqui é onde você insere a tag de fechamento, se existir, ou desabilita a caixa se não. ⪚ `</div>`

Executar diálogo "Editar Tag" se disponível

- Isto executa o editor de diálogo se existe um arquivo de tag definido para este item. Verifique a seção de arquivos de tag para mais informações sobre arquivos de tag.

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

Clique na aba Script para revelar o seguinte:

- Aqui é onde você coloca o executável que você deseja. No nosso caso, ele deve ser `/usr/local/bin/tidy` porque ali é onde eu mantenho o `tidy`.

Agora na aba de Entrada/Saída/Erros.

## Entrada

Nenhuma (botão de opção)

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

Texto selecionado (botão de opção)

- 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 `tidy`, ams isto não tem graça selecionar tudo num documento grande.

Documento atual (botão de opção)

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

Agora clique na aba Saída. Aqui é onde nós decidiremos para onde redirecionar a saída de nosso script.

Nenhum

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

Inserir na posição do cursor

- Apenas o que está dito. Tenha certeza que você está onde deseja que o texto seja inserido. Não é bom para o `tidy`.

Substituir o documento atual

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

Cria novo documento

- Saída para um novo documento na janela de edição. Esta é a melhor escolhar para o `tidy`.

Janela de mensagem

- Saída para a janela de mensagem disponível pressionado &Ctrl;M. Isto é útil para depuração e a aba Erro, mas não muito para Saída. Não para o `tidy`.

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