<chapter id="setup">

<chapterinfo>
  <authorgroup>
    <author
><firstname
>Bernd</firstname
><surname
>Pol</surname
></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title
>Configurar o &kdevelop;</title>

<para
>O &kdevelop; é um IDE muito poderoso e flexível que oferece muitas formas de o ajustar às suas necessidades. Para iniciar a configuração, seleccione <menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Configurar o KDevelop...</guimenuitem
></menuchoice
>. Isto fará com que a janela de configuração se abra, consistindo numa janela de selecção à esquerda e na janela de configuração à direita, cujo conteúdo irá variar de acordo com o item de configuração que seleccionou. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-select.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Seleccionar um item de configuração </para
></caption>
  </mediaobject>
</screenshot>

<para
>Iremos discutir estas configurações por uma ordem diferente, dividindo nos tópicos principais da <link linkend="setup-general"
>Configuração Geral</link
>, <link linkend="setup-docu"
>Configurar a Documentação</link
> e <link linkend="setup-advanced"
>Configuração Avançada</link
>, o que causa uma leitura mais intuitiva. </para>
<para
>Se quiser ver directamente um certo item de configuração, use uma das seguintes referências. </para>
<simplelist>
  <member
><link linkend="setup-main"
>Geral</link
></member>
  <member
><link linkend="setup-plugins"
>'Plugins'</link
></member>
  <member
><link linkend="setup-format"
>Formatador de Código</link
></member>
  <member
><link linkend="setup-new-file-wizard"
>Assistente de Novo Ficheiro</link
></member>
  <member
><link linkend="setup-ui"
>Interface do Utilizador</link
></member>
  <member
><link linkend="setup-editor"
>Editor</link
></member>
  <member
><link linkend="setup-abbrev"
>Abreviaturas</link
></member>
  <member
><link linkend="setup-menu-standard"
>O Menu Ferramentas</link
></member>
  <member
><link linkend="setup-menu-external"
>Ferramentas Externas</link
></member>
  <member
><link linkend="setup-docu"
>Documentação</link
></member>
  <member
><link linkend="setup-snippets"
>Pedaços de Código</link
></member>
  <member
><link linkend="setup-fileselector"
>Selector de Ficheiros</link
></member>
</simplelist>

<sect1 id="setup-general">
<title
>Configuração Geral</title>

<para
>A configuração geral diz respeito às tarefas mais comuns de ajuste do &kdevelop; e consistem em: </para>
<itemizedlist>
  <listitem
><para>
  <link linkend="setup-main"
>Configuração Geral</link>
  </para
></listitem>
  <listitem
><para>
  <link linkend="setup-ui"
>Seleccionar a Interface do Utilizador</link>
  </para
></listitem>
  <listitem>
    <para
>Tarefas de Edição do Código </para>
    <itemizedlist>
      <listitem
><para>
      <link linkend="setup-editor"
>Seleccionar um Editor</link>
      </para
></listitem>
      <listitem
><para>
      <link linkend="setup-format"
>Seleccionar um Estilo de Formatação de Código</link>
      </para
></listitem>
      <listitem
><para>
      <link linkend="setup-snippets"
>Configurar a Ferramenta de Excertos de Código</link>
      </para
></listitem>
    </itemizedlist>
  </listitem>
  <listitem
><para>
  <link linkend="setup-fileselector"
>Configurar o Selector de Ficheiros</link>
  </para
></listitem>
</itemizedlist>

<sect2 id="setup-main">
<title
>Configuração Geral</title>

<para
>A janela de configuração <guilabel
>Geral</guilabel
> permite-lhe definir algum comportamento básico do &kdevelop; que irá mudar pouco no dia-a-dia. Isto respeita a: </para>
<itemizedlist>
  <listitem>
    <para
>Opções gerais do projecto </para>
    <itemizedlist>
      <listitem
><para
>definir uma <link linkend="setup-main-projects"
>directoria-mãe por omissão</link
>, que o &kdevelop; deverá usar para os projectos novos. </para
></listitem>
       <listitem
><para
>decidir se quer que o &kdevelop; <link linkend="setup-main-preload"
>carregue automaticamente</link
> o projecto onde estava a trabalhar da última vez. </para
></listitem>
   </itemizedlist>
  </listitem>
  <listitem>
    <para
>Seleccionar um tipo de letra para as janelas de resultados usadas mais frequentemente, nomeadamente </para>
    <itemizedlist>
      <listitem
><para
>a <link linkend="setup-main-messages-font"
>Janela de Mensagens de Resultado</link
> que o &kdevelop; usa para apresentar &eg; o progresso da compilação e </para
></listitem>
      <listitem
><para
>a <link linkend="setup-main-applications-font"
>Janela de Resultado da Aplicação</link
> que irá mostrar as mensagens de erro e de estado respeitantes a uma aplicação em execução. </para
></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
    <para
>Algum comportamento comum respeitante às linhas apresentadas na <guilabel
>Janela de Mensagens</guilabel
>, como por exemplo </para>
    <itemizedlist>
      <listitem
><para
>se as linhas compridas serão <link linkend="setup-main-wrap"
>repartidas</link
> e </para
></listitem>
      <listitem
><para
>se <link linkend="setup-main-navigation"
>as mensagens de entrada e saída das directorias</link
> geradas pelo <command
>Make</command
> serão apresentadas. </para
></listitem>
    </itemizedlist>
  </listitem>
  <listitem
><para
>O <link linkend="setup-main-compile"
>nível de detalhe</link
> das mensagens correspondentes ao processo de compilação mostrado na janela de <guilabel
>Mensagens</guilabel
>. </para
></listitem>
</itemizedlist>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-general.png" format="PNG"/>
    </imageobject>
    <caption
><para
>A janela de configuração geral </para
></caption>
  </mediaobject>
</screenshot>

<formalpara id="setup-main-preload">
<title
>Carregar o Último Projecto no Arranque</title>

<para
>Assinale esta opção se deseja continuar a trabalhar no último projecto em que trabalhou. Isto fará com que o &kdevelop; carregue automaticamente este projecto no arranque. Será normalmente mostrado no estado em que você deixou o trabalho, para que possa continuar da mesma forma. </para>
</formalpara>

<formalpara id="setup-main-projects">
<title
>Directoria do Projecto por Omissão</title>
<para
>Por omissão, o &kdevelop; usa uma directoria de base comum para todos os projectos novos. Indique a localização absoluta desta directoria comum no campo de texto respectivo ou seleccione-a na sua estrutura de directorias. O &kdevelop; irá colocar os projectos novos aqui como subdirectorias desta. </para>
</formalpara>
<note
><para
>Você poderá, obviamente, mudar a localização de um projecto novo na altura em que o configurar no <link linkend="applicationwizard"
>&appwizard;</link
>. </para
></note>

<formalpara id="setup-main-messages-font">
<title
>Tipo de Letra da Janela de Mensagens</title>
<para
>Para seleccionar um tipo de letra adequado para a <guilabel
>Janela de Mensagens</guilabel
>, carregue no botão do <guilabel
>Tipo de Letra da Janela</guilabel
> que mostra o tipo de letra actual (na imagem acima, diz <quote
>Luxi Sans</quote
>). Irá então aparecer a janela normal do &kde; para <guilabel
>Seleccionar o Tipo de Letra</guilabel
>, na qual voce poderá seleccionar o tipo de letra a ser usado. </para>
</formalpara>
<note
><para
>No primeiro arranque, o &kdevelop; inicializa esta configuração do tipo de letra com base no tipo de letra normal que o seu utilizador do &kde; tem configurada. <emphasis
>Esta configuração é fixa</emphasis
>, por isso, se você alterar as  <menuchoice
><guimenuitem
>Preferências</guimenuitem
><guimenuitem
>Aparência &amp; Temas</guimenuitem
><guimenuitem
>Tipos de Letra</guimenuitem
></menuchoice
> no <guilabel
>Centro de Controlo</guilabel
>, isto irá afectar esta selecção de tipo de letra do &kdevelop;. Você terá de seleccionar de novo explicitamente o tipo de letra da <guilabel
>Janela de Mensagens</guilabel
>. </para
></note>

<formalpara id="setup-main-wrap">
<title
>Mudança de Linha</title>
<para
>Por omissão, o &kdevelop; irá repartir as linhas compridas na janela de <guilabel
>Mensagens</guilabel
>, de modo que a informação valiosa não será ignorada com facilidade. Nalguns casos, isto irá gerar listas de mensagens grandes e confusas. Desligue a opção se não quiser que as linhas sejam repartidas. </para>
</formalpara>
<tip
><para
>Existe uma forma alternativa de alterar a mudança de linha. Basta carregar com o &RMB; na <guilabel
>Janela de Mensagens</guilabel
> e assinalar ou desligar o item <guimenuitem
>Mudança de Linha</guimenuitem
> do menu que irá aparecer. </para
></tip>

<formalpara id="setup-main-navigation">
<title
>Mensagens de Navegação nas Directorias</title>
<para
>A ferramenta <command
>Make</command
> normalmente irá mostrar linhas do tipo <quote
>Entering directory</quote
> (A entrar na directoria), ou <quote
>Leaving directory</quote
> (A sair da directoria), quando ele muda de directoria de trabalho. dado que isto enche a lista de mensagens na janela de <guilabel
>Mensagens</guilabel
>, o &kdevelop; suprime estas mensagens por omissão. Assinale a opção se quiser saber que directorias o <command
>Make</command
> processou. </para>
</formalpara>
<note
><para
>As alterações desta opção farão efeito apenas no processamento das mensagens novas. As mensagens antigas de navegação nas directorias ficarão à mesma visíveis quando você desligar esta funcionalidade. </para
></note>

<formalpara id="setup-main-compile">
<title
>Resultado do Compilador</title>
<para
>O &kdevelop; faz um pré-processamento que a janela das <guilabel
>Mensagens</guilabel
> recebe durante os processos de compilação, de modo a filtrar a informação supérflua. Você poderá controlar o nível de detalhe que o &kdevelop; irá mostrar com as opções exclusivas deste campo. </para>
</formalpara>
<variablelist>
  <varlistentry>
    <term
><guilabel
>Muito Curto</guilabel
></term>
    <listitem
><para
>Mostra apenas os avisos, erros e os ficheiros que estão a ser compilados. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Curto</guilabel
></term>
    <listitem
