path: root/tde-i18n-ru/docs/tdebase/kate/advanced.docbook

<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author>&Anders.Lund; &Anders.Lund.mail;</author>
<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
<othercredit role="translator"><firstname>Андрей</firstname><surname>Балагута</surname><affiliation><address><email>uj2@mail.ru</email></address></affiliation><contrib>Перевод на русский</contrib></othercredit> <othercredit role="translator"><firstname>Алексей</firstname><surname>Опарин</surname><affiliation><address><email>opaleksej@yandex.ru</email></address></affiliation><contrib>Перевод на русский</contrib></othercredit> 
</authorgroup>
</chapterinfo>
<title>Дополнительные возможности редактирования</title>

<sect1 id="advanced-editing-tools-comment">

<title>Комментирование</title>

<para>Команды "Комментировать" и "Раскомментировать", которые доступны из меню <guimenu>Сервис</guimenu>, позволяют добавить или убрать маркеры комментариев для выделенного блока текста (или для текущей строки, если текст не выделен), при условии, что комментарии поддерживаются форматом редактируемого текста.</para>

<para>Правила комментирования определяются синтаксисом; таким образом, если подсветка синтаксиса не включена, то команды "Закомментировать" и "Раскомментировать" будут недоступны. </para>

<para>Некоторые форматы поддерживают только однострочные маркеры комментариев, другие -- только многострочные, третьи -- и те, и другие. Если многострочные маркеры недоступны, то комментирование блока, в котором не до конца выделена последняя строка, будет невозможным.</para>

<para>Предпочтение отдаётся комментированию отдельных строк однострочными маркерами, если последние допустимы синтаксисом и если такое комментирование возможно -- это помогает избежать проблем со вложенными комментариями.</para>

<para>При удалении маркеров комментариев выделение снимается с раскомментированного текста. При удалении маркеров многострочного комментария пробелы снаружи маркеров игнорируются.</para>

<para><indexterm><primary>закомментировать</primary></indexterm> Чтобы закомментировать выделенный текст (или активную строку), выберите пункт меню<menuchoice><guimenu>Сервис</guimenu><guimenuitem>Закомментировать</guimenuitem></menuchoice> или нажмите соответствующее сочетание клавиш (по умолчанию <keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>).</para>

<para><indexterm><primary>раскомментировать</primary></indexterm> Чтобы удалить маркеры комментариев, выберите пункт меню <menuchoice><guimenu>Сервис</guimenu><guimenuitem>Раскомментировать</guimenuitem> </menuchoice> или нажмите соответствующее сочетание клавиш ( по умолчанию <keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>).</para>

</sect1>

<sect1 id="advanced-editing-tools-commandline">
<title>Командная строка компонента редактора</title>

<para>Модуль Kate имеет встроенную командную строку, позволяющую производить различные действия, оставляя интерфейс минималистским. Она представляет из себя поле ввода внизу области редактора. Для получения к ней доступа, выберите пункт меню <menuchoice><guimenu>Вид</guimenu><guimenuitem>Переключиться в командную строку</guimenuitem></menuchoice> или нажмите <keycombo action="simul"><keycap>F7</keycap></keycombo> (по умолчанию). Команды, доступные из неё, описаны ниже, кроме того, модули могут предоставлять свои дополнительные команды.</para>

<para>Для выполнения команды введите её и нажмите Enter. На месте команды будет выведено сообщение об успешном её выполнении или об ошибке. Если вы вызвали командную строку клавишей <keycap>F7</keycap>, она будет автоматически скрыта по прошествии нескольких секунд. Для того чтобы убрать сообщение и ввести новую команду, нажмите <keycap>F7</keycap> ещё раз.</para>

<para>Вы всегда можете получить справку с помощью команды <command>help</command>. Для получение списка всех доступных команд, введите <command>help list</command>, для просмотра справки по определённой команде - <command>help <replaceable>команда</replaceable></command>.</para>

<para>Для навигации по истории команд, воспользуйтесь стрелками <keycap>Вверх</keycap> и <keycap>Вниз</keycap>. При отображении команды из истории, её аргументы будут выделены, так что заменить их на другие легко.</para>

<sect2 id="advanced-editing-tools-commandline-commands">
<title>Стандартные команды</title>

<sect3 id="advanced-editing-tools-commandline-commands-configure">
<title>Параметры редактора</title>

<para>Установленные таким способом параметры применяются только к текущему экземпляру редактора и не сохраняются. Удобно, если нужно установить параметры, отличные от стандартных (например, отступ). </para>

<variablelist>
<title>Типы аргументов</title>

<varlistentry>
<term>BOOLEAN</term>
<listitem><para>Используется для команд включения/выключения. Допустимые значения - <userinput>on</userinput>, <userinput>off</userinput>, <userinput>true</userinput>, <userinput>false</userinput>, <userinput>1</userinput> или <userinput>0</userinput></para></listitem>
</varlistentry>

