path: root/tde-i18n-ca/docs/tdebase/kate/highlighting.docbook

<appendix id="highlight">
<appendixinfo>
<authorgroup>
<author><personname><firstname></firstname></personname></author>
&traductor.Antoni.Bella; 
</authorgroup>
</appendixinfo>
<title>Treballar amb el ressaltat de sintaxi</title>

<sect1 id="highlight-overview">

<title>Vista general</title>

<para>El ressaltat de sintaxi és el que fa que l'editor mostri automàticament text en diferents estils/colors, depenent de la funció de la cadena en relació al propòsit del fitxer. En el codi font d'un programa, per exemple, les sentències de control es poden presentar en negreta, mentre que els tipus de dades i els comentaris poden tenir diferents colors que la resta del text. Això millora considerablement la llegibilitat del text, i ajuda a l'autor a ser més eficient i productiu.</para>

<mediaobject>
<imageobject><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject><phrase>Una funció de Perl, presentada amb ressaltat de sintaxi.</phrase></textobject>
<caption><para>Una funció de Perl, presentada amb ressaltat de sintaxi.</para>
</caption>
</mediaobject>

<mediaobject>
<imageobject><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject><phrase>La mateixa funció de Perl, sense ressaltat.</phrase></textobject>
<caption><para>La mateixa funció de Perl, sense ressaltat.</para></caption>
</mediaobject>

<para>Dels dues exemples, quin resulta més fàcil de llegir?</para>

<para>&kate; compta amb un sistema de ressaltat de sintaxi flexible, configurable i capaç, la distribució estàndard proveeix definicions per a un ampli rang de llenguatges de programació, d'scripts i de marques. A més podeu proveir les vostres pròpies definicions en simples fitxers &XML;.</para>

<para>&kate; detectarà automàticament les regles de sintaxi correctes quan obriu un fitxer, basant-se en el tipus &MIME; del fitxer, determinat per la seva extensió, o, si no en te, pel seu contingut. Si la elecció no és la correcta, podreu establir-la manualment des del menú <menuchoice><guimenu>Document</guimenu><guisubmenu>Mode de ressaltat</guisubmenu></menuchoice>.</para>

<para>Els estils i colors usats per a cada definició de ressaltat de sintaxi es poden configurar usant la pàgina <link linkend="config-dialog-editor-appearance">Aparença</link> del <link linkend="config-dialog">Diàleg de configuració</link>, mentre que els tipus &MIME; per als que s'hauran d'usar, es poden gestionar usant la pàgina <link linkend="config-dialog-editor-highlighting">Ressaltat</link>.</para>

<note>
<para>El ressaltat de sintaxi te el seu ús en la millora de la llegibilitat del text, però no podeu confiar-hi per a validar que el text és correcte. Marcar el text en funció de la seva sintaxi pot ser difícil, depenent del format que s'estigui usant, i en alguns casos els autors de les regles de sintaxi poden estar orgullosos si es processa correctament el 98% del text, si be caldrà un estil molt rar per a veure el 2% incorrecte.</para>
</note>

<tip>
<para>Podeu descarregar actualitzacions o definicions de ressaltat de sintaxi addicionals des del lloc web de &kate; fent clic en el botó <guibutton>Descarrega</guibutton> en la <link linkend="config-dialog-editor-highlighting">Pàgina de ressaltat</link> del <link linkend="config-dialog">Diàleg de configuració</link>.</para>
</tip>

</sect1>

<sect1 id="katehighlight-system">

<title>El sistema de ressaltat de sintaxi de &kate;</title>

<para>Aquesta secció tractarà sobre el mecanisme de ressaltat de sintaxi de &kate; amb més detall. Recomanem la seva lectura si desitgeu aprendre a sobre seu, o si desitgeu crear o canviar les definicions de sintaxi.</para>

<sect2 id="katehighlight-howitworks">

<title>Com funciona</title>

<para>Sempre que obriu un fitxer, una de les primeres coses que fa l'editor de &kate; és detectar quina definició de sintaxi s'usarà per al fitxer. Mentre va llegint el text del fitxer, i mentre hi va escrivint, el sistema de ressaltat de sintaxi analitza el text usant les regles establertes per la definició de sintaxi i marcant a on comencen i acaben els diferents contexts i estils.</para>

<para>Quan escriviu en el document, el text nou és analitzat i marcat al vol, de manera que si esborreu un caràcter que marca el començament o el final d'un context, l'estil del text adjacent canviarà en conseqüència.</para>

<para>Les definicions de sintaxi usades pel sistema de ressaltat de sintaxi de &kate; són fitxers &XML;, que contenen <itemizedlist>
<listitem><para>Regles per a detectar el paper del text, organitzades en blocs de context</para></listitem>
<listitem><para>Llistes de paraules clau</para></listitem>
<listitem><para>Definicions d'ítems d'estil</para></listitem>
</itemizedlist>
</para>

<para>Quan s'analitza el text, les regles de detecció són avaluades en l'ordre en el que estan definides, i si el començament de la cadena actual coincideix amb la regla, s'usarà el context relacionat. El punt d'inici del text es mou al punt final en el que la regla coincideix i comença un nou cicle de regles, començant en el context establert per la regla coincident.</para>

</sect2>

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