><para
>Suprime todas as opções do compilador e forma o resultado para ser mais legível. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Completo</guilabel
></term>
    <listitem
><para
>Mostra todas as mensagens sem modificações. </para
></listitem>
  </varlistentry>
</variablelist>

<tip
><para
>Existe uma forma alternativa de mudar o detalhe do resultado do compilador. Basta carregar com o &RMB; na janela de <guilabel
>Mensagens</guilabel
> e seleccione o nível de detalhe adequado no menu de contexto. </para
></tip>

<formalpara id="setup-main-applications-font">
<title
>Tipo de Letra da Janela do Resultado da Aplicação</title>
<para
>A janela do <guilabel
>Resultado da Aplicação</guilabel
> é usada par amostrar as mensagens de erro e de estado das aplicações que são executadas dentro do &kdevelop;. Estas são informações que a aplicação manda normalmente para a consola quando é executada autonomamente. Por isso, não precisa de sair do IDE ao testar a aplicação em que está a trabalhar. </para>
</formalpara>
<para
>Para seleccionar um tipo de letra adequado para a <guilabel
>Janela do Resultado da Aplicação</guilabel
>, carregue no botão do <guilabel
>Tipo de Letra da Janela</guilabel
>, que mostra o tipo de letra seleccionado de momento (ele diz <quote
>Luxi Sans</quote
> na imagem acima). A janela normal do &kde; para <guilabel
>Seleccionar o Tipo de Letra</guilabel
> irá aparecer, no qual poderá seleccionar o tipo de letra a usar. </para>
<note
><para
>No primeiro arranque, o &kdevelop; inicializa esta configuração do tipo de letra com base no tipo de letra normal que o seu utilizador do &kde; tem configurada. <emphasis
>Esta configuração é fixa</emphasis
>, por isso, se você alterar as  <menuchoice
><guimenuitem
>Preferências</guimenuitem
><guimenuitem
>Aparência &amp; Temas</guimenuitem
><guimenuitem
>Tipos de Letra</guimenuitem
></menuchoice
> no <guilabel
>Centro de Controlo</guilabel
>, isto irá afectar esta selecção de tipo de letra do &kdevelop;. Você terá de seleccionar de novo explicitamente o tipo de letra da <guilabel
>Janela de Resultados da Aplicação</guilabel
>. </para
></note>

</sect2
> <!-- setup-main -->

<sect2 id="setup-ui">
<title
>Seleccionar a Interface do Utilizador</title>

<indexterm zone="setup-ui">
  <primary
>interface do utilizador</primary>
  <secondary
>mudar de modos</secondary
></indexterm>
<indexterm zone="setup-ui">
  <primary
>mudar de modo de interface</primary
></indexterm>

<para
>Como já foi dito nos <link linkend="uimodes-survey"
>Modos Disponíveis de Interface do Utilizador</link
>, existem quatro formas diferentes no &kdevelop; para configurar o espaço de trabalho, sendo eles: </para>
<itemizedlist>
  <listitem
><para>
  <link linkend="ideal-desc"
>Modo IDEAl</link>
  </para
></listitem>
  <listitem
><para>
  <link linkend="mdi-desc"
>Modo de Janelas com Sub-molduras</link>
  </para
></listitem>
  <listitem
><para>
  <link linkend="tabbed-desc"
>Modo por Páginas</link>
  </para
></listitem>
  <listitem
><para>
  <link linkend="toplevel-desc"
>Modo de Janelas de Topo</link>
  </para
></listitem>
</itemizedlist>

<para
>Para mudar o modo da interface do utilizador, seleccione a <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> </menuchoice
> no menu. A janela para <guilabel
>Configurar o KDevelop</guilabel
> irá aparecer, onde então terá de seleccionar <guilabel
>Interface do Utilizador</guilabel
> no campo do lado esquerdo. Isto levá-lo-á à página de configuração mostrada à direita. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="select-user-interface-0.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Seleccione um modo de interface de utilizador </para
></caption>
  </mediaobject>
</screenshot>

<para
>Seleccione a opção exclusiva para o modo de interface do utilizador que deseja utilizar e carregue em <guibutton
>OK</guibutton
>. </para>

<note
><para
>Não se esqueça de reiniciar o &kdevelop; para que estas selecções façam efeito. </para
></note>

<para
>Você você tiver seleccionado o <guilabel
>modo IDEAl</guilabel
> ou o <guilabel
>modo de páginas</guilabel
>, irão ficar disponíveis mais duas secções: a <link linkend="setup-ui-tabs"
>Usar Tabulações</link
> e <link linkend="setup-ui-hover"
>Usar o Fechar ao Passar</link
>. Estas permitem-lhe configurar em que circunstâncias é que os separadores das páginas serão mostrados no topo das janelas dos documentos e se você poderá fechar o documento ao carregar no ícone da página. </para>
<para
>Apenas no <guilabel
>modo de janelas IDEAl</guilabel
>, existirá ainda mais uma secção de configuração, a <link linkend="setup-ui-toolview"
>Disposição das Páginas</link
>, a qual permite de facto seleccionar entre vários tamanhos dos separadores de páginas que rodeiam a área de trabalho principal neste modo. </para>

<formalpara id="setup-ui-tabs">
<title
>Configurar a Visualização da Barra de Páginas dos Documentos</title>

<para
>No modo IDEAl e no modo de páginas existirão páginas com nomes no topo dos diferentes documentos por omissão, de modo que possa seleccionar facilmente vários documentos diferentes ao carregar com o &LMB;. Se preferir ter mais espaço para as janelas dos documentos na área de trabalho principal do  &kdevelop;, você poderá mudar para outro comportamento na secção de configuração <guilabel
>Usa Tabulações</guilabel
>. </para>
</formalpara>

<variablelist>
<varlistentry>
  <term
><guilabel
>Sempre</guilabel
></term>
  <listitem
><para
>Este é o modo por omissão &mdash; mostra uma página cujo separador tem um ícone e o nome do documento na área de trabalho principal do &kdevelop;. </para
></listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Quando mais que uma</guilabel
></term>
  <listitem
><para
>Não mostra o documento numa página, quando só existe de facto um documento aberto. Se existir mais do que um, todavia, o &kdevelop; irá mostrar a barra de páginas normalmente como aparece na selecção <guilabel
>Sempre</guilabel
>. Você poderá seleccionar este modo se trabalhar num único documento na maior parte do tempo, dado que oferece um pouco mais de espaço vertical. </para
></listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Nunca</guilabel
></term>
  <listitem
><para
>Nunca mostra nenhuma página de selecção de documentos. Você poderá preferir este modo se você usa raramente o rato para mudar de documentos. Fornece mais espaço vertical para todas as janelas de documentos. Para seleccionar outra janela de documento ou fechar alguma, use o menu <guimenu
>Janela</guimenu
> do &kdevelop;. </para
></listitem>
</varlistentry>
</variablelist>

<formalpara id="setup-ui-hover">
<title
>Configurar para Fechar um Documento com um 'Click' na sua Página</title>
<para
>Quando você tiver configurado o &kdevelop; para mostrar a barra de páginas dos documentos, seja sempre ou apenas quando é mostrado mais do que um documento na área de trabalho, você poderá adicionar mais funcionalidades aos separadores das páginas para além da sua capacidade de selecção de documentos. Use a secção de configuração <guilabel
>Usar o Fecho ao Passar</guilabel
> para tal. </para>
</formalpara>
<variablelist>
<varlistentry>
  <term
><guilabel
>Não</guilabel
></term>
  <listitem
><para
>Este é o comportamento normal. Não é adicionada mais nenhuma funcionalidade extra às páginas. Elas poderão ser usadas apenas para seleccionar as janelas dos documentos com o &LMB;. </para
></listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Sim</guilabel
></term>
  <listitem
><para
>Quando você tiver seleccionado esta opção exclusiva, o &kdevelop; irá permitir fechar uma janela de um documento com um 'click' do &LMB;. Use o rato para apontar para o pequeno ícone do lado esquerdo do separador de páginas. Ele irá mudar para um símbolo de fecho. Agora, carregue com o &LMB; neste símbolo alterado para que o &kdevelop; feche a janela do documento correspondente. </para
></listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Sim, Atrasado</guilabel
></term>
  <listitem
><para
>Depois de seleccionar esta opção, o &kdevelop; permitirá fechar uma janela de um documento como é mostrado no caso do <guilabel
>Sim</guilabel
> descrito em cima. O ícone não irá mudar instantaneamente, contudo, havendo neste caso um pequeno atraso antes de o ícone aparecer. </para
></listitem>
</varlistentry>
</variablelist>

<formalpara id="setup-ui-toolview">
<title
>Configurar a Disposição das Páginas</title>

<para
>A secção de configuração <guilabel
>Disposição das Páginas</guilabel
> estará disponível apenas no modo IDEAl. Use estes botões para configurar a aparência das páginas que rodeiam a área de trabalho principal neste modo. </para>
</formalpara>
<variablelist>
<varlistentry>
  <term
><guilabel
>Ícones</guilabel
></term>
  <listitem>
  <para
>Cada página irá mostrar apenas um ícone. Se a ferramenta associada estiver visível, a página irá abrir e aparecerá um texto descritivo no seu separador. Você poderá usar este modo se trabalhar num monitor com uma resolução limitada. </para>
  <para
>Os ícones não são muito descritivos, de qualquer forma. Se você quiser saber que ferramenta está associada a uma dada página, coloque o cursor do rato sobre ela e espere um segundo. Irá então aparecer uma dica com o nome da ferramenta. </para>
  </listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Texto</guilabel
></term>
  <listitem
><para
>Este é o modo de apresentação das ferramentas por omissão. Cada página mostra o nome da sua ferramenta associada. </para
></listitem>
</varlistentry>
<varlistentry>
  <term
><guilabel
>Texto e Ícones</guilabel
></term>
  <listitem
><para
>Se as ferramentas normais parecem demasiado planas para si e você está a trabalhar num monitor de alta resolução, você poderá seleccionar esta opção. Fará com que o nome da ferramenta associada seja mostrado em cada página, para além de um ícone à esquerda dele, tornando as páginas mais fáceis de compreender. Veja a imagem das <link linkend="folded-toolview-tabs"
>Páginas de Ferramentas Fechadas</link
> em baixo para um exemplo. </para
></listitem>
</varlistentry>
</variablelist>

