<appendix id="highlight">
<title
>Trabalhar com o Realce de Sintaxe</title>

<sect1 id="highlight-overview">

<title
>Introdução</title>

<para
>O Realce de Sintaxe é o que faz o editor mostrar automaticamente o texto em diferentes estilos/cores, dependendo da função do texto em relação ao propósito do ficheiro. No código-fonte de um programa, por exemplo, as instruções de controlo podem ser representadas a negrito, enquanto os tipos de dados e os comentários têm cores diferentes do resto do texto. Isto aumenta em larga medida a legibilidade do texto, e por isso ajuda o autor a ser mais eficiente e produtivo.</para>

<mediaobject
> <imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject
> <textobject
><phrase
>Uma função de Perl, representada com realce de sintaxe.</phrase
></textobject
> <caption
><para
>Uma função de Perl, representada com realce de sintaxe.</para
> </caption
> </mediaobject>

<mediaobject
> <imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject
> <textobject
><phrase
>A mesma função de Perl, sem realce de sintaxe.</phrase
></textobject
> <caption
><para
>A mesma função de Perl, sem realce de sintaxe.</para
></caption
> </mediaobject>

<para
>Dos dois exemplos, qual é o mais fácil de ler?</para>

<para
>O &kate; vem com um sistema flexível, configurável e capaz de fazer realce de sintaxe; a distribuição normal oferece definições para um conjunto vasto de linguagens de programação, de manipulação e de 'scripting', bem como para outros formatos de texto. Para além disso, podes criar as tuas próprias definições em ficheiros &XML; simples.</para>

<para
>O &kate; irá detectar automaticamente as regras de sintaxe correctas quando abres um ficheiro, baseando-se no tipo &MIME; do ficheiro, pela sua extensão, ou se não tiver nenhuma, pelo seu conteúdo. Se a escolha for errada, podes definir manualmente a sintaxe a usar no menu <menuchoice
><guimenu
>Documentos</guimenu
><guisubmenu
>Modo de Realce</guisubmenu
></menuchoice
>.</para>

<para
>Os estilos e cores usados por cada definição de realce de sintaxe, assim como os tipos &MIME; para os quais deve ser usada, podem ser configurados usando a página de <link linkend="config-dialog-editor-hl"
>Realce</link
> da <link linkend="config-dialog"
>Janela de Configuração</link
>.</para>

<note
> <para
>O realce de sintaxe existe para melhorar a legibilidade do texto correcto, mas não podes esperar que ela valide o teu texto. A marcação do texto para a sintaxe é complicada, dependendo do formato que estás a usar e, em muitos dos casos, os autores das regras de sintaxe sentir-se-ão orgulhosos se 98% do texto for correctamente apresentado, ainda que na maior parte das vezes precisas de um estilo rar para veres os 2% incorrectos.</para
> </note>

<tip
> <para
>Podes obter as definições de sintaxe adicionais ou actualizadas no 'site' Web do &kate; carregando no botão <guibutton
>Obter</guibutton
> na <link linkend="config-dialog-editor-hl"
>Página Realce</link
> da <link linkend="config-dialog"
>Janela de Configuração</link
>.</para
> </tip>

</sect1>

<sect1 id="katehighlight-system">

<title
>O Sistema de Realce de Sintaxe do &kate;</title>

<para
>Esta secção irá discutir o realce de sintaxe do &kate; com mais detalhe. É para ti se quiseres saber acerca dele ou se quiseres criar ou alterar as definições de sintaxe.</para>

<sect2 id="katehighlight-howitworks">

<title
>Como Funciona</title>

<para
>Sempre que abres um ficheiro, uma das primeiras coisas que o editor do &kate; faz é detectar qual a definição de sintaxe a usar para o ficheiro. Enquanto vai lendo o texto do ficheiro, e enquanto vais escrevendo nele, o sistema de realce de sintaxe irá analisar o texto usando as regras definidas pela definição da sintaxe e marcá-la onde os diferentes contextos e estilos começam e acabam.</para>

<para
>Quando escreves no documento, o novo texto é analisado e marcado na altura, por isso se apagares um carácter que está marcado como o início ou o fim de um contexto, o estilo do texto circundante muda de acordo com esse facto.</para>

<para
>As definições de sintaxe usadas pelo sistema de realce de sintaxe do &kate; são ficheiros &XML; que contêm <itemizedlist
> <listitem
><para
>As regras para detectar o papel do texto, organizado em blocos de contextos</para
></listitem
> <listitem
><para
>Listas de palavras-chaves</para
></listitem
> <listitem
><para
>Definições de Itens de Estilo</para
></listitem
> </itemizedlist
> </para>