<para>Les regles de detecció són el nucli del sistema de detecció de ressaltat. Una regla és una cadena, un caràcter o una <link linkend="regular-expressions">expressió regular</link> contra la que haurà de coincidir el text que s'està analitzant. Conté informació sobre l'estil a usar per a la part coincident del text. Es pot canviar el context de treball del sistema, ja sigui cap a un context mencionat explícitament o cap l'anterior context usat pel text.</para>

<para>Les regles s'organitzen en grups de context. Un grup de context s'usa per als conceptes del text principal dins del format, per exemple, les cadenes de text entre cometes o els blocs de comentaris en el codi font d'un programa. Això garanteix que el sistema de ressaltat no necessita realitzar un cicle per a totes les regles quan no és necessari, i que algunes seqüències de caràcters del text es poden tractar de forma diferent depenent del context actual. </para>

<para>En les regles és possible generar contexts dinàmicament per a permetre l'ús de dades específiques d'una instància.</para>

</sect2>

<sect2 id="highlight-context-styles-keywords">
<title>Estils i paraules clau del context</title>

<para>En alguns llenguatges de programació, els números enters són tractats pel compilador (el programa que converteix el codi font en un executable binari) d'una forma diferent als de coma flotant, i poden haver-hi caràcters que tinguin un significat especial dins d'una cadena entre cometes. En aquests casos, te sentit processar-los de diferent manera que el text adjacent, per a que resultin fàcils d'identificar. De manera que si no representen contexts especials, poden ser vistos com a tals pel sistema de ressaltat de sintaxi, així que són marcats per a un processat diferent.</para>

<para>Una definició de sintaxi pot contenir tants estils com siguin requerits per a cobrir tots els conceptes del format per al que s'usa.</para>

<para>En molts formats hi ha llistes de paraules que representen un concepte específic. Per exemple, en els llenguatges de programació, les sentències de control són un concepte, els noms de tipus de dades un altra, i les funcions encastades en el llenguatge són un tercer. El sistema de ressaltat de sintaxi de &kate; pot usar dites llistes per a detectar i marcar paraules en el text per emfatitzar conceptes dels formats de text.</para>

</sect2>

<sect2 id="kate-highlight-system-default-styles">
<title>Estils per omissió</title>

<para>Si obriu un fitxer de codi font de C++, un fitxer font de &Java; i un fitxer <acronym>HTML</acronym> en &kate; podreu comprovar que tot i que els formats són diferents, i per tant les paraules que reben un tractament especial també són diferents, els colors usats són els mateixos. Això es deu a que &kate; te una llista per omissió d'estils per omissió, que s'empren en les definicions de sintaxi individuals.</para>

<para>Això facilita el reconèixer conceptes similars en diferents formats de text. Per exemple, els comentaris estan presents en pràcticament qualsevol llenguatge de programació, scripts o descripció, i si es presenten usant el mateix estil en tots els llenguatges, no haureu de parar-vos a pensar i identificar la seva posició en el text.</para>

<tip>
<para>Tots els estils de definició de sintaxi usen un dels estils per omissió. Hi ha poques definicions de sintaxi que usin més estils dels que hi ha per omissió, així que, si useu un format molt sovint, potser us val la pena obrir el diàleg de configuració per a veure si alguns conceptes estan usant el mateix estil. Per exemple, tan sols hi ha un estil per omissió per a les cadenes, però com el llenguatge de programació Perl usa dos tipus de cadena, podeu millorar el ressaltat configurant ambdues de forma lleugerament diferent. Més endavant s'explicaran tots els <link linkend="kate-highlight-default-styles">estils per omissió disponibles</link>.</para>
</tip>

</sect2>

</sect1>

<sect1 id="katehighlight-xml-format">
<title>El format &XML; de definició de ressaltat</title>

<sect2>
<title>Vista general</title>

<para>Aquesta secció és una introducció al format &XML; de definició de ressaltat. Descriu els components principals, el seu significat i utilització. La següent secció entra en detalls amb les regles de detecció.</para>

<para>La definició formal, és a dir, el <acronym>DTD</acronym>, es desa en el fitxer <filename>language.dtd</filename>, el qual hauria d'estar instal·lat en la carpeta <filename>$<envar>TDEDIR</envar>/share/apps/katepart/syntax</filename> del vostre sistema. </para>

<variablelist>
<title>Principals seccions dels fitxers de definicions de ressaltat de &kate;</title>

<varlistentry>
<term>Tots els fitxers de ressaltat contenen un capçalera que estableix la versió XML i el doctype (tipus de document):</term>
<listitem>
<programlisting>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE language SYSTEM &quot;language.dtd&quot;&gt;
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term>La part principal del fitxer de definició es l'ítem <userinput>languaje</userinput>. Els atributs disponibles són:</term>

<listitem>
<para>Atributs requerits:</para>
<para><userinput>name</userinput> estableix el nom del llenguatge. Després apareixerà en el menú i en els diàlegs.</para>
<para><userinput>section</userinput> especifica la categoria.</para>
<para><userinput>extensions</userinput> defineix les extensions dels fitxers, com &quot;*.cpp;*.h&quot;</para>