<formalpara>
<title
>Páginas das Ferramentas Fechadas</title>
<para
>Se você seleccionou o modo IDEAl, com as páginas a mostrarem os textos (com ou sem os ícones a acompanhar), você não precisa de se preocupar em estar escondido por detrás de uma janela de ferramentas. Se uma das janelas das ferramentas ocupar mais espaço do que está disponível para mostrar todas as páginas (verticais), elas fechar-se-ão como é mostrado nesta figura: </para>
</formalpara>
<screenshot>
  <mediaobject id="folded-toolview-tabs">
    <imageobject>
      <imagedata fileref="folded-tabs.png" format="PNG"/>
    </imageobject>
    <caption
><para
>As páginas de ferramentas fecham-se para não ficarem escondidas detrás de outra janela </para
></caption>
  </mediaobject>
</screenshot>

<note
><para
>A janela de ferramentas activa deverá ser mostrada fixa (sem sobreposição), partilhando a área de trabalho com outras janelas, para permitir esse fecho de páginas. Carregue no pequeno quadrado no contorno da janela para conseguir isto, tal como é mostrado no exemplo. </para
></note>

</sect2
> <!-- setup-ui -->

<sect2 id="setup-editor">
<title
>Seleccionar um Editor</title>

<para
>O &kdevelop; permite-lhe seleccionar a sua ferramenta de edição de texto favorita. Marque o item <guilabel
>Editor</guilabel
> da árvore de selecção da lado esquerdo da janela <guilabel
>Configurar o KDevelop</guilabel
>. Será mostrada a seguinte janela à direita. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-editor.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Seleccionar um editor </para
></caption>
  </mediaobject>
</screenshot>

<para
>Para seleccionar um novo editor, carregue na seta da lista. Dependendo das interfaces dos componentes de edição com que a sua versão do &kde; foi compilada, irá aparecer uma lista dos editores que poderá seleccionar (veja a nota <link linkend="setup-editor-kparts"
>Importante</link
> em baixo para tal). Carregue no editor da sua preferência e carregue em <guilabel
>OK</guilabel
>. De momento, existem três possibilidades: </para>
<variablelist>
  <varlistentry>
  <term
><guilabel
>Editor de Texto Avançado Incorporado</guilabel
></term>
  <listitem
><para
>Esta é a componente de edição normal do &kde;, a <application
>Kate</application
>. </para
></listitem>
  </varlistentry>
  <varlistentry>
  <term
><guilabel
>Componente Embebida do Vim</guilabel
></term>
  <listitem>
    <para
>Esta oferece a aparência e comportamento do seu editor de base do Linux que é o <application
>vi</application
>. </para>
    <note
><itemizedlist>
      <listitem
><para
>Você precisa de ter uma aplicação <application
>Vim</application
> adequada instalada. Dê uma vista de olhos no <ulink url="http://www.freehackers.org/kvim/"
>KVim</ulink
> para mais informações. </para
></listitem>
      <listitem
><para
>Para além disso, você precisa de configurar o componente KParts do Vim no <guilabel
>Centro de Controlo do &kde;</guilabel
> (<menuchoice
><guimenuitem
>Componentes do KDE</guimenuitem
><guimenuitem
>Configuração do Componente Vim</guimenuitem
></menuchoice
>) antes de o poder usar. </para
></listitem>
    </itemizedlist
></note>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term
><guilabel
>Editor de Texto Baseado no Qt Designer</guilabel
></term>
  <listitem
><para
>Este é o editor que o Qt oferece no seu componente <application
>Designer</application
>. </para
></listitem>
  </varlistentry>
</variablelist>

<para
>Estas interfaces de edição estão completamente integradas no conceito de IDE do &kdevelop;. Em particular, a possibilidade de saltar para linha de código-fonte responsável por um dado erro, se carregar no texto da sua mensagem na janela de <guilabel
>Mensagens</guilabel
> é oferecida por elas. </para>

<note
><para
>A mudança de editor não irá afectar os ficheiros já abertos. Existem duas possibilidades de prosseguir. Ou fecha todas as janelas de texto abertas e reabre-as uma a uma ou então simplesmente fecha o projecto inteiro e abre-o outra vez. As janelas serão então automaticamente abertas com a nova interface de edição de texto. </para
></note>

<important id="setup-editor-kparts"
><para
>O &kdevelop; deixa-o usar as interfaces de edição que foram registadas no &kde; e que oferecem uma interface do KatePart. Se você acha que falta uma das selecções mostradas acima, verifique a sua instalação do &kde; para saber se o KPart foi instalado correctamente. </para
></important>
</sect2
> <!-- setup-editor -->

<sect2 id="setup-format">
<title
>Seleccionar um Estilo de Formatação de Código</title>

<para
>O &kdevelop; formata automaticamente o texto de código de um estilo predefinido. Este estilo é altamente configurável. </para>

<note
><para
>A funcionalidade de reformatação de código está disponível apenas para o C, o C++ e o &Java;, de momento. Em especial, você não a poderá usar para as linguagens de 'scripting' como o PHP. Isto é porque o &kdevelop; usa a aplicação <ulink url="http://astyle.sourceforge.net/"
>astyle</ulink
> para implementar esta funcionalidade. </para
></note>

<para
>Para configurar um estilo de formatação específico, seleccione <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> </menuchoice
> no menu. A janela para <guilabel
>Personalizar o KDevelop</guilabel
> irá aparecer, onde terá de seleccionar o <guilabel
>Formatador de Código</guilabel
> na árvore da esquerda. Isto irá mostrar uma série de três páginas de configuração à direita, nomeadamente uma <link linkend="setup-format-general"
>Configuração Geral da Formatação</link
>, uma <link linkend="setup-format-indent"
>Configuração do Estilo de Indentação</link
> e <link linkend="setup-format-other"
>Outra Configuração de Formatação</link
>. </para>

<tip
><para
>Todas as mudanças de estilo aplicam-se apenas ao ficheiro acabado de introduzir. Se você quiser mudar o estilo de formatação de um texto de código já existente, você terá de usar explicitamente o comando <menuchoice
><guimenu
>Editar</guimenu
><guimenuitem
>Reformatar o Código</guimenuitem
></menuchoice
>. </para
></tip>

<note
><para
>A consequência exacta destas definições de formatação do estilo dependem do <link linkend="setup-editor"
>editor</link
> que usa. De momento, a maioria das configurações são adequadas para a componente de edição do Kate (o <quote
>Editor de Texto Avançado Incorporado</quote
>). Outros editores (&eg; o editor do Qt) poderão basear-se apenas na sua configuração própria. Você terá  de experimentar neste caso para saber os efeitos exactos da configuração de estilo oferecida aqui. </para
></note>

<warning
><para
>Poderão existir incompatibilidades entre a configuração do estilo aqui oferecida e o editor que usa, até mesmo nos casos extremos, em que poderá corromper os seus ficheiros. Certifique-se que tem uma cópia de segurança dos seus ficheiros de código antes de tentar usar a sua configuração com um editor incompatível com o &kde;. </para
></warning>

<sect3 id="setup-format-general">
<title
>Configuração Geral da Formatação</title>

<para
>A página <guilabel
>Geral</guilabel
> da janela do <guilabel
>Formatador de Código</guilabel
> permite-lhe seleccionar um de cinco estilos predefinidos de formatação de código. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-general.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configuração geral do estilo de formatação de código </para
></caption>
  </mediaobject>
</screenshot>

<para
>Será mostrado um exemplo de código formatado no campo à direita. Se nenhum dos estilos predefinidos é do seu agrado, você poderá carregar na opção de topo <guilabel
>Definido pelo utilizador</guilabel
> e definir as suas preferências de formatação de código nas outras duas páginas que ficarão disponíveis. </para>

<note
><para
>De momento, só os estilos de formatação predefinidos é que serão demonstrados com um texto de exemplo. Se você decidir definir o seu próprio estilo, não será apresentado nenhum texto de exemplo. Você terá de experimentar no próprio texto do código actual para ajustar a configuração ao seu gosto. </para
></note>

</sect3
> <!-- setup-format-general -->

<sect3 id="setup-format-indent">
<title
>Configuração do Estilo de Indentação</title>

<para
>Uma indentação adequada é a forma principal de melhorar a legibilidade do texto do código. Se você seleccionou a página <guilabel
>Indentação</guilabel
> na janela do <guilabel
>Formatador do Código</guilabel
>, ser-lhe-á apresentada uma série de opções de formatação, agrupadas em três opções, como as que aparecem a seguir. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-indent.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configuração do estilo da indentação do código </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Configuração por Omissão</title>
<para
>As escolhas de formato predefinidas fazem com que o código lembre o estilo de formatação da ANSI: </para>
</formalpara>
<screen
>namespace espacoXpto
{
  int Xpto()
  {
    if (eOla)
    {
      ola();
      return 1;
    }
    else
      return 0;
  }
}
</screen>

<formalpara id="setup-format-indent-filling">
<title
>Definir o Tamanho e os Caracteres da Indentação</title>
<para
>As opções exclusivas agrupadas no grupo <guilabel
>Preenchimento</guilabel
>, definem como é que a indentação do código será feita. </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Usar tabulações</guilabel
></term>
    <listitem>
    <para
>Isto fará com que o editor insira um carácter de tabulação por cada nível de indentação. O tamanho da tabulação está predefinido na configuração do editor (é normalmente de 8 ou 4 caracteres). Use o <menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Configurar o Editor...</guimenuitem
></menuchoice
> para o definir de novo. </para>
    <note
><para
>O procedimento de definição da largura da tabulação actual depende do editor que seleccionou no passo de configuração em <link linkend="setup-editor"
>Seleccionar um Editor</link
>. Você terá de ver na ajuda correspondente do editor para descobrir como fazê-lo. </para
></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Usar espaços</guilabel
></term>
    <listitem
><para
>Se você seleccionar esta opção, o editor irá introduzir um conjunto de espaços por cada nível de indentação. Mude o número do valor por omissão 2 para o tamanho que preferir. </para
></listitem>
  </varlistentry>
</variablelist>

<formalpara>
<title
>Entidades Indentadas</title>
<para
>Isto define quais as entidades de (C/C++) que serão formatadas com uma indentação extra para além do nível de indentação actual. </para>
</formalpara>
<para
>Por omissão, só os <guilabel
>namespaces</guilabel
> (espaços de nomes) e os <guilabel
>labels</guilabel
> (identificadores) terão uma indentação extra. Você poderá querer experimentar com várias opções para se ajustar a essas indentações extra de acordo com o seu agrado. </para>