<varlistentry>
<term>INTEGER</term>
<listitem><para>Целое число</para></listitem>
</varlistentry>

<varlistentry>
<term>STRING</term>
<listitem><para>Строка</para></listitem>
</varlistentry>

</variablelist>

<variablelist>

<varlistentry>
<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER width</arg></cmdsynopsis></term>
<listitem><para>Устанавливает расстояние между позициями табуляции</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER width</arg></cmdsynopsis></term>
<listitem><para>Устанавливает ширину отступа. Только при создании отступов пробелами.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER width</arg></cmdsynopsis></term>
<listitem><para>Устанавливает максимальную длину строк в случае, если включён автоматический перенос.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN enable</arg> </cmdsynopsis></term>
<listitem><para>Устанавливает видимость рамок пиктограмм.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Устанавливает видимость маркеров сворачивания блоков кода.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Устанавливает видимость нумерации строк.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Заменять при вводе символы табуляции на пробелы. </para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Удалять пробелы в конце строки при снятии с неё курсора.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Представлять символы табуляции пробельное пространство в конце строк маленькими точками.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Вставлять заданное количество пробелов для каждого уровня отступа, вместо одного символа табуляции.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Использовать для отступов как символы табуляции, так и пробелы. Это реализуется путём замены пробелов в количестве, кратном ширине символа табуляциями, на последние.</para>
<para>Эта команда также включит расстановку отступов пробелами, и установит ширину отступов, если она не указана, в половину значения <option>tab-width</option> (для текущего документа на время выполнения).</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Динамический перенос слов</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable </arg></cmdsynopsis></term>
<listitem><para>Заменять символы табуляции на пробелы при сохранении.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
<listitem><para>Удалить пробелы в конце строк при сохранении.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-mode</command><arg>name</arg></cmdsynopsis></term>
<listitem><para>Выбрать режим расстановки отступов. Параметр <userinput>name</userinput> может иметь следующие значения: 'cstyle', 'csands', 'xml', 'python', 'varindent' и 'none'. При других значениях используется 'none'.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-highlight</command><arg>highlight</arg></cmdsynopsis></term>
<listitem><para>Выбрать формат для подсветки, один из содержащихся в подменю<menuchoice><guimenu>Сервис</guimenu><guisubmenu>Подсветка синтаксиса</guisubmenu></menuchoice>. Доступно также автозавершение параметра.</para></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-edit">
<title>Команды редактирования</title>

<para>Команды, которые непосредственно изменяют текущий документ.</para>

<variablelist>
<varlistentry>
<term><cmdsynopsis><command>indent</command></cmdsynopsis></term>
<listitem><para>Подставляет отступы к выделенным строкам или к текущей.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term>
<listitem><para>Снимает отступы с выделенных строк или с текущей.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term>
<listitem><para>Очистить отступы в выделенных строках или в текущей в соответствии с параметрами расстановки отступов для текущего документа. </para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>comment</command></cmdsynopsis></term>
<listitem><para>Вставляет маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла (определяется способом подсветки синтаксиса).</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term>
<listitem><para>Удалить маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term>
<listitem><para>Удаляет текущую строку.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>replace</command><arg>pattern</arg><arg>replacement</arg></cmdsynopsis></term>
<listitem><para>Заменить текст, совпадающий с <userinput>pattern</userinput> на <userinput>replacement</userinput>. Для включения пробелов в <userinput>pattern</userinput>, нужно заключить в двойные или одинарныекавычки и <userinput>pattern</userinput>, и <userinput>replacement</userinput>. Если аргументы не заключены в кавычки, первое слово будет принято за <userinput>pattern</userinput>, а остальное - за <userinput>replacement</userinput>. Если <userinput>replacement</userinput> не задать, все <userinput>pattern</userinput> будут удалены.</para>
<para>Для настройки параметров поиска, нужно указать соответствующие флаги после двоеточия (<userinput>replace:options pattern replacement</userinput>). Возможные параметры: <variablelist>

<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Искать в обратном направлении.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Искать от позиции курсора.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Искать только в выделенном тексте.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Аргумент <userinput>pattern</userinput> - регулярное выражение. Вы можете использовать <userinput>\N</userinput> в <userinput>replacement</userinput> для получения N-ной подстроки найденного текста.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>С учётом регистра.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>p</userinput></term>
<listitem><para>Подтверждать каждую замену.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Только целые слова.</para></listitem>
</varlistentry>

