summaryrefslogtreecommitdiffstats
path: root/doc/kate
diff options
context:
space:
mode:
authorMichele Calgaro <michele.calgaro@yahoo.it>2014-02-12 17:52:49 +0900
committerMichele Calgaro <michele.calgaro@yahoo.it>2014-02-12 17:52:49 +0900
commitba09c43f50c9191cd7a4a640b46a373eca475b24 (patch)
tree8f911367c120cb0dbcb66307a123d3aee25d5471 /doc/kate
parentaf72e1310c8339e27ff4dbd2acc30d73864e2c6e (diff)
downloadtdebase-ba09c43f50c9191cd7a4a640b46a373eca475b24.tar.gz
tdebase-ba09c43f50c9191cd7a4a640b46a373eca475b24.zip
Kate handbook review - chapter 4,5 additions, chapter 6
Diffstat (limited to 'doc/kate')
-rw-r--r--doc/kate/advanced.docbook503
-rw-r--r--doc/kate/configuring.docbook2
-rw-r--r--doc/kate/mdi.docbook82
-rw-r--r--doc/kate/part.docbook7
-rw-r--r--doc/kate/plugins.docbook9
5 files changed, 307 insertions, 296 deletions
diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook
index a5d5c789e..e0d552c80 100644
--- a/doc/kate/advanced.docbook
+++ b/doc/kate/advanced.docbook
@@ -3,6 +3,7 @@
<authorgroup>
<author>&Anders.Lund; &Anders.Lund.mail;</author>
<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
+<author>&tde-authors;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</chapterinfo>
@@ -14,8 +15,8 @@
<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,
-if comments are supported by the format of the text you are
+markers to the selection, or to the current line if no text is selected,
+if comments are supported by the format of the file you are
editing.</para>
<para>The rules for how commenting is done are defined in the syntax
@@ -56,23 +57,23 @@ action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para>
perform various actions from a minimal GUI. The command line is a text entry
in the bottom of the editor area, to show it select
<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice>
-or use the shortcut (default is
+or use the keyboard shortcut (default is
<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides
a set of commands as documented below, and additional commands can be provided
by plugins.</para>
-<para>To execute a command, type the comand then press the return key. The
-command line will indicate wether it succeded and possibly display a message. If
+<para>To execute a command, type the command and then press the enter key. The
+command line will indicate whether it succeeded and possibly display a message. If
you entered the command line by pressing <keycap>F7</keycap> it will
automatically hide after a few seconds. To clear the message and enter a new
command, press <keycap>F7</keycap> again.</para>
-<para>The command line has a built-in help system, issue the command
+<para>The command line has a built-in help system, you can type the command
<command>help</command> to get started. To see a list of all available commands
-issue <command>help list</command>, to view help for a specific command, do
+type <command>help list</command>, to view help for a specific command, do
<command>help <replaceable>command</replaceable></command>.</para>
-<para>The command line has a built in history, so you can reuse commands already
+<para>The command line has a built-in history too, so you can reuse commands already
typed. To navigate the history, use the <keycap>Up</keycap> and
<keycap>Down</keycap> keys. When showing historical commands, the argument part
of the command will be selected, allowing you to easily overwrite the
@@ -81,23 +82,15 @@ arguments.</para>
<sect2 id="advanced-editing-tools-commandline-commands">
<title>Standard Command Line Commands</title>
-<sect3 id="advanced-editing-tools-commandline-commands-configure">
-<title>Commands for Configuring the Editor</title>
-
-<para>These commands are provided by the editor component, and allows you to
-configure the active document and view only. This is handy if you want to use
-a setting different from the default settings, for example for indentation.
-</para>
-
<variablelist>
<title>Argument types</title>
<varlistentry>
<term>BOOLEAN</term>
-<listitem><para>This is used with commands that turns things on or off.
+<listitem><para>This is used with commands that turn things on or off.
Legal values are <userinput>on</userinput>, <userinput>off</userinput>,
<userinput>true</userinput>, <userinput>false</userinput>,
-<userinput>1</userinput> or <userinput>0</userinput></para></listitem>
+<userinput>1</userinput>, <userinput>0</userinput></para></listitem>
</varlistentry>
<varlistentry>
@@ -112,6 +105,14 @@ Legal values are <userinput>on</userinput>, <userinput>off</userinput>,
</variablelist>
+<sect3 id="advanced-editing-tools-commandline-commands-configure">
+<title>Commands for Configuring the Editor</title>
+
+<para>These commands are provided by the editor component, and allows you to
+configure the active document and view only. This is handy if you want to use
+a setting different from the default settings, for example for indentation.
+</para>
+
<variablelist>
<varlistentry>
@@ -195,7 +196,7 @@ enable</arg></cmdsynopsis></term>
<varlistentry>
<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable
</arg></cmdsynopsis></term>
-<listitem><para>When enabled, tabs will be replaced with whitespace whenever
+<listitem><para>When enabled, tabs will be replaced with whitespaces whenever
the document is saved.</para></listitem>
</varlistentry>
@@ -390,26 +391,26 @@ To use it launch the Editing Command dialog and type <userinput>char:
<term>
<indexterm><primary>replace, sed style</primary>
<secondary>search, sed style</secondary></indexterm>
-<command>s///[ig]</command> <command>%s///[ig]</command></term>
+<command>s///[ig]</command> and <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
+<para>In short, &kate; searches 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
+middle and last slash. Parenthesis in the search pattern
create <emphasis>back references</emphasis>, that is the command
-remembers which part of the match matched in the parentheses; these
+remembers which part of the text matched in the parenthesis. These
strings can be reused in the replace pattern, referred to as
-<userinput>\1</userinput> for the first set of parentheses,
+<userinput>\1</userinput> for the first set of parenthesis,
<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>
+<literal>)</literal>, you need to escape 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. If you put a
@@ -428,7 +429,7 @@ is not defined.</para>
<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;
+<guibutton>OK</guibutton> button, save the file and compile
successfully without the error.</para>
</example>
@@ -438,62 +439,16 @@ successfully without the error.</para>
<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,
+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>Enter the command line and issue the command
-<userinput>%s/Miss Jensen/Ms Jones/</userinput> and hit return, you
+<userinput>%s/Miss Jensen/Ms. Jones/</userinput> and hit enter, 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>character 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>
@@ -543,9 +498,7 @@ following options are supported:
<varlistentry>
<term><userinput>r</userinput></term>
-<listitem><para>Do regular expression search. If set, you may use
-<userinput>\N</userinput> where N is a number to represent captures in the
-replacement string.</para></listitem>
+<listitem><para>Do regular expression search.</para></listitem>
</varlistentry>
<varlistentry>
@@ -568,10 +521,10 @@ replacement string.</para></listitem>
<varlistentry>
<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term>
-<listitem><para>This command provides <quote>as-you-type</quote> searching. You
+<listitem><para>This command provides <quote>incremental (as-you-type)</quote> searching. You
can configure the behavior of the search by appending a colon
followed by one or more options, like this:
-<userinput>ifind:options pattern</userinput>. Allowed options are
+<userinput>ifind:options pattern</userinput>. Allowed options are:
<variablelist>
<varlistentry>
@@ -611,10 +564,10 @@ followed by one or more options, like this:
<para>Code folding allows you to hide parts of a document in the editor, making
it easier to overview large documents. In &kate; the foldable regions are
-calculated using rules defined in the syntax highlight definitions, and
-therefore it is only available in some formats - typically program source code,
-XML markup and similar. Most highlight definitions supporting code folding
-also lets you manually define foldable regions, typically using the
+calculated using rules defined in the syntax highlight definitions and
+therefore it is only available in some file formats - typically program source code,
+XML markup and similar. Most highlight definition files supporting code folding
+also let you manually define foldable regions, typically using the
<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para>
<para>To use the code folding feature, activate the folding markers using
@@ -622,23 +575,22 @@ also lets you manually define foldable regions, typically using the
Markers</guimenuitem></menuchoice> menu item if they are not already visible.
The Folding Markers Pane in the left side of the screen displays a graphical
view of the foldable regions, with +/- signs to indicate the possible operation
-on a given region: a - means that the region is expanded, clicking the - will
+on a given region. A - means that the region is expanded; clicking on the - will
collapse the region and a + will be displayed instead.</para>
<para>Four commands are provided to manipulate the state of folding regions,
-see the <link linkend="view-code-folding">menu documentation</link>.
+see the <link linkend="view-code-folding">menu documentation</link> for details.
</para>
-<para>If you do not want to use the code folding feature, you can disable
-the <guilabel>Show folding markers (if available)</guilabel> option in the
-<link linkend="config-dialog-editor-appearance">Appearance page of the editor
-configuration</link></para>
+<para>If you do not want to use the code folding feature, you can disable it
+completely using the <guilabel>Show folding markers (if available)</guilabel> option in the
+<link linkend="appearance-code-folding">Editor Appearance</link> configuration page</para>
</sect1>
<sect1 id="advanced-editing-tools-scripting">
-<title>Scripting the editor component with Javascript</title>
+<title>Scripting the editor with JS</title>
<sect2 id="advanced-editing-tools-scripting-introduction">
@@ -648,24 +600,15 @@ configuration</link></para>
scripting with ECMA script, also known as JavaScript.</para>
<para>Scripts can be used through <link
-linkend="advanced-editing-tools-commandline">the built in command line</link>
-only. The requirements is that the script is placed in a folder where &kate;
-can find it, along with an optional .desktop file that defines the related
-properties. The valid folder are named <filename>katepart/scripts</filename>
+linkend="advanced-editing-tools-commandline">the built-in command line</link>
+only. The requirements are that the scripts are placed in a folder where &kate;
+can find them, along with an optional .desktop file that defines the related
+properties. The valid folders are named <filename>katepart/scripts</filename>
in the &tde; data folders. You can find the data folders by running the command
-<command>tde-config <option>--path</option> <parameter>data</parameter></command>
+<command>tde-config <option>--path</option> <parameter>data</parameter></command>.
You will usually have at least a system and a personal data folder. Of course
scripts in the system data folder are available to all users on the system,
-while those in the personal folder are available for you only.</para>
-
-<note><para>This feature is experimental and will most likely change during
-future development.</para>
-<para>We know that many of you will be disappointed because you can't add
-your scripts to the menu or assign shortcuts to them. Sorry, sometime
-in the future that will likely be possible.</para>
-<para>It is also not possible to pass any arguments to your scripts yet. Be
-patient, and that may be added in the bright future ;)</para>
-</note>
+while those in the personal folder are available to you only.</para>
</sect2>
@@ -673,33 +616,32 @@ patient, and that may be added in the bright future ;)</para>
<title>The Kate JavaScript API</title>
-<para>Here is listed the complete set of functions and properties available
+<para>Here is the complete set of functions and properties available
in the <type>document</type> and <type>view</type> objects.
-In addition you can of course use all the standard objects such as
+In addition, you can use all the standard objects such as
<type>Math</type>, <type>String</type> <type>Regex</type> and so forth.</para>
<para>When a script is run, the <classname>document</classname> object is the
current document, and the <classname>view</classname> object is the current
view.</para>
-<note><para>The types of arguments are of course not used in JavaScript at
-this time, they are there solely to indicate what sort of value the funcitons
-expect.</para></note>
+<note><para>Types are not used in JavaScript. In this list, they are
+there solely to indicate what sort of arguments the functions expect.</para></note>
<variablelist id="advanced-editing-tools-scripting-global">
<title>Global Functions</title>
<varlistentry>
-<term><function>debug( <parameter><replaceable>string</replaceable></parameter>)
-[function]</function></term>
+<term><function>debug(<parameter><replaceable>string s</replaceable></parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>parameters</title>
-<listitem><para><parameter>string</parameter> the string to output</para>
+<listitem><para><parameter>s</parameter> the string to output.</para>
</listitem>
</itemizedlist>
<para>Outputs the string to <acronym>STDERR</acronym> using
<function>kdDebug()</function>. A dedicated output area is used for the output,
-which will be prefixed <computeroutput>Kate (KJS Scripts):</computeroutput>
+which will be prefixed by "<emphasis>Kate (KJS Scripts):</emphasis>"
</para>
</listitem>
</varlistentry>
@@ -709,19 +651,19 @@ which will be prefixed <computeroutput>Kate (KJS Scripts):</computeroutput>
<title>The <classname>document</classname> API</title>
<varlistentry>
-<term><function>document.attribute( <parameter><replaceable>line</replaceable>
-</parameter>, <parameter><replaceable>column</replaceable></parameter> );
- [function]</function></term>
+<term><function>document.attribute(<parameter><replaceable>uint line</replaceable></parameter>,
+<parameter><replaceable>uint column</replaceable></parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>uint line</parameter> The line of the position for which
+<listitem><para><parameter>line</parameter> the line of the position for which
to find the attribute.</para></listitem>
-<listitem><para><parameter>uint column</parameter> The column of the position for
+<listitem><para><parameter>column</parameter> the column of the position for
which to find the attribute.</para></listitem>
</itemizedlist>
<para>Returns the numeric ID of the attribute for the document position
-[<parameter>line</parameter>,<parameter>column</parameter>]. The attribute
+[<parameter>line</parameter>, <parameter>column</parameter>]. The attribute
represents the visual appearance or style of the text, and is also used to
calculate the syntax highlight for a specific part of the text in mixed formats
like HTML or PHP.</para>
@@ -729,133 +671,125 @@ like HTML or PHP.</para>
</varlistentry>
<varlistentry>
-<term><function>document.canBreakAt( <parameter>Char c</parameter>,
-<parameter>uint attribute</parameter> ); [function]</function></term>
+<term><function>document.canBreakAt(<parameter>char c</parameter>,
+<parameter>attribute attrib</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>c</parameter> The character to test</para></listitem>
-<listitem><para><parameter>attribute</parameter> The attribute at the position
+<listitem><para><parameter>c</parameter> the character to test.</para></listitem>
+<listitem><para><parameter>attrib</parameter> the attribute at the position
of <parameter>c</parameter>.</para></listitem>
</itemizedlist>
-<para>Returns whether it is allowed to break the line at a character c with
-attribute attribute. The result is decided by querying the highlight owning
-attribute for which characters allow breaking the line.</para>
+<para>Returns whether it is allowed to break the line at the character
+<parameter>c</parameter> with attribute <parameter>attribute</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.canComment( <parameter>uint start_attribute</parameter>,
-<parameter>uint end_attribute</parameter> ); [function]</function></term>
+<term><function>document.canComment(<parameter>attribute start_attrib</parameter>,
+<parameter>attribute end_attrib</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>start_attribute</parameter> The attribute at the
+<listitem><para><parameter>start_attrib</parameter> the attribute at the
start of the range to turn into a comment.</para></listitem>
-<listitem><para><parameter>end_attribute</parameter> The attribute at end of
+<listitem><para><parameter>end_attrib</parameter> the attribute at end of
the range to turn into a comment.</para></listitem>
</itemizedlist>
-<para>Returns whether start_attribute and end_attribute belongs to the same
-syntax highlight system. If they do, it is sane.
+<para>Returns whether <parameter>start_attribute</parameter> and
+<parameter>end_attribute</parameter> belongs to the same
+syntax highlight system. If they do, it is possible to comment the block.
</para>
-<example>
-<title>using canComment</title>
-<programlisting>
-if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
- // 1,0 and 5,0 belongs to the same syntax highlighting system
-}
-</programlisting>
-</example>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.clear(); [function]</function></term>
+<term><function>document.clear() function</function></term>
<listitem><para>Clears the document.</para></listitem>
</varlistentry>
<varlistentry>
-<term><function>document.commentStart( <parameter>uint attribute</parameter> );
-[function]</function></term>
+<term><function>document.commentStart(<parameter>attribute attrib</parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>attribute</parameter> The attribute of the text for
+<listitem><para><parameter>attrib</parameter> the attribute of the text for
which to get the commentStart string.</para></listitem>
</itemizedlist>
<para>Returns the string required to start a multiline comment for a text with
-attribute, or an empty string if multiline comments are not supported for that
+attribute <parameter>attrib</parameter>, or an empty string if multiline comments are not supported for that
text.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.commentMarker( <parameter>uint attribute</parameter> );
-[function]</function></term>
+<term><function>document.commentMarker(<parameter>attribute attrib</parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>attribute</parameter> The attribute of the text for
-which to get the commentMarker string</para></listitem>
+<listitem><para><parameter>attrib</parameter> the attribute of the text for
+which to get the commentMarker string.</para></listitem>
</itemizedlist>
<para>Returns the string used to mark the rest of the line as a comment for a
-text with attribute or an empty string if single line comments are not supported
-for that text.</para>
+text with attribute <parameter>attrib</parameter> or an empty string if single
+line comments are not supported for that text.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.commentEnd( <parameter>uint attribute</parameter> );
-[function]</function></term>
+<term><function>document.commentEnd(<parameter>attribute attrib</parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>attribute</parameter> The attribute of the text for
-which to get the commentEnd string</para></listitem>
+<listitem><para><parameter>attrib</parameter> the attribute of the text for
+which to get the commentEnd string.</para></listitem>
</itemizedlist>
<para>Returns the string required to end a multiline comment for a text with
-attribute, or an empty string if multiline comments are not supported for that
-text.</para>
+attribute <parameter>attrib</parameter>, or an empty string if multiline
+comments are not supported for that text.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.editBegin(); [function]</function></term>
+<term><function>document.editBegin() function</function></term>
<listitem>
-<para>Start an editing group. All actions done until the call of editEnd() will
-be grouped as one undo-action.</para>
+<para>Starts an editing group. All actions done until the call to editEnd() will
+be grouped as a single undo action.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.editEnd(); [function]</function></term>
+<term><function>document.editEnd() function</function></term>
<listitem>
-<para>Finish an editing group.</para>
+<para>Ends an editing group.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.highlightMode; [property:read only]</function></term>
+<term><function>document.highlightMode property, read only</function></term>
<listitem>
<para>The name of the document's highlight mode, such as JavaScript or C++.
-If no syntax highlight mode is set for the document, the value is None. Notice
-that you need to use the English name in cases where it differs from the
+If no syntax highlight mode is set for the document, the value is <emphasis>none</emphasis>.
+Notice that you need to use the English name in cases where it differs from the
translated one.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.indentMode; [property:read only]</function></term>
+<term><function>document.indentMode property, read only</function></term>
<listitem>
<para>The name of the document indent mode, such as
<literal>normal</literal> or <literal>cstyle</literal>.
-Remember that if no indent mode is set, the value is <literal>none</literal>.
+If no indent mode is set, the value is <emphasis>none</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.indentWidth; [property:read only]</function></term>
+<term><function>document.indentWidth property, read only</function></term>
<listitem>
<para>The indentation width set for the document. This is used if space
indenting is enabled.</para>
@@ -863,14 +797,14 @@ indenting is enabled.</para>
</varlistentry>
<varlistentry>
-<term><function>document.insertLine( <parameter>uint line</parameter>,
-<parameter>string text</parameter> ); [function]</function></term>
+<term><function>document.insertLine(<parameter>uint line</parameter>,
+<parameter>string text</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> document line number</para>
+<listitem><para><parameter>line</parameter> the document line number.</para>
</listitem>
-<listitem><para><parameter>text</parameter> text to insert</para></listitem>
+<listitem><para><parameter>text</parameter> the text to insert.</para></listitem>
</itemizedlist>
<para>Inserts a new line with the text <parameter>text</parameter> at the
line <parameter>line</parameter>.</para>
@@ -878,102 +812,97 @@ line <parameter>line</parameter>.</para>
</varlistentry>
<varlistentry>
-<term><function>document.insertText( <parameter>uint line</parameter>,
-<parameter>uint column</parameter>, <parameter>string text</parameter> );
-[function]</function></term>
+<term><function>document.insertText(<parameter>uint line</parameter>,
+<parameter>uint column</parameter>, <parameter>string text</parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> the line number</para></listitem>
-<listitem><para><parameter>column</parameter> the column</para></listitem>
-<listitem><para><parameter>text</parameter> the text which is to be
-inserted</para></listitem>
+<listitem><para><parameter>line</parameter> the line number.</para></listitem>
+<listitem><para><parameter>column</parameter> the column number.</para></listitem>
+<listitem><para><parameter>text</parameter> the text to insert.</para></listitem>
</itemizedlist>
<para>Inserts the text <parameter>text</parameter> in line
-<parameter>line</parameter> and column <parameter>column</parameter>.</para>
+<parameter>line</parameter> at column <parameter>column</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term>document.length(); [function]</term>
+<term>document.length() function</term>
<listitem>
<para>Returns the document's size in bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.lines(); [function]</function></term>
+<term><function>document.lines() function</function></term>
<listitem>
<para>Returns the number of lines in the document.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term>document.mixedIndent; [property:read only]</term>
+<term>document.mixedIndent property, read only</term>
<listitem>
<para>A boolean telling whether the mixed-indent setting is enabled for the
document. If so, indentation is optimized to contain a mix of tab characters and
-spaces like used by the Emacs editor.</para>
+spaces like in the Emacs editor.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term>document.removeLine( <parameter>uint line</parameter> ); [function]</term>
+<term>document.removeLine(<parameter>uint line</parameter>) function</term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> line number</para></listitem>
+<listitem><para><parameter>line</parameter> the line number.</para></listitem>
</itemizedlist>
-<para>Removes the document line line.</para>
+<para>Removes the document line <parameter>line</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.removeText( <parameter>uint startLine</parameter>,
+<term><function>document.removeText(<parameter>uint startLine</parameter>,
<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
-<parameter>uint endColumn</parameter> ); [function]</function></term>
+<parameter>uint endColumn</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>startLine</parameter> specifies the beginning
-line</para></listitem>
-<listitem><para><parameter>startColumn</parameter> specifies the beginning
-column</para></listitem>
-<listitem><para><parameter>endLine</parameter> specifies the ending
-line</para></listitem>
-<listitem><para><parameter>endColumn</parameter> specifies the ending
-column</para></listitem>
+<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem>
</itemizedlist>
<para>Removes the text range from line <parameter>startLine</parameter> and
-column <parameter>startColumn</parameter> up to line
+column <parameter>startColumn</parameter> to line
<parameter>endLine</parameter> and column <parameter>endColumn</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.setText( <parameter>string text</parameter> );
-[function]</function></term>
+<term><function>document.setText(<parameter>string text</parameter>)
+function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>text</parameter> document text</para></listitem>
+<listitem><para><parameter>text</parameter> the new document text.</para></listitem>
</itemizedlist>
<para>Sets the entire document content to <parameter>text</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.spaceIndent; [property:read only]</function></term>
+<term><function>document.spaceIndent property, read only</function></term>
<listitem>
<para>A boolean telling whether space-indent is enabled for the document.
-If so, the document is indented with indentWidth spaces pr level, otherwise
-indentation is one tab character pr. level.</para>
+If so, the document is indented with indentWidth spaces per level, otherwise
+indentation is one tab character per level.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.textFull(); [function]</function></term>
+<term><function>document.textFull() function</function></term>
<listitem>
<para>Returns the full document text. If the text spans over multiple lines the
linefeed character is <constant>\n</constant>.</para>
@@ -981,31 +910,27 @@ linefeed character is <constant>\n</constant>.</para>
</varlistentry>
<varlistentry>
-<term><function>document.textLine( uint line ); [function]</function></term>
+<term><function>document.textLine(<parameter>uint line</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> the line</para></listitem>
+<listitem><para><parameter>line</parameter> the line number.</para></listitem>
</itemizedlist>
-<para>Returns the text of line <parameter>line</parameter>.</para>
+<para>Returns the text at line <parameter>line</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>document.textRange( <parameter>uint startLine</parameter>,
+<term><function>document.textRange(<parameter>uint startLine</parameter>,
<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
-<parameter>uint endColumn</parameter> ); [function]</function></term>
+<parameter>uint endColumn</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>startLine</parameter> specifies the beginning
-line</para></listitem>
-<listitem><para><parameter>startColumn</parameter> specifies the beginning
-column</para></listitem>
-<listitem><para><parameter>endLine</parameter> specifies the ending line</para>
-</listitem>
-<listitem><para><parameter>endColumn</parameter> specifies the ending
-column</para></listitem>
+<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem>
</itemizedlist>
<para>Returns the specified text range. If the range spans over multiple lines
the linefeed character is <constant>\n</constant>.</para>
@@ -1018,57 +943,57 @@ the linefeed character is <constant>\n</constant>.</para>
<title>The <classname>view</classname> API</title>
<varlistentry>
-<term><function>view.clearSelection(); [function]</function></term>
+<term><function>view.clearSelection() function</function></term>
<listitem>
<para>Deselects all text.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.cursorColumn(); [function]</function></term>
+<term><function>view.cursorColumn() function</function></term>
<listitem>
<para>Returns the current cursor column (TAB characters are expanded).</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.cursorColumnReal(); [function]</function></term>
+<term><function>view.cursorColumnReal() function</function></term>
<listitem>
-<para>Returns the current real cursor column (TAB characters counts one).</para>
+<para>Returns the current real cursor column (a TAB character counts as one).</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.cursorLine(); [function]</function></term>
+<term><function>view.cursorLine() function</function></term>
<listitem>
<para>Returns the current cursor line.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.hasSelection(); [function]</function></term>
+<term><function>view.hasSelection() function</function></term>
<listitem>
-<para>Returns <constant>true</constant> if the view contains selected text,
+<para>Returns <constant>true</constant> if some text in the view has been selected,
otherwise <constant>false</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.removeSelectedText(); [function]</function></term>
+<term><function>view.removeSelectedText() function</function></term>
<listitem>
<para>Removes the selected text, if the view has a selection.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.selectAll(); [function]</function></term>
+<term><function>view.selectAll() function</function></term>
<listitem>
<para>Selects all text.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.selection(); [function]</function></term>
+<term><function>view.selection() function</function></term>
<listitem>
<para>Returns the selected text. If the selection spans over multiple lines the
linefeed character is <constant>\n</constant>.</para>
@@ -1076,84 +1001,79 @@ linefeed character is <constant>\n</constant>.</para>
</varlistentry>
<varlistentry>
-<term><function>view.selectionEndColumn; [property:read only]</function></term>
+<term><function>view.selectionEndColumn property, read only</function></term>
<listitem>
<para>Returns the ending column of the selection.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.selectionEndLine; [property:read only]</function></term>
+<term><function>view.selectionEndLine property, read only</function></term>
<listitem>
<para>Returns the ending line of the selection.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.selectionStartColumn; [property:read only]</function></term>
+<term><function>view.selectionStartColumn property, read only</function></term>
<listitem>
<para>Returns the starting column of the selection.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.selectionStartLine; [property:read only]</function></term>
+<term><function>view.selectionStartLine property, read only</function></term>
<listitem>
<para>Returns the starting line of the selection.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.setCursorPosition( <parameter>uint line</parameter>,
-<parameter>uint column</parameter> ); [function]</function></term>
+<term><function>view.setCursorPosition(<parameter>uint line</parameter>,
+<parameter>uint column</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> Specifies the line for the
-cursor.</para></listitem>
-<listitem><para><parameter>column</parameter> Specifies the column for the
-cursor.</para></listitem>
+<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem>
+<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem>
</itemizedlist>
-<para>Sets the input cursor position in the view to [<parameter>line</parameter>,
-<parameter>col</parameter>]. This sets the cursor position by visual means,
-that is the a TAB character counts up to <replaceable>tabwidth</replaceable>
-depending on the position inside the line. The cursor position is made visible.
-Both line and column are zero-based.</para>
+<para>Sets the input cursor position in the view to (<parameter>line</parameter>,
+<parameter>column</parameter>). TAB characters are expanded and
+the cursor position is made visible. Both <parameter>line</parameter>
+and <parameter>column</parameter> are zero-based.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.setCursorPositionReal( <parameter>uint line</parameter>,
-<parameter>uint column</parameter> ); [function]</function></term>
+<term><function>view.setCursorPositionReal(<parameter>uint line</parameter>,
+<parameter>uint column</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>line</parameter> Specifies the line for the
-cursor.</para></listitem>
-<listitem><para><parameter>column</parameter> Specifies the column for the
-cursor.</para></listitem>
+<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem>
+<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem>
</itemizedlist>
-<para>Sets the input cursor position to [<parameter>line</parameter>,
-<parameter>col</parameter>]. This sets the string position, that is a TAB
-character counts for 1. The cursor position is made visible. Both line and
-column are zero-based.</para>
+<para>Sets the input cursor position to (<parameter>line</parameter>,
+<parameter>column</parameter>). This sets the string position, that is a TAB
+character counts for 1, and the cursor position is made visible. Both <parameter>line</parameter>
+and <parameter>column</parameter> are zero-based.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><function>view.setSelection( <parameter>uint startLine</parameter>,
+<term><function>view.setSelection(<parameter>uint startLine</parameter>,
<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
-<parameter>uint endColumn</parameter> ); [function]</function></term>
+<parameter>uint endColumn</parameter>) function</function></term>
<listitem>
<itemizedlist>
<title>Parameters</title>
-<listitem><para><parameter>startLine</parameter> specifies the beginning line</para></listitem>
-<listitem><para><parameter>startColumn</parameter> specifies the beginning column</para></listitem>
-<listitem><para><parameter>endLine</parameter> specifies the ending line</para></listitem>
-<listitem><para><parameter>endColumn</parameter> specifies the ending column</para></listitem>
+<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem>
</itemizedlist>
<para>Sets a selection from line <parameter>startLine</parameter> and column
-<parameter>startColumn</parameter> up to line <parameter>endLine</parameter>
+<parameter>startColumn</parameter> to line <parameter>endLine</parameter>
and column <parameter>endColumn</parameter>.</para>
</listitem>
</varlistentry>
@@ -1163,13 +1083,13 @@ and column <parameter>endColumn</parameter>.</para>
<example id="advanced-editing-tools-scripting-example">
<title>A sample script</title>
-<para>As an example we will create a small script that uppercases the selection.
-It is obvious that we first need to check whether a selection exists, if so we
-get the text, change the case and then replace it with the new one. An
-implementation could look like this:</para>
+<para>As an example we will create a small script that transforms the selected
+text to upper case. We first need to check whether a selection exists: if so we
+get the text, change the case and then replace the original text with the new one.
+An implementation would look something like this:</para>
<programlisting>
-if ( view.hasSelection() )
+if (view.hasSelection())
{
// uppercase selection
column = view.selectionStartColumn;
@@ -1179,17 +1099,18 @@ if ( view.hasSelection() )
document.editBegin();
view.removeSelectedText();
- document.insertText( line, column, selection );
+ document.insertText(line, column, selection);
document.editEnd();
}
</programlisting>
-<para>To group this action together so that they will be reverted by a single
-activation of <guimenuitem>Undo</guimenuitem> we encapsulate the lines
-<programlisting>view.removeSelectedText()</programlisting> and
-<programlisting>document.insertText()</programlisting> with a
-<programlisting>document.editBegin()</programlisting> and
-<programlisting>document.editEnd()</programlisting>.</para>
+<para>To group this actions together so that they will be reverted by a single
+activation of <guimenuitem>Undo</guimenuitem>, we encapsulate the lines
+<programlisting>
+view.removeSelectedText()
+document.insertText()
+</programlisting> in a <emphasis>document.editBegin()</emphasis> -
+<emphasis>document.editEnd()</emphasis> block.</para>
</example>
@@ -1202,36 +1123,32 @@ activation of <guimenuitem>Undo</guimenuitem> we encapsulate the lines
# Example of a .desktop file
[Desktop Entry]
Encoding=UTF-8
-Name=Kate Part JavaScript Uppercase
-Comment=Script to uppercase the selection
+Name=Kate Part JavaScript Uppercase Script
+Comment=Script to transform the selected text to upper case
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>As you can see you can define the Encoding, set a Name, a Comment, a help
-text using X-Kate-Help and the command line name via X-Kate-Command. The entries
-Name, Comment and X-Kate-Help are automatically translated into other languages
-by the KDE translation teams, if the files are in KDE's SVN repository.</para>
+text using X-Kate-Help and the command line name via X-Kate-Command.</para>
</example>
<sect3>
-<title>Putting it togeather</title>
+<title>Putting it all together</title>
<para>&kate; will search the script folders (see <link
linkend="advanced-editing-tools-scripting-introduction">above</link>) for
-<filename>*.js</filename> files. For every file it checks whether there is a
-corresponding <filename>.desktop</filename> file, like for uppercase.js it
-would look for uppercase.desktop.</para>
-<para>If a <filename>.desktop</filename> file can not be found the script will
-be registered in katepart's command line with the filename without the ending
-.js, so in our example this would be <literal>uppercase</literal>. If the
-command-name is fine and you don't need the extra features a
-<filename>.desktop</filename> file provides you do not need a
+<filename>.js</filename> files. For every such file found, &kate; will check
+whether there is a corresponding <filename>.desktop</filename> file with
+the same basename (for example script.js and script.desktop).</para>
+<para>If a corresponding <filename>.desktop</filename> file exists, the script
+will be registered using the name from the .desktop entry <emphasis>X-Kate-Command</emphasis>.</para>
+<para>If a corresponding <filename>.desktop</filename> file can not be found, the script will
+be registered with the file basename (i.e. without the ending .js).
+If you only need the command name and none of the extra features
+that a <filename>.desktop</filename> file would provide, you do not need a
<filename>.desktop</filename> file at all.</para>
-<para>If a <filename>.desktop</filename> file exists katepart will read the name
-under which the script will be registered from the .desktop-entry
-X-Kate-Command, for example X-Kate-Command=uppercase-selection.</para>
</sect3>
diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook
index 46a3e4703..f7cd3bff6 100644
--- a/doc/kate/configuring.docbook
+++ b/doc/kate/configuring.docbook
@@ -484,7 +484,7 @@ wrapped lines.</para></listitem>
</listitem>
</varlistentry>
-<varlistentry>
+<varlistentry id="appearance-code-folding">
<term><guilabel>Code Folding</guilabel></term>
<listitem>
<variablelist>
diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook
index 0402c4d57..993682b6e 100644
--- a/doc/kate/mdi.docbook
+++ b/doc/kate/mdi.docbook
@@ -286,6 +286,88 @@ information, see the &konsole; manual.</para>
</sect1>
+<sect1 id="kate-mdi-tools-find-in-files">
+<title>The Find in Files Panel</title>
+
+<para><indexterm><primary>The Find in Files Panel</primary></indexterm>
+The Find in Files panel in &kate; allows you to search for text in
+multiple files at once.</para>
+<para>Results of the search will be displayed in the list at the bottom of the
+panel, while search errors will be displayed in a separate dialog.</para>
+
+<para>The panel offers the following options:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Pattern</guilabel></term>
+<listitem><para>The text to look for. The interpretation of the string
+depends on some of the options described below.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Case sensitive</guilabel></term>
+<listitem>
+<para>If enabled, the search will be case sensitive.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Regular expression</guilabel></term>
+<listitem>
+<para>If checked, the search string will be interpreted as a regular
+expression.</para>
+<para>See <link linkend="regular-expressions">Regular
+Expressions</link> for more on these.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Template</guilabel> (edit field and dropbox)</term>
+<listitem>
+<para>Here you can specify an additional context string to be used as a wrapper around
+the search pattern. Some default templates are available through the dropbox on the right
+of the template edit field.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Files</guilabel></term>
+<listitem>
+<para>The file name pattern used to select which files to search.
+It is possible to specify multiple patterns by separating them with commas
+(for example *.h, *.cpp).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Folder</guilabel></term>
+<listitem>
+<para>The folder to search for files.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Recursive</guilabel></term>
+<listitem>
+<para>If checked, the search will also recurse in the subfolders of the
+specified folder.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>You can use the <guimenuitem>Find</guimenuitem> button to start the search
+and the <guimenuitem>Cancel</guimenuitem> button to interrupt a running search.
+</para>
+<para>The <guimenuitem>Clear</guimenuitem> button can be used to clear the search
+list at the bottom of the panel.</para>
+
+<para>The default location of the Find in Files panel in &kate; is at the bottom,
+below the editing area.</para>
+
+</sect1>
+
<sect1 id="kate-mdi-tools-externaltools">
<title>External Tools</title>
diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook
index e99985539..ad74be9c7 100644
--- a/doc/kate/part.docbook
+++ b/doc/kate/part.docbook
@@ -359,6 +359,7 @@ with the corresponding string capture (parenthesized substring)
from the search pattern. A button for listing all available string captures
will also be enabled. You can click on any of the available string captures
to include them in your replacement string.</para>
+<note><para>Placeholders can only be used when searching using regular expressions.</para></note>
</listitem>
</varlistentry>
@@ -460,6 +461,12 @@ captured in parenthesized subpatterns of the expression.</para>
</sect2>
+<sect2>
+<title>Finding text in multiple files</title>
+<para>To search for text in multiple files at once, please refer to the
+<link linkend="kate-mdi-tools-find-in-files">Find in Files Panel</link> section.</para>
+</sect2>
+
</sect1>
<sect1 id="kate-part-bookmarks">
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index 196aae7e8..48c164de2 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -21,9 +21,14 @@ linkend="configuring-kate-configdialog">configuration dialog</link>, which also
provides access to additional configuration options for plugins that requires
that.</para>
-<para>There are many plugins for various purposes available in the tdeaddons
+<para>There are many plugins for various purposes available in the <emphasis>tdeaddons</emphasis>
module, and you can search the web for more. A few plugins are shipped with the
-editor component, for doing word completion, automatic bookmarks, insert files,
+editor component, for doing word completion, insert files,
thesaurus and word spell checking and incremental search.</para>
+<para>You can find additional information about some of &kate;'s plugins in
+<emphasis>The Kate Plugins Handbook</emphasis> accessible from
+<menuchoice><guimenu>Help</guimenu><guimenuitem>Plugins Handbook</guimenuitem></menuchoice>
+if the <emphasis>tdeaddons</emphasis> module has been installed on your system</para>
+
</chapter>