<formalpara>
<title
>Continuação</title>
<para
>As opções aqui agrupadas aplicam-se aos casos em que o formatador de código reparte automaticamente as linhas de código grandes. Ele tem dois casos especiais em conta, nomeadamente os casos em que as indentações são demasiado grandes e é necessário haver espaço restante para o código e para as condições, que deverão ter níveis de indentação extra para que sejam suficientemente perceptíveis. </para>
</formalpara>

<note
><para
>Isto aplica-se aos <emphasis
>casos de mudanças de linha estáticas</emphasis
> apenas quando é usado um tamanho de linha máximo fixo no código. Se você configurar o seu editor para repartir dinamicamente as linhas apenas na visualização (o que é possível, na componente de edição do Kate), os efeitos destas configurações não serão visíveis. </para
></note>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Máximo na instrução</guilabel
></term>
    <listitem>
    <para
>Esta configuração limita a indentação máxima possível para as linhas de continuação para que sobre espaço suficiente para manter o texto legível. Nenhuma linha de continuação será indentada para além do número de colunas que seleccionar neste campo. </para>
    <para
>O tamanho por omissão está definido como 40 colunas de caracteres (metade de uma página de 80 colunas normal). Você poderá querer aumentar este valor para ter em conta o papel mais largo (&eg; se você usa a impressão no modo paisagem para o seu código) ou então diminui-lo se quiser ter em conta a configuração das margens nas suas impressões. </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Mínimo nas condições</guilabel
></term>
    <listitem>
    <para
>As condições ou o código que se segue &eg; a um operador de atribuição deverão ter normalmente uma indentação extra nas linhas de continuação para manter o texto legível. A quantidade desta indentação extra é aqui definida. </para>
    <para
>O valor por omissão é igual a <quote
>Duas vezes o actual</quote
>, o que significa que as condições continuadas irão ter um nível de indentação extra em relação ao tamanho de indentação normal que seleccionou no grupo <link linkend="setup-format-indent-filling"
>Preenchimento</link
>. Você poderá alterar esta indentação extra para outro tamanho fixo (incluindo zero), usando as setas ou indicando o valor directamente. </para>
    </listitem>
  </varlistentry>
</variablelist>

</sect3
> <!-- setup-format-indent -->

<sect3 id="setup-format-other">
<title
>Outras Configurações de Formatação</title>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-other.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Outra configuração do estilo de formatação do código </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Controlar a Posição das Chavetas</title>
<para
>As opções no grupo (talvez mal chamado) <guilabel
>Parêntesis</guilabel
> controlam a posição das chavetas que delimitam os blocos no código em C/C++. Existem três possibilidades para você seleccionar. </para>
</formalpara>
<variablelist>
  <varlistentry>
    <term
><guilabel
>Interrupção</guilabel
></term>
    <listitem>
    <para
>Esta insere uma quebra de linha antes de cada chaveta de abertura. Ambas as chavetas delimitadoras de um bloco serão colocadas ao mesmo nível de indentação que a instrução de topo do bloco.</para>
    <screen
>namespace espacoXpto
{
  int Xpto()
  {
    if (eOla)
    {
      ola();
      return 1;
    }
    else
      return 0;
  }
}
    </screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Anexar</guilabel
></term>
    <listitem>
    <para
>Isto irá manter a chaveta de abertura de um bloco alinhada com a instrução de topo do bloco. As chavetas de fecho estarão ao mesmo nível de indentação que a instrução de topo do bloco. O <token
>else</token
> de uma instrução <token
>if</token
> será mantido em linha com a chaveta de fecho do bloco anterior. </para>
    <screen
>namespace espacoXpto {
  int Xpto() {
    if (eOla) {
      ola();
      return 1;
    } else
      return 0;
  }
}
    </screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Estilo do Linux</guilabel
></term>
    <listitem>
    <para
>Este é um compromisso entre os estilos listados acima. As chavetas de delimitação dos blocos serão colocadas em linhas extra. As chavetas que abrem um bloco numa instrução condicional ou de ciclo serão mantidas na mesma linha. </para>
    <screen
>namespace espacoXpto
{
  int Xpto()
  {
    if (eOla) {
      ola();
      return 1;
    } else
      return 0;
  }
}
    </screen>
    </listitem>
  </varlistentry>
</variablelist>

<formalpara>
<title
>Controlar os Espaços Extra</title>
<para
>Por omissão, o &kdevelop; minimiza a utilização dos espaços no código. </para>
</formalpara>

<screen
>if (eOla(argXpto)==valorOla)
</screen>

<para
>Você poderá aumentar a legibilidade se forçar o formatador de código a inserir os espaços extra em posições especiais. </para>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Adicionar espaços à volta dos parêntesis</guilabel
></term>
    <listitem>
    <para
>De facto, o que esta opção pretende fazer é adicionar espaços à volta do texto entre parêntesis. Isto aumenta a legibilidade dos argumentos das funções e das condições.</para>
    <screen
>if ( eOla( argXpto )==valorOla )
    </screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Adicionar espaços à volta dos operadores</guilabel
></term>
    <listitem>
    <para
>Isto irá colocar espaços à volta dos operadores de atribuição e de comparação para aumentar a legibilidade.</para>
    <screen
>if (eOla(argXpto) == valorOla)
    </screen>
    </listitem>
  </varlistentry>
</variablelist>

<formalpara>
<title
>Controlar a Formatação das Construções de uma Linha</title>
<para
>Existem alguns casos em que você não quer que o formatador de código divida uma linha em duas. Para o código de C/C++, isto poderá ser controlado aqui. </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Manter as instruções de uma linha</guilabel
></term>
    <listitem
><para
>Isto mantém as instruções de uma linha em conjunto, mesmo nas situações em que elas excedem um tamanho máximo de linha. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Manter os blocos de uma linha</guilabel
></term>
    <listitem
><para
>Isto mantém os blocos de uma única linha em conjunto, mesmo nas situações em que elas excedem um tamanho máximo de linha. </para
></listitem>
  </varlistentry>
</variablelist>

</sect3
> <!-- setup-format-other -->

</sect2
> <!-- setup-format -->

<sect2 id="setup-snippets">
<title
>Configurar a Ferramenta de Excertos de Código</title>

<para
>Ao editar no &kdevelop; você poderá gravar excertos de código usados frequentemente como <link linkend="editing-snippets"
>Excertos de Código</link
>. Para configurar as capacidades da componente de excertos de código, seleccione a <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> </menuchoice
> no menu. A janela para <guilabel
>Configurar o KDevelop</guilabel
> irá aparecer, onde então terá de seleccionar <guilabel
>Excertos de Código</guilabel
> no campo do lado esquerdo. Isto levá-lo-á à página de configuração mostrada em baixo. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-snippets.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar a Ferramenta de Excertos de Código </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Antevisão da Activação de um Excerto</title>
<para
>Assinale a opção <quote
><guilabel
>Mostrar o texto do excerto na dica</guilabel
></quote
> se você quiser ver o texto armazenado numa janela de dica de ferramentas, sempre que você deixar o cursor do rato sobre o título desse excerto de código. </para>
</formalpara>

<formalpara>
<title
>Lidar com as Variáveis dos Excertos</title>
<para
>A ferramenta de <guilabel
>Excertos de Código</guilabel
> permite a definição de texto variável em locais bem definidos, sempre que desejar inserir um excerto num ficheiro. Para conseguir isto, os <guilabel
>Excertos de Código</guilabel
> têm o seu próprio mecanismo de variáveis. Você poderá configurar o seu comportamento no grupo <guilabel
>Variáveis</guilabel
>. </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Separador</guilabel
></term>
    <listitem
><para
>A ferramenta de <guilabel
>Excertos de Código</guilabel
> distingue as variáveis no texto, rodeando os nomes das variáveis com símbolos delimitadores especiais. Para usar o seu próprio delimitador, altere o valor predefinido <guilabel
>$</guilabel
> no campo <guilabel
>Delimitador</guilabel
>. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Método de introdução das variáveis</guilabel
></term>
    <listitem
><itemizedlist>
      <listitem
><para
><guilabel
>Uma janela para cada variável do excerto</guilabel
> &ndash; irá mostrar uma janela separada para cada variável que a ferramenta encontre ao inserir o excerto de código seleccionado. </para
></listitem>
      <listitem
><para
><guilabel
>Uma janela para todas as variáveis do excerto</guilabel
> &ndash; irá mostrar uma janela comum, onde o utilizador terá de de preencher os valores de todas as variáveis antes de o excerto ser inserido </para
></listitem>
    </itemizedlist
></listitem>
  </varlistentry>
</variablelist>

</sect2
> <!-- setup-snippets -->

<sect2 id="setup-fileselector">
<title
>Configurar o Selector de Ficheiros</title>

<para
>O &kdevelop; oferece um <guilabel
>Selector de Ficheiros</guilabel
> que, quando é carregado no arranque, permite navegar até chegar a qualquer ficheiro ou directoria do sistema. </para>

<screenshot id="setup-fileselector-image">
  <mediaobject>
    <imageobject>
      <imagedata fileref="file-selector.png" format="PNG"/>
    </imageobject>
    <caption
><para
>O selector de ficheiros (modo IDEAl) </para
></caption>
  </mediaobject>
</screenshot>

<para
>O comportamento do <guilabel
>Selector de Ficheiros</guilabel
> é altamente configurável. Seleccione a <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> </menuchoice
> no menu. A janela para <guilabel
>Configurar o KDevelop</guilabel
> irá aparecer, onde então terá de seleccionar <guilabel
>Selector de Ficheiros</guilabel
> no campo do lado esquerdo. Isto levá-lo-á à página de configuração mostrada em baixo. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-file-selector.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar o selector de ficheiros </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Configurar a Barra de Ferramentas</title>
<para
>Existe uma barra de ferramentas no topo do <guilabel
>Selector de Ficheiros</guilabel
>, que poderá ser configurada como de costume no grupo <guilabel
>Barra de Ferramentas</guilabel
>. </para>
</formalpara>

<procedure id="setup-fileselector-add-action">
  <title
>Adicionar uma Acção à Barra de Ferramentas</title>
  <step>
    <para