</variablelist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term>
<listitem><para>Вставить строку с датой/временем в указанном формате (задаётся параметром <userinput>format</userinput>), или в <quote>yyyy-MM-dd hh:mm:ss</quote>, если параметр упущен. Доступны следующие подстановки: <informaltable> <tgroup cols="2"> <tbody>
<row><entry><literal>d</literal></entry><entry>Номер дня в месяце без ведущего нуля (1-31).</entry></row>
<row><entry><literal>dd</literal></entry><entry>Номер дня в месяце с ведущим нулём (01-31).</entry></row>
<row><entry><literal>ddd</literal></entry><entry>Сокращённое название дня недели ('Пн'..''Вс, 'Mon'..'Sun').</entry></row>
<row><entry><literal>dddd</literal></entry><entry>Полное названия дня недели ('Понедельник'..'Воскресенье', 'Monday'..'Sunday').</entry></row>
<row><entry><literal>M</literal></entry><entry>Номер месяца без ведущего нуля (1-12).</entry></row>
<row><entry><literal>MM</literal></entry><entry>Номер месяца с ведущим нулём (01-12).</entry></row>
<row><entry><literal>MMM</literal></entry><entry>Сокращённое название месяца ('Янв'..'Дек', 'Jan'..'Dec').</entry></row>
<row><entry><literal>yy</literal></entry><entry>Год двумя цифрами (00-99).</entry></row>
<row><entry><literal>yyyy</literal></entry><entry>Год четырьмя цифрами (1752-8000).</entry></row>
<row><entry><literal>h</literal></entry><entry>Час без ведущего нуля (0..23 или 1..12, в зависимости от настроек).</entry></row>
<row><entry><literal>hh</literal></entry><entry>Час с ведущим нулём (00..23 or 01..12, в зависимости от настроек).</entry></row>
<row><entry><literal>m</literal></entry><entry>Минуты без ведущего нуля (0..59).</entry></row>
<row><entry><literal>mm</literal></entry><entry>Минуты с ведущим нулём (00..59).</entry></row>
<row><entry><literal>s</literal></entry><entry>Секунды без ведущего нуля (0..59).</entry></row>
<row><entry><literal>ss</literal></entry><entry>Секунды с ведущим нулём (00..59).</entry></row>
<row><entry><literal>z</literal></entry><entry>Миллисекунды без ведущих нулей (0..999).</entry></row>
<row><entry><literal>zzz</literal></entry><entry>Миллисекунды с ведущими нулями (000..999).</entry></row>
<row><entry><literal>AP</literal></entry><entry>Использовать 12-часовый формат часов. AP будет заменено на "AM" или "PM".</entry></row>
<row><entry><literal>ap</literal></entry><entry>Использовать 12-часовый формат часов. ap будет заменено на "am" или "pm".</entry></row>

</tbody>
</tgroup>
</informaltable>

</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>char</command><arg>identifier</arg></cmdsynopsis></term>
<listitem>
<para>Эта команда позволяет вставить символ по его числовому идентификатору в десятичной, восьмеричной или шестнадцатеричной системах счисления. Чтобы использовать её, откройте диалоговое окно "Команда правки" и наберите <userinput>char: [number]</userinput> в строке ввода, после чего нажмите кнопку <guibutton>OK</guibutton>.</para>

<example>
<title>Примеры использования команды <command>char</command></title>

<para>Введите: <userinput>char:234</userinput></para>
<para>Получите: <computeroutput>&#234;</computeroutput></para>
<para>Введите: <userinput>char:0x1234</userinput></para>
<para>Получите: <computeroutput>&#x1234;</computeroutput></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term>
<indexterm><primary>замена в стиле sed</primary>
<secondary>поиск в стиле sed</secondary></indexterm>
<command>s///[ig]</command> <command>%s///[ig]</command></term>

