The K Desktop Environment

6.4. Utilizar o Navegador de Documentação

O navegador de documentação permite acesso rápido e fácil a todos os manuais e documentações que são disponibilizadas com o KDevelop ou geradas automaticamente, incluindo documentação electrónica para as bibliotecas KDE e a documentação do seu projecto. Mais, a Árvore de Documentação na vista de árvore permite-lhe costumizar uma pasta especial "Outras" que contém toda a documentação adicionada individualmente.

6.4.1. Requisitos

Para fazer uso de todas as funcionalidades do Navegador de Ajuda, deverá ter o KDoc e o glimpse instalados. O KDoc irá gerar todo o tipo de documentação electrónica de classes para as bibliotecas KDE durante o processo de instalação, mas pode também ser invocado por opção na Configuração do KDevelop. Para a geração de uma Documentação da API (Application Programming Interface - Interface de Programação da Aplicação) para as classes do seu projecto, o KDoc é também utilizado e chamado pelo menu Construir, entrada "Fazer Doc-API". Isto irá processar todos os ficheiros header actuais do projecto mais uma referência cruzada com as bibliotecas da Qt e KDE se estas estiverem disponíveis no Navegador de Ajuda. Para a geração de manuais do projecto, deverá ter o ksgml2html (disponibilizado com o KDE-SDK ) e, como um mínimo, as ferramentas SGML instaladas no seu sistema. Para aumentar e modificar a documentação electrónica do seu projecto, tem de editar o ficheiro de documentação do seu projecto seleccionando-o no VFR. Após gravar as suas modificações, chame "Fazer Manual do Utilizador" a partir do menu Construir. No caso das ferramentas sgml detectarem erros de formatação, estes serão apresentadas na janela de output permitindo-lhe descobrir directamente a linha com o erro. O programa "glimpse" é utilizado para criar automaticamente um índice de busca pessoal para a sua documentação. O índice é geralmente construido durante o processo de instalação, mas pode também ser construido com o diálogo da Configuração do KDevelop. Para uma descrição das funções de busca disponibilizadas veja Utilizar o Índice de Busca.

6.4.2. Documentação Disponibilizada

O ambiente de desenvolvimento KDevelop vem com dois conjuntos de documentação electrónica, que podem ser acedidos quer através do menu Ajuda ou através da árvore de documentação na Vista de Árvore na pasta do KDevelop. O primeiro livro apresentado é o manual electrónico contendo toda a informação de que poderá necessitar no sentido de instalar, configurar, funcionalidades disponíveis e introdução ao desenvolvimento de aplicações. O segundo livro é o Manual de Programação do KDevelop na sua primeira edição. O manual de programação cobre a maior parte das questões relativas à criação e expansão de projectos que funcionem com o KDevelop. Através de explicações passo-a-passo o utilizador obtém uma introdução às ricas potencialidades que aplicações criadas com as bibliotecas da Qt e/ou KDE têm a oferecer bem como dar linhas mestras para assegurar compatibilidade com o KDE , o que cobre as mesmas instruções dadas na página de internet do http://developer.kde.org. No entanto, o manual de programação não pode ser substituido por nenhuma documentação adicional disponível em formato impresso ou electrónico sobre a linguagem de programação C++ bem como sobre a utilização da biblioteca Qt sob certos termos.

A Referência C/C++ utiizada com o KDevelop é actualmente a única disponível na página de internet do KDevelop em http://www.kdevelop.org. Pode ser instalada facilmente puxando o ficheiro e copiando o código fonte para o directório principal do KDE ($KDEDIR). Aí, tem de descomprimir o ficheiro como root com tar zxvf c_c++_reference.tar.gz, a referência será então copiada para o directório de documentação do KDevelop. Para desinstalar a documentação de referência apenas tem de apagar o directório "reference" em ($KDEDIR)/share/doc/HTML/default/kdevelop/reference.