<para>Atributs opcionals:</para>
<para><userinput>mimetype</userinput> fitxers associats al tipus &MIME; en que es basen.</para>
<para><userinput>version</userinput> especifica la versió actual del fitxer de definició.</para>
<para><userinput>kateversion</userinput> especifica la última versió suportada per &kate;.</para>
<para><userinput>casesensitive</userinput> defineix quan les paraules clau són o no sensibles a majúscules i minúscules.</para>
<para><userinput>priority</userinput> es necessària si una altra definició de ressaltat usa les mateixes extensions. S'usarà la de major prioritat.</para>
<para><userinput>author</userinput> conté el nom de l'autor i la seva adreça de correu electrònic.</para>
<para><userinput>license</userinput> conté la llicència, normalment LPGL, Artistic, GPL i d'altres.</para>
<para><userinput>hidden</userinput> defineix quan hauria d'aparèixer el nom en els menús de &kate;.</para>
<para>De manera que dita línia pot tenir un aspecte similar a:</para>
<programlisting>&lt;language name=&quot;C++&quot; version=&quot;1.00&quot; kateversion=&quot;2.4&quot; section=&quot;Sources&quot; extensions=&quot;*.cpp;*.h&quot; /&gt;
</programlisting>
</listitem>
</varlistentry>


<varlistentry>
<term>A continuació estaria l'element <userinput>highlighting</userinput>, el qual conté l'element opcional <userinput>list</userinput> i els elements requerits <userinput>contexts</userinput> i <userinput>itemDatas</userinput>.</term>
<listitem>
<para>Els elements <userinput>list</userinput> contenen una llista de paraules clau. En aquest cas les paraules clau són <emphasis>class</emphasis> i <emphasis>const</emphasis>. Podeu afegir tantes llistes com us calguin.</para>
<para>L'element <userinput>contexts</userinput> conté tots els contexts. El primer és l'usat per omissió i amb aquest s'iniciarà el ressaltat. Hi ha dues regles en el context <emphasis>Normal Text</emphasis>, que faran coincidir la llista de paraules clau amb el nom <emphasis>algun_nom</emphasis> i una regla que detecta una cometa i canvia el context a <emphasis>cadena</emphasis>. Per aprendre més sobre les regles llegiu el següent capítol.</para>
<para>La tercera part és l'ítem <userinput>itemDatas</userinput>. Conté tots els colors i tipus de lletra que necessiten els contexts i les regles. En aquest exemple, s'usen <userinput>itemData</userinput> <emphasis>Normal Text</emphasis>, <emphasis>String</emphasis> i <emphasis>Keyword</emphasis>. </para>
<programlisting>&lt;highlighting&gt;
    &lt;list name=&quot;algun_nom&quot;&gt;
      &lt;item&gt; class &lt;/item&gt;
      &lt;item&gt; const &lt;/item&gt;
    &lt;/list&gt;
    &lt;contexts&gt;
      &lt;context attribute=&quot;text_normal&quot; lineEndContext=&quot;#pop&quot; name=&quot;text_normal&quot; &gt;
        &lt;keyword attribute=&quot;paraula_clau&quot; context=&quot;#stay&quot; String=&quot;algun_nom&quot; /&gt;
        &lt;DetectChar attribute=&quot;cadena&quot; context=&quot;string&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
      &lt;context attribute=&quot;cadena&quot; lineEndContext=&quot;#stay&quot; name=&quot;cadena&quot; &gt;
        &lt;DetectChar attribute=&quot;cadena&quot; context=&quot;#pop&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
    &lt;/contexts&gt;
    &lt;itemDatas&gt;
      &lt;itemData name=&quot;text_normal&quot; defStyleNum=&quot;dsNormal&quot; /&gt;
      &lt;itemData name=&quot;paraula_clau&quot; defStyleNum=&quot;dsParaula_clau&quot; /&gt;
      &lt;itemData name=&quot;cadena&quot; defStyleNum=&quot;dsCadena&quot; /&gt;
    &lt;/itemDatas&gt;
  &lt;/highlighting&gt;
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term>L'última part de la definició de ressaltat és la secció opcional <userinput>general</userinput>. Pot contenir informació sobre paraules clau, plegat de codi, comentaris i sagnat.</term>

<listitem>
<para>La secció <userinput>comment</userinput> defineix amb quina cadena s'introdueix un comentari en una línia senzilla. També podeu definir comentaris en múltiples línies usant <emphasis>multiLine</emphasis> amb l'atribut addicional <emphasis>end</emphasis>. Això s'usa si l'usuari prem la drecera corresponent per a <emphasis>comenta/descomenta</emphasis>.</para>
<para>La secció <userinput>keywords</userinput> defineix si les llistes de paraules clau són sensibles a majúscules i minúscules o no. Més endavant s'explicaran d'altres atributs.</para>
<programlisting>&lt;general&gt;
    &lt;comments&gt;
      &lt;comment name="singleLine" start="#"/&gt;
    &lt;/comments&gt;
    &lt;keywords casesensitive="1"/&gt;
  &lt;/general&gt;
&lt;/language&gt;
</programlisting>
</listitem>
</varlistentry>

</variablelist>


</sect2>

<sect2 id="kate-highlight-sections">
<title>Les seccions al detall</title>
<para>Aquesta part descriu tots els atributs disponibles per als contexts, llistes de dades, paraules clau, comentaris, plegat de codi i sagnat.</para>