<para
>Ao analisar o texto, as regras de detecção são avaliadas na ordem em que são definidas, e se o início do texto actual corresponder a uma regra, o contexto relacionado é usado. O ponto inicial do texto é movido para o ponto final a partir do qual essa regra correspondeu e dá-se início a mais um ciclo das regras, o qual dá início no conjunto de contextos definido pela regra correspondente.</para>

</sect2>

<sect2 id="highlight-system-rules">
<title
>Regras</title>

<para
>As regras de detecção são o 'coração' do sistema de detecção de sintaxe. Uma regra é uma cadeia de caracteres, um carácter ou uma <link linkend="regular-expressions"
>expressão regular</link
> com a qual se faz a correspondência do texto a analisar. Contém informações sobre o estilo a usar para a parte correspondente do texto. Pode mudar do contexto actual do sistema para um outro contexto explícito ou para o contexto anterior usado pelo texto.</para>

<para
>As regras são organizadas em grupos de contextos. Um grupo de contextos é usado para os conceitos principais do formato, como por exemplo as cadeias de caracteres entre aspas ou os blocos de comentários no código-fonte do programa. Isto garante que o sistema de realce de sintaxe não necessita de circular por todas as regras quando não é necessário, e que algumas sequências de caracteres no texto podem ser tratadas de modo diferente, dependendo do contexto actual. </para>

</sect2>

<sect2 id="highlight-context-styles-keywords">
<title
>Estilos de Contexto e Palavras-Chave</title>

<para
>Em algumas linguagens de programação, os números inteiros são tratados de forma diferente dos números de vírgula flutuante pelo compilador (o programa que converte o código-fonte num executável binário), assim como podem existir caracteres com um significado especial dentro de uma cadeia de caracteres entre aspas. Em ambos os casos, faz sentido mostrá-los de forma diferente dos seus vizinhos, de modo a que sejam fáceis de identificar enquanto lês o texto. Por isso, mesmo que não representem contextos especiais, podem ser vistos como tal pelo sistema de realce de sintaxe, de modo a que possam ser marcados para ser desenhados de diferente forma.</para>

<para
>Uma definição de sintaxe pode conter tantos estilos quanto os necessários para cobrir os conceitos do formato no qual é usado.</para>

<para
>Em vários formatos, existem listas de palavras que representam um conceito específico. Como exemplo nas linguagens de programação, as instruções de controlo são um conceito, os tipos de dados são outro e as funções intrínsecas à linguagem são um terceiro conceito. O Sistema de Realce de Sintaxe do &kate; pode usar essas listas para detectar e marcar as palavras no texto de modo a realçar os conceitos dos formatos de texto.</para>

</sect2>

<sect2 id="kate-highlight-system-default-styles">
<title
>Estilos por Omissão</title>

<para
>Se abrires um ficheiro de código em C++, um ficheiro de &Java; e um documento em <acronym
>HTML</acronym
> no &kate;, verás que, ainda que os formatos sejam diferentes e por isso sejam seleccionadas palavras diferentes para um tratamento especial, as cores usadas são as mesmas. Isto deve-se ao facto do &kate; ter uma lista predefinida de Estilos por Omissão, os quais são empregues pelas definições de sintaxe individuais.</para>

<para
>Isto facilita o reconhecimento de conceitos similares nos diferentes formatos de texto. Por exemplo, os comentários estão presentes em quase todas as linguagens de programação, 'scripting' ou de marcação, e quando são representados com o mesmo estilo em todas as linguagens, não tens de parar e pensar para os identificar no texto.</para>

<tip
> <para
>Todos os estilo de uma definição de sintaxe usam um dos estilos por omissão. Algumas definições de sintaxe usam mais estilos para além dos predefinidos, por isso se usares um formato frequentemente, pode valer a pena abrir a janela de configuração para veres se alguns conceitos estão a usar o mesmo estilo. Por exemplo, só existe um estilo por omissão para as cadeias de caracteres, mas como a linguagem de programação Perl lida com dois tipos de cadeias de caracteres, podes melhorar o realce configurando esses dois tipos de uma forma ligeiramente diferente.</para
> </tip>

</sect2>

</sect1>

<sect1 id="katehighlight-xml-format">
<title
>O Formato &XML; da Definição de Realce</title>

<sect2>
<title
>Introdução</title>

<para
>Esta secção é uma introdução ao formato &XML; da Definição de Realce. Irá descrever as componentes principais, bem como o seu significado e utilização, indo em mais detalhes com as regras de detecção.</para>

<para
>A definição formal, mais conhecida por <acronym
>DTD</acronym
> é guardada no ficheiro <filename
>language.dtd</filename
>, o qual deve estar instalado no teu sistema na directoria <filename
>$<envar
>KDEDIR</envar
>/share/apps/kate/syntax</filename
>.</para>