>Seleccione um item na lista das <guilabel
>Acções seleccionadas</guilabel
> à direita, para que a acção nova seja então introduzida. </para>
  </step>
  <step>
    <para
>Seleccione a acção a ser introduzida na lista de <guilabel
>Acções disponíveis</guilabel
> à esquerda. </para>
  </step>
  <step>
    <para
>Carregue na seta direita (em cima) entre as duas listas. </para>
    <para
>A acção será removida da lista de <guilabel
>Acções disponíveis</guilabel
> e será introduzida nas <guilabel
>Acções seleccionadas</guilabel
> por baixo do item seleccionado. </para>
  </step>
</procedure>

<procedure>
  <title
>Remover uma Acção da Barra de Ferramentas</title>
  <step>
    <para
>Seleccione o item a ser removido da lista de <guilabel
>Acções seleccionadas</guilabel
> à direita. </para>
  </step>
  <step>
    <para
>Carregue na seta para a esquerda (em baixo) entre as listas. </para>
    <para
>O item seleccionado será removido da lista de <guilabel
>Acções seleccionadas</guilabel
> e colocada de novo na lista de <guilabel
>Acções disponíveis</guilabel
>. </para>
  </step>
</procedure>

<procedure>
  <title
>Reordenar as Acções na Barra de Ferramentas</title>
  <step>
    <para
>Seleccione a acção a ser mudada de posição na lista de <guilabel
>Acções seleccionadas</guilabel
> à direita. </para>
  </step>
  <step>
    <para
>Carregue nas setas para cima e para baixo, à direita desta lista. </para>
    <para
>O item seleccionado será movido para cima ou para baixo na lista de <guilabel
>Acções seleccionadas</guilabel
>. </para>
  </step>
</procedure>

<formalpara id="setup-fileselector-autosync">
<title
>Definir Quando o Conteúdo Deverá Mudar</title>
<para
>A actualização do conteúdo da janela do <guilabel
>Selector de Ficheiros</guilabel
> leva tempo e ocupa alguns recursos, especialmente ao mudar para outra directoria. Como tal, o <guilabel
>Selector de Ficheiros</guilabel
> está configurado por omissão de forma a que o seu conteúdo só se altera a pedido, &ie; quando você selecciona outra directoria ou quando desejar explicitamente actualizar o seu conteúdo. </para>
</formalpara>

<note
><para
>Carregue no botão <guilabel
>Actualizar</guilabel
> da barra de ferramentas para actualizar o conteúdo do <guilabel
>Selector de Ficheiros</guilabel
>. Esta barra de ferramentas não está disponível por omissão, todavia. Você precisa de a <link linkend="setup-fileselector-add-action"
>inserir</link
> primeiro. </para
></note>

<para
>Você poderá configurar o <guilabel
>Selector de Ficheiros</guilabel
> para reflectir imediatamente certas alterações no seu trabalho. As opções do grupo <guilabel
>Auto-Sincronização</guilabel
> da janela de configuração são responsáveis por isto. </para>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Quando um documento fica activo</guilabel
></term>
    <listitem
><para
>Se você seleccionar esta opção, o conteúdo do <guilabel
>Selector de Ficheiros</guilabel
> será actualizado sempre que for para outro documento aberto, &eg; quando você carrega na página da janela de edição respectiva no modo IDEAl. Se necessário, o <guilabel
>Selector de Ficheiros</guilabel
> irá mudar para a directoria a que este ficheiro pertence e actualizará a área visível para mostrar o conteúdo actual da mesma. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Quando um documento é aberto</guilabel
></term>
    <listitem
><para
>Se você seleccionar esta opção, o conteúdo da janela do <guilabel
>Selector de Ficheiros</guilabel
> será actualizado sempre que um documento é aberto, &eg; pela opção do menu <menuchoice
><guimenu
>Ficheiro</guimenu
><guimenuitem
>Abrir</guimenuitem
></menuchoice
>. Se necessário, o <guilabel
>Selector de Ficheiros</guilabel
> irá mudar para a directoria a que este ficheiro pertence e irá refrescar a visualização para mostrar o conteúdo actual. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Quando o selector de ficheiros fica visível</guilabel
></term>
    <listitem
><para
>Se seleccionar esta opção, o conteúdo do <guilabel
>Selector de Ficheiros</guilabel
> será actualizado sempre que ficar visível de novo. Se necessário, o <guilabel
>Selector de Ficheiros</guilabel
> irá mudar para a directoria a que este ficheiro pertence e irá refrescar a visualização para mostrar o conteúdo actual. </para
></listitem>
  </varlistentry>
</variablelist>

<para
>Você poderá combinar estas opções para ajustar o comportamento da actualização do <guilabel
>Selector de Ficheiros</guilabel
> ao seu gosto. </para>

<formalpara>
<title
>Controlar o Histórico nas Listas</title>
<para
>Existem duas listas na parte superior e na inferior da janela de conteúdo do <guilabel
>Selector de Ficheiros</guilabel
> que controlam a directoria a ser mostrada (a lista no topo) e os filtros a serem aplicados à janela de ficheiros (a lista de baixo). Um histórico das opções mais recentes é mantido no campo de selecção de cada lista. Você poderá configurar o número de itens do histórico da seguinte forma. </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Recordar as localizações</guilabel
></term>
    <listitem
><para
>Indique aqui o número máximo de selecções de directorias que a lista de cima deverá recordar. </para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Recordar os filtros</guilabel
></term>
    <listitem
><para
>Indique aqui o número máximo de definições de filtros que a lista em baixo deverá recordar. </para
></listitem>
  </varlistentry>
</variablelist>

<formalpara>
<title
>Controlar o que Deverá Ser Recordado Entre Sessões</title>
<para
>Por omissão, o <guilabel
>Selector de Ficheiros</guilabel
> está configurado de forma a que mostre o conteúdo da sessão mais recente no próximo arranque do &kdevelop;. Você poderá alterar este comportamento no grupo de configuração <guilabel
>Sessão</guilabel
>. </para>
</formalpara>

<note
><para
>Se o &kdevelop; foi reiniciado automaticamente pelo gestor de sessões do &kde;, as alterações a estas opções não farão efeito. Neste caso, a configuração da localização e dos filtros da sessão mais recente do &kde; será sempre reposta. </para
></note>

<variablelist>
  <varlistentry>
    <term
><guilabel
>Repor a localização</guilabel
></term>
    <listitem>
    <para
>Desligue esta opção se não quiser que a localização apresentada seja guardada entre sessões. </para>
    <note
><para
>Se você seleccionou uma das opções de <link linkend="setup-fileselector-autosync"
>auto-actualização</link
>, a localização apresentada poderá mudar automaticamente, independentemente do que foi recordado da sessão recente. </para
></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Repor os filtros</guilabel
></term>
    <listitem>
    <para
>Desligue esta opção se não quiser que os filtros apresentados sejam guardados entre sessões. </para>
    </listitem>
  </varlistentry>
</variablelist>

</sect2
> <!-- setup-fileselector -->

<sect2 id="setup-new-file-wizard">
<title
>Configurar o Assistente de Ficheiros Novos</title>

<para
>(... ainda não escrito ...) </para>

</sect2
> <!-- setup-new-file-wizard -->

</sect1
> <!-- setup-general -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="setup-docu">
<title
>Configurar a Documentação</title>

<para
>O &kdevelop; contém uma funcionalidade de documentação muito poderosa que fornece o acesso a vários tipos de documentação extensa. Por exemplo, no modo IDEAl, você irá encontrar uma página de <guilabel
>Documentação</guilabel
> do lado direito da área de trabalho. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="documents-contents.png" format="PNG"/>
    </imageobject>
    <caption
><para
>A árvore de documentação do &kdevelop; (modo IDEAl) </para
></caption>
  </mediaobject>
</screenshot>

<note
><para
>O &kdevelop; precisa de ter carregado o 'plugin' de <guilabel
>Documentação</guilabel
> para ver a árvore de documentação. Veja as <link linkend="setup-plugins"
>Ferramentas em 'Plugins'</link
> para mais informações. </para
></note>

<para
>Você poderá configurar o conteúdo desta árvore de documentação se seleccionar a <menuchoice
> <guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> </menuchoice
> no menu. A janela para <guilabel
>Configurar o KDevelop</guilabel
> irá aparecer, onde então terá de seleccionar <guilabel
>Documentação</guilabel
> no campo do lado esquerdo. </para>

<para
>A <link linkend="configure-docu-general"
>página de configuração</link
> que é mostrada apresenta um conjunto de páginas de configuração, nomeadamente: </para>

<simplelist>
  <member
><link linkend="setup-docu-general"
>Colectâneas de Documentação</link
></member>
  <member
><link linkend="setup-docu-textsearch"
>Pesquisa por Texto Completo</link
></member>
  <member
><link linkend="setup-docu-other"
>Outro</link
></member>
</simplelist>

<sect2 id="setup-docu-general">
<title
>Configurar as Colectâneas de Documentação</title>

<para
>A configuração da documentação foi dividida numa série de colectâneas de documentação, em que cada uma fornece o acesso aos ficheiros de documentação de um determinado formato e tipo de conteúdo únicos. Esta configuração controla quais os itens de documentação que serão listados na página de <guilabel
>Conteúdo</guilabel
> da funcionalidade de <guilabel
>Documentação</guilabel
> do &kdevelop;, e como é que o utilizador pode aceder aos detalhes da documentação, através de procuras indexadas e pelo texto completo. </para>
<para
>A página de <guilabel
>Documentação</guilabel
> oferece uma série de páginas de configuração que são ordenadas verticalmente como uma pilha de cartões de índice. Cada uma das páginas, de cada vez, irá abrir ao carregar no título do seu cartão de índice: </para>
<simplelist>
  <member
><link linkend="setup-docu-general-qt"
>Colectânea de Documentação do Qt</link
></member>
  <member
><link linkend="setup-docu-general-chm"
>Colectânea de Documentação CHM</link
></member>
  <member
><link linkend="setup-docu-general-dox"
>Colectânea de Documentação do Doxygen</link
></member>
  <member
><link linkend="setup-docu-general-toc"
>Colectânea de Documentação do KDevelopTOC</link
></member>
  <member
><link linkend="setup-docu-general-devhelp"
>Colectânea de Documentação do DevHelp</link
></member>
  <member
><link linkend="setup-docu-general-custom"
>Colectânea de Documentação Personalizada</link
></member>
</simplelist>

