tde-i18n/tde-i18n-nl/docs/tdebase/kate/advanced.docbook

<chapter id="advanced-editing-tools">
<title>Advanced Editing Tools</title>

<sect1 id="comment">

<title>Comment/Uncomment</title>

<para>The Comment and Uncomment commands, available from the
<guimenu>Tools</guimenu> menu allow you to add or remove comment
markers to the selection, or the current line if no text is selected,
it comments are supported by the format of the text you are
editing.</para>

<para>The rules for how commenting is done are defined in the syntax
definitions, so if syntax highlighting is not used,
commenting/uncommenting is not possible.</para>

<para>Some formats define single line comment markers, some multi line
markers and some both.  If multi line markers are not available,
commenting out a selection that does not fully include its last line
is not possible.</para>

<para>If a single line marker is available, commenting single lines is
preferred where applicable, as this helps to avoid problems with
nested comments.</para>

<para>When removing comment markers, no uncommented text should be
selected. When removing multiline comment markers from a selection,
any whitespace outside the comment markers is ignored.</para>

<para>To place comment markers, use the
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice>
menu item or the related keyboard shortcut sequence, default is
<keycombo action="simul">&Ctrl;<keycap>#</keycap></keycombo>.</para>

<para>To remove comment markers, use the
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>
menu item or the related keyboard shortcut, default is <keycombo
action="simul">&Ctrl;&Shift;<keycap>#</keycap></keycombo>.</para>

</sect1>

<sect1 id="edit-command">

<title>Editing Command</title>

<para>This tool, available from the
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Editing
Command</guimenuitem></menuchoice> menu item, provides access to a
small set of
<application>vi</application>/<application>vim</application>-like
commands for editing the text. It is a no nonsense tool for advanced
or experienced users, but do not let that hold you back from
experiencing its powers!</para>

<para>Currently, the following commands are available:</para>

<variablelist>
<varlistentry>
<term><command>time</command></term>

<listitem>
<para>This command will output the current time as known by your
computer in the format <quote>HH:MM:SS</quote></para>

<para>To use it, launch the Editing Command Dialog and type into the
input box the word <userinput>time</userinput></para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>char</command></term>
<listitem>
<para>This command allows you to insert literal characters by their
numerical identifier, in decimal, octal or hexadecimal form.
To use it launch the Editing Command dialog and type <userinput>char:
[number]</userinput> in the entry box, then hit
<guibutton>OK</guibutton>.</para> 

<example>
<title><command>char</command> examples</title>

<para>Input: <userinput>char:234</userinput></para>
<para>Output: <computeroutput>ê</computeroutput></para>
<para>Input: <userinput>char:0x1234</userinput></para>
<para>Output: <computeroutput>ê</computeroutput></para>
<para>Input: <userinput>char:1232</userinput></para>
<para>Output: <computeroutput>ê</computeroutput></para>
</example>

</listitem>

</varlistentry>

<varlistentry>

<term><command>s///[ig]</command> <command>%s///[ig]</command></term>

<listitem>
<para>This command does a sed-like search/replace operation on the
current line, or on the whole file (<command>%s///</command>).</para>

<para>In short, the text is searched for text matching the
<emphasis>search pattern</emphasis>, the regular expression between
the first and the second slash, and when a match is found, the
matching part of the text is replaced with the expression between the
middle and last part of the string. Parentheses in the search pattern
create <emphasis>back references</emphasis>, that is the command
remembers which part of the match matched in the parentheses; these
strings can be reused in the replace pattern, referred to as
<userinput>\1</userinput> for the first set of parentheses,
<userinput>\2</userinput> for the second and so on.</para>

<para>To search for a literal <literal>(</literal> or
<literal>)</literal>, you need to <emphasis>escape</emphasis> it using
a backslash character: <userinput>\(\)</userinput></para>

<para>If you put an <userinput>i</userinput> at the end of the
expression, the matching will be case insensitive.</para>

<example>

<title>Replacing text in the current line</title>

<para>Your friendly compiler just stopped, telling you that the class
<classname>myClass</classname> mentioned in line 3902 in your source file
is not defined.</para>

<para>&quot;Buckle!&quot; you think, it is of course
<classname>MyClass</classname>. You go to line 3902, and instead of trying
to find the word in the text, you launch the Editing Command Dialog,
enter <userinput>s/myclass/MyClass/i</userinput>, hit the
<guibutton>OK</guibutton> button, save the file and compile &ndash;
successfully without the error.</para>

</example>

<example>
<title>Replacing text in the whole file</title>

<para>Imagine that you have a file, in which you mention a <quote>Miss
Jensen</quote> several times, when someone comes in and tells you that
she just got married to <quote>Mr Jones</quote>. You want, of course,
to replace each and every occurrence of <quote>Miss Jensen</quote>
with <quote>Ms Jones</quote>.</para>

<para>Launch the Editing Command dialog, and type into the entry box:
<userinput>%s/Miss Jensen/Ms Jones/</userinput> and hit return, you
are done.</para>

</example>

<example>
<title>A More Advanced Example</title>

<para>This example makes use of <emphasis>back references</emphasis>
as well as a <emphasis>word class</emphasis> (if you do not know what
that is, please refer to the related documentation mentioned
below).</para>

<para>Suppose you have the following line:

<programlisting>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para>Now you realize that this is not nice code, and decide that you
want to use the <constant>const</constant> keyword for all
<quote>address of</quote> arguments, those characterized by the &amp;
operator in front of the argument name. You would also like to
simplify the white space, so that there is only 1 whitespace character
between each word.</para>

<para>Launch the Editing Command Dialog, and enter:
<userinput>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput> and hit the
<guibutton>OK</guibutton> button. The <userinput>g</userinput> at the end of the expression makes
the regular expression recompile for each match to save the <emphasis>backreferences</emphasis>.</para>

<para>Output:

<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>Mission completed! Now, what happened? Well, we looked for some
white space (<literal>\s+</literal>) followed by one or more
alphabetic characters (<literal>\w+</literal>) followed by some more
whitespace (<literal>\s+</literal>) followed by an ampersand, and in
the process saved the alphabetic chunk and the ampersand for reuse in
the replace operation. Then we replaced the matching part of our line
with one whitespace followed by <quote>const</quote> followed by one
whitespace followed by our saved alphabetical chunk
(<literal>\1</literal>) followed by one whitespace followed by our
saved ampersand (<literal>\2</literal>)</para>

<para>Now in some cases the alphabetical chunk was
<quote>String</quote>, in some <quote>int</quote>, so using the
character class <literal>\w</literal> and the <literal>+</literal>
quantifier proved a valuable asset.</para>

</example>

</listitem>
</varlistentry>

</variablelist>

<warning>
<para>This is extremely powerful, and though the actions can be undone
by calling the
<menuchoice><guimenuitem>Undo</guimenuitem></menuchoice> command
several times (as required) I recommend you practice a bit before
using this command for serious editing if you are not familiar with
<application>sed</application> or perl regular expressions.</para>
</warning>

</sect1>

</chapter>