<variablelist
> <title
>Componentes principais das Definições de Realce do &kate;</title
> <varlistentry
> <term
>A Secção Geral</term
> <listitem
> <para
>A Secção Geral contém informações no formato dos comentários da linguagem descrita, e define quais as palavras-chave que são distintas se forem maiúsculas ou minúsculas.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Realce</term
> <listitem
> <para
>A secção Reace contém todos os dados necessários para analisar e desenhar o texto. Isto inclui:</para
> <variablelist
> <varlistentry
> <term
>ItemDatas</term
> <listitem
><para
>Contém os elementos ItemData, em que cada uma define um estilo.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Listas de palavras-chaves</term
> <listitem
> <para
>Cada lista tem um nome e pode conter uma quantidade qualquer de itens.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Contexts</term
> <listitem
> <para
>Contém os contextos, que definem de novo as regras de detecção de sintaxe.</para
> </listitem
> </varlistentry
> </variablelist
> </listitem
> </varlistentry
> </variablelist>

</sect2>

</sect1>

<sect1 id="kate-highlight-rules-detailled">
<title
>Regras de Detecção do Realce</title>

<para
>Esta secção descreve as regras de detecção da sintaxe.</para>

<para
>Cada regra pode corresponder a zero ou mais caracteres no início do texto que é testado. Se a regra corresponder, é atribuído o estilo ou <emphasis
>atributo</emphasis
> definido pela regra aos caracteres correspondentes; uma regra, pode perguntar se o contexto actual será alterado.</para>

<para
>O <emphasis
>atributo</emphasis
> e os atributos de <emphasis
>contexto</emphasis
> são comuns a todas as regras.</para>

<para
>Uma regra parece-se com o seguinte:</para>

<programlisting
>&lt;NomeRegra attribute=&quot;(identificador)&quot; context=&quot;(identifier|order)&quot; [atributos específicos da regra] /&gt;</programlisting>

<para
>O <emphasis
>attribute</emphasis
> identifica o estilo a usar para os caracteres correspondentes pelo nome ou índice; o <emphasis
>context</emphasis
> identifica, como será de esperar, o contexto a usar a partir daqui.</para>

<para
>O <emphasis
>attribute</emphasis
> pode ser identificado quer por nome, quer pelo seu índice, a começar em zero, no grupo ItemDatas.</para>

<para
>O <emphasis
>context</emphasis
> pode ser identificador por:</para>

<itemizedlist
> <listitem
> <para
>Um <emphasis
>identificador</emphasis
>, o qual é, de momento, somente o seu índice com início em zero no grupo de contextos.</para
> </listitem
> <listitem
> <para
>Uma <emphasis
>ordem</emphasis
> que indica ao motor para permanecer no contexto actual (<userinput
>#stay</userinput
>) ou para voltar a um contexto anterior usado no texto (<userinput
>#pop</userinput
>).</para
> <para
>Para recuar mais vezes, a palavra #pop pode ser repetida: <userinput
>#pop#pop#pop</userinput
></para
> </listitem
> </itemizedlist>

<para
>Algumas regras podem ter <emphasis
>regras-filho</emphasis
>, as quais podem ser avaliadas se e só se a regra-mãe foi verificada. O texto inteiro verificado terá o atributo definido pela regra-mãe. Uma regra com regras-filho será algo do género:</para>

<programlisting>
&lt;NomeRegra (atributos)&gt;
  &lt;NomeRegraFilhoe (atributos) /&gt;
  ...
&lt;/NomeRegra&gt;
</programlisting>


<para
>Os atributos específicos da regra variam e estão descritos na lista seguinte.</para
> 