<para id="configure-docu-general">
<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar as colectâneas de documentação </para
></caption>
  </mediaobject>
</screenshot>
</para>

<sect3 id="setup-docu-general-common">
<title
>Estrutura Comum de Configuração da Documentação</title>

<para
>Todas as páginas de configuração da página de <guilabel
>Documentação</guilabel
> usam uma disposição comum. Você irá encontrar os itens de documentação disponíveis de momento, listados na página aberta à esquerda, bem como uma série de botões à direita. </para>

<formalpara id="setup-docu-buttons">
<title
>Botões de Gestão da Lista de Documentação</title>

<para
>Existem três botões disponíveis para manter o conteúdo das páginas de configuração da documentação: </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guibutton
>Adicionar</guibutton
></term>
    <listitem>
      <para
>Abre uma janela de <guilabel
>Propriedades do Catálogo de Documentação</guilabel
>, tal como é mostrado em baixo, na qual poderá seleccionar a localização da fonte de documentação a adicionar, bem como lhe poderá atribuir um nome.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guibutton
>Editar</guibutton
></term>
    <listitem>
      <para
>Abre uma janela de <guilabel
>Propriedades do Catálogo de Documentação</guilabel
>, tal como é mostrado em baixo, na qual poderá alterar a localização da fonte de documentação a adicionar, bem como lhe poderá mudar o nome.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guibutton
>Remover</guibutton
></term>
    <listitem>
      <para
>Remove o item de documentação seleccionado da lista.</para>
      <note
><para
>O item só será removido da lista. Todas as fontes de documentação permanecerão inalteradas. Você terá de as remover explicitamente por outros meios. </para
></note>
    </listitem>
  </varlistentry>
</variablelist>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-edit.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Adicionar ou alterar um item de documentação </para
></caption>
  </mediaobject>
</screenshot>

<para
>O botão à direita do campo de <guilabel
>Localização</guilabel
> abre uma janela de directorias, cujos itens serão filtrados de acordo com o tipo de ficheiro da página de configuração seleccionada. </para>
<para
>O campo de <guilabel
>Título</guilabel
> poderá não estar acessível, dependendo do tipo de documentação a ser mantido. </para>

<formalpara id="setup-docu-columns">
<title
>Estrutura da Lista de Documentação</title>

<para
>Cada página de configuração de documentação mostra os itens de documentação listados numa tabela com quatro colunas: </para>
</formalpara>

<variablelist>
  <varlistentry>
    <term
><guilabel
>TOC</guilabel
></term>
    <listitem>
      <para
>Se esta opção estiver assinalada, este item de documentação irá aparecer na página de <guilabel
>Conteúdo</guilabel
> da funcionalidade de <guilabel
>Documentation</guilabel
> do &kdevelop;. </para>
      <note
><para
>Se desligar a opção <guilabel
>TOC</guilabel
>, esta irá por sua vez desactivar as opções <guilabel
>Índice</guilabel
> e <guilabel
>Procurar</guilabel
> (ver em baixo). Como tal, você não poderá ter itens da colectânea de documentação indexados mas que não estejam visíveis no conteúdo. </para
></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Índice</guilabel
></term>
    <listitem>
      <para
>Se esta opção estiver assinalada, será criado um índice interno a partir deste item de documentação. Isto oferece um acesso rápido à documentação, através do uso das páginas de <guilabel
>Índice</guilabel
> e (opcionalmente) <guilabel
>Procurar</guilabel
> da funcionalidade de <guilabel
>Documentation</guilabel
> do &kdevelop;. </para>
      <note>
        <para
>O índice interno será criado da primeira vez que o utilizador seleccionar a página de <guilabel
>Índice</guilabel
>. Isto irá atrasar consideravelmente o primeiro acesso, porque o índice será lido do disco e depois é então colocado numa 'cache'. </para>
        <para
>Todas as pesquisas subsequentes irão usar então esta 'cache' e, por isso, irão funcionar muito mais depressa. </para>
      </note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Procurar</guilabel
></term>
    <listitem>
      <para
>Se esta opção estiver assinalada, o conteúdo deste item de documentação será incluído nas localizações de procura por texto completo da página <guilabel
>Procurar</guilabel
> da funcionalidade de <guilabel
>Documentation</guilabel
> do &kdevelop;. </para>
      <note>
        <para
>O &kdevelop; usa a colectânea de aplicações do 'htdig' para efectuar as pesquisas por texto completo. Esta pesquisa é feita sobre um índice interno que a plataforma do 'htdig' tem de criar antes de poder ser usada. </para>
        <para
>Todas as alterações feitas na opção <guilabel
>Procurar</guilabel
> irão apenas afectar as pesquisas depois de reconstruir o índice da página <guilabel
>Procurar</guilabel
> da funcionalidade de <guilabel
>Documentation</guilabel
> do &kdevelop;. </para>
      </note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
><guilabel
>Título</guilabel
></term>
    <listitem
><para
>Este é o nome do item de Documentação que será mostrado na página de <guilabel
>Conteúdo</guilabel
> da funcionalidade de <guilabel
>Documentação</guilabel
> do &kdevelop;. </para
></listitem>
  </varlistentry>
</variablelist>

<note
><para
>As versões anteriores do &kdevelop; permitiam seleccionar os itens de documentação por projecto. Isto já não é mais possível. </para
></note>

</sect3
> <!-- setup-docu-general-common -->

<sect3 id="setup-docu-general-qt">
<title
>Colecções de documentação do Qt</title>

<para
>Nesta página de configuração é configurada toda a documentação do &Qt;. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar a colectânea de documentação do &Qt; </para
></caption>
  </mediaobject>
</screenshot>

<para
>Normalmente, o &kdevelop; irá preencher isto no seu primeiro arranque. Ele irá procurar pelos ficheiros de documentação normais <filename
>*.xml</filename
> e <filename
>*.dcf</filename
> da directoria de instalação do &Qt;. A tabela à esquerda irá listar os ficheiros que o &kdevelop; encontrou pelo seu título normal. </para>

<para
>Se você tem uma instalação fora do normal, então poderá não existir nenhuma informação indicada, ou então os endereços irão apontar para locais inválidos (&eg; para outra instalação do &Qt; disponível no seu sistema). Você poderá ajustar os itens, usando os <link linkend="setup-docu-buttons"
>botões</link
> à direita da lista. </para>

<note
><para
>O &kdevelop; irá usar os títulos já fornecidos pela documentação do &Qt; instalada. Por isso, o campo <guilabel
>Título</guilabel
> da janela de <guilabel
>Propriedades do Catálogo de Documentação</guilabel
> está inacessível. </para
></note>

<para
>Por omissão, nem toda a documentação do &Qt; estará visível na página de <guilabel
>Conteúdo</guilabel
> da funcionalidade de <guilabel
>Documentation</guilabel
> do &kdevelop;. Use a opção <guilabel
>TOC</guilabel
> na <link linkend="setup-docu-columns"
>tabela de configuração</link
> para seleccionar a documentação a ser apresentada. </para>

<para
>Se você quiser incluir mais alguma documentação específica do &Qt; nos índices de pesquisa ou na pesquisa por texto completo, use as opções de <guilabel
>Índice</guilabel
> e <guilabel
>Procurar</guilabel
> da <link linkend="setup-docu-columns"
>tabela de configuração</link
>. </para>

</sect3
> <!-- setup-docu-general-qt -->

<sect3 id="setup-docu-general-chm">
<title
>Configurar a Colectânea de Documentação CHM</title>

<para
>Nesta página de configuração, você poderá recolher a documentação referente à norma de ficheiros de ajuda CHM da &Microsoft;. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-chm.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar os ficheiros de documentação CHM normais da &Microsoft; </para
></caption>
  </mediaobject>
</screenshot>

<para
>Por omissão, esta página de configuração estará vazia (como é mostrado acima). Você poderá adicionar novos itens com os <link linkend="setup-docu-buttons"
>botões</link
> à direita do campo da lista. O &kdevelop; irá filtrar os ficheiros <filename
>*.chm</filename
> na janela de directoria associada aos botões <guibutton
>Adicionar</guibutton
> e <guibutton
>Editar</guibutton
>. </para>

<para
>Para mais informações sobre o formatos dos ficheiros <filename
>*.chm</filename
> da &Microsoft;, veja &eg; a Documentação do PHP - Formato CHM Extendido em <ulink url="http://de2.php.net/docs-echm.php"
>http://de2.php.net/docs-echm.php</ulink
>. </para>

</sect3
> <!-- setup-docu-general-chm -->

<sect3 id="setup-docu-general-dox">
<title
>Documentação Gerada pelo Doxygen</title>

<para
>Nesta página de configuração, toda a documentação da API gerada pelo &doxygen; será configurada. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-dox.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar a documentação da API gerada pelo Doxygen </para
></caption>
  </mediaobject>
</screenshot>

<para
>Em resumo, estas APIs documentam a interface para as funções de certas bibliotecas. Para produzir a documentação da API desta página é usada a ferramenta <ulink url="http://www.stack.nl/~dimitri/doxygen/"
>&doxygen;</ulink
>. </para>
<para
>A documentação da API gerada pelo &doxygen; consiste numa série de ficheiros <filename
>HTML</filename
>, a começar pelo <filename
>index.html</filename
>. Adicionalmente, poderão existir ficheiros <filename
>tag</filename
> que contêm informações para se associar a documentações de API já existentes. Como tal, o &kdevelop; irá procurar pelo <filename
>index.html</filename
> e pelos ficheiros <filename
>*.tag</filename
> ao procurar pela documentação de API gerada pelo &doxygen;. </para>
<para
>Existem algumas restrições estruturais assumidas ao procurar pela documentação da API gerada pelo &doxygen;. A directoria na qual se encontra o ficheiro <filename
>index.html</filename
> deverá conter algumas subdirectorias com colectâneas de documentação separadas. Assume-se que cada uma destas subdirectorias contém um ficheiro <filename
>.tag</filename
> e uma subdirectoria <filename class="directory"
>html/</filename
>. </para>
<para
>Você poderá dar uma vista de olhos em <filename class="directory"
>$KDEDIR/share/doc/HTML/en/kdelibs-apidocs</filename
> para ter um exemplo de uma disposição de documentação de API em &doxygen;. </para>