<listitem>
<para>"Типичный пользователь" при виде этих команд обязательно вздрогнет и начнёт искать на клавиатуре кнопку "Windows". В самом деле, кому придёт в голову искать текст подобным образом? Но вы же не "типичный", не так ли? Поэтому попробуем разобраться в этих двух sed-подобных командах. Первая выполняет поиск/замену в текущей строке, вторая -- во всём файле (<command>%s///</command>).</para>

<para>Вкратце, команды производят поиск текста, заданного <emphasis>маской поиска</emphasis> -- регулярным выражением (regexp) между первой и второй наклонной чертой, и, при нахождении, выполняет замену выражением, которое задано между второй и третьей чертой. Круглые скобки в маске поиска позволяют задать подстроки в найденном тексте, на которые можно потом ссылаться в выражении замены. Обратная ссылка -- это регулярное выражение, которое при совпадении заменяется на фактический текст и может быть использовано в шаблоне замены. Для этого, в нужном месте поставьте обратную черту, а за ней номер подстроки по порядку (<userinput>\1</userinput> -- для первой пары скобок, <userinput>\2</userinput> -- для второй, и т. д.).</para>

<para>Чтобы искать сами скобки <literal>(</literal> или <literal>)</literal>, нужно предварить их обратной чертой: <userinput>\(\)</userinput></para>

<para>Если в самом конце указать <userinput>i</userinput>, поиск будет проводиться с учётом регистра, а если <userinput>g</userinput> - будут заменены все вхождения текста, совпадающего с регулярным выражением, иначе - только первое.</para>

<example>

<title>Замена текста в текущей строке</title>

<para>Будучи противником принципа "разделяй и властвуй", вы решили откомпилировать свою программу. Но компилятор начал на вас ругаться: класс <classname>myClass</classname>, упомянутый в строке 3902, не определён.</para>

<para>&quot;Чёрт!&quot;, - думаете вы, -- &quot;да это же мой класс <classname>MyClass</classname>&quot;. Вы добираетесь до строки 3902 и, вместо того, чтобы пытаться искать слово в этой длинной строке (а кто сейчас укладывает каждую строчку кода в 60 символов?), вы запускаете диалоговое окно "Команда правки", вводите <userinput>s/myclass/MyClass/i</userinput>, жмёте <guibutton>OK</guibutton>, сохраняете и компилируйте -- успешно и без ошибок.</para>

</example>

<example>
<title>Замена текста во всём файле</title>

<para>Представьте себе, что у вас есть файл, в котором вы несколько раз упоминаете некоего человека по имени <quote>госпожа Иванова</quote>. Но вдруг вам сообщают, что эта самая госпожа Иванова вчера вышла замуж за господина с редкой фамилией <quote>Петров</quote>. Естественно, вам нужно заменить все упоминания о госпоже Ивановой на текст <quote>госпожа Петрова</quote>.</para>

<para>Вызовите командную строку и введите следующий текст: <userinput>%s/госпожа Иванова/госпожа Петрова/</userinput> -- и ваша работа сделана.</para>

</example>

<example>
<title>Более сложный пример</title>

<para>Этот пример показывает, как пользоваться <emphasis>обратными ссылками</emphasis> и <emphasis>классами символов</emphasis> (если вы не знаете, что это такое, советуем ознакомиться с приведенными ниже разделами).</para>

<para>Допустим, у вас набрана такая строка: <programlisting>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para>Теперь вы думаете, что это недостаточно "красивый" код, и решаете, что вам нужно использовать ключевое слово <constant>const</constant> с параметрами, передаваемыми по ссылке (теми, перед которыми стоит амперсанд). Вы также хотите удалить лишние пробелы.</para>

<para>Запустите диалоговое окно "Команда правки" и наберите: <userinput>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput>, и не забудьте нажать кнопку <guibutton>OK</guibutton> -- иначе ничего не выйдет. Символ <userinput>g</userinput> в конце команды указывает компилятору "пересчитывать" регулярное выражение обратной ссылки каждый раз, когда встречаются совпадения.</para>

<para>Вывод: <computeroutput>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar String *p, const int &amp;a, const int &amp;b )</computeroutput></para>

<para>Миссия завершена! Ну, и что же произошло? Мы искали некоторое количество пробелов (<literal>\s+</literal>), за которыми идут несколько латинских символов (<literal>\w+</literal>), следом за ними опять несколько пробелов (<literal>\s+</literal>), после которых стоит амперсанд, и по ходу дела сохраняли эти алфавитные символы и амперсанд для использования их в операции замены. После этого мы заменили совпадающие части строки следующей последовательностью: один пробел, за которым идёт спецификатор <quote>const</quote>, за ним ещё один пробел, после которого наши сохранённые символы (<literal>\1</literal>), ещё один пробел и сохранённый амперсанд (<literal>\2</literal>)</para>

<para>В одном случае латинские символы составили слово <quote>String</quote>, в другом -- слово <quote>int</quote>, т.е. символьный класс <literal>\w</literal> с последующим знаком <literal>+</literal> определяет символьный набор произвольной длины.</para>

</example>

</listitem>

</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-navigation">
<title>Команды навигации</title>

<variablelist>

<varlistentry>
<term><cmdsynopsis><command>goto</command><arg>INT line</arg></cmdsynopsis></term>
<listitem><para>Перейти к указанной строке.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>find</command><arg>pattern</arg></cmdsynopsis></term>
<listitem><para>Перейти к первому образцу, заданному параметром <userinput>pattern</userinput>. Последующие вхождения образца можно найти посредством пункта меню <menuchoice><guimenu>Правка</guimenu><guimenuitem>Найти далее</guimenuitem></menuchoice> (клавиша по умолчанию - <keycap>F3</keycap>).</para>
<para>Параметры команды поиска можно задавать добавлением двоеточия и "флагов" после её имени (<userinput>find:options pattern</userinput>). Флаги - набор из следующих букв: <variablelist>

