<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>
<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>
<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>
<para>Установленные таким способом параметры применяются только к текущему экземпляру редактора и не сохраняются. Удобно, если нужно установить параметры, отличные от стандартных (например, отступ). </para>
<listitem><para>Используется для команд включения/выключения. Допустимые значения - <userinput>on</userinput>, <userinput>off</userinput>, <userinput>true</userinput>, <userinput>false</userinput>, <userinput>1</userinput> или <userinput>0</userinput></para></listitem>
<listitem><para>Использовать для отступов как символы табуляции, так и пробелы. Это реализуется путём замены пробелов в количестве, кратном ширине символа табуляциями, на последние.</para>
<para>Эта команда также включит расстановку отступов пробелами, и установит ширину отступов, если она не указана, в половину значения <option>tab-width</option> (для текущего документа на время выполнения).</para></listitem>
<listitem><para>Выбрать режим расстановки отступов. Параметр <userinput>name</userinput> может иметь следующие значения: 'cstyle', 'csands', 'xml', 'python', 'varindent' и 'none'. При других значениях используется 'none'.</para></listitem>
<listitem><para>Выбрать формат для подсветки, один из содержащихся в подменю<menuchoice><guimenu>Сервис</guimenu><guisubmenu>Подсветка синтаксиса</guisubmenu></menuchoice>. Доступно также автозавершение параметра.</para></listitem>
<listitem><para>Очистить отступы в выделенных строках или в текущей в соответствии с параметрами расстановки отступов для текущего документа. </para></listitem>
<listitem><para>Вставляет маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла (определяется способом подсветки синтаксиса).</para></listitem>
<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>
<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>
<para>Эта команда позволяет вставить символ по его числовому идентификатору в десятичной, восьмеричной или шестнадцатеричной системах счисления. Чтобы использовать её, откройте диалоговое окно "Команда правки" и наберите <userinput>char: [number]</userinput> в строке ввода, после чего нажмите кнопку <guibutton>OK</guibutton>.</para>
<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>
<para>Будучи противником принципа "разделяй и властвуй", вы решили откомпилировать свою программу. Но компилятор начал на вас ругаться: класс <classname>myClass</classname>, упомянутый в строке 3902, не определён.</para>
<para>"Чёрт!", - думаете вы, -- "да это же мой класс <classname>MyClass</classname>". Вы добираетесь до строки 3902 и, вместо того, чтобы пытаться искать слово в этой длинной строке (а кто сейчас укладывает каждую строчку кода в 60 символов?), вы запускаете диалоговое окно "Команда правки", вводите <userinput>s/myclass/MyClass/i</userinput>, жмёте <guibutton>OK</guibutton>, сохраняете и компилируйте -- успешно и без ошибок.</para>
<para>Представьте себе, что у вас есть файл, в котором вы несколько раз упоминаете некоего человека по имени <quote>госпожа Иванова</quote>. Но вдруг вам сообщают, что эта самая госпожа Иванова вчера вышла замуж за господина с редкой фамилией <quote>Петров</quote>. Естественно, вам нужно заменить все упоминания о госпоже Ивановой на текст <quote>госпожа Петрова</quote>.</para>
<para>Вызовите командную строку и введите следующий текст: <userinput>%s/госпожа Иванова/госпожа Петрова/</userinput> -- и ваша работа сделана.</para>
<para>Этот пример показывает, как пользоваться <emphasis>обратными ссылками</emphasis> и <emphasis>классами символов</emphasis> (если вы не знаете, что это такое, советуем ознакомиться с приведенными ниже разделами).</para>
<para>Допустим, у вас набрана такая строка: <programlisting>void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b )</programlisting>
<para>Теперь вы думаете, что это недостаточно "красивый" код, и решаете, что вам нужно использовать ключевое слово <constant>const</constant> с параметрами, передаваемыми по ссылке (теми, перед которыми стоит амперсанд). Вы также хотите удалить лишние пробелы.</para>
<para>Запустите диалоговое окно "Команда правки" и наберите: <userinput>s/\s+(\w+)\s+(&)/ const \1 \2/g</userinput>, и не забудьте нажать кнопку <guibutton>OK</guibutton> -- иначе ничего не выйдет. Символ <userinput>g</userinput> в конце команды указывает компилятору "пересчитывать" регулярное выражение обратной ссылки каждый раз, когда встречаются совпадения.</para>
<para>Вывод: <computeroutput>void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &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>
<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>
<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>
<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>
<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>
<para>Выводит строку на стандартный поток ошибок, используя функцию <function>kDebug()</function>. Для вывода используется выделенное пространство, в начало может быть добавлен префикс <computeroutput>Kate (KJS Scripts):</computeroutput> </para>
<para>Возвращает числовые значения позиции атрибута в документе [<parameter>line</parameter>,<parameter>column</parameter>]. Атрибут представляет собой вид или стиль текста, а также используется для определения подсветки синтаксиса в различных частях текста смешанных форматов вроде HTML или PHP.</para>
<para> Возвращает допустимость разрыва строки на знаке c с атрибутом attribute. Результат зависит от того, какие атрибуты допускают разрыв строки без потери принадлежности подсветки.</para>
<para>Возвращает строку, необходимую для начала многострочного комментария к тексту с атрибутом, или пустую строку, если в этом тексте не поддерживаются многострочные комментарии.</para>
<para>Возвращает пометку остатка строки как комментария к тексту с атрибутом, либо пустую строку для текста, в котором не поддерживаются комментарии в той же строке.</para>
<para>Возвращает строку, необходимую для окончания многострочного комментария к тексту с атрибутом, либо пустую строку для текста, в котором многострочные комментарии не поддерживаются.</para>
<para>Название режима подсветки (JavaScript или C++). Если к документу не применяется режим подсветки, устанавливается значение None. Помните - необходимо использовать англоязычное название.</para>
<para>Название режима отступов документа, такое как <literal>normal</literal> или <literal>cstyle</literal>. Помните - если режим отступов не задан, устанавливается значение <literal>none</literal>. </para>
<para>Логическая величина. Сообщает, применяется ли в документе смешанный тип отступов. Если это так - отступы осуществляются при помощи и пробелов, и позиций табуляции, сходно с редактором Emacs.</para>
<para>Удаляет участок текста, начиная от строки номер <parameter>startLine</parameter> и столбца номер <parameter>startColumn</parameter> до строки номер <parameter>endLine</parameter> и столбца номер <parameter>endColumn</parameter>. </para>
<para>Логическая величина. Сообщает, применяется ли к документу отступ пробелами. Если это так, то отступы в документе производятся на величину indentWidth между уровнями, иначе сдвиг происходит на одну позицию табуляции.</para>
<para>Возвращает указанный участок текста. Если в пределах участка есть переводы строк, то знак перевода отобразится как <constant>\n</constant>.</para>
<para>Устанавливает курсор ввода в позицию [<parameter>line</parameter>, <parameter>col</parameter>]. Установка курсора происходит визуально, символ табуляции считается за несколько символов, в зависимости от расположения текста, но не больше значения параметра <guilabel>Ширина табуляции</guilabel>. Отсчёт номеров строк и столбцов начинается от нуля.</para>
<para>Устанавливает курсор в позицию [<parameter>line</parameter>, <parameter>col</parameter>]. При рассчёте позиции табуляция соответствует одному символу. Отсчёт строк и столбцов начинается от нуля.</para>
<para>Устанавливает выделение от строки номер <parameter>startLine</parameter> и столбца номер <parameter>startColumn</parameter> до строки номер <parameter>endLine</parameter> и столбца номер <parameter>endColumn</parameter>.</para>
<para>В качестве примера рассмотрим небольшой сценарий, переводящий выделенный текст в верхний регистр. Очевидно, сначала необходимо проверить, есть ли выделенный текст вообще. Если есть - возьмём этот текст, изменим регистр и заменим его новым текстом. Сценарий будет выглядеть примерно так:</para>
<para>Для группировки действий так, чтобы их можно было отменить одним вызовом пункта меню <guimenuitem>Отмена</guimenuitem>, мы поместили строки <programlisting>view.removeSelectedText()</programlisting> и <programlisting>document.insertText()</programlisting> между <programlisting>document.editBegin()</programlisting> и <programlisting>document.editEnd()</programlisting>.</para>
<para>Мы видим, что здесь можно определить кодировку, ввести название, комментарий, указать путь к справке с помощью X-Kate-Help и название для командной строки через X-Kate-Command. Если файлы находятся в SVN-хранилище KDE, то пункты Name, Comment and X-Kate-Help автоматически переводятся на другие языки командами переводчиков KDE.</para>
<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>