<note
><para
>O formato de documentação da API mais antigo do &kde;, o <ulink url="http://sirtaj.net/projects/kdoc/"
>KDoc</ulink
>, já não é mais suportado directamente. Se quiser usar à mesma essa documentação, você podê-la-á adicionar à mesma na página da <link linkend="setup-docu-general-custom"
>Colectânea Personalizada de Documentação</link
>. </para
></note>

<para
>O &kdevelop; terá preenchido numa ligação a API actual das Bibliotecas do &kde;, desde que tivesse achado alguma na altura da instalação. Existem várias formas de o &kdevelop; a descobrir: </para>

<itemizedlist>
  <listitem
><para
>Ou você indicou no comando <command
>configure</command
> a opção <option
>--with-kdelibsdoxy-dir</option
>, quando compilou o &kdevelop; (veja o capítulo <link linkend="make-api"
>Como Obter a Documentação da API do KDevelop</link
>). </para
></listitem>
  <listitem
><para
>Ou então o comando <command
>configure</command
> descobriu automaticamente uma API das Bibliotecas do &kde; gerada pelo &doxygen; num dos locais normais que ele conhece à partida. </para
></listitem>
  <listitem
><para
>Ou, como último recurso, a pasta <filename class="directory"
>$KDEDIR/share/doc/HTML/en/kdelibs-apidocs/</filename
> foi encontrada no primeiro arranque do &kdevelop;. </para
></listitem>
</itemizedlist>

<para
>Se o &kdevelop; não encontrou nenhuma documentação da API das Bibliotecas do &kde; gerada pelo &doxygen;, então a lista da <guilabel
>Documentação Gerada pelo Doxygen</guilabel
> aparecerá vazia. </para>

<para
>Você poderá adicionar os seus próprios itens de documentação da API (&eg; dos seus projectos actuais), usando os <link linkend="setup-docu-buttons"
>botões</link
> à direita. Se os quiser incluir na pesquisa indexada ou por texto completo marque as opções <guilabel
>Índice</guilabel
> ou <guilabel
>Procurar</guilabel
> da <link linkend="setup-docu-columns"
>tabela de configuração</link
>. </para>

<note
><para
>O &kdevelop; usa a informação do título do ficheiro <filename
>index.html</filename
>. Daí, o campo <guilabel
>Título</guilabel
> na janela de <guilabel
>Propriedades do Catálogo de Documentação</guilabel
> estar inacessível. </para
></note>

<tip>
  <para
>O sistema do &kde; fornece mais documentação da API do que apenas a API das Bibliotecas do &kde;. Você irá precisar de mais informações de interfaces se quiser, &eg;, incluir a componente do &kate; nos seus programas. Para esta API da componente do &kate;, você deverá compilar e instalar a API das Bibliotecas de Base do &kde; a partir do <ulink url="http://developer.kde.org/source/index.html"
>código</ulink
> (com os comandos <command
>make apidox</command
> e <command
>make install</command
> no código do <filename class="directory"
>kdebase</filename
>), adicionando então um item à lista <guilabel
>Documentação Gerada pelo Doxygen</guilabel
> como se segue: </para>
  <screenshot
><mediaobject>
      <imageobject>
        <imagedata fileref="configure-adddialog-baselibs.png" format="PNG"/>
      </imageobject>
      <caption
><para
>Adicionar uma API de Base do &kde; à Lista </para
></caption>
    </mediaobject
></screenshot>
  <para
>(Claro que deverá substituir a directoria <filename class="directory"
>/home/dev/o-meu-kde/</filename
> no campo <guilabel
>Localização</guilabel
> com a localização da sua instalação do &kde;). </para>
</tip>

<note
><para
>Você precisa também de colocar a API do seu projecto actual nesta <guilabel
>Colectânea de Documentação do Doxygen</guilabel
>. As versões mais antigas do &kdevelop; colocavam-na na árvore de documentação ao nível do projecto. Isto já não é mais suportado. </para
></note>

</sect3
> <!-- setup-docu-general-dox -->

<sect3 id="setup-docu-general-toc">
<title
>Lidar com Documentação Estruturada (Ficheiros KDevelopTOC)</title>

<para
>O bloco principal da árvore de documentação do &kdevelop; fornece o acesso imediato à documentação estruturada, seja esta local ou remota. Você poderá configurar isto na página da <guilabel
>Colectânea de Documentação do KDevelopTOC</guilabel
>. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-toc.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Fornecer o acesso à documentação estruturada do KDevelopTOC </para
></caption>
  </mediaobject>
</screenshot>

<para
>O &kdevelop; vem com um conjunto de ficheiros KDevelopTOC predefinidos que são introduzidos automaticamente na tabela, na altura da instalação. Para manter o ambiente de trabalho fácil de gerir, só a documentação usada com maior frequência é que será marcada inicialmente para ser visualizada. Se você quiser ver outra documentação, marque a opção <guilabel
>TOC</guilabel
> na <link linkend="setup-docu-columns"
>tabela de configuração</link
>. </para>

<para
>Os ficheiros KDevelopTOC não podem ser indexados para fazer uma pesquisa por texto completo, porque normalmente apontam para uma localização remota. Por outro lado, qualquer um desses ficheiros <filename
>.toc</filename
> poderá ter um índice definido manualmente, usando a marca <computeroutput
>&lt;index&gt;</computeroutput
>. Daí, a opção <guilabel
>Índice</guilabel
> ficará activa apenas quando o &kdevelop; encontrar uma marca <computeroutput
>&lt;index&gt;</computeroutput
> no ficheiro <filename
>.toc</filename
>. (Para mais detalhes, veja a descrição em baixo na secção de <link linkend="setup-docu-general-toc-files"
>Ficheiros de Índice do &kdevelop;</link
>.) </para>
<para
>A opção <guilabel
>Procurar</guilabel
> na <link linkend="setup-docu-columns"
>tabela de configuração</link
> ficará sempre desactivada. </para>

<para
>Você poderá adicionar novos itens com os <link linkend="setup-docu-buttons"
>botões</link
> à direita da lista. O &kdevelop; irá filtrar os ficheiros <filename
>*.toc</filename
> na janela de directoria associada aos botões <guibutton
>Adicionar</guibutton
> e <guibutton
>Editar</guibutton
>. </para>

<note
><para
>Só nas versões mais antigas do &kdevelop; é que o botão <guibutton
>Remover</guibutton
> irá alterar os ficheiros <filename
>*.toc</filename
> em disco, como tal a operação de remoção é segura agora. </para
></note>

</sect3
> <!-- setup-docu-general-toc -->

<sect3 id="setup-docu-general-toc-files">
<title
>Ficheiros de índice do &kdevelop;</title>

<para
>Existe uma funcionalidade especial associada a isto. Para ilustrá-la, siga estes passos: Na árvore de documentação, escolha um item ligeiramente abaixo da documentação do &Qt;/&kde; (&eg;, o <quote
>Livro de Programação no KDE2 (kde.org)</quote
>). Carregue no sinal de mais (+) ao lado dele. Irá abrir uma árvore, na qual você poderá navegar pelos capítulos subsequentes que se encontram vários níveis abaixo, tudo de forma desligada. Porém, se você seleccionar finalmente um dos capítulos, o &kdevelop; irá em muitos dos casos tentar aceder a um ficheiro de documentação <emphasis
>remoto</emphasis
>. </para>

<para
>A razão por detrás disto e não só navegar localmente pela documentação remota sem desperdiçar recursos de acesso à rede, mas também para oferecer ao programador um acesso simples e estruturado à documentação que precisa. Com as ferramentas aqui oferecidas, uma pessoa poderá aceder a quase qualquer documentação local ou remota de forma estruturada, mesmo que o documento original seja um só ou a sua estrutura original seja diferente. Tudo o que é preciso é o acesso aos ficheiro e/ou partes dos outros ficheiros que são legíveis no &konqueror;. </para>

<para
>Esse acesso estruturado é possível com a utilização de <quote
>ficheiros de índice</quote
> especiais, os quais são identificados pela extensão <filename
>.toc</filename
>. Qualquer um desses ficheiros de índice do &kdevelop; contêm uma descrição estruturada em &XML; do documento a ser acedido. </para>

<formalpara>
<title
>Directoria Normal dos Ficheiros de Índice do &kdevelop;</title>
<para
>Quando o &kdevelop; foi instalado, normalmente foi colocada uma série de ficheiros <filename
>.toc</filename
> predefinidos na directoria <filename class="directory"
>$KDEDIR/share/apps/kdevdoctreeview/tocs</filename
>. Estes são ficheiros de texto estruturado relativamente simples. Você poderá olhar para eles com um editor de texto ou com outra funcionalidade de apresentação de texto. </para>
</formalpara>

<variablelist id="toc-file-structure">
  <title
>Estrutura Básica dos Ficheiros de Índice do &kdevelop;</title>
  <varlistentry>
    <term
>cabeçalho</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput
>&lt;!DOCTYPE kdeveloptoc&gt;</computeroutput>
        </member>
        <member>
          <computeroutput
>&lt;kdeveloptoc&gt;</computeroutput>
        </member>
        <member>
          <emphasis
>(título)</emphasis>
        </member>
        <member>
          <emphasis
>(endereço de base)</emphasis>
        </member>
        <member>
          <emphasis
>(estrutura do conteúdo)</emphasis>
        </member>
        <member>
          <emphasis
>(estrutura do índice)</emphasis>
        </member>
        <member>
          <computeroutput
>&lt;/kdeveloptoc&gt;</computeroutput>
        </member>
      </simplelist>
      <para
>Esta estrutura em &XML; será processada pelo 'plugin' de <guilabel
>Documentação</guilabel
> do &kdevelop; para configurar o conteúdo da árvore de documentação e para guiar o utilizador na navegação pela documentação. Ele contém toda a informação necessária para mostrar os títulos e aceder ao conteúdo do ficheiro de documentação. </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
>title</term>
    <listitem>
      <simplelist>
        <member
><computeroutput
>&lt;title&gt;</computeroutput
> <emphasis
>(algum texto de título)</emphasis
> <computeroutput
>&lt;/title&gt;</computeroutput
> </member>
      </simplelist>
      <para
>Este é o título que o &kdevelop; irá mostrar nos níveis básicos da árvore de documentação. </para>
      <note