<variablelist>
<varlistentry>
<term>L'element <userinput>context</userinput> pertany al grup <userinput>contexts</userinput>. Un context defineix les regles específiques de context que s'han de seguir quan el sistema de ressaltat abasta el final d'una línia. Els atributs disponibles són:</term>


<listitem>
<para><userinput>name</userinput> és el nom del context. Les regles usaran el nom per especificar el context al que canviar si les regles coincideixen.</para>
<para><userinput>lineEndContext</userinput> defineix el context al que canviarà el sistema de ressaltat si abasta el final de la línia. Pot ser un nom o un altra context, <userinput>#stay</userinput> permetrà que no es canviï el context (&pex;, no fer res) o <userinput>#pop</userinput> farà que es surti aquest context. És possible usar per exemple <userinput>#pop#pop#pop</userinput> per a sortir tres vegades.</para>
<para><userinput>lineBeginContext</userinput> defineix el context si es troba el començament d'una línia. Per omissió: #stay.</para>
<para><userinput>fallthrough</userinput> defineix si el sistema de ressaltat canviarà al context especificat en fallthroughtContext si no coincideixen les regles. Per omissió: <emphasis>false</emphasis>.</para>
<para><userinput>fallthroughContext</userinput> especifica el context següent si no hi ha regles que coincideixin.</para>
<para><userinput>dynamic</userinput> si està a <emphasis>true</emphasis>, el context recordarà cadenes/ítems substituïbles desats per les regles dinàmiques. Això es necessita per als documents HERE, per exemple. Per omissió: <emphasis>false</emphasis>.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>L'element <userinput>itemData</userinput> es troba en el grup <userinput>itemDatas</userinput>. Defineix l'estil i els colors dels tipus de lletra. Per tant és possible definir els vostres propis estils i colors, encara que recomanem usar els estils per omissió, atès que així l'usuari veurà colors homogenis per als diferents llenguatges. Si be, algunes vegades no hi ha altres possibilitats i és necessari canviar el color i els atributs dels tipus de lletra. Els atributs name i defStyleNum són necessaris, els altres són opcionals. Els atributs disponibles són:</term>

<listitem>
<para><userinput>name</userinput> estableix el nom del itemData. Els contexts i les regles usaran aquest nom en els seus atributs <emphasis>attribute</emphasis> per a fer referència a un itemData.</para>
<para><userinput>defStyleNum</userinput> defineix quin estil s'usarà per omissió. Més endavant s'explicaran els estils per omissió disponibles.</para>
<para><userinput>color</userinput> defineix un color. Els formats vàlids són '#rrggbb' o '#rgb'.</para>
<para><userinput>selColor</userinput> defineix el color de la selecció.</para>
<para><userinput>italic</userinput> si està a <emphasis>true</emphasis>, el text es mostrarà en cursiva.</para>
<para><userinput>bold</userinput> si està a <emphasis>true</emphasis>, el text es mostrarà en negreta.</para>
<para><userinput>underline</userinput> si està a <emphasis>true</emphasis>, el text es mostrarà subratllat.</para>
<para><userinput>strikeout</userinput> si està a <emphasis>true</emphasis>, el text es mostrarà taxat.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>L'element <userinput>keywords</userinput> en el grup <userinput>general</userinput> defineix les propietats keyword. Els atributs disponibles són:</term>

<listitem>
<para><userinput>casesensitive</userinput> pot ser <emphasis>true</emphasis> o <emphasis>false</emphasis>. Si està a <emphasis>true</emphasis>, totes les paraules clau seran sensibles a majúscules i minúscules.</para>
<para><userinput>weakDeliminator</userinput> és una llista de caràcters que no actuen com a delimitadors de paraules (delimitador feble). Per exemple el punt <userinput>'.'</userinput> és un delimitador de paraula. Si tenim una paraula clau en una <userinput>list</userinput> que conté un punt, tan sols la trobareu si especifiqueu el punt com a delimitador feble.</para>
<para><userinput>additionalDeliminator</userinput> defineix delimitadors addicionals.</para>
<para><userinput>wordWrapDeliminator</userinput> defineix els caràcters al darrera dels quals pot ocórrer un ajust de línia.</para>
<para>Els delimitadors per omissió i els d'ajust de línia són els caràcters <userinput>.():!+,-&lt;=&gt;%&amp;*/;?[]^{|}~\</userinput>, space (<userinput>' '</userinput>) i tabulació (<userinput>'\t'</userinput>).</para>
</listitem>
</varlistentry>


<varlistentry>
<term>L'element <userinput>comment</userinput> en el grup <userinput>comments</userinput> defineix les propietats dels comentaris emprats per <menuchoice><guimenu>Eines</guimenu><guimenuitem>Comenta</guimenuitem></menuchoice> i <menuchoice><guimenu>Eines</guimenu> <guimenuitem>Descomenta</guimenuitem></menuchoice>. Els atributs disponibles són:</term>

