path: root/tde-i18n-en_GB/docs/kdebase/kate/advanced.docbook

<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author
>&Anders.Lund; &Anders.Lund.mail;</author>
<othercredit role="translator"
><firstname
>Malcolm</firstname
><surname
>Hunter</surname
><affiliation
><address
><email
>[email protected]</email
></address
></affiliation
><contrib
>Conversion to British English</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<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
><indexterm
><primary
>comment</primary
></indexterm
> 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
><indexterm
><primary
>uncomment</primary
></indexterm
> 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 Dialogue 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 dialogue 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>
<indexterm
><primary
>replace, sed style</primary>
<secondary
>search, sed style</secondary
></indexterm>
<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 Dialogue, 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 dialogue, 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 realise 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 characterised 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 Dialogue, 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 practise 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>