A pasta de documentação das bibliotecas Qt/KDE permite acesso directo à documentação electrónica da sua cópia da biblioteca Qt. O caminho para a documentação da biblioteca é normalmente detectado pelo programa de instalação do KDevelop, mas pode ser definido manualmente no diálogo de Configuração do KDevelop. Também, toda a documentação disponível para as bibliotecas KDE são listadas por ordem de nome de biblioteca, pelo qie se você utilizar classes de uma dada biblioteca é fácil determinar o tipo de biblioteca a ser adicionada às definições de linkagem do projecto. Lembre-se de que toda a documentação da biblioteca KDE apenas é acessível quando gerada pelo KDoc- pelo que este programa, incluido no KDE-SDK , tem de estar instalado antes da documentação poder ser gerada. Como o programa de instalação do KDevelop faz isto automaticamente, deve ser instalado antes do KDevelop ser iniciado pela primeira vez. Se este não for o caso e a documentação não conseguir ser construida, é-lhe possível cria-la posteriormente a qualquer momento através do diálogo Configuração do KDevelop.

A árvore de documentação das bibliotecas é seguida de uma pasta "Outros" que se destina a conter toda a documentação costumizada pessoalmente como descrito abaixo. Finalmente, a Árvore de Doc permite um acesso rápido à API de um Projecto e ao Manual do Projecto para o projecto actual.

6.4.3. Adicionar Documentação ao Navegador de Ajuda

Para costumizar o Navegador de Ajuda, abra a Vista de Árvore e seleccione a pasta "ADOC". Verá uma árvore aberta chamada Documentação, contendo quatro pastas. A pasta "Outras" está, por defeito, vazia. Com um clique do botão direito do rato sobre esta pasta, um menu de contexto abre e possui uma entrada "Adicionar Entrada". Seleccione este para abrir o diálogo de Adicionar Entrada onde terá de inserir dois valores: o de cima para o nome que será apresentado para a documentação dentro da árvore de Doc, e, por baixo dessa, uma linha de entrada de ficheiro. Aqui, tem de inserir o caminho e nome de ficheiro para a página inicial que será aberta pela selecção da entrada mais tarde. Você pode indicar o caminho e nome de ficheiro directamente ou selecciona-lo premindo um botão à direita para abrir um diálogo de escolha de ficheiro. Isto permite uma visão rápida do seu sistem até ao caminho para a sua página inicial. Lembre-se que apenas documentação HTML pode ser seleccionada, pelo que apenas é possível escolher ficheiros HTML. Seleccionando OK irá adicionar a entrada à árvore de Doc e encontra-se desde logo disponível.

6.4.4. Utilizar o Índice de Busca

O KDevelop inclui um conjunto de funções para ajudar a busca de informação dentro da documentação HTML. Para utilizar estas funcionalidades, o seu sistema tem de ter o programa "glimpse", um gerador de bases de dados gratuito, instalado, que irá criar o índice de busca e executar as procuras dentro da documentação. Para definir o índice, veja Configuração do KDevelop. O índice é também gerado automaticamente durante o programa de instalação.

As funções de busca estão disponíveis através de várias formas que pode escolher:

  1. no editor, seleccione o texto sobre o qual deseja ter ajuda ou coloque o cursor na palavra que deseja procurar. Depois prima o botão direito do rato e seleccione procurar: "expressão" Isto também pode ser feito seleccionado "Procurar Texto Marcado" a partir do menu de ajuda, da tecla de atalho F2 ou seleccionando o icon de Busca a partir da barra de ferramentas.

  2. no Navegador de Documentação seleccione o texto que deseja procurar e prima o botão direito do rato, seleccione procurar :"expressão" ou seleccione "Procurar Texto Marcado" ou o icon de busca como acima.

  3. se deseja procurar uma palavra chave específica, seleccione "Procurar Ajuda sobre..." no menu de ajuda ou seleccione o icon "Procurar Ajuda sobre..." a partir da barra de ferramentas, abrindo um diálogo de busca onde poderá inserir a expressão sobre a qual deseja obter informações.

Acesso directo a documentação específica é dado seleccionando o icon correspondente na vista de árvore "ADOC" ou através das entradas do menu de ajuda.

O Navegador de Ajuda também disponibiliza suporte para grep para procurar por uma selecção dentro do projecto actual, por ex. você abriu a página de documentação para a classe KTMainWindow (biblioteca KDEUI) e deseja saber onde no seu código KTMainWindow surge. Marque KTMainWindow e seleccione "Grep: KTMainWindow" ou então prima Shift+F2. O diálog "Procurar nos Ficheiros" abre com os resultados sobre a sua busca grep directamente. Depois pode escolher uma linha de resultado e ir para o código fonte respectivo.