<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Искать в обратном направлении.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Искать от позиции курсора.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Искать только в выделенном тексте.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Аргумент <userinput>pattern</userinput> - регулярное выражение. Вы можете использовать <userinput>\N</userinput> в <userinput>replacement</userinput> для получения N-ной подстроки найденного текста.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>С учётом регистра.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Только целые слова.</para></listitem>
</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term>
<listitem><para>Поиск по мере набора. Поддерживается установка дополнительных флагов <variablelist>
<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Искать в обратном направлении.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Поиск по регулярному выражению.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>С учётом регистра.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Искать от позиции курсора.</para></listitem>
</varlistentry>

</variablelist>
</para></listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

</sect1>

<sect1 id="advanced-editing-tools-code-folding">
<title>Использование сворачивания кода</title>

<para>Сворачивание кода позволяет скрывать участки документа в редакторе, упрощая осмотр громоздких документов. В &kate; разделение на сворачиваемые участки определяется правилами подсветки синтаксиса, следовательно, доступно не для всех форматов файлов. В основном, сворачивание кода доступно в режиме написания исходного кода, XML-разметки и т.п. Большинство способов подсветки позволяют также самостоятельно определять скрываемые области, чаще всего используя ключевые слова <userinput>BEGIN</userinput> и <userinput>END</userinput>.</para>

<para>Для того чтобы включить/отключить функцию сворачивания, выберите пункт меню <menuchoice><guimenu>Вид</guimenu><guimenuitem>Показать маркеры сворачивания</guimenuitem></menuchoice>. На панели маркеров сворачивания с левой стороны документа появится графическое представление сворачиваемых участков. Знак "-" показывает, что участок развёрнут, знак "+" обозначает свёрнутый участок. Щелчок на знаке "+" приведёт к разворачиванию свёрнутого участка, и наоборот (с одновременным изменением графического представления).</para>

<para>Для управления состоянием сворачиваемых участков служат четыре команды, смотрите <link linkend="view-code-folding">справку по меню</link>. </para>

<para>Если вы не хотите использовать функцию сворачивания, можно отключить параметр <guilabel>Показать маркеры сворачивания (если доступны)</guilabel> на <link linkend="config-dialog-editor-appearance">странице настройки внешнего вида редактора</link></para>

</sect1>

<sect1 id="advanced-editing-tools-scripting">

<title>Написание сценариев Javascript в компоненте редактора</title>

<sect2 id="advanced-editing-tools-scripting-introduction">

<title>Введение</title>

<para>Начиная с версии 2.5, компонент редактора &kate; поддерживает написание сценариев на языке ECMA, известном также как JavaScript.</para>

<para>Сценарии можно вызывать только из <link linkend="advanced-editing-tools-commandline">встроенной командной строки</link>. При этом необходимо, чтобы сценарий и файл .desktop (если он существует) находились в той папке, в которой &kate; сможет их разыскать. Подходящая папка для этого - <filename>katepart/scripts</filename> в папках данных &kde;. Найти папки данных можно командой <command>tde-config <option>--path</option> <parameter>data</parameter></command>. Как правило, существуют системная и пользовательские папки данных. Естественно, сценарии в системных папках доступны всем пользователям системы, а в пользовательских - только их владельцам.</para>

<note><para>Эта функциональность находится на экспериментальной стадии разработки, весьма вероятно его изменение в дальнейшем.</para>
<para>Сценарии нельзя добавлять в меню или назначать им комбинации клавиш. Может быть, в дальнейшем мы сможем это исправить.</para>
<para>Также невозможно использовать в сценариях аргументы. Потерпите, в светлом будущем это вполне может произойти ;)</para>
</note>

</sect2>

<sect2 id="advanced-editing-tools-scripting-reference">

<title>Программный интерфейс (API) Kate JavaScript</title>

<para>Здесь приведен полный список функций и свойств, доступных для объектов <type>document</type> и <type>view</type>. Разумеется, доступны любые стандартные объекты языка, такие как <type>Math</type>, <type>String</type>, <type>Regex</type> и т.д.</para>

<para>Во время исполнения сценария, объектом <classname>document</classname> является текущий документ, а объектом <classname>view</classname> является текущий вид (панель).</para>

<note><para>Конечно, в настоящее время типы аргументов в JavaScript не используются, они просто информируют, какие виды значений ожидаются функциями.</para></note>

<variablelist id="advanced-editing-tools-scripting-global">
<title>Глобальные функции</title>
<varlistentry>
<term><function>debug( <parameter><replaceable>string</replaceable></parameter>) [функция]</function></term>
<listitem>
<itemizedlist>
<title>параметры</title>
<listitem><para><parameter>string</parameter> выводимая строка</para>
</listitem>
</itemizedlist>
<para>Выводит строку на стандартный поток ошибок, используя функцию <function>kDebug()</function>. Для вывода используется выделенное пространство, в начало может быть добавлен префикс <computeroutput>Kate (KJS Scripts):</computeroutput> </para>
</listitem>
</varlistentry>
</variablelist>

