Christopher Hornbaker

chrishornbaker@earthlink.net

András Mantia

amantia@kde.org

PedroMorais

morais@kde.org

Tradução Este capítulo descreve como personalizar o &quantaplus; de acordo com as suas necessidades particulares e como pode ajudar o &quantaplus; a tornar-se melhor. Os Pacotes de Edição do Tipo de Documentos (&DTEP;s) são usados no &quantaplus; para adicionar o suporte para as linguagens de formatação e de 'scripting', bem como para o &CSS;. Estas permitem ao &quantaplus; oferecer as funcionalidades como a auto-completação e as árvores de nós. A sua simplicidade e flexibilidade são o que tornam o &quantaplus; um &IDE; rápido e amigável para os programadores Web. São também o que fazem do &quantaplus; um ambiente produtivo e simples de utilizar. Os &DTEP;s vêm em dois formatos: a Família 1, que corresponde às linguagens de formatação e a Família 2, que corresponde ao 'scripting' e ao &CSS;. Os &DTEP;s são compostos por duas partes, a Pasta de Marcas e as Barras de Ferramentas. As Pastas de Marcas são compostas por dois tipos de ficheiros, o &descriptionrc; e os ficheiros de TagXML, os quais contêm a extensão '.tag'. As barras de ferramentas são as páginas de botões úteis e orientados por ícones (por cima da janela de edição) que colocam o texto num documento de forma mais rápida do que o utilizador consegue escrever. Os &DTEP;s podem ser criados manualmente (veja em baixo), obtidos da Internet ou criados automaticamente a partir de uma DTD existente. Veja em os detalhes da conversão. Este documento descreve como é possível criar ficheiros TagXML, o &descriptionrc; e as barras de ferramentas. Em resumo, como criar um &DTEP;. Os ficheiros TagXML (.tag) definem tanto os atributos específicos para uma marca como a disposição e o conteúdo da janela de propriedades que o &quantaplus; irá mostrar para a marca. O ficheiro &descriptionrc; contém as regras e a informação para o próprio &DTEP;. As barras de ferramentas oferecem uma forma rápida de adicionar marcas num documento, sem haver a preocupação com erros de escrita e outros erros do género. As Pastas de Marcas são isso mesmo - pastas. Estas são compostas apenas pelos ficheiros &descriptionrc; e TagXML. As Pastas de Marcas contêm o nome da linguagem de formatação e a versão, se tal se aplicar. (Por exemplo, html-4.01-strict) A tabela em baixo enumera os elementos que são definidos no TagXML e refere se estes são obrigatórios ou não. Embora nem todos sejam necessários, recomenda-se que você use tantos quantos possíveis para que os outros utilizadores possam ter uma melhor experiência e mais informação com que lidar. Elemento Utilização Predefinida Caso de Utilização TAGS necessário sempre tag necessário sempre label opcional necessário para criar uma janela de propriedades attr opcional necessário para definir um atributo tooltip opcional necessário para que a janela de propriedades mostre uma dica whatsthis opcional necessário para que a janela de propriedades mostre um O Que é Isto? list opcional necessário quando um determinado atributo é do tipo list (lista) item opcional necessário quando o <list> é usado textlocation opcional sempre location opcional necessário quando é usada uma legenda text opcional necessário quando é usada uma legenda children opcional uma lista das marcas que poderão aparecer dentro da marca que está a ser definida child necessário um item-filho stoppingtags opcional uma lista das marcas que indicam o fim para outra marca stoppingtag necessário um item de interrupção da marca As secções seguintes irão descrever, em detalhe, cada elemento. Tudo desde onde eles poderão estar até o que poderão conter é descrito aqui de uma forma simples de seguir. Este é o elemento de raiz (topo) de um documento de TagXML. Só poderá aparecer num documento uma única vez. Poderá conter a definição de várias marcas. Este é um elemento do tipo apenas para elementos. Pai(s) Filhos NENHUM tag Uma cobertura para a marca a ser definida. Este é um elemento do tipo apenas para elementos. Pai(s) Filhos TAGS label, attr, stoppingtags AtributoTipoValores PredefiniçãoUtilizaçãoDescrição namestring necessárioIndica o nome da marca a ser definida. singleboolean opcionalIndica se a marca necessita de uma 'tag' de fecho ou não (</(nome da marca)>. typestringxmltag opcionalIndica o tipo da marca a ser definida. xmltag O tipo da marca baseia-se em XML. (Apenas na Família 1.) entity A marca descreve uma entidade. (Apenas na Família 1.) property O tipo da marca relaciona-se com a &CSS; (Apenas Família 2.) function O tipo da marca é uma função de programação. Quando é usado, os elementos <attr> tornam-se os argumentos da função (apenas na Família 2). class O tipo da marca é uma classe de programação. (apenas na Família 2.) method O tipo da marca é um método da classe. (apenas na Família 2.) returnTypestringvoid opcionalIndica o tipo devolvido pela marca a ser definida. (apenas na Família 2). void O tipo da marca não devolve nada ('void'). int O tipo da marca devolve um inteiro. float O tipo da marca devolve um número de vírgula flutuante. long O tipo da marca devolve um número longo. string O tipo de marca devolve uma cadeia de caracteres. versionstring opcionalIndica a versão da linguagem para a qual esta marca é válida extendsstring opcionalSó é válido se o tipo da marca for o "class". O nome da classe de base desta classe. (Apenas na família 2). classstring opcionalSó é válido se o tipo for "method". O nome da classe a que este método pertence. (Apenas na família 2). commonboolean opcionalSe for igual a "yes", a marca corresponde a um grupo de atributos comum e os atributos desta marca poderão ser anexados a qualquer outra marca. (Apenas na Família 1.) commentstring opcionalo texto do comentário aparece perto do nome da marca na lista de completação Coloca uma legenda na janela. O texto é referido na marca <text>. Este é um elemento do tipo apenas para elementos. Pai(s) Filhos tag text, location Define um atributo da marca. Este elemento ocorre uma vez para cada atributo. Define o nome e o tipo do atributo. Também contém as marcas adicionais que indicam como o atributo deverá ser mostrado, etc. Este é um elemento do tipo apenas para elementos. Pai(s) Filhos tag location, list, tooltip, whatsthis, textlocation AtributoTipoValores PredefiniçãoUtilizaçãoDescrição namestring necessárioIndica o nome do atributo a ser definido. typestringinput necessárioIndica o tipo do atributo a ser definido. input O campo suporta a introdução de texto livre (campo de texto). check O valor do campo é booleano (opção). color O valor do campo é uma cor. url O valor do campo é um &URL;. (Ficheiro local que referencia.) list O valor do campo é um item de uma lista indicada. statusstringopcional necessárioIndica se o argumento é ou não obrigatório. (Apenas na Família 2). opcional O argumento é opcional. necessário O argumento é necessário. implied O argumento é implícito. sourcestring opcionalIndica as origens usadas para preencher o item do atributo na janela de edição da marca e na árvore de atributos selection O texto seleccionado será usado como origem dcop Será usado o resultado de um método de DCOP como origem interfacestring opcionalNecessita do 'source="dcop"'. A interface de DCOP a partir da qual o &quantaplus; irá buscar os dados de origem. methodstring opcionalNecessita do 'source="dcop"' e do nome de uma interface. O nome do método de DCOP a partir do qual o &quantaplus; irá buscar os dados de origem. argumentsstring opcionalNecessita do 'source="dcop"', de uma interface e de um nome de um método. Os argumentos que são passados ao método. Poderá estar em branco ou aceitar o "%tagname%", que corresponde ao nome actual da marca. Define a dica para um campo na janela. Este elemento é apenas de texto. De momento só é suportado texto simples (você não pode usar nenhuma formatação). Pai(s) Filhos attr NENHUM Define a ajuda 'O Que É Isto?' para um campo da janela. Este elemento contém apenas texto. De momento só é suportado texto simples (você não pode usar nenhuma formatação). Pai(s) Filhos attr NENHUM Uma marca que apenas agrupa os itens de uma lista. Só pode aparecer uma vez por cada descrição de um atributo. Este é um elemento do tipo apenas para elementos. Pai(s) Filhos attr item Define um item da lista. Este elemento contém apenas texto. Pai(s) Filhos list NENHUM Indica a posição do atributo de uma marca dentro de uma janela. Esta marca só poderá ocorrer uma vez por cada atributo da janela (&ie; um por cada marca <attr>). Este elemento fica vazio. Pai(s) Filhos attr NENHUM AtributoTipo UtilizaçãoDescrição rownonNegativeInteger necessárioIndica a linha na disposição da janela de um campo ou legenda. colnonNegativeInteger necessárioIndica a coluna na disposição da janela para um campo ou uma legenda. rowspannonNegativeInteger opcionalIndica o número de linhas que um campo poderá ocupar. colspannonNegativeInteger opcionalIndica o número de colunas que um campo poderá ocupar. Indica a posição e o tamanho de um campo na janela. Esta marca só deverá aparecer uma vez por cada campo da janela (&ie; um por cada marca de <attr> e <label>). Este elemento fica vazio. Pai(s)Filhos label, attrNENHUM AtributoTipo UtilizaçãoDescrição rownonNegativeInteger necessárioIndica a linha na disposição da janela de um campo ou legenda. colnonNegativeInteger necessárioIndica a coluna na disposição da janela para um campo ou uma legenda. rowspannonNegativeInteger opcionalIndica o número de linhas que um campo poderá ocupar. colspannonNegativeInteger opcionalIndica o número de colunas que um campo poderá ocupar. Define o texto para uma legenda ou para uma opção. Este campo contém apenas texto. Pai(s)Filhos label, attrNENHUM Define uma lista dos elementos que podem aparecer dentro da marca a ser criada. Este elemento é do tipo apenas para elementos. Pai(s)Filhos tagchild Define uma marca-filha. Este elemento fica vazio. Pai(s)Filhos childrenNENHUM AtributoTipoValores UtilizaçãoDescrição namestring necessárioDefine uma marca que poderá aparecer dentro da marca indicada. usagestring opcionalIndica a relação com o pai. necessário O pai deverá ter pelo menos um filho com esse nome. Define uma lista dos elementos que obrigam a marca a terminar. Este elemento é do tipo apenas para elementos. Pai(s)Filhos tagstoppingtag Define uma marca de interrupção ou de fecho. Este elemento fica vazio. Pai(s)Filhos stoppingtagsNENHUM AtributoTipo UtilizaçãoDescrição namestring necessárioIndica quais as marcas que obrigam ao fecho de outra marca. Todos os ficheiros de TagXML deverão começar pela declaração de &XML;: <?xml version="1.0" encoding="UTF-8"?> e deverão estar devidamente aninhados e fechados. 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, nos elementos como o <tooltip>, o <whatsthis> e o <text>. Se não o fizer não irá estoirar o programa, mas poderá fazer com que certos pedaços do seu trabalho desapareçam, nesse caso. Para validar os seus ficheiros TagXML, basta carregar na janela das Ferramentas no topo do &quantaplus; e seleccionar Validar o TagXML. Irá então aparecer uma janela na qual você terá apenas de seguir as indicações simples. Esta funcionalidade de momento não está presente. Actualmente a validação ocorre quando os ficheiros TagXML são carregados no &quantaplus;. O seguinte irá mostrar um ficheiro de TagXML da Família 1 válido. Este ficheiro descreve também o elemento <schema> do &XML; Schema da &W3C;. O nome do ficheiro para este ficheiro TagXML seria então schema.tag. Simples, não é? <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE TAGS> <TAGS> <tag name="schema"> <label> <text>id</text> <location col="0" row="0"/> </label> <attr name="id" type="input"> <tooltip>Um ID único para o elemento.</tooltip> <whatsthis>Um ID único para o elemento.</whatsthis> <location col="1" row="0"/> </attr> <label> <text>version</text> <location col="0" row="1"/> </label> <attr name="version" type="input"> <tooltip>A versão do esquema.</tooltip> <whatsthis>A versão do esquema.</whatsthis> <location col="1" row="1"/> </attr> <label> <text>targetNamespace</text> <location col="0" row="2"/> </label> <attr name="targetNamespace" type="input"> <tooltip>Uma referência de &URI; para o espaço de nomes deste esquema.</tooltip> <whatsthis>Uma referência de &URI; para o espaço de nomes deste esquema.</whatsthis> <location col="1" row="2"/> </attr> <label> <text>xmlns</text> <location col="0" row="3"/> </label> <attr name="xmlns" type="input"> <tooltip>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema. Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.</tooltip> <whatsthis>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema. Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.</whatsthis> <location col="1" row="3"/> </attr> <label> <text>attributeFormDefault</text> <location col="0" row="4"/> </label> <attr name="attributeFormDefault" type="list"> <items> <item>qualified</item> <item>unqualified</item> </items> <tooltip>O formato por omissão para todos os atributos dentro deste esquema.</tooltip> <whatsthis>O formato por omissão para todos os atributos dentro deste esquema.</whatsthis> <location col="1" row="4"/> </attr> <label> <text>elementFormDefault</text> <location col="0" row="5"/> </label> <attr name="elementFormDefault" type="list"> <items> <item>qualified</item> <item>unqualified</item> </items> <tooltip>O formato por omissão para todos os elementos dentro deste esquema.</tooltip> <whatsthis>O formato por omissão para todos os elementos dentro deste esquema.</whatsthis> <location col="1" row="5"/> </attr> <label> <text>blockDefault</text> <location col="0" row="6"/> </label> <attr name="blockDefault" type="input"> <location col="1" row="6"/> </attr> <label> <text>finalDefault</text> <location col="0" row="7"/> </label> <attr name="finalDefault" type="input"> <location col="1" row="7"/> </attr> </tag> </TAGS> O seguinte irá mostrar-lhe um ficheiro TagXML da Família 2 válido. Este ficheiro descreve a função 'overload' do &PHP;. O nome do ficheiro TagXML seria overload.tag. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE tags> <tags> <tag name="overload" type="function" returnType="void"> <attr name="class_name" type="string" status="optional"/> </tag> </tags> O ficheiro &descriptionrc; também é bastante simples e existe um editor para ele, acessível através da opção DTDEditar a Configuração da DTD. Isto irá editar o &descriptionrc; de um &DTEP; que você poderá seleccionar numa lista. Para editar o &descriptionrc; para um &DTEP; acabado de criar, deverá criar um único &descriptionrc; com os seguintes itens: [General] Version = Use 1 para o &quantaplus; versão <=3.1.2 e 2 para as versões posteriores. Name = Texto de definição da DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN) NickName = O nome bonito da DTD. (HTML 4.01 Transitional). Se não estiver definido, o Name é usado como NickName. Logo que o tenha criado e colocado junto com os ficheiros de marcas, carregue o &DTEP; acabado de criar com a opção DTDCarregar o Pacote de DTD (DTEP) e, depois de carregado, você poderá prosseguir com a edição da configuração do &DTEP;. Verifique as dicas e o texto 'o que é isto' na janela do editor para compreender o significado de cada item. Em alternativa, poderá ler o ficheiro quanta/data/dtep/dtd-description.txt do pacote de código, que contém uma descrição do formato. As acções são muito comuns em todas as aplicações. Você necessita delas com frequência quando usa qualquer aplicação. Se carregar num ícone da barra de ferramentas, seleccionar um item do menu ou usar um atalho de teclado irá normalmente executar uma acção. No &quantaplus;, as acções são levadas a um outro nível. Em vez de ter as acções implementadas de forma estanque (criadas pelo programador da aplicação ao nível do código-fonte), é possível para um utilizador normal criar e modificar acções e, deste modo, adicionar novas funcionalidades ao &quantaplus;. Estas são as acções definidas pelo utilizador; muitas das acções normais do &quantaplus; são definidas pelo utilizador (e modificáveis pelo mesmo). Existem três tipos de acções definidas pelo utilizador: Acções de texto Acções de marcas Acções de programas Poderá criar uma acção se for a Configuração Configurar as Acções . Carregue em Nova Acção para que lhe apareça uma janela semelhante: Tipo Define o tipo da acção (Texto, Marca, Programa). Texto O nome da acção visível para o utilizador. O botão perto da legenda do Texto O ícone atribuído a esta acção. Carregue nele para mudar o ícone actual. Dica Uma breve descrição do que a acção faz. Atalho O atalho atribuído a esta acção. Carregue em Personalizado ou no botão perto de Personalizado para atribuir um atalho; carregue em Nenhum para remover o atalho atribuído de momento. Barras de Ferramentas de Contentores As barras de ferramentas definidas pelo utilizador onde esta acção irá aparecer. Veja em . Configuração Detalhada A configuração específica para o tipo diferente de acções. Veja em baixo. As acções mais simples. Poderá indicar algum texto na Configuração Detalhada e, sempre que a acção for executada, este texto será inserido no seu documento, na posição actual do cursor. Veja o exemplo em baixo. É útil para introduzir marcas de XML, mas claro que as poderá usar para outros fins. <marca> O nome da marca. </marca> Se estiver assinalado, quando a acção for executada, este texto será inserido como uma marca de fecho. Se existir alguma área seleccionada no documento, antes de você executar a acção, a <marca> será inserida antes da área seleccionada e a </marca> a seguir. Correr o "Editar a marca" se disponível Se estiver assinalada e existir um ficheiro tagXML para esta marca, irá aparecer uma janela de edição da marca antes de a introduzir dentro do documento, para que possa definir os atributos da mesma. A <marca> e a </marca> serão introduzidas tal e qual as indicou aí. O <, o > ou o sinal de / não serão adicionados automaticamente. O tipo de acção mais poderoso. Com a ajuda desta acção, poderá executar aplicações externas (normalmente programas, embora não esteja limitado a estes), que poderão alterar o seu documento ou usá-lo (ou parte deste) como dados de entrada. Os exemplos do próprio &quantaplus; são a janela de Introdução e as várias acções de Ver Em... dos DTEPs de (X)HTML. Primeiro, terá de introduzir o nome do seu programa, acompanhado do interpretador. Exemplo: sh /home/aMinhaArea/oMeuPrograma.sh. Ainda que possa usar localizações completas, a forma recomendada será usar a variável %scriptdir na linha de comandos, como por exemplo sh %scriptdir/oMeuPrograma.sh. Desta forma, o &quantaplus; irá tentar localizar o seu programa nos seguintes locais: pasta de programas globais: $TDEDIR/share/apps/quanta/scripts pasta de programas locais: $TDEHOME/share/apps/quanta/scripts a sua 'path': $PATH Existem outras variáveis especiais que poderá usar na linha de comandos: %f: será substituída pelo URL do documento actual. No caso dos documentos locais, o 'file:/' será retirado do documento. %input: será substituído pela entrada seleccionada. Veja em baixo. %projectbase: será substituído pelo URL do projecto actual. Estará em branco se não estiver nenhum projecto carregado. %pid: será substituído pelo PID do processo do &quantaplus; em execução. Se o &quantaplus; estiver a correr em modo único, o texto "único " será colocado antes do número do PID. É útil quando você usa o DCOP para controlar o &quantaplus; a partir do programa externo. %userarguments: é útil no caso dos eventos. Este item será substituído pelas propriedades do evento na seguinte ordem: Primeiro argumento O identificador único do 'script' Segundo argumento o nome do evento Terceiro argumento os parâmetros do evento, sendo normalmente o nome do documento actual ou a localização do ficheiro do projecto. Para além dos métodos normais, o programa poderá receber dados à entrada do &quantaplus; no 'standard input'. Na lista Entrada, poderá seleccionar o que é enviado para o 'standard input'. As opções são: Nenhum: não é enviado nada para o programa. Documento actual: é enviado o documento inteiro para o programa. Texto seleccionado: a área seleccionada do documento é enviada para o programa. A utilização da variável %input faz normalmente sentido só quando se usa esta opção. De forma semelhante à Entrada, você poderá capturar o resultado da aplicação executada. Existem dois tipos de saídas: a saída normal, que é impressa no 'standard output'; as mensagens de erro, que são impressas no 'standard error'. Poderá indicar o que deverá acontecer ao texto impresso para o 'standard output'. Isto pode ser feito se modificar o valor da lista da Saída: Nenhum: o resultado da aplicação é ignorado. Inserir na posição do cursor: o resultado será inserido no documento actual, mais concretamente na posição do cursor. Substituir a selecção: a área seleccionada no documento será substituída pelo resultado. Substituir a selecção: a área seleccionada no documento será substituída pelo resultado. Criar um novo documento: será criado um novo documento que irá conter o resultado do programa. Substituir o documento actual: o documento inteiro será substituído pelo resultado. Janela de mensagem: o resultado irá aparecer na área de Mensagens. As escolhas para o resultado do 'standard error' (Erros) são as mesmas que para o resultado normal. O seguinte irá mostrar como criar barras de ferramentas para um &DTEP;. As barras de ferramentas são elementos gráficos que se encontram associados a acções. As acções no &quantaplus; 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. Para começar, você irá precisar de criar uma barra de ferramentas do utilizador. Seleccione a opção Barras de Ferramentas Adicionar uma Barra de Ferramentas do Utilizador . Se existirem várias marcas para a linguagem de formatação, recomenda-se que você divida as marcas em grupos lógicos. Irá precisar de criar uma nova barra de ferramentas do utilizador para cada grupo. Neste caso, não existem muitas, por isso vamos criar apenas uma barra de ferramentas e dar-lhe o nome da formatação. Logo que todas as suas barras de ferramentas forem criadas, você precisa adicionar e configurar as acções. Para o fazer, seleccione Configuração Configurar as Acções . As componentes desta janela são relativamente intuitivas. Carregue no botão Nova acção no fundo da janela para entrar no modo de edição. Preencha todos os campos necessários e adicione a marca à(s) barra(s) de ferramentas apropriada(s). Complete o resto e, se a marca tiver atributos e planeia usá-los sempre, assinale a opção Correr a janela "Editar a marca" se disponível de modo a que não tenha de ser avisado de cada vez que a acção é usada. Agora você deverá ter algo muito semelhante ao seguinte. Carregue no botão Aplicar para ver a acção adicionada à barra ou barras de ferramentas que seleccionou. Ui! Este é um ícone horrível. Como é que você próprio e os outros irão recordar que aquele ícone corresponde a aquela acção? Vamos substitui-lo antes que haja problemas. Para criar um ícone que descreva de forma mais adequada essa acção, nós iremos usar o &kiconedit;. Seleccione-o no &kmenu;, Gráficos Mais Programas (ou onde quer qe a sua distribuição o tenha posto). O &kiconedit; usa por omissão o tamanho de 32x32 pixels, mas nós precisamos do tamanho 22x22. Para o alterar, seleccione Editar Redimensionar . Lembre-se que você está a criar um ícone que o irá ajudar não só a si a lembrar o objectivo daquela acção, mas também aos outros utilizadores do &DTEP;. Dado que a marca para a qual estou a criar o ícone se chama iniciar, decidi criar um ícone de sinal de Iniciar. Ao usar a cor verde (o verde é normalmente interpretado como seguir, iniciar, ou prosseguir) irá, ou pelo menos é suposto, fornecer ao utilizador uma mensagem de que, se carregar nesta acção, irá colocar a marca de <inicio> no documento actual. Agora que terminei a criação do ícone, vou então gravá-lo. Logo que tenha acabado de criar o ícone ou ícones, você precisa associar o ícone à acção. Para o fazer, abra a Configuração Configurar as Acções de novo (no &quantaplus;) e seleccione a acção para a qual criou o ícone. Para além do campo de Texto, você irá ver um botão; neste momento, carregue no mesmo. Seleccione Outros Ícones e carregue então no botão Escolher. Vá para a pasta na qual gravou o ícone, seleccione o mesmo e carregue em OK. Carregue no botão Aplicar e poderá então continuar a fazer o mesmo com as outras marcas, se existirem, ou poderá então carregar em OK para terminar. Digamos que você desejaria adicionar mais algumas funções comuns do &quantaplus; à sua barra de ferramentas ou então acharia que a barra de ferramentas ficaria melhor se ficasse arrumada com alguns separadores para agrupar as acções. Abra a janela de Configurar as Barras de Ferramentas indo à opção Configuração Configurar as Barras de Ferramentas . Certifique-se que a sua barra de ferramentas está seleccionada. Irei então escolher o separador (em cima na coluna da esquerda) para a minha barra de ferramentas. Logo que você tenha seleccionado o item que deseja adicionar à sua barra de ferramentas, carregue no botão com a seta para a direita. Isto irá adicioná-lo à sua barra de ferramentas. Penso que gostaria de uma forma mais rápida de aceder à Antevisão no Konqueror. Irei então seleccioná-la e adicioná-la à barra de ferramentas. Repare como o separador ajuda a agrupar. Alguém que não conhecesse bem a minha barra de ferramentas poderia ter pensado que o botão do &konqueror; seria semelhante ou o oposto do botão de início. Aplique as suas alterações e, quando tiver terminado, carregue em OK para terminar. Ah, veja a nova e fantástica barra de ferramentas! Muito mais útil agora. Lembre-se de testar a sua barra de ferramentas, carregando em todos os botões, de modo a que saiba que o resultado é o correcto. Agora, para gravar a barra de ferramentas, iremos seleccionar a opção Barras de Ferramentas Gravar as Barras de Ferramentas Gravar como Barra de Ferramentas Local . Grave-a na pasta correcta. Dado que a NeXML não existe, irei tê-la apenas na pasta de topo, mas as suas barras de ferramentas deverão ser gravadas na pasta correcta. Certifique-se que ajusta o seu &descriptionrc; para que este carregue as mesmas barras de cada vez que um ficheiro desse tipo é criado. Robert Nickel

