<para>System podświetlania składni służy do wyświetlania określonych fragmentów tekstu w różnych stylach czcionki i kolorach, w zależności od funkcji tego tekstu w strukturze edytowanego pliku. Na przykład jeżeli jest to kod źródłowy jakiegoś programu, to instrukcje kontrolne mogą być pogrubione, zaś typu zmiennych i komentarze mogą być wyróżnione kolorem innym od reszty tekstu. To znacznie podnosi czytelność tekstu, dzięki czemu tworzenie programów jest bardziej efektywne i produktywne.</para>
<para>Który z dwóch powyższych przykładów jest bardziej czytelny?</para>
<para>Edytor &kate; ma zintegrowany potężny, elastyczny i w pełni konfigurowalny system podświetlania składni, zaś domyślna instalacja programu zawiera wiele definicji dla różnych języków programowania, języków skryptowych, języków opartych na znacznikach oraz innych plików tekstowych. Dodatkowo użytkownik może tworzyć własne definicje podświetlania składni w plikach &XML; o stosunkowo prostej strukturze.</para>
<para>Podczas otwierania pliku tekstowego, &kate; automatycznie wykryje odpowiednią dla tego pliku definicję podświetlania składni na podstawie przypisanego dla niego typu &MIME;. Typ pliku określany jest na podstawie rozszerzenia nazwy pliku, a jeżeli plik nie ma rozszerzenia. to na podstawie jego zawartości. Jeżeli typ pliku został wykryty niepoprawnie, to można ręcznie zmienić definicję podświetlania składni za pomocą menu <menuchoice><guimenu>Narzędzia</guimenu><guisubmenu>Typ pliku</guisubmenu></menuchoice>.</para>
<para>Styl i kolor tekstu dla wszystkich reguł podświetlania może zostać zdefiniowany w karcie <link linkend="config-dialog-editor-appearance">Czcionki i kolory</link> <link linkend="config-dialog"> Okna konfiguracji</link> natomiast typy &MIME;, dla których powinny być stosowane określone reguły konfigurowane są w karcie <link linkend="config-dialog-editor-highlighting">Podświetlenie</link>.</para>
<para>Podświetlanie składni ma na celu zwiększenie czytelności treści dokumentu, ale nie należy zbyt polegać na jego możliwościach wskazywania błędów w kodzie programu. Algorytmy rozpoznawania składni mogą być skomplikowane i zależy to od używanego formatu dokumentu. Autorzy reguł podświetlania składni mogą się pochwalić 98% skutecznością stosowanych algorytmów rozpoznawania składni, jednak często jest ona wyższa i tylko naprawdę rzadko stosowane definicje reguł podświetlania powodują 2% błędnych podświetleń.</para>
<para>Ze strony WWW programu &kate; można pobrać nowe i zaktualizowane bieżące definicje reguł podświetlania składni. Można to zrobić naciskając przycisk <guibutton>Pobierz...</guibutton> w karcie <link linkend="config-dialog-editor-highlighting">Podświetlenie</link> okna dialogowego <link linkend="config-dialog">Konfiguracji</link>.</para>
<para>Poniższa sekcja zawiera bardziej szczegółowe omówienie mechanizmów podświetlania składni w programie &kate;. Jest ona przeznaczona dla użytkowników chcących dodawać lub modyfikować istniejące reguły podświetlania, lub dla osób chcących się czegoś więcej na ten temat dowiedzieć.</para>
<para>Przy każdej operacji otwierania pliku program &kate; próbuje wykryć odpowiednią dla niego regułę podświetlania składni. Podczas wyświetlania pliku i w trakcie jego edycji system podświetlania składni będzie analizował tekst za pomocą reguł określonych w definicji podświetlania składni oraz zaznaczać miejsca, w których poszczególne konteksty treści i style tekstu rozpoczynają się i kończą.</para>
<para>Podczas edycji dokumentu nowo wprowadzany tekst jest analizowany i oznaczany na bieżąco, jeżeli więc użytkownik usunie znak będący początkiem lub końcem jakiegoś kontekstu to styl otaczającego ten znak tekstu zmieni się zgodnie z wymaganiami bieżącej reguły podświetlania składni.</para>
<para>Definicje reguł podświetlania składni w &kate; to pliki zapisane w standardzie &XML; zawierające: <itemizedlist>
<listitem><para>Zasady opisujące rolę spełnianą przez określone fragmenty tekstu zorganizowane w odpowienie bloki kontekstowe</para></listitem>
<listitem><para>Listy słów kluczowych</para></listitem>
<listitem><para>Definicje elementów stylu</para></listitem>
<para>Podczas analizy składni reguły są sprawdzane w kolejności ich wystąpienia w pliku. Jeżeli początek bieżącego tekstu zostaje dopasowany do danej reguły to następuje przełączenie na wskazany kontekst. Punkt przetwarzania treści przesuwa się na koniec bieżącego dopasowania reguły, a pętla sprawdzania reguł rozpoczyna się na nowo, ale już w kontekście przetwarzania wskazanym przez poprzednie dopasowanie.</para>
<para>Reguły stanowią serce systemu rozpoznawania składni. Reguła może odnosić się do napisu, pojedynczego znaku lub <link linkend="regular-expressions">wyrażenia regularnego</link>. Do reguł dopasowywany jest analizowany tekst dokumentu. Reguły wskazują, jakiego stylu należy użyć do wyświetlenia dopasowanego fragmentu tekstu, mogą też przełączać kontekst roboczy systemu podświetlania składni przez podanie nazwy kontekstu lub nakazując powrót do kontekstu poprzedniego.</para>
<para>Reguły są zgrupowane w bloki kontekstowe. Blok kontekstowy jest związany z głównymi elementami składni analizowanego tekstu np. tekst w cudzysłowach lub bloki komentarzy kodu źródłowego. Dzięki temu system podświetlania składni nie musi analizować wszystkich reguł, jeżeli nie jest to konieczne. Także pewne sekwencje znaków w tekście mogą być różnie traktowane w zależności od wybranego kontekstu przetwarzania. </para>
<para>Kontekst przetwarzania może być generowany dynamicznie, pozwalając na stosowaniu w regułach danych zależnych od wystąpienia określonego tekstu w treści dokumentu.</para>
<para>W niektórych językach programowania kompilator (czyli program zmieniający tzw. kod źródłowy programu na plik wykonywalny) w różny sposób traktuje liczby całkowite i zmiennoprzecinkowe. Dodatkowo wewnątrz otoczonego cudzysłowami napisu mogą być znaki o specjalnym znaczeniu. W takich wypadkach sensowne jest wyróżnienie ich z otaczającego tekstu tak aby były łatwo identyfikowalne. Tak więc nawet jeżeli takie fragmenty tekstu nie stanowią osobnego kontekstu, to są tak traktowane przez system podświetlania składni i dzięki temu mogą być odpowiednio różnicowane przy wyświetlaniu.</para>
<para>Dla wielu formatów dokumentów definiuje się listy słów reprezentujących określone pojęcia. Na przykład w językach programowania są to instrukcje kontrolne, typy zmiennych oraz wbudowane funkcje (każda z tych kategorii stanowi osobne pojęcie). System podświetlania składni w &kate; wykorzystuje listy słów kluczowych do zaznaczania w tekście wystąpień poszczególnych kategorii skadniowych danego formatu dokumentu.</para>
<para>W przypadku otwarcia pliku z programem w C++ , &Java; lub dokumentu <acronym>HTML</acronym> można zauważyć, że mimo iż poszczególne typy dokumentów znacząco się od siebie różnią (inne słowa są podświetlane, itp.) to używane przez &kate; kolory są identyczne. Dzieje się tak dlatego ponieważ w &kate; istnieje zdefiniowana lista stylów domyślnych tekstu wykorzystywanych przez wszystkie definicje reguł podświetlania składni.</para>
<para>Pozwala to na użytkownikowi na rozpoznawanie pojęć o podobnym znaczeniu w różnych formatach dokumentu. Na przykład komentarze, które istnieją w kodzie źródłowym w niemal wszystkich językach programowania, językach skryptowych lub językach znaczników, są wyświetlane z użyciem tego samego stylu co pozwala użytkownikowi łatwo zidentyfikować wyróżniony w tekście fragment jako komentarz, niezależnie w jakim języku programowania ten tekst będzie napisany.</para>
<para>Wszystkie definicje podświetlania składni korzystają z minimum jednego stylu domyślnego. Część z nich wykorzystuje więcej stylów domyślnych. Jeżeli z danego formatu dokumentu użytkownik często korzysta, to warto uruchomić okno konfiguracji i sprawdzić jakie pojęcia są dla niego zdefiniowane w zbiorze reguł podświetlania. Na przykład, dostępny jest tylko jeden styl domyślny dla napisów, jednak ponieważ język Perl działa na dwóch rodzajach napisów, to możliwe jest takie skonfigurowanie systemu podświetlania, aby oba rodzaje były wyświetlane w różny sposób. Wszystkie dostępne <link linkend="kate-highlight-default-styles">style domyślne</link> zostaną omówione poniżej.</para>
<para>Poniższa sekcja zawiera opis formatu pliku definicji podświetlania składni. Opisane zostaną główne elementy skadni &XML; pliku, ich znaczenie oraz sposoby wykorzystania. Kolejna sekcja zawiera szczegółowy opis poszczególnych reguł interpretacji składni.</para>
<para>Formalna definicja struktury pliku &XML; (czyli tak zwany dokument <acronym>DTD</acronym>) zawarta jest w pliku <filename>language.dtd</filename>, który najczęściej zlokalizowany jest w katalogu: <filename>$<envar>TDEDIR</envar>/share/apps/katepart/syntax</filename>. </para>
<term>Głównym elementem składowym pliku z definicją jest element <userinput>language</userinput> posiadający następujące atrybuty:</term>
<listitem>
<para>Atrybuty wymagane:</para>
<para><userinput>name</userinput> określa nazwę języka (format dokumentu), która pojawia się później w menu i w oknach dialogowych.</para>
<para><userinput>section</userinput> określa kategorię danego formatu dokumentu.</para>
<para><userinput>extensions</userinput> określa rozszerzenia nazw plików, np.: "*.cpp;*.h"</para>
<para>Atrybuty opcjonalne:</para>
<para><userinput>mimetype</userinput> typy &MIME; plików, których dotyczy zbiór definicji.</para>
<para><userinput>version</userinput> określa wersję pliku definicji reguł podświetlania.</para>
<para><userinput>kateversion</userinput> określa minimalną wersję &kate;, wymaganą do prawidłowego działania pliku definicji.</para>
<para><userinput>casesensitive</userinput> określa wrażliwość na wielkość liter w słowach kluczowych.</para>
<para><userinput>priority</userinput> określa priorytet stosowania danego zbioru definicji dla tych samych rozszerzeń nazw plików. Jeżeli do danego rozszerzenia pasuje kilka plików definicji, to zostaje wybrany ten o najwyższym priorytecie.</para>
<para><userinput>author</userinput> zawiera imię i nazwisko autora definicji oraz jego adres e-mail.</para>
<para><userinput>license</userinput> określa na jakiej licencji został udostępniony plik. Z reguły są to licencje: LGPL, Artistic, GPL, ale mogą też być inne.</para>
<para><userinput>hidden</userinput> wyłącza wyświetlanie nazwy zbioru definicji w menu programu &kate;.</para>
<para>Czyli kolejny wiersz pliku definicji może wyglądać następująco:</para>
<term>Następnym elementem struktury pliku jest znacznik <userinput>highlighting</userinput> zawierający element opcjonalny <userinput>list</userinput> oraz elementy wymagane:<userinput>contexts</userinput> oraz <userinput>itemDatas</userinput>.</term>
<para>Elementy typu <userinput>list</userinput> zawierają listy słów kluczowych. W przedstawionym poniżej przykładzie są to słowa <emphasis>class</emphasis> i <emphasis>const</emphasis>. Możliwe jest dodanie wielu elementów typu <userinput>list</userinput> w zależności od potrzeb.</para>
<para>Element <userinput>contexts</userinput> zawiera wszystkie konteksty występujące w składni definiowanego formatu dokumentu. Pierwszy kontekst jest domyślny i to od niego rozpoczyna się analiza składni. W omawianym przykładzie występują dwie reguły w kontekście o nazwie: <emphasis>Normal Text</emphasis>, dopasowujące listę słów kluczowych o nazwie: <emphasis>somename</emphasis> oraz reguła wykrywająca tekst w cudzysłowie przełączająca kontekst na: <emphasis>string</emphasis>. Więcej o regułach można przeczytać w kolejnym rozdziale.</para>
<para>Trzecia część to element <userinput>itemDatas</userinput>. Zawiera on wszystkie kolory i style czcionek wykorzystywane przez konteksty i reguły. W omawianym przykładzie występują następujące elementy typu <userinput>itemData</userinput>: <emphasis>Normal Text</emphasis>, <emphasis>String</emphasis> i <emphasis>Keyword</emphasis>. </para>
<term>Ostatnią częścią struktury piku definicji podświetlania jest opcjonalna sekcja <userinput>general</userinput>, która może zawierać dodatkowe informacje o słowach kluczowych, zasadach zwijaniu kodu, komentarzach i wcięciach.</term>
<para>W części <userinput>comment</userinput> definiowany jest napis rozpoczynający komentarz jedno-wierszowy. Możliwe jest także definiowanie komentarzy wielowierszowych za pomocą <emphasis>multiLine</emphasis> z dodatkowym atrybutem <emphasis>end</emphasis>. Ta część definicji jest niezbędna do działania poleceń <emphasis>Komentarz/Odkomentuj</emphasis> dostępnych w programie &kate;.</para>
<para>W sekcji <userinput>keywords</userinput> określona jest wrażliwość na wielkość liter przy rozpoznawaniu słów kluczowych. Pozostałe atrybuty opisane są poniżej.</para>
<title>Szczegółowy opis poszczególnych sekcji</title>
<para>W tej części omówione zostaną wszystkie dostępne atrybuty dla elementów typu: context, itemData, keywords, a także dla komentarzy, zasad zwijania kodu i wcięć.</para>
<term>Element <userinput>context</userinput>, należący do grupy <userinput>contexts</userinput>, definiuje reguły specyficzne dla określonego kontekstu, czyli np. co ma się stać, jeżeli system analizy składni dojdzie do końca wiersza. Dostępne atrybuty to:</term>
<para><userinput>name</userinput> określa nazwę kontekstu wykorzystywaną w operacjach przełączania kontekstu podczas interpretacji reguł analizy składni.</para>
<para><userinput>lineEndContext</userinput> określa na jaki kontekst system analizy powinien się przełączyć po osiągnięciu końca wiersza. Może to być nazwa kontekstu, napis <userinput>#stay</userinput> oznaczający pozostanie w bieżącym kontekście lub napis <userinput>#pop</userinput> powodujący przejście do poprzedniego kontekstu. Możliwe jest wielokrotne użycie #pop np.:<userinput>#pop#pop#pop</userinput> aby przejść do trzeciego kontekstu wstecz.</para>
<para><userinput>lineBeginContext</userinput> określa zmianę kontekstu w przypadku wykrycia początku wiersza. Wartość domyślna: #stay.</para>
<para><userinput>fallthrough</userinput> nakazuje systemowi podświetlania składni do przełączenia się do innego kontekstu (określonego przez "fallthroughContext"), jeżeli żadna reguła nie zostanie dopasowana. Wartość domyślna: <emphasis>false</emphasis>.</para>
<para><userinput>fallthroughContext</userinput> określa kontekst, do którego system powinien się przełączyć, jeżeli żadna reguła nie zostanie dopasowana.</para>
<para><userinput>dynamic</userinput> jeżeli ma wartość <emphasis>true</emphasis>, to powoduje zachowywanie napisów/wskaźników miejsca zapisanych przez reguły dynamiczne. Jest to wymagane np. przez dokumenty typu HERE. Wartość domyślna: <emphasis>false</emphasis>.</para>
<term>Element <userinput>itemData</userinput> należący do grupy <userinput>itemDatas</userinput> definiuje style czcionki i kolory. Możliwe jest z jego pomocą samodzielne definiowanie własnych stylów i kolorów, chociaż zalecane jest korzystanie ze stylów domyślnych, tak aby użytkownik widział te same kolory w różnych językach programowania. Czasami jednak niezbędne jest zdefiniowanie własnych kolorów i stylów czcionki. Dla tego elementu wymagane są atrybuty "name" oraz "defStyleNum" zaś pozostałe są opcjonalne. Dostępne atrybuty:</term>
<para><userinput>name</userinput> określa nazwę elementu itemData. Poszczególne reguły i konteksty będą korzystać z tej nazwy, odnosząc się do tego elementu itemData.</para>
<para><userinput>defStyleNum</userinput> określa styl domyślny, który należy wykorzystać do wyświetlania. Dostępne style domyślne są opisane poniżej.</para>
<para><userinput>color</userinput> określa kolor w formacie '#rrggbb' lub '#rgb'.</para>
<para><userinput>selColor</userinput> określa kolor zaznaczenia.</para>
<para><userinput>italic</userinput> jeżeli <emphasis>true</emphasis> to tekst będzie wyświetlony kursywą.</para>
<para><userinput>bold</userinput> jeżeli <emphasis>true</emphasis> to tekst będzie pogrubiony.</para>
<para><userinput>underline</userinput> jeżeli <emphasis>true</emphasis> to tekst będzie podkreślony.</para>
<para><userinput>strikeout</userinput> jeżeli <emphasis>true</emphasis> to tekst będzie przekreślony.</para>
<term>Element <userinput>keywords</userinput> należący do grupy <userinput>general</userinput> określa właściwości dla słów kluczowych i posiada następujące atrybuty:</term>
<para>Atrybut <userinput>casesensitive</userinput> mogący przyjmować wartości <emphasis>true</emphasis> lub <emphasis>false</emphasis>. Jeżeli będzie to wartość <emphasis>true</emphasis> to operacja dopasowania słów kluczowych będzie wrażliwa na wielkość liter.</para>
<para><userinput>weakDeliminator</userinput> zawiera listę znaków nie pełniących funkcji rozdzielającej słowa. Na przykład kropka <userinput>'.'</userinput> rozdziela słowa. Jeżeli więc jakieś słowo kluczowe na liście <userinput>list</userinput> zawiera kropkę, to zostanie dopasowane tylko wtedy, gdy kropka zostanie zdefiniowana tutaj jako znak nie pełniący funkcji rozdzielającej.</para>
<para><userinput>additionalDeliminator</userinput> określa dodatkowe znaki rozdzielające.</para>
<para><userinput>wordWrapDeliminator</userinput> określa znak, po którym może nastąpić przejście do następnego wiersza.</para>
<para>Domyślnymi znakami rozdzielającymi są znaki: <userinput>.():!+,-<=>%&*/;?[]^{|}~\</userinput>, spacja (<userinput>' '</userinput>) oraz tabulator (<userinput>'\t'</userinput>).</para>
<term>Element <userinput>comment</userinput> należący do grupy <userinput>comments</userinput> zawiera informacje niezbędne do działania poleceń menu: <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Komentarz</guimenuitem></menuchoice> oraz <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Odkomentuj</guimenuitem></menuchoice>. Dostępne atrybuty:</term>
<para>Atrybut <userinput>name</userinput> może mieć wartość <emphasis>singleLine</emphasis> lub <emphasis>multiLine</emphasis>. W przypadku użycia argumentu <emphasis>multiLine</emphasis> wymagane stają się atrybuty <emphasis>end</emphasis> oraz <emphasis>region</emphasis>.</para>
<para><userinput>start</userinput> określa napis oznaczający początek komentarza (np. w języku C++ jest to "/*").</para>
<para><userinput>end</userinput> określa napis oznaczający koniec komentarza (np. w języku C++ jest to "*/").</para>
<para><userinput>region</userinput> określa nazwę dla zwijalnego wielowierszowego komentarza. Zakładając, że zdefiniowane są następujące reguły: <emphasis>beginRegion="Comment"</emphasis> ... <emphasis>endRegion="Comment"</emphasis> można jako wartość tego atrybutu ustawić <emphasis>region="Comment"</emphasis>. Dzięki temu odkomentowywanie tekstu działa nawet jeżeli nie zostanie zaznaczony cały komentarz wielowierszowy. Wystarczy, że kursor znajduje się w dowolnym miejscu treści tego komentarza.</para>
<term>Element <userinput>folding</userinput> należący do grupy <userinput>general</userinput> określa właściwości funkcji zwijania kodu. Dostępne są dla niego następujące atrybuty:</term>
<para><userinput>indentationsensitive</userinput> jeżeli jest <emphasis>true</emphasis>, to znaczniki zwijania będą dodawane z uwzględnieniem wcięć, tak jak w języku skryptowym Python. Z reguły nie jest to jednak wymagane, a wartością domyślną jest: <emphasis>false</emphasis>.</para>
<term>Element <userinput>indentation</userinput> należący do grupy <userinput>general</userinput> określa algorytm generowania automatycznych wcięć. Definiowanie tego elementu nie jest wskazane, dlatego iż wcięcia są generowane w zależności od typu pliku lub od trybu edycji wiersza. Jeżeli element zostanie zdefiniowany to spowoduje wymuszenie na użytkowniku stosowania automatycznych wcięć, nawet jeżeli on tego nie potrzebuje. Dla elementu dostępne są atrybuty:</term>
<para><userinput>mode</userinput> określa nazwę trybu generowania wcięć. Możliwe są następujące tryby: <emphasis>normal, cstyle, csands, xml, python</emphasis> oraz <emphasis>varindent</emphasis>.</para>
<para>Style domyślne zostały już wcześniej <link linkend="kate-highlight-system-default-styles">krótko omówione</link>. Są to predefiniowane w programie &kate; style i kolory czcionki.</para>
<para>Każda reguła może zostać dopasowana do zera lub większej liczby znaków, począwszy od początku napisu podlegającego interpretacji. Jeżeli reguła zostaje dopasowana, to określonym znakom przypisany zostaje styl lub <emphasis>atrybut</emphasis> określony przez tę regułę. Może też zostać przełączony kontekst analizy treści.</para>
<para>Element <emphasis>attribute</emphasis> określa nazwę stylu wyświetlania dla dopasowanego napisu, zaś <emphasis>context</emphasis> określa kontekst, który powinien obowiązywać począwszy od tego miejsca.</para>
<para><emphasis>Kolejność</emphasis> tzn. określenie czy system ma pozostać w bieżącym kontekście(<userinput>#stay</userinput>) czy też zmienić kontekst na poprzedni (<userinput>#pop</userinput>).</para>
<para>Przejście o kilka kontekstów wstecz możliwe jest za pomocą powtórzeń słowa #pop, np: <userinput>#pop#pop#pop</userinput></para>
<para>Niektóre reguły mogą posiadać <emphasis>reguły powiązane</emphasis>, które są przetwarzane w przypadku zaistnienia dopasowania reguły podstawowej. Całość dopasowanego napisu otrzyma atrybut zdefiniowany przez regułę podstawową. Przykładowa reguła zawierająca regułę powiązaną wygląda tak:</para>
<para>Wszystkie reguły posiadają pewne wspólne zestawy atrybutów, co zaznaczone jest w opisie reguły określeniem: <userinput>(atrybuty wspólne)</userinput>. Atrybuty <emphasis>attribute</emphasis> oraz <emphasis>context</emphasis> są wymagane, a wszystkie pozostałe są opcjonalne. </para>
<para><emphasis>context</emphasis>: Określa kontekst, na który ma przełączyć się system podświetlania składni, jeżeli reguła zostanie dopasowana.</para>
<para><emphasis>lookAhead</emphasis>: Jeżeli jest <emphasis>true</emphasis>, to system podświetlania nie będzie przetwarzał całej długości dopasowania. Wartość domyślna to: <emphasis>false</emphasis>.</para>
<para><emphasis>firstNonSpace</emphasis>: Dopasowuje regułę, ale tylko wtedy gdy dany napis jest pierwszym napisem w wierszu, nie rozpoczynającym się od spacji. Wartość domyślna: <emphasis>false</emphasis>.</para>
<para>Niektóre reguły dopuszczają stosowanie atrybutu logicznego <userinput>dynamic</userinput>, który ma wartość domyślną <emphasis>false</emphasis>. Jeżeli nadana zostanie mu wartość <emphasis>true</emphasis>, to reguła może wtedy wykorzystać znacznik pozycji dla tekstu dopasowanego przez regułę z <emphasis>wyrażeniem regularnym</emphasis>, która spowodowała przełączenie się do bieżącego kontekstu. Dla <userinput>napisu</userinput> znacznik miejsca <replaceable>%N</replaceable> (gdzie N to liczba) będzie zamieniony przez tekst odpowiadający <replaceable>N</replaceable>-temu podwyrażeniu w wyrażeniu regularnym. Dla <userinput>znaku</userinput> znacznik ten też musi być liczbą i zostanie zamieniony na pierwszy znak <replaceable>N</replaceable>-tego podwyrażenia w wyrażeniu regularnym. Jeżeli reguła dopuszcza istnienie tego atrybutu, to zostanie oznaczona napisem <emphasis>(dynamiczna)</emphasis> w poniższej dokumentacji.</para>
<para>Atrybut <userinput>String</userinput> określa napis wyszukiwany. Atrybut <userinput>insensitive</userinput> ma wartość domyślną <emphasis>false</emphasis> i jest przekazywany do funkcji porównywania napisów. Jeżeli wartość tego atrybutu jest <emphasis>true</emphasis>, to dopasowanie tekstów będzie wrażliwe na wielkość liter.</para>
<para>Atrybut <userinput>String</userinput> zawiera wyrażenie regularne.</para>
<para>Atrybut <userinput>insensitive</userinput> ma wartość domyślną <emphasis>false</emphasis> i jest przekazywany jako parametr do systemu interpretacji wyrażeń regularnych.</para>
<para><userinput>minimal</userinput> ma wartość domyślną<emphasis>false</emphasis> i jest przekazywany jako parametr do systemu interpretacji wyrażeń regularnych.</para>
<para>Ponieważ reguły są zawsze dopasowywane od początku bieżącego tekstu, wyrażenie regularne rozpoczynające się od znaku karetki (<literal>^</literal>) będzie oznaczać, iż reguła powinna być dopasowana tylko na początku wiersza.</para>
<para>Więcej informacji na ten temat w części: <link linkend="regular-expressions">Wyrażenia regularne</link>.</para>
<para>Reguła ta nie posiada dodatkowych atrybutów. Reguły powiązane są zwykle wykorzystywane do wykrywania kombinacji znaków <userinput>L</userinput> oraz <userinput>U</userinput>, następujących po liczbie, określających zwykle typ liczby całkowitej w kodzie programu. Jako regułę powiązaną można wykorzystać dowolną inną regułę mimo tego, że definicja składni <acronym>DTD</acronym> dopuszcza jedynie powiązanie z regułą <userinput>StringDetect</userinput>.</para>
<para>Poniższy przykład przedstawia regułę, która dopasowuje liczbę całkowitą po której wystąpi litera 'L'. <programlisting><Int attribute="Decimal" context="#stay" >
<para>Ta reguła nie ma dodatkowych atrybutów. Może być powiązana z regułą <userinput>AnyChar</userinput>, która wykorzystywana jest często do wyszukiwania różnych wariantów. Podobne zastosowanie przedstawiono przy omawianiu reguły <userinput>Int</userinput>.</para>
<para>Ta reguła nie ma dodatkowych atrybutów.</para>
<para>Dopasowuje sekwencje specjalne, reprezentujące znaki specjalne często używane w kodach źródłowych programów, np. <userinput>\n</userinput> (znak nowego wiersza) lub <userinput>\t</userinput> (znak tabulacji).</para>
<para>Zostaną dopasowane następujące znaki zapisane po odwrotnym ukośniku (<literal>\</literal>) : <userinput>abefnrtv"'?\</userinput>. Dodatkowo dopasowane zostaną sekwencje zawierające liczby szesnastkowe: <userinput>\xff</userinput> lub ósemkowe <userinput>\033</userinput>.</para>
<para>Ta reguła nie ma dodatkowych atrybutów.</para>
<para>Reguła dopasowuje pojedynczy znak w języku C zamknięty apostrofami (np.:<userinput>'c'</userinput>). Wewnątrz apostrofów może znajdować się pojedynczy znak lub sekwencja specjalna opisująca pojedynczy znak. Więcej o dopasowaniu sekwencji specjalnych znajduje się w opisie reguły HlCStringChar.</para>
<para><userinput>char</userinput> określa początkowy znak zakresu znaków, zaś <userinput>char1</userinput> określa znak kończący zakres.</para>
<para>Reguła może być wykorzystywana do wykrywania krótkich napisów w cudzysłowach, należy jednak pamiętać, iż system podświetlania składni analizuje pojedyncze wiersze, tak więc nie zostaną wykryte napisy wielowierszowe.</para>
<para>Ta reguła nie ma dodatkowych atrybutów.</para>
<para>Reguła ta jest przydatna przy przełączaniu kontekstu po osiągnięciu końca wiersza, jeżeli ostatnim znakiem jest odwrotny ukośnik (<userinput>'\'</userinput>). Jest to wykorzystywane na przykład w językach C i C++ do zapisu makr w wielu wierszach kodu.</para>
<para>Parametr <userinput>context</userinput> określa kontekst, który należy dołączyć.</para>
<para>Jeżeli parametr jest nazwą innego kontekstu to spowoduje, to przyłączenie wszystkich określonych w innym kontekście reguł do bieżącego kontekstu, np.: <programlisting><IncludeRules context="anotherContext" /></programlisting></para>
<para>Jeżeli podany napis rozpoczyna się od <userinput>##</userinput>, to system podświetlania składni odszuka definicji innego języka o podanej nazwie, np.: <programlisting><IncludeRules context="##C++" /></programlisting></para>
<para>Jeżeli atrybut <userinput>includeAttrib</userinput> ma wartość <emphasis>true</emphasis>, to nastąpi zmiana atrybutów na występujący w źródle. Może to być przydatne do podświetlania fragmentów z przykładami w innym formacie dokumentu, tzn. gdy tekst dopasowany przez dołączony kontekst wykorzystuje inną definicję dla podświetlania składni. </para>
<para>Ta reguła nie ma dodatkowych atrybutów.</para>
<para>Regułę tę wykorzystuje się w przypadkach, gdy wiadome jest, iż w wierszu znajduje się wiele spacji, np. przy wciętych wierszach. Spowoduje ona pominięcie wszystkich spacji jednocześnie zamiast testowania wszystkich reguł znak po znaku dla każdej z nich.</para>
<para>Ta reguła nie ma dodatkowych atrybutów.</para>
<para>Reguła powyższa służy do pomijania całego napisu składającego się ze znaków składających się na wyraz, zamiast sprawdzania wielu reguł z powodu braku dopasowania.</para>
<para>Po zrozumieniu zasady działania mechanizmu przełączania kontekstów tworzenie definicji reguł podświetlania stanie się proste. Należy jednak zawsze dokładnie sprawdzić dostosowanie wybranej reguły do konkretnej sytuacji. Wyrażenia regularne dają ogromne możliwości, ale działają wolno w porównaniu z innymi regułami. Poniżej opisano kilka porad pomocnych w tworzeniu plików definicji reguł podświetlania. </para>
<para>Jeżeli poszukiwane są tylko dwa znaki to należy wykorzystywać regułę <userinput>Detect2Chars</userinput> zamiast <userinput>StringDetect</userinput> (to samo dotyczy reguły <userinput>DetectChar</userinput>).</para>
<para>Użycie wyrażeń regularnych jest proste, jednak często istnieją inne, dużo szybsze sposoby osiągnięcie tego samego rezultatu. Zakładając, iż konieczne jest dopasowanie znaku <userinput>'#'</userinput> jako pierwszego w wierszu. Odpowiednie wyrażenie regularne miałoby postać: <programlisting><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting>To samo można uzyskać poprzez: <programlisting><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting> Zamiast wyrażenia regularnego <userinput>'^#'</userinput> można zastosować regułę <userinput>DetectChar</userinput> z atrybutem <userinput>column="0"</userinput>. Atrybut <userinput>column</userinput> odnosi się do znaków w tekście, tak więc znak tabulatora zostanie policzony jako jeden znak. </para>
<para>Możliwe jest przełączanie kontekstów bez przetwarzania znaków. Przypuśćmy, iż konieczne jest przełączenie kontekstu po napotkaniu napisu <userinput>*/</userinput> ale konieczne jest przetworzenie tego napisu w kolejnym kontekście. Poniższa reguła zostanie dopasowana, zaś atrybut <userinput>lookAhead</userinput> spowoduje zachowanie dopasowanego napisu do przetwarzania w kolejnym kontekście. <programlisting><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
<para>Można podejrzeć zawartość innych plików definicji reguł podświetlania, aby zorientować się w sposobie definiowania bardziej skomplikowanych reguł.</para>
<para>Sprawdzenie poprawności stworzonego pliku XML możliwe jest z wykorzystaniem polecenia: <command>xmllint --dtdvalid language.dtd mySyntax.xml</command>.</para>