<variablelist id="advanced-editing-tools-scripting-document">
<title>Программный интерфейс (API) класса <classname>document</classname></title>

<varlistentry>
<term><function>document.attribute( <parameter><replaceable>line</replaceable> </parameter>, <parameter><replaceable>column</replaceable></parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>uint line</parameter> Строка, в которой находится атрибут.</para></listitem>
<listitem><para><parameter>uint column</parameter> Столбец, в котором находится атрибут.</para></listitem>
</itemizedlist>
<para>Возвращает числовые значения позиции атрибута в документе [<parameter>line</parameter>,<parameter>column</parameter>]. Атрибут представляет собой вид или стиль текста, а также используется для определения подсветки синтаксиса в различных частях текста смешанных форматов вроде HTML или PHP.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.canBreakAt( <parameter>Char c</parameter>, <parameter>uint attribute</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>c</parameter> Знак для проверки</para></listitem>
<listitem><para><parameter>attribute</parameter> Атрибут для позиции <parameter>c</parameter>.</para></listitem>
</itemizedlist>
<para> Возвращает допустимость разрыва строки на знаке c с атрибутом attribute. Результат зависит от того, какие атрибуты допускают разрыв строки без потери принадлежности подсветки.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.canComment( <parameter>uint start_attribute</parameter>, <parameter>uint end_attribute</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>start_attribute</parameter> Атрибут начала участка комментария.</para></listitem>
<listitem><para><parameter>end_attribute</parameter> Атрибут конца участка комментария.</para></listitem>
</itemizedlist>
<para>Возвращает принадлежность start_attribute и end_attribute к одной и той же системе подсветки синтаксиса. Если это так - всё нормально. </para>
<example>
<title>использование canComment</title>
<programlisting>if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
    // 1,0 и 5,0 принадлежат к одной системе подсветки синтаксиса
}
</programlisting>
</example>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.clear(); [функция]</function></term>
<listitem><para>Очищает документ.</para></listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentStart( <parameter>uint attribute</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>attribute</parameter> Атрибут текста, для которого вводится строка commentStart.</para></listitem>
</itemizedlist>
<para>Возвращает строку, необходимую для начала многострочного комментария к тексту с атрибутом, или пустую строку, если в этом тексте не поддерживаются многострочные комментарии.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentMarker( <parameter>uint attribute</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>attribute</parameter> Атрибут текста, для которого вводится строка commentMarker</para></listitem>
</itemizedlist>
<para>Возвращает пометку остатка строки как комментария к тексту с атрибутом, либо пустую строку для текста, в котором не поддерживаются комментарии в той же строке.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentEnd( <parameter>uint attribute</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>attribute</parameter> Атрибут текста, для которого вводится строка commentEnd</para></listitem>
</itemizedlist>
<para>Возвращает строку, необходимую для окончания многострочного комментария к тексту с атрибутом, либо пустую строку для текста, в котором многострочные комментарии не поддерживаются.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.editBegin(); [функция]</function></term>
<listitem>
<para>Начало группы редактирования. Все действия включаются в одну группу отмены до вызова editEnd().</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.editEnd(); [функция]</function></term>
<listitem>
<para>Окончание группы редактирования.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.highlightMode; [свойство:только для чтения]</function></term>
<listitem>
<para>Название режима подсветки (JavaScript или C++). Если к документу не применяется режим подсветки, устанавливается значение None. Помните - необходимо использовать англоязычное название.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.indentMode; [свойство:только для чтения]</function></term>
<listitem>
<para>Название режима отступов документа, такое как <literal>normal</literal> или <literal>cstyle</literal>. Помните - если режим отступов не задан, устанавливается значение <literal>none</literal>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.indentWidth; [свойство:только для чтения]</function></term>
<listitem>
<para>Устанавливает ширину отступа. Только при создании отступов пробелами.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.insertLine( <parameter>uint line</parameter>, <parameter>string text</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> номер строки в документе</para>
</listitem>
<listitem><para><parameter>text</parameter> вставляемый текст</para></listitem>
</itemizedlist>
<para>Вставляет новую строку с текстом <parameter>text</parameter> в строку под номером <parameter>line</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.insertText( <parameter>uint line</parameter>, <parameter>uint column</parameter>, <parameter>string text</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> номер строки</para></listitem>
<listitem><para><parameter>column</parameter> номер столбца</para></listitem>
<listitem><para><parameter>text</parameter> вставляемый текст</para></listitem>
</itemizedlist>
<para>Вставляет текст <parameter>text</parameter> в строку номер <parameter>line</parameter>, столбец номер <parameter>column</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.length(); [функция]</term>
<listitem>
<para>Возвращает размер документа в байтах.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.lines(); [функция]</function></term>
<listitem>
<para>Возвращает число строк в документе.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.mixedIndent; [свойство:только для чтения]</term>
<listitem>
<para>Логическая величина. Сообщает, применяется ли в документе смешанный тип отступов. Если это так - отступы осуществляются при помощи и пробелов, и позиций табуляции, сходно с редактором Emacs.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.removeLine( <parameter>uint line</parameter> ); [функция]</term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> номер строки</para></listitem>
</itemizedlist>
<para>Удаляет строку документа номер line.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.removeText( <parameter>uint startLine</parameter>, <parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, <parameter>uint endColumn</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>startLine</parameter> указывает начальную строку</para></listitem>
<listitem><para><parameter>startColumn</parameter> указывает начальный столбец</para></listitem>
<listitem><para><parameter>endLine</parameter> указывает конечную строку</para></listitem>
<listitem><para><parameter>endColumn</parameter> указывает конечный столбец</para></listitem>
</itemizedlist>
<para>Удаляет участок текста, начиная от строки номер <parameter>startLine</parameter> и столбца номер <parameter>startColumn</parameter> до строки номер <parameter>endLine</parameter> и столбца номер <parameter>endColumn</parameter>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.setText( <parameter>string text</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>text</parameter> текст документа</para></listitem>
</itemizedlist>
<para>Приводит всё содержимое документа к тексту с параметрами <parameter>text</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.spaceIndent; [свойство:только для чтения]</function></term>
<listitem>
<para>Логическая величина. Сообщает, применяется ли к документу отступ пробелами. Если это так, то отступы в документе производятся на величину indentWidth между уровнями, иначе сдвиг происходит на одну позицию табуляции.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textFull(); [функция]</function></term>
<listitem>
<para>Возвращает весь текст документа. Если в тексте есть переводы строк, то знак перевода строки отобразится как <constant>\n</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textLine( uint line ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> строка номер</para></listitem>
</itemizedlist>
<para>Возвращает текст строки номер <parameter>line</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textRange( <parameter>uint startLine</parameter>, <parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, <parameter>uint endColumn</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>startLine</parameter> указывает начальную строку</para></listitem>
<listitem><para><parameter>startColumn</parameter> указывает начальный столбец</para></listitem>
<listitem><para><parameter>endLine</parameter> указывает конечную строку</para>
</listitem>
<listitem><para><parameter>endColumn</parameter> указывает конечный столбец</para></listitem>
</itemizedlist>
<para>Возвращает указанный участок текста. Если в пределах участка есть переводы строк, то знак перевода отобразится как <constant>\n</constant>.</para>
</listitem>
</varlistentry>

</variablelist><!--/ document API -->

<variablelist id="advanced-editing-tools-scripting-view">
<title>Аппаратно-программный интерфейс (API) <classname>view</classname></title>

<varlistentry>
<term><function>view.clearSelection(); [функция]</function></term>
<listitem>
<para>Снимает выделение со всего текста.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorColumn(); [функция]</function></term>
<listitem>
<para>Возвращает столбец, в котором находится курсор (учитываются все знаки табуляции).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorColumnReal(); [функция]</function></term>
<listitem>
<para>Возвращает номер столбца, в котором реально находится курсор (знак табуляции считается за один символ).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorLine(); [функция]</function></term>
<listitem>
<para>Возвращает номер строки, в которой находится курсор.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.hasSelection(); [функция]</function></term>
<listitem>
<para>Если выделенный текст есть, возвращает <constant>true</constant>, иначе <constant>false</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.removeSelectedText(); [функция]</function></term>
<listitem>
<para>Если есть выделенный текст, он удаляется.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectAll(); [функция]</function></term>
<listitem>
<para>Выделяет весь текст.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selection(); [функция]</function></term>
<listitem>
<para>Возвращает выделенный текст. Если в пределах выделенного текста есть переводы строк, они отображаются знаком <constant>\n</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionEndColumn; [свойство:только для чтения]</function></term>
<listitem>
<para>Возвращает номер последней позиции выделяемого участка.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionEndLine; [свойство:только для чтения]</function></term>
<listitem>
<para>Возвращает номер последней строки выделяемого участка.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionStartColumn; [свойство:только для чтения]</function></term>
<listitem>
<para>Возвращает номер начальной позиции выделяемого участка.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionStartLine; [свойство:только для чтения]</function></term>
<listitem>
<para>Возвращает номер начальной строки выделяемого участка.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setCursorPosition( <parameter>uint line</parameter>, <parameter>uint column</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> Указывает строку для курсора.</para></listitem>
<listitem><para><parameter>column</parameter> Указывает столбец для курсора.</para></listitem>
</itemizedlist>
<para>Устанавливает курсор ввода в позицию [<parameter>line</parameter>, <parameter>col</parameter>]. Установка курсора происходит визуально, символ табуляции считается за несколько символов, в зависимости от расположения текста, но не больше значения параметра <guilabel>Ширина табуляции</guilabel>. Отсчёт номеров строк и столбцов начинается от нуля.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setCursorPositionReal( <parameter>uint line</parameter>, <parameter>uint column</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>line</parameter> Указывает строку для курсора.</para></listitem>
<listitem><para><parameter>column</parameter> Указывает столбец для курсора.</para></listitem>
</itemizedlist>
<para>Устанавливает курсор в позицию [<parameter>line</parameter>, <parameter>col</parameter>]. При рассчёте позиции табуляция соответствует одному символу. Отсчёт строк и столбцов начинается от нуля.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setSelection( <parameter>uint startLine</parameter>, <parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, <parameter>uint endColumn</parameter> ); [функция]</function></term>
<listitem>
<itemizedlist>
<title>Параметры</title>
<listitem><para><parameter>startLine</parameter> указывает начальную строку</para></listitem>
<listitem><para><parameter>startColumn</parameter> указывает начальный столбец</para></listitem>
<listitem><para><parameter>endLine</parameter> указывает конечную строку</para></listitem>
<listitem><para><parameter>endColumn</parameter> указывает конечный столбец</para></listitem>
</itemizedlist>
<para>Устанавливает выделение от строки номер <parameter>startLine</parameter> и столбца номер <parameter>startColumn</parameter> до строки номер <parameter>endLine</parameter> и столбца номер <parameter>endColumn</parameter>.</para>
</listitem>
</varlistentry>

</variablelist>

<example id="advanced-editing-tools-scripting-example">

<title>Пример сценария</title>
<para>В качестве примера рассмотрим небольшой сценарий, переводящий выделенный текст в верхний регистр. Очевидно, сначала необходимо проверить, есть ли выделенный текст вообще. Если есть - возьмём этот текст, изменим регистр и заменим его новым текстом. Сценарий будет выглядеть примерно так:</para>

<programlisting>if ( view.hasSelection() )
{
  column = view.selectionStartColumn;
  line = view.selectionStartLine;

  selection = view.selection().toUpperCase();

  document.editBegin();
  view.removeSelectedText();
  document.insertText( line, column, selection );
  document.editEnd();
}
</programlisting>

<para>Для группировки действий так, чтобы их можно было отменить одним вызовом пункта меню <guimenuitem>Отмена</guimenuitem>, мы поместили строки <programlisting>view.removeSelectedText()</programlisting> и <programlisting>document.insertText()</programlisting> между <programlisting>document.editBegin()</programlisting> и <programlisting>document.editEnd()</programlisting>.</para>

</example>

<example id="advanced-editing-tools-desktop-example">
<title>Пример файла <filename>.desktop</filename></title>

<para>Вот пример простого .desktop-файла, соответствующего приведенному выше сценарию.</para>

<programlisting>[Desktop Entry]
Encoding=UTF-8
Name=Kate Part JavaScript Uppercase
Comment=Script to uppercase the selection
X-Kate-Command=uppercase-selection
X-Kate-Help=&lt;p&gt;Usage: &lt;code&gt;uppercase-selection&lt;/code&gt;&lt;/p&gt;
</programlisting>

<para>Мы видим, что здесь можно определить кодировку, ввести название, комментарий, указать путь к справке с помощью X-Kate-Help и название для командной строки через X-Kate-Command. Если файлы находятся в SVN-хранилище KDE, то пункты Name, Comment and X-Kate-Help автоматически переводятся на другие языки командами переводчиков KDE.</para>

</example>

<sect3>
<title>Резюме</title>

<para>&kate; может разыскивать в определённых папках (см. <link linkend="advanced-editing-tools-scripting-introduction">выше</link>) файлы <filename>*.js</filename>. Для каждого найденного файла будет проведен поиск соответствующего файла <filename>.desktop</filename>, например файлу uppercase.js соответствует файл uppercase.desktop. </para>
<para>Если требуемый файл <filename>.desktop</filename> не найден, сценарий будет зарегистрирован в командной строке katepart с именем без расширения .js, для нашего примера это будет <literal>uppercase</literal>.Если такое формирование названия команды подходит, и вам не требуются какие-то дополнительные возможности, которые предоставляет файл <filename>.desktop</filename>, он может не понадобиться вам совсем. </para>
<para>Если файл <filename>.desktop</filename> найден, то katepart считывает имя из пункта .desktop-файла X-Kate-Command, например X-Kate-Command=uppercase-selection.</para>

</sect3>

</sect2>

</sect1>

</chapter>