<para>Polecenia Komentarz i Odkomentuj dostępne z menu <guimenu>Narzędzia</guimenu> pozwalają na dodanie znaczników komentarza do zaznaczonego fragmentu tekstu (lub do bieżącego wiersza, gdy brak zaznaczenia). Bieżący format dokumentu musi obsługiwać możliwość komentowania tekstu.</para>
<para>Sposób komentowania jest określony w definicji reguł podświetlania składni. Jeżeli podświetlanie składni jest wyłączone, to polecenia Komentarz i Odkomentuj są nieaktywne. </para>
<para>Dla pewnych formatów dokumentów zdefiniowane są znaczniki komentowania wiersza, inne zaś zawierają znaczniki komentarzy jedno- i wielowierszowych. Jeżeli znaczniki komentarza wielowierszowego są niedostępne, to nie będzie się dało skomentować zaznaczenia nie zawierającego w sobie całości ostatniego wiersza.</para>
<para>Gdy dostępny jest znacznik komentarza dla całego wiersza kodu, to jego użycie jest preferowane, gdyż pozwala na uniknięcie problemów w przypadku zagnieżdżonych komentarzy.</para>
<para>Podczas usuwania znaczników komentarza nie należy zaznaczać tekstu nie będącego komentarzem. Jeżeli usuwany jest komentarz wielowierszowy z zaznaczenia, to wszystkie spacje znajdujące się poza znacznikami komentarza są ignorowane.</para>
<para><indexterm><primary>komentuj</primary></indexterm> Aby skomentować fragment tekstu należy użyć menu <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Komentarz</guimenuitem></menuchoice>, lub skrótu klawiszowego <keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para>
<para><indexterm><primary>odkomentuj</primary></indexterm> Aby usunąć znaczniki komentarza z wybranego fragmentu tekstu, należy użyć menu <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Odkomentuj</guimenuitem></menuchoice>, lub skrótu klawiszowego <keycombo action="simul">&Ctrl; &Shift;<keycap>D</keycap></keycombo>.</para>
<para>Komponent edytora w &kate; zawiera wbudowaną linię poleceń, pozwalającą na sterowanie pracą bez pośrednictwa graficznego interfejsu użytkownika. Linia poleceń znajduje sią w dolnej części okna edytora, aby ją włączyć należy wybrać z menu: <menuchoice><guimenu>Widok</guimenu><guimenuitem>Przełącz do linii poleceń</guimenuitem></menuchoice> lub skorzystać ze skrótu klawiszowego (domyślnie jest to <keycombo action="simul"><keycap>F7</keycap></keycombo>). Zestaw poleceń dostępnych w linii poleceń edytora opisany został poniżej. Może on ulec rozszerzeniu przez zastosowanie wtyczek.</para>
<para>Naciśnięcie klawisza ENTER uruchamia wprowadzone polecenie. Komunikat wyświetlony w linii poleceń pokaże informacje o wynikach polecenia lub ewentualnym błędzie. Jeżeli linia poleceń została wyświetlona za pomocą klawisza <keycap>F7</keycap>, to schowa się ona automatycznie po kilku sekundach. Ponowne naciśnięcie klawisza <keycap>F7</keycap> usuwa komunikat i pozwala na wprowadzenie następnego polecenia.</para>
<para>Linia poleceń zawiera wbudowany system pomocy uruchamiany poleceniem <command>help</command>. Aby wyświetlić listę wszystkich dostępnych poleceń należy wpisać <command>help list</command>. Pomoc dotycząca wybranego polecenia dostępna jest po wpisaniu: <command>help <replaceable>polecenie</replaceable></command>.</para>
<para>Linia poleceń przechowuje historię poleceń pozwalając na ponowne użycie poleceń wcześniej już wpisanych. Dostęp i nawigacja w historii linii poleceń odbywa się za pomocą klawiszy strzałek <keycap>w górę</keycap> oraz <keycap>w dół</keycap>. Argumenty wywołanych z historii poleceń będą zaznaczone, pozwalając na łatwą ich zmianę.</para>
<para>Polecenia opisane poniżej dotyczą wbudowanego edytora i pozwalają na konfigurację bieżącego widoku i dokumentu. Może to być przydatne, gdy użytkownik chce wykorzystać ustawienia inne niż domyślne, np. dla automatycznych wcięć. </para>
<listitem><para>Stosowane dla poleceń, które włączają lub wyłączają jakąś funkcję. Dopuszczalne wartości takiego argumentu to:<userinput>on</userinput>, <userinput>off</userinput>, <userinput>true</userinput>, <userinput>false</userinput>, <userinput>1</userinput> lub <userinput>0</userinput></para></listitem>
<listitem><para>Ustawia szerokość wcięcia na wartość określoną przez argument <userinput>szerokość</userinput>. Polecenie odnosi się do trybu wcięć dokonywanych za pomocą znaku spacji.</para></listitem>
<listitem><para>Ustawia liczbę znaków w wierszu dla funkcji statycznego zawijania wyrazów na wartość określoną przez argument <userinput>szerokość</userinput>. Działa jedynie w przypadku włączonego automatycznego zawijania wyrazów.</para></listitem>
<listitem><para>Włącza lub wyłącza generowanie wcięć za pomocą zdefiniowanej przez parametr <option>indent-width</option> liczby spacji, dla każdego poziomu wcięcia. Wyłączenie opcji przywraca stosowanie znaku tabulacji do generowania wcięć.</para></listitem>
<listitem><para>Włączenie tej opcji pozwala na jednoczesne użycie znaków tabulacji i spacji do generowania wcięć przez &kate;. Poziomy wcięć będą określane zgodnie z ustawieniami opcji <option>indent-width</option>, zaś wcięcia wielopoziomowe będą generowane za pomocą największej możliwej liczby znaków tabulacji.</para>
<para>Po wykonaniu tego polecenia, dodatkowo włączona zostanie funkcja wcięć za pomocą spacji, a jeżeli szerokość wcięcia jest nieokreślona, to zostanie ustawiona na połowę wartości parametru <option>tab-width</option> określonego dla bieżącego dokumentu.</para></listitem>
<listitem><para>Określa tryb automatycznych wcięć, możliwe <userinput>nazwy</userinput> trybów to: 'cstyle', 'csands', 'xml', 'python', 'varindent' oraz 'none'. Jeżeli wprowadzona nazwa jest nieznana to przyjęta zostanie wartość 'none'.</para></listitem>
<listitem><para>Wybiera zestaw reguł podświetlania składni dla dokumentu. Argument musi określać nazwę istniejącej reguły podświetlania. Dostępne nazwy widoczne są w menu: <menuchoice><guimenu>Narzędzia</guimenu><guisubmenu>Podświetlenie</guisubmenu></menuchoice>. W trakcie wprowadzania polecenia, pojawi się pomocnicza lista automatycznego dopełniania nazwy.</para></listitem>
<listitem><para>Wyrównuje wcięcia dla zaznaczonego fragmentu tekstu lub dla bieżącego wiersza, zgodnie z ustawionymi dla dokumentu regułami wcięć. </para></listitem>
<listitem><para>Wprowadza znaczniki komentarza dla zaznaczonego fragmentu tekstu lub dla bieżącego wiersza, zgodnie z definicją reguł podświetlania składni wybraną dla bieżącego dokumentu.</para></listitem>
<listitem><para>Usuwa znaczniki komentarza z zaznaczonego fragmentu tekstu lub bieżącego wiersza, zgodnie z definicją reguł podświetlania składni wybraną dla bieżącego dokumentu.</para></listitem>
<listitem><para>Zamienia tekst pasujący do napisu: <userinput>wzorzec</userinput> tekstem określonym w: <userinput>zastąpienie</userinput>. Jeżeli wzorzec lub zastąpienie zawiera spację, to oba argumenty należy podać w cudzysłowach (pojedynczych lub podwójnych). Jeżeli argument nie jest zamknięty w cudzysłowie, to pierwsze słowo traktowane jest jako <userinput>wzorzec</userinput>, a reszta tekstu jako <userinput>zastąpienie</userinput>. Jeżeli tekst <userinput>zastąpienie</userinput> nie zostanie podany, to każde wystąpienie <userinput>wzorca</userinput> zostanie usunięte.</para>
<para>Parametry działania polecenia zamień mogą być dostosowywane poprzez dodanie dwukropka i jednej z dostępnych opcji. Polecenie przyjmuje wówczas postać: <userinput>replace:opcja wzorzec zastąpienie</userinput>. Dostępne są następujące opcje: <variablelist>
<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Szuka tekstu wstecz.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Szuka począwszy od pozycji kursora.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Szuka w ramach zaznaczonego fragmentu.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Wykonuje polecenie szukania za pomocą wyrażenia regularnego. W przypadku użycia tej opcji, można w argumencie "zastąpienie" użyć parametru <userinput>\N</userinput>, gdzie N jest numerem podwyrażenia, które zostanie wstawione w zastępowanym tekście.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>Szuka zwracając uwagę na wielkość liter.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>p</userinput></term>
<listitem><para>Pyta się przed zastąpieniem kolejnego wystąpienia.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Szuka dopasowując tylko całe wyrazy.</para></listitem>
<listitem><para>Wprowadza do dokumentu bieżący czas i datę w formacie określonym przez: <userinput>format</userinput> lub w formacie <quote>yyyy-MM-dd hh:mm:ss</quote> gdy brak jest argumentu. Interpretacja treści argumentu <userinput>format</userinput> jest następująca: <informaltable> <tgroup cols="2"> <tbody>
<row><entry><literal>d</literal></entry><entry>Dzień podany jako liczba bez wiodącego zera (1-31).</entry></row>
<row><entry><literal>dd</literal></entry><entry>Dzień podany jako liczba z wiodącym zerem (01-31).</entry></row>
<row><entry><literal>ddd</literal></entry><entry>Skrót zlokalizowanej nazwy dnia (np. 'Pon'..'Nie').</entry></row>
<row><entry><literal>dddd</literal></entry><entry>Pełna zlokalizowana nazwa dnia (np.: 'Poniedziałek'..'Niedziela').</entry></row>
<row><entry><literal>M</literal></entry><entry>Miesiąc jako liczba bez wiodącego zera (1-12).</entry></row>
<row><entry><literal>MM</literal></entry><entry>Miesiąc jako liczba z wiodącym zerem (01-12).</entry></row>
<row><entry><literal>MMM</literal></entry><entry>Skrót zlokalizowanej nazwy miesiąca (np. 'Sty'..'Gru').</entry></row>
<para>Polecenie pozwala na wstawianie do treści dokumentu znaku określonego przez wartość numeryczną w formie dziesiętnej, ósemkowej lub szesnastkowej.</para>
<para>To polecenie wykonuje operację znajdź/zamień analogicznie jak program "sed". Polecenie działa dla bieżącego wiersza lub dla całego dokumentu (<command>%s///</command>).</para>
<para>Działanie polecenia polega na wyszukaniu w tekście <emphasis>wzorca wyszukiwania</emphasis> (określonego przez wyrażenie regularne pomiędzy pierwszym i drugim ukośnikiem). Po znalezieniu wzorca dopasowany tekst jest zamieniany na wyrażenie zawarte pomiędzy środkową i ostatnią częścią polecenia. Nawiasy we wzorcu wyszukiwania określają tzw.<emphasis>odwołania zwrotne</emphasis>, co oznacza iż program zapamiętuje wyszukany napis, który następnie może być użyty w definicji wyrażenia zastępującego. Odwołanie do zapamiętanego napisu odbywa się przez użycie <userinput>\1</userinput> dla pierwszego zestawu nawiasów, <userinput>\2</userinput> dla drugiego i tak dalej.</para>
<para>Wyszukiwanie w tekście nawiasów <literal>(</literal> lub <literal>)</literal> wymaga zastosowania sekwencji specjalnych, z użyciem znaku odwrotnego ukośnika. Nawiasy będą reprezentowane przez napisy: <userinput>\(</userinput> oraz <userinput>\)</userinput></para>
<para>Użycie znaku <userinput>i</userinput> na końcu wyrażenia spowoduje, iż przy wyszukiwaniu nie będzie uwzględniana wielkość liter. Jeżeli na końcu wyrażenia wprowadzone zostanie <userinput>g</userinput> spowoduje to zamienienie wszystkich wystąpień poszukiwanego wzorca (w innym wypadku zamienione zostanie tylko pierwsze wystąpienie).</para>
<para>Wyobraźmy sobie komunikat kompilatora informujący o następującym błędzie w wierszu 3902 edytowanego kodu programu: Klasa: <classname>myClass</classname> nie jest zdefiniowana.</para>
<para>Zamiast przeszukiwania i edycji wiersza 3902, celem zamienienia złej nazwy klasy na poprawną (<classname>MyClass</classname>), wystarczy uruchomić linię poleceń, uruchomić polecenie <userinput>s/myclass/MyClass/i</userinput>, zapisać plik, a następnie już bez błędów skompilować program.</para>
<title>Zastępowanie tekstu w całym dokumencie</title>
<para>Wyobraźmy sobie sytuację, że w trakcie edycji dokumentu, w którym często występuje napis <quote>Pani Nowak</quote> ktoś przychodzi i mówi, iż osoba ta wyszła za mąż za pana <quote>Kowalskiego</quote>. Należy oczywiście zamienić wszystkie wystąpienia <quote>Pani Nowak</quote> na <quote>Pani Kowalska</quote>.</para>
<para>W linii poleceń wystarczy wprowadzić:<userinput>%s/Pani Nowak/Pani Kowalska/</userinput> i po naciśnięciu ENTER wszystko już będzie w porządku.</para>
<para>W tym przykładzie zastosowano <emphasis>odwołanie zwrotne</emphasis> oraz mechanizm <emphasis>klas znaków</emphasis> (więcej informacji na ten temat znajduje się we wspomnianej poniżej dokumentacji).</para>
<para>Dokument zawiera następujący wiersz kodu: <programlisting>void MyClass::DoStringOps( String &foo, String &bar, String *p, int &a, int &b )</programlisting>
<para>Konieczne jest dodanie operatora <constant>const</constant> do wszystkich argumentów określonych przez <quote>referencję</quote> (reprezentowanych przez znak & na początku nazwy argumentu). Dodatkowo trzeba ujednolicić odstępy między słowami tak, aby była to tylko jedna spacja).</para>
<para>Po uruchomieniu linii poleceń, należy wpisać: <userinput>s/\s+(\w+)\s+(&)/ const \1 \2/g</userinput> i nacisnąć ENTER. Znak <userinput>g</userinput> na końcu wyrażenia wymusza ponowną kompilacją wyrażenia regularnego po każdym dopasowaniu wyrażenia w tekście, co jest wymagane do poprawnego działania mechanizmu <emphasis>odwołań zwrotnych</emphasis>.</para>
<para>Interpretacja opisanego wyrażenia jest następujące. Najpierw wyszukuje ono spacje (<literal>\s+</literal>) po których wystąpił jeden lub więcej znaków alfanumerycznych (<literal>\w+</literal>) zakończonych kolejną spacją (<literal>\s+</literal>), za którą znajduje się znak &. Pełna treść tego dopasowania zostaje zachowana do dalszego wykorzystania przy wykonaniu zastąpienia tekstu. W drugiej części dopasowany fragment zostaje zastąpiony spacją i napisem <quote>const</quote>, po którym następuje kolejna spacja i zachowany wcześniej fragment tekstu (<literal>\1</literal>), a dalej spacja i kolejny fragment dopasowany po znaku & (<literal>\2</literal>)</para>
<para>W powyższym przykładzie pierwszy dopasowany fragment mógł zawierać napis <quote>String</quote> lub też <quote>int</quote>, dlatego też zastosowanie klasy znakowej <literal>\w</literal> i operatora <literal>+</literal> dało wymagany efekt.</para>
<listitem><para>Spowoduje przejście do pierwszego wystąpienia napisu <userinput>wzorzec</userinput> zgodnie z bieżącą konfiguracją funkcji wyszukiwania. Kolejne wystąpienia mogą zostać wyszukane za pomocą menu <menuchoice><guimenu>Edycja</guimenu><guimenuitem>Znajdź następne</guimenuitem></menuchoice> (domyślny skrót klawiszowy to <keycap>F3</keycap>).</para>
<para>Polecenie "find" może być skonfigurowane poprzez dodanie jednej lub więcej opcji po dwukropku w postaci: <userinput>find:opcje wzorzec</userinput>. Dostępne są następujące opcje: <variablelist>
<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Szuka tekstu wstecz.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Szuka począwszy od pozycji kursora.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Szuka w ramach zaznaczonego fragmentu.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Wykonuje polecenie szukania za pomocą wyrażenia regularnego. W przypadku użycia tej opcji, można w argumencie "zastąpienie" użyć parametru <userinput>\N</userinput>, gdzie N jest numerem podwyrażenia, które zostanie wstawione w zastępowanym tekście.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>Szuka zwracając uwagę na wielkość liter.</para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Szuka dopasowując tylko całe wyrazy.</para></listitem>
<listitem><para>Polecenie wyszukuje tekst <quote>w trakcie pisania</quote>. Dodatkowo można skonfigurować zachowanie za pomocą opcji podanych po dwukropku w postaci: <userinput>ifind:opcje wzorzec</userinput>. Dostępne są następujące opcje: <variablelist>
<title>Korzystanie ze zwijania kodu źródłowego</title>
<para>Zwijanie kodu, pozwala na ukrywanie wydzielonych części tekstu, dzięki czemu łatwiej jest przeglądać duże fragmenty edytowanego kodu źródłowego. &kate; określa możliwość zwinięcia danej części na podstawie reguł określonych w definicji podświetlania składni. Zwijanie jest dostępne tylko dla niektórych formatów dokumentów, zwykle są to pliki XML, kod źródłowy, itp. Większość definicji podświetlania, obsługujących funkcję zwijania kodu, pozwala też na ręczne definiowanie zwijalnych fragmentów tekstu, zwykle za pomocą słów kluczowych <userinput>BEGIN</userinput> oraz <userinput>END</userinput>.</para>
<para>Aby włączyć funkcję zwijania kodu, należy skorzystać z menu <menuchoice><guimenu>Widok</guimenu><guimenuitem>Pokaż znaczniki zwijania</guimenuitem></menuchoice> (jeżeli nie były one wcześniej widoczne). Pasek znaczników zwijania, widoczny po lewej stronie okna edycji menu, wyświetla graficzną reprezentację zwijalnych fragmentów kodu wraz ze znakami +/- wskazującymi na możliwe do wykonania na nim operacje. Naciśnięcie znaku "-" zwija dotyczący go fragment, zaś "+" rozwija go.</para>
<para>W menu dostępne są cztery dodatkowe polecenia pozwalające na manipulację zwiniętymi częściami tekstu, więcej informacji na ten temat dostępne jest w <link linkend="view-code-folding">dokumentacji menu</link>. </para>
<para>Jeżeli użytkownik nie chce korzystać z funkcji zwijania kodu, to może wyłączyć opcję <guilabel>Pokaż znaczniki zwijania (jeżeli dostępne)</guilabel> w karcie <link linkend="config-dialog-editor-appearance">Edytor -> Wygląd</link> w oknie konfiguracji.</para>
<para>Począwszy od wersji 2.5, edytor &kate; umożliwia tworzenie skryptów w standardzie ECMA, znanym również jako JavaScript.</para>
<para>Ze skryptów można korzystać tylko za pomocą <link linkend="advanced-editing-tools-commandline">wbudowanej linii poleceń</link>. Skrypt musi być zlokalizowany w katalogu, w którym &kate; może go odszukać wraz z opcjonalnym plikiem .desktop definiującym jego dodatkowe właściwości. Domyślnym katalogiem dla skryptów jest podkatalog <filename>katepart/scripts</filename> znajdujący się w katalogu z danymi środowiska &kde;. Ścieżka dostępu do katalogu z danymi środowiska jest wyświetlana za pomocą polecenia <command>tde-config <option>--path</option> <parameter>data</parameter></command>. Zwykle podczas instalacji systemu operacyjnego tworzone są katalogi danych: systemowy i użytkownika. Skrypty umieszczone w katalogu systemowym są dostępne dla wszystkich użytkowników, zaś w katalogu użytkownika dostępne są tylko dla tego użytkownika.</para>
<note><para>Ta funkcja programu ma charakter eksperymentalny i jej działanie może się zmienić w przyszłych wersjach programu.</para>
<para>W chwili obecnej nie jest możliwe dodawanie skryptów do menu lub przypisywanie im skrótów klawiszowych. W przyszłości ta możliwość może się pojawić.</para>
<para>Nie jest jeszcze możliwe przekazywanie do uruchamianego skryptu żadnych argumentów. Ta możliwość również w przyszłości się pojawi ;)</para>
<title>Interfejs programisty (API) dla JavaScript w &kate;</title>
<para>Poniżej przedstawiono pełny zestaw funkcji i właściwości dostępnych dla obiektów <type>document</type> oraz <type>view</type>. Oczywiście możliwe jest korzystanie z innych obiektów standardowych Javascript takich jak np.: <type>Math</type>, <type>String</type> <type>Regex</type>, itd.</para>
<para>Podczas działania skryptu, obiekt <classname>document</classname> odnosi się do bieżącego dokumentu, a obiekt <classname>view</classname> odnosi się do bieżącego widoku.</para>
<note><para>Typy argumentów nie są w chwili obecnej stosowane w JavaScript, przedstawione są tylko dla zilustrowania jakiego rodzaju wartości dana funkcja oczekuje.</para></note>
<para>Przekazuje napis na standardowe wyjście <acronym>STDERR</acronym> wykorzystując funkcję <function>kdDebug()</function>. Wykorzystywany jest specjalnie przydzielony obszar do wyświetlania komunikatów, oznaczony przedrostkiem <computeroutput>Kate (KJS Scripts):</computeroutput> </para>
<para>Zwraca kod ID atrybutu znajdującego się w określonej pozycji dokumentu [<parameter>wiersz</parameter>,<parameter>kolumna</parameter>]. Atrybut reprezentuje wygląd tekstu lub styl tekstu, i wykorzystywany jest do podświetlania składni określonego fragmentu tekstu, co jest wykorzystywane w formatach mieszanych takich jak np.: HTML lub PHP.</para>
<para>Zwraca informację, dotyczącą możliwości łamania wiersza dla znaku "c" i atrybutu "atrybut". Wynik działania funkcji zależy od reguł podświetlania, określających możliwość łamania wiersza dla danego znaku i atrybutu.</para>
<para>Zwraca informację o tym, czy atrybut_początkowy i atrybut_końcowy są zgodne z bieżącymi regułami podświetlania składni. Jeżeli tak, to możliwe jest wtedy przekształcenie tego fragmentu w komentarz. </para>
<para>Zwraca napis wymagany do rozpoczęcia wielowierszowego komentarza dla tekstu o określonym atrybucie, lub napis pusty, jeżeli komentarze wielowierszowe nie są obsługiwane dla tego typu dokumentu.</para>
<para>Zwraca napis, wykorzystywany do komentowania wiersza dokumentu, lub pusty napis jeżeli komentarze dla całych wierszy nie są dostępne dla tego typu dokumentu.</para>
<para>Zwraca napis wymagany do zakończenia wielowierszowego komentarza dla tekstu o określonym atrybucie, lub napis pusty, jeżeli komentarze wielowierszowe nie są obsługiwane dla tego typu dokumentu.</para>
<para>Rozpoczyna grupę operacji edycyjnych. Wszystkie działania wykonane do momentu uruchomienia funkcji editEnd() będą zgrupowane w jedną operację cofania.</para>
<para>Zawiera nazwę trybu reguł podświetlania dla bieżącego dokumentu (np. "JavaScript" lub "C++"). Jeżeli dokument nie ma zdefiniowanego trybu podświetlania składni, zostanie zwrócona wartość "None". Konieczne jest korzystanie z nazwy w języku angielskim, w przypadkach gdy różni się ona od nazwy przetłumaczonej.</para>
<para>Nazwa trybu automatycznych wcięć dla bieżącego dokumentu (np.:<literal>normal</literal> lub <literal>cstyle</literal>). Jeżeli tryb automatycznych wcięć jest wyłączony, to zwrócona zostanie wartość <literal>none</literal>. </para>
<para>Wartość prawda/fałsz informująca czy tryb mieszanych wcięć dla dokumentu jest włączony. Jeżeli tak, to wcięcia są optymalizowane, tak że zawierają mieszankę znaków tabulacji i spacji (podobnie jak w edytorze Emacs).</para>
<para>Usuwa tekst w dokumencie od wiersza <parameter>wiersz_początku</parameter> i kolumny <parameter>kolumna_początku</parameter> do wiersza<parameter>wiersz_końca</parameter> i kolumny <parameter>kolumna_końca</parameter>. </para>
<para>Wartość prawda/fałsz określająca czy tryb wcinania spacjami jest włączony. Jeżeli tak, to wcięcia w dokumencie są generowane odpowiednią, zdefiniowaną przez "indentWidth", liczbą spacji. W przeciwnym wypadku, wcięcia dokonywane są za pomocą znaków tabulacji (jeden znak na jeden poziom wcięcia).</para>
<para>Zwraca pełną zawartość dokumentu. Jeżeli dokument zawiera wiele wierszy, to rozdzielane są one znakiem końca wiersza: <constant>\n</constant>.</para>
<para>Zwraca zdefiniowany zakres tekstu dokumentu. Jeżeli zawiera on wiele wierszy, to rozdzielane są one znakiem końca wiersza: <constant>\n</constant>.</para>
<para>Zwraca wartość <constant>true</constant> (logiczna prawda), jeżeli widok zawiera zaznaczenie, lub <constant>false</constant> (logiczny fałsz), gdy w widoku brak zaznaczenia.</para>
<para>Ustawia kursor w widoku w pozycji [<parameter>wiersz</parameter>, <parameter>kolumna</parameter>]. Pozycja zostaje ustalona wizualnie, czyli znaki tabulacji rozwijane są na odpowiednią (określoną przez <replaceable>tabwidth</replaceable>) liczbę spacji w zależności od pozycji w wierszu. Kursor staje się widoczny. Parametry wiersz i kolumna rozpoczynają się od zera.</para>
<para>Ustawia kursora w pozycji podanej przez <parameter>wiersz</parameter> i <parameter>kolumnę</parameter>. Argumenty określają pozycję w tekście, czyli znaki tabulacji traktowane są jako jeden znak. Kursor stanie się widoczny. Numery wiersza i kolumny rozpoczynają się od zera.</para>
<para>Zaznacza fragment tekstu począwszy od wiersza <parameter>wiersz_początku</parameter> i kolumny <parameter>kolumna_początku</parameter> do wiersza <parameter>wiersz_końca</parameter> i kolumny <parameter>kolumna_końca</parameter>.</para>
<para>Przedstawiony poniżej skrypt, przerabia wszystkie litery w zaznaczonym fragmencie na duże. Pierwszym krokiem jest sprawdzenie istnienia zaznaczenia, następnie pobranie zaznaczonego tekstu, zamienienie wielkości znaków oraz wstawienie zmienionego tekstu do dokumentu. Zapis programu wygląda następująco:</para>
<para>Zgrupowanie poleceń edycyjnych tak, aby można je było wycofać jednym poleceniem <guimenuitem>Cofnij</guimenuitem>, polega na objęciu poleceń<programlisting>view.removeSelectedText()</programlisting> i <programlisting>document.insertText()</programlisting> poleceniami <programlisting>document.editBegin()</programlisting> oraz <programlisting>document.editEnd()</programlisting>.</para>
<para>W pliku tym, możliwe jest zdefiniowanie kodowania znaków (Encoding), nazwy skryptu (Name), komentarza (Comment), tekstu pomocy (X-Kate-Help) i polecenia linii poleceń (X-Kate-Command). Jeżeli plik .desktop znajdzie się w repozytoriach SVN środowiska KDE, to parametry: Name, Comment i X-Kate-Help będą automatycznie tłumaczone na inne języki przez zespoły tłumaczy KDE.</para>
<para>Program &kate; przeszuka katalogi ze skryptami (patrz <link linkend="advanced-editing-tools-scripting-introduction">wyżej</link>) w poszukiwaniu plików o nazwie <filename>*.js</filename>. Dla każdego znalezionego pliku sprawdzane jest istnienie odpowiadającego mu pliku <filename>.desktop</filename> (np. dla skryptu: uppercase.js, poszukiwany będzie plik uppercase.desktop). </para>
<para>Jeżeli plik <filename>.desktop</filename> nie zostanie znaleziony, to skrypt zostanie zarejestrowany przez linię poleceń edytora pod nazwą pliku bez rozszerzenia .js. W opisywanym przykładzie będzie to <literal>uppercase</literal>. Jeżeli taka nazwa skryptu odpowiada użytkownikowi oraz nie ma potrzeby korzystania z innych możliwości, jakie daje plik <filename>.desktop</filename>, to wtedy użycie pliku <filename>.desktop</filename> nie jest wymagane. </para>
<para>Jeżeli istnieje plik <filename>.desktop</filename>, edytor odczyta nazwę skryptu z tego pliku z pozycji X-Kate-Command, na przykład: X-Kate-Command=uppercase-selection.</para>