<listitem>
<para><userinput>name</userinput> pot ser <emphasis>singleLine</emphasis> o <emphasis>multiLine</emphasis>. Si escolliu <emphasis>multiLine</emphasis> es necessiten els atributs <emphasis>end</emphasis> i <emphasis>region</emphasis>.</para>
<para><userinput>start</userinput> defineix la cadena que s'usa per iniciar un comentari. En C++ seria &quot;/*&quot;.</para>
<para><userinput>end</userinput> defineix la cadena usada per a tancar un comentari. En C++ seria &quot;*/&quot;.</para>
<para><userinput>region</userinput> serà el nom amb el que es desarà el comentari multi-línia. Si assumim que tenim una regió <emphasis>beginRegion="Comentari"</emphasis> ... <emphasis>endRegion="Comentari"</emphasis> en les vostres regles, haureu d'usar <emphasis>region="Comentari"</emphasis>. D'aquesta manera es descomentarà fins i tot si no heu seleccionat tot el text en un comentari multi-línia. Tan sols és necessari que el cursor estigui dins del comentari multi-línia.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>L'element <userinput>folding</userinput> en el grup <userinput>general</userinput> defineix les propietats de plegat de codi. Els atributs disponibles són:</term>

<listitem>
<para><userinput>indentationsensitive</userinput> si està a <emphasis>true</emphasis>, els marcadors de plegat de codi seran afegits al sagnat, com en el llenguatge d'script Python. Normalment no us caldrà establir-lo, pel que per omissió és <emphasis>false</emphasis>.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>L'element <userinput>indentation</userinput> en el grup <userinput>general</userinput> defineix quin sagnat s'usarà, encara que us recomanem fervorosament que l'ometeu, atès que el sagnat sol ser establert en el tipus de fitxer o a l'afegir el mode de línia al fitxer de text. Tot i que si especifiqueu un sagnat, podreu forçar un sagnat específic per a un usuari, per un altra que us agradi més. Els atributs disponibles són:</term>

<listitem>
<para><userinput>mode</userinput> és el nom del sagnat. Els sagnats disponibles a la dreta són: <emphasis>normal, cstyle, csands, xml, python</emphasis> i <emphasis>varindent</emphasis>.</para>
</listitem>
</varlistentry>


</variablelist>


</sect2>

<sect2 id="kate-highlight-default-styles">
<title>Estils per omissió disponibles</title>
<para>Els estils per omissió <link linkend="kate-highlight-system-default-styles">ja s'han explicat</link>, a mode de resum: Els estils per omissió estan predefinits per als estils de colors i tipus de lletra.</para>
<variablelist>
<varlistentry>
<term>Veurem la llista dels estils per omissió disponibles:</term>
<listitem>
<para><userinput>dsNormal</userinput>, usat per al text normal.</para>
<para><userinput>dsKeyword</userinput>, usat per a les paraules clau.</para>
<para><userinput>dsDataType</userinput>, usat per als tipus de dades.</para>
<para><userinput>dsDecVal</userinput>, usat per als valors decimals.</para>
<para><userinput>dsBaseN</userinput>, usat per als valors en una base diferent a 10.</para>
<para><userinput>dsFloat</userinput>, usat per a valors de coma flotant.</para>
<para><userinput>dsChar</userinput>, usat per a un caràcter.</para>
<para><userinput>dsString</userinput>, usat per a cadenes.</para>
<para><userinput>dsComment</userinput>, usat per a comentaris.</para>
<para><userinput>dsOthers</userinput>, usat per a d''altres' coses.</para>
<para><userinput>dsAlert</userinput>, usat per a missatges d'avis.</para>
<para><userinput>dsFunction</userinput>, usat per a crides a funcions.</para>
<para><userinput>dsRegionMarker</userinput>, usat per a marcadors de regió.</para>
<para><userinput>dsError</userinput>, usat per a errors de ressaltat i sintaxi incorrecta.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>

<sect1 id="kate-highlight-rules-detailled">
<title>Regles de detecció del ressaltat</title>

<para>Aquesta secció descriu les regles de detecció del ressaltat.</para>

<para>Cada regla pot coincidir en cap o amb varis caràcters del començament de la cadena amb la que es comparen. Si la regla coincideix, als caràcters coincidents se'ls assigna l'estil o <emphasis>attribute</emphasis> definit per la regla, tan mateix una regla pot demanar que es canviï el context actual.</para>

<para>Una regla te aquest aspecte:</para>

<programlisting>&lt;NomRegla attribute=&quot;(identificador)&quot; context=&quot;(identificador)&quot; [atributs específics de la regla] /&gt;</programlisting>

<para>L'<emphasis>attribute</emphasis> identifica l'estil que usaran els caràcters coincidents per nom, i el <emphasis>context</emphasis> identifica el context a usar des d'aquí.</para>

<para>El <emphasis>context</emphasis> es pot identificar per:</para>