robert@artnickel.com

PedroMorais

morais@kde.org

Tradução Provavelmente as adições mais notáveis ao &quantaplus; 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 &quantaplus; 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 '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 docrc está repartido em duas secções: Tree (árvore) e Context (contexto). 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 pastas 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 &quantaplus;. A secção Context é a secção do ficheiro 'docrc' que é usada para facilitar a ajuda dependente do contexto. Por exemplo, você está a fazer um programa em &PHP; e deseja ver a documentação para a função mysql_fetch_array. Basta você seleccionar a função e carregar então em &Ctrl;H para obter a ajuda de contexto. A documentação do mysql_fetch_array irá aparecer imediatamente. Existem apenas dois tipos de itens aqui: o ContextList e as linhas de associações de ficheiros. ContextList Muito simplesmente, isto é apenas uma lista separada por vírgulas dos itens de contexto que você deseja ter disponíveis (para o &PHP;, estas serão as funções de &PHP;). Linhas de associação de ficheiros Estas estão no formato de item de contexto=página HTML de documentação, ⪚ acos=funcao.acos.html Uma versão muito resumida da minha secção Context do docrc encontra-se a seguir: #Palavras-chave para a ajuda de contexto [Context] ContextList=abs,acos,acosh,addcslashes,addslashes,... abs=funcao.abs.html acos=funcao.acos.html acosh=funcao.acosh.html addcslashes=funcao.addcslashes.html addslashes=funcao.addslashes.html ... Agora poderá gravar o seu ficheiro docrc, colocá-lo na pasta $HOME/.trinity/share/apps/quanta/doc ou em $TDEDIR/share/apps/quanta/doc para o uso local ou global, respectivamente. Crie então uma pasta (a especificada no seu ficheiro 'docrc') na mesma pasta que no seu ficheiro 'docrc' e copie as suas páginas de documentação em &HTML; para lá. Terá de reiniciar o &quantaplus; 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 &quantaplus; 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. Com o &quantaplus;, você não está sozinho. É possível partilhar os vários recursos (pacotes DTEP, barras de ferramentas com acções, programas, modelos) com outras pessoas. Existem duas formas de o fazer: Enviar por E-mail Os recursos poderão ser enviados por e-mail para os seus amigos, colegas ou para quem você quiser. Irá ver os itens de menu Enviar por E-mail em vários sítios, como o DTDEnviar o Pacote de DTD (DTEP) por E-mail, Barras de FerramentasEnviar a Barra de Ferramentas por E-mail, no menu de contexto dos ficheiros e pastas dos e na árvore de Modelos e 'Scripts'. Enviar para o servidor principal Os recursos podem ser remetidos para o nosso repositório principal, a partir do qual todos os outros utilizadores do &quantaplus; os poderão obter. Os envios são revistos e disponibilizados, se a nossa equipa considerar que estão correctos e são úteis. Para fazer um envio válido, sugere-se que assine os recursos, pelo que irá necessitar de uma chave de GPG/PGP. Esta informação é usada para verificar a origem dos recursos, tanto pela nossa equipa como por quem irá obter os recursos. Para saber como obter os recursos do servidor principal, veja em . Ao enviar, ser-lhe-á pedido para indicar a senha da sua chave privada de GPG (a senha não será gravada) ou, no caso de ter mais chaves privadas, poderá escolher a que deseja usar. Na janela para Partilhar Coisas Novas, preencha os campos de entrada (o URL de Antevisão poderá ficar em branco) e inicie o envio, carregando para tal em OK. O envio poderá ser iniciado em DTDEnviar o Pacote do DTD (DTEP), Barras de FerramentasEnviar a Barra de Ferramentas, no menu de contexto dos ficheiros e pastas na árvore de Modelos e 'Scripts'. É possível actualizar o seu &quantaplus; sem obter uma versão nova, obtendo os recursos novos como os pacotes DTEP, as barras de ferramentas com acções, modelos, 'scripts' e documentação. Uma possibilidade será que você obteve os recursos por e-mail ou a partir de um servidor Web; nesses casos, você terá de os instalar manualmente. Se teve sorte, você também obteve um programa de instalação no local de onde transferiu os recursos. Contudo, o &quantaplus; tem um servidor dedicado que mantém os recursos que não foram instalados na distribuição principal, devido aos seus tamanhos ou a utilizações pouco frequentes ou que foram contribuídos posteriormente pelos utilizadores, sendo estes recursos instalados automaticamente. Para obter esses recursos, use os vários itens de menu para Obter. Você poderá encontrá-los em DTDObter o Pacote de DTD (DTEP), Barras de FerramentaObter Barra de Ferramentas, no menu de contexto ou numa área vazia ou num item de topo nas árvores de Modelos, 'Scripts' e Documentação. Depois de obter um recurso, mas antes de o instalar, o &quantaplus; verifica se o recurso é válido, verificando a integridade e a assinatura. No caso de ocorrerem problemas, ele avisá-lo-á e você poderá decidir se deseja continuar ou não. Por favor reveja as janelas de avisos com cuidado. No caso de a integridade ser correcta e o recurso estar devidamente assinado, você irá obter à mesma uma janela de informação, para que possa ver quem criou o recurso. Certifique-se que instala os recursos, principalmente as barras de ferramentas e os 'scripts', apenas a partir de fontes de confiança! É possível trabalhar em linguagens de XML que não sejam suportadas de momento pelo &quantaplus; se criar um pacote DTEP. Contudo, a criação poderá levar bastante tempo, dado que poderá ter de indicar centenas de ficheiros de marcas no formato tagXML. Obviamente, existe uma forma melhor de o fazer, convertendo a DTD automaticamente para um pacote DTEP. A conversão poderá ser iniciada a partir da opção do menu DTDCarregar e Converter a DTD. Seleccione o ficheiro .dtd que define a DTD que deseja usar, onde irá ver a janela seguinte: Os itens são: Nome da pasta-alvo:o &DTEP; acabado de criar irá parar, com este nome, à pasta $TDEHOME/share/apps/quanta/dtep. Nome:: o nome (texto de definição) da DTD Nome alternativo:: o nome visível para o utilizador do &DTEP; Linha de definição do !DOCTYPE: o texto que deverá aparecer na marca !DOCTYPE, como por exemplo HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd" URL da DTD: o URL que aponta para o ficheiro da DTD Extensão por omissão: a extensão que será usada normalmente para os ficheiros que foram escritos nesta DTD Marcas e atributos com distinção de maiúsculas: esta opção costuma estar assinalada para o caso das variantes da linguagem XML Afinar o DTEP após a conversão: se estiver assinalado, após a conversão, o &quantaplus; irá invocar o editor do &descriptionrc;, de modo a que você possa afinar alguns detalhes do &DTEP; acabado de criar. Recomenda-se que deixe esta opção assinalada.