<variablelist
> <title
>As Regras em Detalhe</title
> <varlistentry
> <term
>DetectChar</term
> <listitem
> <para
>Detecta um único carácter específico. É usado vulgarmente para encontrar, por exemplo, o fim das cadeias de caracteres entre aspas.</para
> <programlisting
>&lt;DetectChar char=&quot;(carácter)&quot; (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>char</userinput
> define o carácter a encontrar.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Detect2Chars</term
> <listitem
> <para
>Detecta dois caracteres específicos numa ordem definida.</para
> <programlisting
>&lt;Detect2Chars char=&quot;(carácter)&quot; char1=&quot;(carácter)&quot; (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>char</userinput
> define o primeiro carácter a encontrar, enquanto <userinput
>char1</userinput
> define o segundo.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>AnyChar</term
> <listitem
> <para
>Detecta um carácter de um conjunto de caracteres especificados.</para
> <programlisting
>&lt;AnyChar String=&quot;(texto)&quot; (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>String</userinput
> define o conjunto de caracteres.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>StringDetect</term
> <listitem
> <para
>Detecta um texto exacto.</para
> <programlisting
>&lt;StringDetect String=&quot;(string)&quot; [insensitive=&quot;TRUE|FALSE;&quot;] (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>String</userinput
> define a sequência a encontrar. O atributo <userinput
>insensitive</userinput
> é por omissão <userinput
>FALSE</userinput
> e é passado à função de comparação de cadeias de caracteres. Se o valor for <userinput
>TRUE</userinput
> a comparação não faz distinção entre maiúsculas e minúsculas.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>RegExpr</term
> <listitem
> <para
>Corresponde a uma expressão regular.</para
> <programlisting
>&lt;RegExpr String=&quot;(texto)&quot; [insensitive=&quot;TRUE|FALSE;&quot;] [minimal=&quot;TRUE|FALSE&quot;] (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>String</userinput
> define a expressão regular.</para
> <para
>O <userinput
>insensitive</userinput
> é por omissão <userinput
>FALSE</userinput
>  e é passado ao motor de expressões regulares.</para
> <para
>O <userinput
>minimal</userinput
> é por omissão <userinput
>FALSE</userinput
> e é passado ao motor de expressões regulares.</para
> <para
>Como as regras se aplicam ao início do texto actual, uma expressão regular que comece por um acento circunflexo (<literal
>^</literal
>) indica que a regra só deve ser verificada se for no início de uma linha.</para
> <para
>Vê as <link linkend="regular-expressions"
>Expressões Regulares</link
> para mais informações sobre elas.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Keyword</term
> <listitem
> <para
>Detecta uma palavra-chave de uma lista específica.</para
> <programlisting
>&lt;keyword String=&quot;(nome da lista)&quot; (atributos comuns) /&gt;</programlisting
> <para
>O atributo <userinput
>String</userinput
> identifica a lista de palavras-chave pelo seu nome. Deve existir uma lista com esse nome.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Int</term
> <listitem
> <para
>Detecta um número inteiro.</para
> <para
><programlisting
>&lt;Int (atributos comuns) /&gt;</programlisting
></para
> <para
>Esta regra não tem atributos específicos. As regras-filho são tipicamente usadas para detectar as combinações de <userinput
>L</userinput
> e <userinput
>U</userinput
> depois do número, o que indica o tipo inteiro no código do programa.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>Float</term
> <listitem
> <para
>Detecta um número de vírgula flutuante.</para
> <para
><programlisting
>&lt;Float (atributos comuns)
/&gt;</programlisting
></para
> <para
>Esta regra não tem atributos específicos.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>HlCOct</term
> <listitem
> <para
>Detecta uma representação de um número octal.</para
> <para
><programlisting
>&lt;HlCOct (atributos comuns) /&gt;</programlisting
></para
> <para
>Esta regra não tem atributos específicos.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>HlCHex</term
> <listitem
> <para
>Detecta uma representação de um número em hexadecimal.</para
> <para
><programlisting
>&lt;Int (atributos comuns) /&gt;</programlisting
></para
> <para
>Esta regra não tem atributos específicos.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>HlCStringChar</term
> <listitem
> <para
>Detecta um carácter 'escapado'.</para
> <para
><programlisting
>&lt;HlCStringChar (atributos comuns)
/&gt;</programlisting
></para
> <para
>Esta regra não tem atributos específicos.</para
> <para
>Corresponde a representações literais dos caracteres invisíveis usados normalmente no código do programa, como por exemplo o <userinput
>\n</userinput
> (nova linha) ou o <userinput
>\t</userinput
> (TAB).</para
> <para
>Os seguintes caracteres irão corresponder se estiverem a seguir a uma barra invertida (<literal
>\</literal
>): <userinput
>abefnrtv&quot;'?</userinput
>. Para além disso, os números escapados em hexadecimal como por exemplo o <userinput
>\xff</userinput
> e os números octais escapados, como o <userinput
>\033</userinput
> irão corresponder.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>RangeDetect</term
> <listitem
> <para
>Detecta uma cadeia de caracteres com os caracteres de início e fim definidos.</para
> <programlisting
>&lt;RangeDetect char=&quot;(carácter)&quot;  char1=&quot;(carácter)&quot; (atributos comuns) /&gt;</programlisting
> <para
>O <userinput
>char</userinput
> define o carácter de início e o <userinput
>char2</userinput
> o carácter de termina o intervalo.</para
> <para
>Útil para detectar, por exemplo, pequenas cadeias de caracteres entre aspas e semelhantes, mas repara que, dado que o motor de realce de sintaxe funciona com uma linha de cada vez, isto não irá encontrar as cadeias de caracteres que se prolonguem por mais do que uma linha.</para
> </listitem
> </varlistentry
> <varlistentry
> <term
>LineContinue</term
> <listitem
> <para
>Corresponde ao fim da linha.</para
> <programlisting
>&lt;LineContinue (atributos comuns) /&gt;</programlisting
> <para
>Esta regra não tem atributos específicos.</para
> <para
>Esta regra é útil para mudar de contexto no fim da linha.</para
> </listitem
> </varlistentry
> </variablelist>

</sect1>

</appendix>