<itemizedlist>
<listitem>
<para>Un <emphasis>identifier</emphasis>, que és el nom dels altres contexts.</para>
</listitem>
<listitem>
<para>Una <emphasis>order</emphasis> us indica al motor que romandrà en el context actual (<userinput>#stay</userinput>), o que salti al context anterior (<userinput>#pop</userinput>).</para>
<para>Per a retrocedir més passes, es pot repetir la paraula clau #pop: <userinput>#pop#pop#pop</userinput></para>
</listitem>
</itemizedlist>

<para>Algunes regles poden tenir <emphasis>regles fill</emphasis> que s'executen únicament si la regla pare resulta aplicable. A tota la cadena coincident se us donarà l'atribut definit per la regla pare. Una regla amb regles fills te aquest aspecte:</para>

<programlisting>&lt;NomRegla (atributs)&gt;
  &lt;NomReglaFill (atributs) /&gt;
  ...
&lt;/NomRegla&gt;
</programlisting>


<para>Els atributs específics de la regla varien, i es descriuen en les següents seccions.</para>


<itemizedlist>
<title>Atributs comuns</title>
<para>Totes les regles tenen els següents atributs comuns i estan disponibles sempre que apareixen <userinput>(atributs comuns)</userinput>. <emphasis>attribute</emphasis> i <emphasis>context</emphasis> són atributs requerits, els demés són opcionals. </para>

<listitem>
<para><emphasis>attribute</emphasis>: Un mapa d'atributs d'un definit <emphasis>itemData</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>context</emphasis>: Especifica el context al que canviarà el sistema de ressaltat si les regles coincideixen.</para>
</listitem>
<listitem>
<para><emphasis>beginRegion</emphasis>: Inicia un bloc de plegat de codi. Per omissió: unset.</para>
</listitem>
<listitem>
<para><emphasis>endRegion</emphasis>: Tanca un bloc de plegat de codi. Per omissió: unset.</para>
</listitem>
<listitem>
<para><emphasis>lookAhead</emphasis>: Si està a <emphasis>true</emphasis>, el sistema de ressaltat no processarà les longituds coincidents. Per omissió: <emphasis>false</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>firstNonSpace</emphasis>: Tan sols coincidiran si la cadena no conté un espai en blanc al començament de la línia. Per omissió: <emphasis>false</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>column</emphasis>: Tan sols coincideix, si la columna coincideix. Per omissió: unset.</para>
</listitem>
</itemizedlist>

<itemizedlist>
<title>Regles dinàmiques</title>
<para>Algunes regles permeten l'atribut opcional <userinput>dynamic</userinput> de tipus lògic que per omissió és <emphasis>false</emphasis>. Si dynamic està a <emphasis>true</emphasis>, la regla podrà usar arguments que representin el text coincident amb una regla d'una <emphasis>expressió regular</emphasis> que canviï al context actual per al contingut en els atributs <userinput>string</userinput> o <userinput>char</userinput>. En un <userinput>string</userinput>, l'argument <replaceable>%N</replaceable> (a on N és un número) es substituirà amb la corresponent <replaceable>N</replaceable> capturada des de l'expressió regular cridada. En un <userinput>char</userinput> l'argument haurà de ser un número <replaceable>N</replaceable> i serà substituït amb el primer caràcter de la corresponent <replaceable>N</replaceable> capturada des de l'expressió regular cridada. Sempre que un regla permeti aquest atribut haurà de contenir un <emphasis>(dynamic)</emphasis>.</para>

<listitem>
<para><emphasis>dinàmic</emphasis>: pot ser <emphasis>(true|false)</emphasis>.</para>
</listitem>
</itemizedlist>

<sect2 id="highlighting-rules-in-detail">
<title>Les regles en detall</title>

<variablelist>
<varlistentry>
<term>DetectChar</term>
<listitem>
<para>Detecta un únic caràcter específic. Normalment s'usa per a trobar el final de les cadenes entre cometes.</para>
<programlisting>&lt;DetectChar char=&quot;(caràcter)&quot; (atributs comuns) (dinàmic) /&gt;</programlisting>
<para>L'atribut <userinput>char</userinput> defineix el caràcter a comparar.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Detect2Chars</term>
<listitem>
<para>Detecta dos caràcters especificats en l'ordre definit.</para>
<programlisting>&lt;Detect2Chars char=&quot;(caràcter)&quot; char1=&quot;(caràcter)&quot; (atributs comuns) (dinàmic) /&gt;</programlisting>
<para>L'atribut <userinput>char</userinput> defineix el primer caràcter a comparar, <userinput>char1</userinput> el segon.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>AnyChar</term>
<listitem>
<para>Detecta un caràcter d'un conjunt de caràcters especificats.</para>
<programlisting>&lt;AnyChar String=&quot;(cadena)&quot; (atributs comuns) /&gt;</programlisting>
<para>L'atribut <userinput>String</userinput> defineix el conjunt de caràcters.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>StringDetect</term>
<listitem>
<para>Detecta una cadena exacta.</para>
<programlisting>&lt;StringDetect String=&quot;(cadena)&quot; [insensitive=&quot;true|false&quot;] (atributs comuns) (dinàmic) /&gt;</programlisting>
<para>L'atribut <userinput>String</userinput> defineix la cadena a comparar. L'atribut <userinput>insensitive</userinput> per omissió és a <userinput>false</userinput> i es passa a la funció de comparació de cadena. Si el valor és <userinput>true</userinput> la comparació no serà sensible a majúscules i minúscules.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>RegExpr</term>
<listitem>
<para>Cerca la coincidència amb una expressió regular.</para>
<programlisting>&lt;RegExpr String=&quot;(cadena)&quot; [insensitive=&quot;true|false&quot;] [minimal=&quot;true|false&quot;] (atributs comuns) (dinàmic) /&gt;</programlisting>
<para>L'atribut <userinput>String</userinput> defineix l'expressió regular.</para>
<para><userinput>insensitive</userinput> per omissió és a <userinput>false</userinput> i és passada al motor d'expressions regulars.</para>
<para><userinput>minimal</userinput> per omissió és a <userinput>false</userinput> i és passada al motor d'expressions regulars.</para>
<para>Atès que les regles coincideixen amb el començament de la cadena actual, una expressió regular que comenci amb el símbol del barret (<literal>^</literal>) indica que la regla tan sols s'haurà de comparar amb el començament d'una línia.</para>
<para>Mireu la secció sobre <link linkend="regular-expressions">expressions regulars</link> per a obtenir més informació.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>keyword</term>
<listitem>
<para>Detecta una paraula clau des d'una llista especificada.</para>
<programlisting>&lt;keyword String=&quot;(nom de la llista)&quot; (atributs comuns) /&gt;</programlisting>
<para>L'atribut <userinput>String</userinput> identifica la llista de paraules clau pel seu nom. Haurà d'existir una llista amb aquest nom.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Int</term>
<listitem>
<para>Detecta un número enter.</para>
<para><programlisting>&lt;Int (atributs comuns) (dinàmic) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics. Les regles fill normalment s'usen per a detectar combinacions de <userinput>L</userinput> i <userinput>U</userinput> després del número, indicant el tipus d'enter en el codi del programa. En realitat s'admeten totes les regles com a regles fill, tot i que, el <userinput>DTD</userinput> tan sols permet la regla fill <userinput>StringDetect</userinput>.</para>
<para>El següent exemple troba números enters seguits del caràcter 'L'. <programlisting>&lt;Int attribute="Decimal" context="#stay" &gt;
  &lt;StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/&gt;
&lt;/Int&gt;
</programlisting></para>

</listitem>
</varlistentry>

<varlistentry>
<term>Float</term>
<listitem>
<para>Detecta un número de coma flotant.</para>
<para><programlisting>&lt;Float (atributs comuns) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics. Es permet <userinput>AnyChar</userinput> com a regla fill i normalment s'usa per a detectar combinacions, mireu la regla <userinput>Int</userinput> com a referència.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>HlCOct</term>
<listitem>
<para>Detecta una representació numèrica d'un número octal.</para>
<para><programlisting>&lt;HlCOct (atributs comuns) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>HlCHex</term>
<listitem>
<para>Detecta una representació numèrica d'un número hexadecimal.</para>
<para><programlisting>&lt;HlCHex (atributs comuns) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>HlCStringChar</term>
<listitem>
<para>Detecta un caràcter escapat.</para>
<para><programlisting>&lt;HlCStringChar (atributs comuns) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics.</para>

<para>Localitza representacions literals de caràcters que s'usen habitualment en el codi de programació, per exemple <userinput>\n</userinput> (nova línia) o <userinput>\t</userinput> (TAB).</para>

<para>Els següents caràcters coincideixen amb la regla si segueixen a una barra invertida (<literal>\</literal>): <userinput>abefnrtv&quot;'?\</userinput>. A més seran vàlids els números hexadecimals escapats com per exemple <userinput>\xff</userinput>, i els números octals escapats, per exemple <userinput>\033</userinput>.</para>

</listitem>
</varlistentry>

<varlistentry>
<term>HlCChar</term>
<listitem>
<para>Detecta un caràcter C.</para>
<para><programlisting>&lt;HlCChar (atributs comuns) /&gt;</programlisting></para>
<para>Aquesta regla no te atributs específics.</para>

<para>Localitza caràcters C tancats en una marca (Exemple: <userinput>'c'</userinput>). La marca pot ser un caràcter simple o un caràcter escapat. Veure HICStringChar per a localitzar seqüències de caràcters escapats.</para>

</listitem>
</varlistentry>

<varlistentry>
<term>RangeDetect</term>
<listitem>
<para>Detecta una cadena amb caràcters d'inici i de final definits.</para>
<programlisting>&lt;RangeDetect char=&quot;(caràcter)&quot;  char1=&quot;(caràcter)&quot; (atributs comuns) /&gt;</programlisting>
<para><userinput>char</userinput> defineix el caràcter que inicia el rang, <userinput>char1</userinput> el caràcter que finalitza el rang.</para>
<para>És molt útil per a detectar per exemple petites cadenes entre cometes i similars, però tingueu en compte que el motor de ressaltat tan sols pot treballar amb una cada vegada, així que no es detectaran cadenes que estiguin dividides en dues línies o més.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>LineContinue</term>
<listitem>
<para>Localitza el final de la línia.</para>
<programlisting>&lt;LineContinue (atributs comuns) /&gt;</programlisting>
<para>Aquesta regla no te atributs específics.</para>
<para>Aquesta regla és pràctica per a canviar el context al final de la línia, si l'últim caràcter és una barra invertida (<userinput>'\'</userinput>). Això és necessari per exemple en C/C++ per a continuar macros o cadenes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>IncludeRules</term>
<listitem>
<para>Inclou regles des d'un altra context o llenguatge/fitxer.</para>
<programlisting>&lt;IncludeRules context=&quot;contextlink&quot; [includeAttrib=&quot;true|false&quot;] /&gt;</programlisting>

<para>L'atribut <userinput>context</userinput> defineix el context a incloure.</para>
<para>Si és una cadena simple inclou totes les regles definides en el context actual, exemple: <programlisting>&lt;IncludeRules context=&quot;anotherContext&quot; /&gt;</programlisting></para>

<para>Si la cadena comença amb <userinput>##</userinput> el sistema de ressaltat cercarà una altra definició de llenguatge amb el nom indicat, exemple: <programlisting>&lt;IncludeRules context=&quot;##C++&quot; /&gt;</programlisting></para>
<para>Si l'atribut <userinput>includeAttrib</userinput> està a <emphasis>true</emphasis>, canvia l'atribut de destí per un altra de la font. Això és necessari, per exemple, per al treball comentar, si el text coincideix amb el context introduït s'usa un ressaltat diferent que amb el context amfitrió. </para>
</listitem>
</varlistentry>


<varlistentry>
<term>DetectSpaces</term>
<listitem>
<para>Detecta espais en blanc.</para>
<programlisting>&lt;DetectSpaces (atributs comuns) /&gt;</programlisting>

<para>Aquesta regla no te atributs específics.</para>
<para>Useu aquesta regla si sabeu que hi poden haver varis espais en blanc al davant, per exemple, al començament de les línies sagnades. Aquesta regla ometrà tots els espais en blanc a la vegada, en comptes de comprovar múltiples regles i saltar si no hi ha coincidències.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>DetectIdentifier</term>
<listitem>
<para>Detecta identificadors de cadenes (com una expressió regular: [a-zA-Z_][a-zA-Z0-9_]*).</para>
<programlisting>&lt;DetectIdentifier (atributs comuns) /&gt;</programlisting>

<para>Aquesta regla no te atributs específics.</para>
<para>Useu aquesta regla per a saltar d'una vegada una cadena de paraula de caràcters, en comptes de comprovar múltiples regles i saltar si no hi ha coincidències.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2>
<title>Consells i trucs</title>

<itemizedlist>
<para>Una vegada que hageu entès com funciona el canvi de context serà fàcil escriure definicions de ressaltat. Tot i que hauria de tenir cura de comprovar quina situació s'hauria de seleccionar una regla. Les expressions regulars són molt potents, però són lentes en comparació amb d'altres regles. Per això haureu de tenir en compte els següents consells. </para>

<listitem>
<para>Si tan sols heu de localitzar dos caràcters useu <userinput>Detect2Chars</userinput> en comptes de <userinput>StringDetect</userinput>. El mateix s'aplica a <userinput>DetectChar</userinput>.</para>
</listitem>
<listitem>
<para>Les expressions regulars són fàcils d'usar però a vegades hi ha formes molt més ràpides d'obtenir el mateix resultat. Imagineu que tan sols desitgeu localitzar el caràcter <userinput>'#'</userinput> si aquest és el primer caràcter de la línia. Una solució basada en una expressió regular seria quelcom semblant a això: <programlisting>&lt;RegExpr attribute=&quot;Macro&quot; context=&quot;macro&quot; String=&quot;^\s*#&quot; /&gt;</programlisting>Podeu aconseguir el mateix molt més ràpid usant: <programlisting>&lt;DetectChar attribute=&quot;Macro&quot; context=&quot;macro&quot; char=&quot;#&quot; firstNonSpace=&quot;true&quot; /&gt;</programlisting>Si desitgeu que l'expressió regular localitzi <userinput>'^#'</userinput> també podeu usar <userinput>DetectChar</userinput> amb l'atribut <userinput>column=&quot;0&quot;</userinput>. L'atribut <userinput>column</userinput> compta els caràcters base, per tant el tabulador és tan sols un caràcter. </para>
</listitem>
<listitem>
<para>Podeu canviar de context sense processar caràcters. Suposeu que desitgeu canviar de context quan trobeu una cadena <userinput>*/</userinput>, però us cal processar aquesta cadena en el següent context. La regla de a sota coincidirà, i l'atribut <userinput>lookAhead</userinput> farà que es desi la cadena coincident per al següent context. <programlisting>&lt;Detect2Chars attribute=&quot;Comment&quot; context=&quot;#pop&quot; char=&quot;*&quot; char1=&quot;/&quot; lookAhead=&quot;true&quot; /&gt;</programlisting>
</para>
</listitem>
<listitem>
<para>Useu <userinput>DetectSpaces</userinput> si sabeu quants espais en blanc hi ha.</para>
</listitem>
<listitem>
<para>Useu <userinput>DetectIdentifier</userinput> en comptes de l'expressió regular <userinput>'[a-zA-Z_]\w*'</userinput>.</para>
</listitem>
<listitem>
<para>Usa els estils per omissió sempre que es pugui. D'aquesta manera l'usuari es trobarà un entorn familiar.</para>
</listitem>
<listitem>
<para>Mireu d'altres fitxers XML per a comprovar de quina forma implementen regles delicades les altres persones.</para>
</listitem>
<listitem>
<para>Podeu validar cadascun dels fitxers XML usant el comandament <command>xmllint --dtdvalid llenguatge.dtd mevaSintaxi.xml</command>.</para>
</listitem>
<listitem>
<para>Si tot sovint repetiu expressions regulars complexes podeu usar <emphasis>ENTITATS</emphasis>. Exemple:</para>
<programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE language SYSTEM "language.dtd"
[
        &lt;!ENTITY la_meva_ref    "[A-Za-z_:][\w.:_-]*"&gt;
]&gt;
</programlisting>
<para>Ara podeu usar <emphasis>&amp;la_meva_ref;</emphasis> en comptes de l'expressió regular.</para>
</listitem>
</itemizedlist>
</sect2>

</sect1>

</appendix>