><para
>Este título apresentado não pode de momento ser alterado pelo utilizador. Se você quiser mostrar outro texto, você terá de alterar manualmente o item <computeroutput
>&lt;title&gt;</computeroutput
> no ficheiro <filename
>.toc</filename
>. </para
></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
>endereço de base</term>
    <listitem>
      <simplelist>
        <member
><computeroutput
>&lt;base href="</computeroutput
> <emphasis
>(&URL; do documento de base)</emphasis
> <computeroutput
>"/&gt;</computeroutput
> </member>
      </simplelist>
      <para
>Este &URL; aponta para a localização em que todos os ficheiros desta documentação se localizam. Será inserida no início de cada &URL; de secção na seguinte lista da estrutura do conteúdo. Por isso, se você &eg; obter alguma documentação de um servidor remoto, tudo o que precisa para mostrar os ficheiros nesta nova localização é mudar o &URL; da <computeroutput
>&lt;base&gt;</computeroutput
>. </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
>estrutura do conteúdo</term>
    <listitem>
      <simplelist>
        <member
><computeroutput
>&lt;tocsect1 name="</computeroutput
> <emphasis
>(título da secção)</emphasis
> <computeroutput
>" url="</computeroutput
> <emphasis
>(&URL; da secção)</emphasis
> <computeroutput
>"&gt;</computeroutput
> </member>
        <member
>...</member>
        <member
><computeroutput
>&lt;tocsectn name="</computeroutput
> <emphasis
>(título da secção)</emphasis
> <computeroutput
>" url="</computeroutput
> <emphasis
>(&URL; da secção)</emphasis
> <computeroutput
>"/&gt;</computeroutput
> </member>
        <member
>...</member>
        <member>
          <computeroutput
>&lt;/tocsect1&gt;</computeroutput>
        </member>
      </simplelist>
      <para
>Toda a informação restante de navegação e de acesso é guardada numa série de pares <computeroutput
>&lt;tocsecti&gt;</computeroutput
> ... <computeroutput
>&lt;/tocsecti&gt;</computeroutput
> aninhados. Cada <emphasis
>i</emphasis
> corresponde a um nível consecutivo de aninhamento abaixo do nível <emphasis
>n</emphasis
>, correspondente à secção de documentação finalmente apresentada. </para>
      <para
>Todos os itens <computeroutput
>&lt;tocsecti&gt;</computeroutput
> devem ter um atributo <computeroutput
>name="xxx"</computeroutput
> associado a eles (o "xxx" representa o título actual). Isto será mostrado como o título do nível na árvore de documentação. Ele irá corresponder a uma secção da documentação actual. </para>
      <para
>Poderá existir um atributo <computeroutput
>url=""</computeroutput
> associado ao nível de aninhamento <emphasis
>i</emphasis
>. Quando o utilizador carregar no título de uma secção da documentação, o &kdevelop; irá tentar aceder ao ficheiro na localização indicada pelo endereço de base combinado com o &URL; da secção. </para>
      <para
>O item <computeroutput
>&lt;tocsectn/&gt;</computeroutput
> precisa de ter um atributo <computeroutput
>url=""</computeroutput
>, de qualquer forma. Este <computeroutput
>&lt;tocsectn/&gt;</computeroutput
> final não vem aos pares, mas será sim fechado por um <computeroutput
>/</computeroutput
> antes do carácter <computeroutput
>&gt;</computeroutput
>. </para>
      <note
><para
>Qualquer endereço resultante da combinação do endereço de base e do &URL; da secção precisam de apontar para um ficheiro de texto visível. Normalmente, ester será um ficheiro estruturado em HTML. É possível fazer referência a 'âncoras' num desses ficheiros, usando a notação normal do '#', com o formato: <filename
>/url-de-base/url-da-seccao#ancora</filename
>. </para
></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term
>estrutura do índice</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput
>&lt;index&gt;</computeroutput>
        </member>
        <member
><computeroutput
>&lt;entry name="</computeroutput
> <emphasis
>(título do índice)</emphasis
> <computeroutput
>" url="</computeroutput
> <emphasis
>(&URL; da secção do índice)</emphasis
> <computeroutput
>"/&gt;</computeroutput
> </member>
        <member>
          <computeroutput
>&lt;/index&gt;</computeroutput>
        </member>
      </simplelist>
      <para
>O índice é uma lista simples de itens de índice - pares de títulos e &URL;s. O índice não é obrigatório. </para>
    </listitem>
  </varlistentry>
</variablelist>

</sect3
> <!-- setup-docu-general-toc-files  -->

<sect3 id="setup-docu-general-devhelp">
<title
>Documentação do DevHelp</title>

<para
>A documentação do DevHelp é outra forma de aceder à documentação estruturada. Ele usa os ficheiros de índice estruturados identificados por uma extensão <filename
>.devhelp</filename
> semelhante aos <link linkend="setup-docu-general-toc-files"
>ficheiros TOC do &kdevelop;</link
> para aceder à documentação do ambiente de trabalho do GNOME 2. </para>
<para
>Você poderá controlar quais os ficheiros do DevHelp que deverão estar acessíveis na página de configuração da <guilabel
>Colectânea de Documentação do DevHelp</guilabel
>. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-devhelp.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Fornecer a documentação do DevHelp </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Como adquirir a documentação do DevHelp</title>
<para
>Os ficheiros do DevHelp originalmente estavam acessíveis no 'site' Web do <ulink url="http://lidn.sourceforge.net/"
>LiDN</ulink
>, mas estes parece que não são mantido já há algum tempo. A documentação do DevHelp mais recente está disponível na página Web para <ulink url="http://htmlhelp.berlios.de/books/devhelp.php"
>Obter os Livros do DevHelp</ulink
>. </para>
</formalpara>

<para
>Quando o &kdevelop; é instalado, ele irá tentar procurar todos os ficheiros <filename
>.devhelp</filename
> nos locais-padrão do sistema, &eg; nas subdirectorias de <filename class="directory"
>/opt/gnome/share/</filename
>. Inicialmente, estes ficheiros não serão marcados para serem visualizados. Se quiser ver outra documentação, marque a opção <guilabel
>TOC</guilabel
> da <link linkend="setup-docu-columns"
>tabela de configuração</link
>. </para>

<para
>Você poderá adicionar novos itens com os <link linkend="setup-docu-buttons"
>botões</link
> à direita da lista. O &kdevelop; irá filtrar os ficheiros <filename
>*.toc</filename
> na janela de directoria associada aos botões <guibutton
>Adicionar</guibutton
> e <guibutton
>Editar</guibutton
>. </para>

</sect3
> <!-- setup-docu-general-devhelp -->

<sect3 id="setup-docu-general-custom">
<title
>Configurar as Colectâneas de Documentação Personalizadas</title>

<para
>Isto é para o seu próprio fim. Você poderá adicionar quase qualquer tipo de documentação, desde que possa ser mostrada pelos 'plugins' do &konqueror;. </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-custom.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Fornecer a documentação personalizada </para
></caption>
  </mediaobject>
</screenshot>

<para
>Normalmente, esta colecção estará vazia no primeiro arranque do &kdevelop;. Foi preenchido deliberadamente um item para mostrar a estrutura do item. </para>
<para
>O tratamento é relativamente simples aqui. Use os <link linkend="setup-docu-buttons"
>botões</link
> à direita da lista para adicionar, editar ou remover os itens dos documentos. O &kdevelop; não irá filtrar nada da janela de directorias que esteja associado aos botões <guibutton
>Adicionar</guibutton
> e <guibutton
>Editar</guibutton
>. </para>

<para
>Você terá de seleccionar explicitamente os itens para os mostrar na funcionalidade de documentação do &kdevelop;. Marque a opção <guilabel
>TOC</guilabel
> do item na <link linkend="setup-docu-columns"
>tabela de configuração</link
>. </para>

<note
><para
>A documentação personalizada não pode ser indexada ou pesquisada. Como tal, as opções <guilabel
>Índice</guilabel
> e <guilabel
>Procurar</guilabel
> não farão efeito, como é mostrado acima. </para
></note>

</sect3
> <!--- setup-docu-general-custom -->

</sect2
> <!-- setup-docu-general -->

<sect2 id="setup-docu-textsearch">
<title
>Configurar os Índices de Pesquisa de Texto</title>

<para
>(... ainda não escrito ...) </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-doctree-textsearch.png" format="PNG"/>
    </imageobject>
    <caption
><para
>Configurar os índices de pesquisa de texto </para
></caption>
  </mediaobject>
</screenshot>

</sect2
> <!-- setup-docu-textsearch -->

<sect2 id="setup-docu-other">
<title
>Outras Configurações de Documentação</title>

<para
>(... ainda não escrito ...) </para>

</sect2
> <!-- setup-docu-other -->

</sect1
> <!-- setup-docu -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="setup-advanced">
<title
>Configuração Avançada</title>

<para
>(... ainda não escrito ...) </para>

<sect2 id="setup-plugins">
<title
>Ferramentas em 'Plugins'</title>

<para
>(... ainda não escrito ...) </para>
</sect2
> <!-- setup-plugins -->

<sect2 id="setup-abbrev">
<title
>Abreviaturas para a Completação de Palavras</title>

<para
>(... ainda não escrito ...) </para>
</sect2
> <!-- setup-abbrev -->

<sect2 id="setup-menu-standard">
<title
>Adicionar Aplicações Normais do &kde; ao Menu Ferramentas</title>

<para
>(... ainda não escrito ...) </para>
</sect2
> <!-- setup-menu-standard -->


<sect2 id="setup-menu-external">
<title
>Adicionar Aplicações Externas aos Menus</title>

<para
>(... ainda não escrito ...) </para>

<sect3 id="setup-menu-external-tools">
<title
>Adicionar ao Menu Ferramentas</title>

<para
>(... ainda não escrito ...) </para>
</sect3
> <!-- setup-menu-external-tools -->

<sect3 id="setup-menu-external-filecontext">
<title
>Adicionar ao Menu de Contexto dos Ficheiros</title>

<para
>(... ainda não escrito ...) </para>
</sect3
> <!-- setup-menu-external-filecontext -->

<sect3 id="setup-menu-external-dircontext">
<title
>Adicionar ao Menu de Contexto das Directorias</title>

<para
>(... ainda não escrito ...) </para>
</sect3
> <!-- setup-menu-external-dircontext -->

</sect2
> <!-- setup-menu-external -->

</sect1
> <!-- setup-advanced -->

</chapter
> <!-- setup -->
