[kde-doc-english] [kate] /: move scripting docs from advanced.docbook to development.docbook
T.C. Hollingsworth
tchollingsworth at gmail.com
Mon May 27 20:27:52 UTC 2013
Git commit ef6d65286d40906938b904b2a30a9cf402e0ec7a by T.C. Hollingsworth.
Committed on 19/05/2013 at 23:15.
Pushed by hollingsworth into branch 'master'.
move scripting docs from advanced.docbook to development.docbook
M +1 -1710 doc/kate/advanced.docbook
M +1706 -0 doc/kate/development.docbook
M +3 -3 doc/kate/menus.docbook
M +1 -1 doc/kwrite/menus.docbook
M +1 -1 part/snippet/editsnippet.cpp
http://commits.kde.org/kate/ef6d65286d40906938b904b2a30a9cf402e0ec7a
diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook
index 045b16b..edc333d 100644
--- a/doc/kate/advanced.docbook
+++ b/doc/kate/advanced.docbook
@@ -237,7 +237,7 @@ argument.</para></listitem>
<varlistentry>
<term><cmdsynopsis><command>reload-scripts</command></cmdsynopsis></term>
-<listitem><para>Reload all <link linkend="advanced-editing-tools-scripting">JavaScript
+<listitem><para>Reload all <link linkend="dev-scripting">JavaScript
scripts</link> used by Kate, including indenters and command line scripts.</para></listitem>
</varlistentry>
@@ -905,1713 +905,4 @@ configuration.</para>
</sect1>
-<sect1 id="advanced-editing-tools-scripting">
-<title>Extending &kappname; with Scripts</title>
-
-<para>
-Since &kappname; 3.4 in KDE 4.4 the &kappname; editor component is easily extensible by
-writing scripts. The scripting language is ECMAScript (widely known as JavaScript).
-&kappname; supports two kinds of scripts: indentation and command line scripts.
-</para>
-
-<sect2 id="advanced-editing-tools-scripting-indentation">
-<title>Indentation Scripts</title>
-
-<para>
-Indentation scripts - also referred as indenters - automatically indent the
-source code while typing text. As example, after hitting the return-key code
-the indentation level often increases.
-</para>
-
-<para>
-The following sections describe step by step how to create the skeleton for a
-simple indenter. As first step, create a new <filename>*.js</filename> file
-called e.g. <filename>javascript.js</filename> in the local home folder
-<filename>$KDEHOME/share/apps/katepart/script/indentation</filename>.
-</para>
-
-<sect3 id="advanced-editing-tools-scripting-indentation-header">
-<title>The Indentation Script Header</title>
-<para>
-The header of the file <filename>javascript.js</filename> is embedded in a
-comment and is of the following form
-
-<programlisting>
-/* kate-script
- * name: JavaScript
- * author: Example Name <example.name at some.address.org>
- * license: BSD
- * revision: 1
- * kate-version: 3.4
- * required-syntax-style: javascript
- * indent-languages: javascript
- * priority: 0
- * i18n-catalog: mycatalog
- *
- * A line without colon ':' stops header parsing. That is, you can add optional
- * text here such as a detailed license.
- */
-</programlisting>
-
-Each entry is explained in detail now:
-<itemizedlist>
-<listitem><para>
-<literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.
-</para></listitem>
-<listitem><para>
-<literal>name</literal> [required]: This is the indenter name that appears in the menu
-<menuchoice><guimenu>Tools</guimenu><guimenuitem>Indentation</guimenuitem></menuchoice>
-and in the configuration dialog.
-</para></listitem>
-<listitem><para>
-<literal>author</literal> [optional]: The author's name and contact information.
-</para></listitem>
-<listitem><para>
-<literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.
-</para></listitem>
-<listitem><para>
-<literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.
-</para></listitem>
-<listitem><para>
-<literal>kate-version</literal> [required]: Minimal required &kappname; version.
-</para></listitem>
-<listitem><para>
-<literal>required-syntax-style</literal> [optional]: Comma separated list of required syntax highlighting styles. This is important for indenters that rely on specific highlight information in the document. If a required syntax style is specified, the indenter is available only when the appropriate highlighter is active. This prevents <quote>undefined behavior</quote> caused by using the indenter without the expected highlighting schema. For instance, the Ruby indenter makes use of this in the files <filename>ruby.js</filename> and <filename>ruby.xml</filename>.
-</para></listitem>
-<listitem><para>
-<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, e.g.: c++, java.
-</para></listitem>
-<listitem><para>
-<literal>priority</literal> [optional]: If several indenters are suited for a certain highlighted file, the priority decides which indenter is chosen as default indenter.
-</para></listitem>
-<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party indenters.</para></listitem>
-</itemizedlist>
-</para>
-
-<para>
-&kappname; reads all pairs of the form
-<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote>
-until it cannot find a colon anymore. This implies that the header can contain
-arbitrary text such as a license as shown in the example.
-</para>
-
-</sect3>
-
-<sect3 id="advanced-editing-tools-scripting-indentation-body">
-<title>The Indenter Source Code</title>
-<para>
-Having specified the header this section explains how the indentation scripting
-itself works. The basic skeleton of the body looks like this:
-
-<programlisting>
-// required katepart js libraries, e.g. range.js if you use Range
-require ("range.js");
-
-triggerCharacters = "{}/:;";
-function indent(line, indentWidth, ch)
-{
- // called for each newline (ch == '\n') and all characters specified in
- // the global variable triggerCharacters. When calling <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>
- // the variable ch is empty, i.e. ch == ''.
- //
- // see also: Scripting API
- return -2;
-}
-</programlisting>
-
-The function <function>indent()</function> has three parameters:
-<itemizedlist>
-<listitem><para><literal>line</literal>: the line that has to be indented</para></listitem>
-<listitem><para><literal>indentWidth</literal>: the indentation width in amount of spaces</para></listitem>
-<listitem><para><literal>ch</literal>: either a newline character (<literal>ch == '\n'</literal>), the trigger character specified in <literal>triggerCharacters</literal> or empty if the user invoked the action <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>.</para></listitem>
-</itemizedlist>
-The return value of the <function>indent()</function> function specifies how
-the line will be indented. If the return value is a simple integer number, it
-is interpreted as follows:
-<itemizedlist>
-<listitem><para>return value <literal>-2</literal>: do nothing</para></listitem>
-<listitem><para>return value <literal>-1</literal>: keep indentation (searches for previous non-blank line)</para></listitem>
-<listitem><para>return value <literal> 0</literal>: numbers >= 0 specify the indentation depth in spaces</para></listitem>
-</itemizedlist>
-Alternatively, an array of two elements can be returned:
-<itemizedlist>
-<listitem><para><literal>return [ indent, align ];</literal></para></listitem>
-</itemizedlist>
-In this case, the first element is the indentation depth like above with the
-same meaning of the special values. However, the second element is an absolute
-value representing a column for <quote>alignment</quote>. If this value is higher than the
-indent value, the difference represents a number of spaces to be added after
-the indentation of the first parameter. Otherwise, the second number is ignored.
-Using tabs and spaces for indentation is often referred to as <quote>mixed mode</quote>.
-</para>
-
-<para>
-Consider the following example: Assume using tabs to indent, and tab width is set
-to 4. Here, <tab> represents a tab and '.' a space:
-<programlisting>
-1: <tab><tab>foobar("hello",
-2: <tab><tab>......."world");
-</programlisting>
-When indenting line 2, the <function>indent()</function> function returns [8, 15]. As result, two
-tabs are inserted to indent to column 8, and 7 spaces are added to align the
-second parameter under the first, so that it stays aligned if the file is viewed
-with a different tab width.
-</para>
-
-<para>
-A default KDE installation ships &kappname; with several indenters. The
-corresponding JavaScript source code can be found in <filename>$KDEDIR/share/apps/katepart/script/indentation</filename>.
-</para>
-
-<para>
-Developing an indenter requires to reload the scripts to see whether the changes
-behave appropriately. Instead of restarting the application, simply switch to
-the command line and invoke the command <command>reload-scripts</command>.
-</para>
-
-<para>
-If you develop useful scripts please consider contributing to the &kappname; Project
-by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>.
-</para>
-
-</sect3>
-</sect2>
-
-<sect2 id="advanced-editing-tools-scripting-command-line">
-<title>Command Line Scripts</title>
-
-<para>
-As it is hard to satisfy everyone's needs, &kappname; supports little helper tools
-for quick text manipulation through the
-<link linkend="advanced-editing-tools-commandline">built-in command line</link>.
-For instance, the command
-<command>sort</command> is implemented as script. This section explains how to create
-<filename>*.js</filename> files to extend &kappname; with arbitrary helper scripts.
-</para>
-
-<para>
-Command line scripts are located in the same folder as indentation scripts.
-So as first step, create a new <filename>*.js</filename> file called
-<filename>myutils.js</filename> in the local home folder
-<filename>$KDEHOME/share/apps/katepart/script/commands</filename>.
-</para>
-
-<sect3 id="advanced-editing-tools-scripting-command-line-header">
-<title>The Command Line Script Header</title>
-<para>
-The header of each command line script is embedded in a comment and is of the
-following form
-
-<programlisting>
-/* kate-script
- * author: Example Name <example.name at some.address.org>
- * license: BSD
- * revision: 1
- * kate-version: 3.4
- * functions: sort, format-paragraph
- * i18n-catalog: mycatalog
- *
- * A line without colon ':' stops header parsing. That is, you can add optional
- * text here such as a detailed license.
- */
-</programlisting>
-
-Each entry is explained in detail now:
-<itemizedlist>
-<listitem><para><literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.</para></listitem>
-<listitem><para><literal>author</literal> [optional]: The author's name and contact information.</para></listitem>
-<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.</para></listitem>
-<listitem><para><literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.</para></listitem>
-<listitem><para><literal>kate-version</literal> [required]: Minimal required &kappname; version.</para></listitem>
-<listitem><para><literal>functions</literal> [required]: Comma separated list of commands in the script.</para></listitem>
-<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem>
-</itemizedlist>
-</para>
-
-<para>
-&kappname; reads all pairs of the form
-<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote>
-until it cannot find a colon
-anymore. This implies that the header can contain arbitrary text such as a license
-as shown in the example. The value of the key functions is a comma separated list
-of command line commands. This means a single script contains an arbitrary amount
-of command line commands. Each function is available through &kappname;'s
-<link linkend="advanced-editing-tools-commandline">built-in command line</link>.
-</para>
-</sect3>
-
-<sect3 id="advanced-editing-tools-scripting-command-line-body">
-<title>The Script Source Code</title>
-
-<para>
-All functions specified in the header have to be implemented in the script.
-For instance, the script file from the example above needs to implement the two
-functions <command>sort</command> and <command>format-paragraph</command>.
-All functions have the following syntax:
-
-<programlisting>
-// required katepart js libraries, e.g. range.js if you use Range
-require ("range.js");
-
-function <name>(arg1, arg2, ...)
-{
- // ... implementation, see also: Scripting API
-}
-</programlisting>
-</para>
-
-<para>
-Arguments in the command line are passed to the function as
-<parameter>arg1</parameter>, <parameter>arg2</parameter>, etc.
-In order to provide documentation for each command, simply implement the
-'<function>help</function>' function as follows:
-
-<programlisting>
-function help(cmd)
-{
- if (cmd == "sort") {
- return i18n("Sort the selected text.");
- } else if (cmd == "...") {
- // ...
- }
-}
-</programlisting>
-
-Executing <command>help sort</command> in the command line then calls this help function with
-the argument <parameter>cmd</parameter> set to the given command, i.e.
-<parameter>cmd == "sort"</parameter>. &kappname; then presents the returned text as
-documentation to the user. Make sure to
-<link linkend="advanced-editing-tools-scripting-api-i18n">translate the strings</link>.
-</para>
-
-<sect4 id="advanced-editing-tools-scripting-command-line-shortcuts">
-<title>Binding Shortcuts</title>
-<para>In order to be able to assign shortcuts, the script needs to provide a
-function called <literal>action</literal> as follows:
-<programlisting>
-function action(cmd)
-{
- var a = new Object();
- if (cmd == "sort") {
- a.text = i18n("Sort Selected Text");
- a.icon = "";
- a.category = "";
- a.interactive = false;
- a.shortcut = "";
- } else if (cmd == "moveLinesDown") {
- // same for next action
- }
- return a;
-}
-</programlisting>
-The parameter <literal>cmd</literal> of the function specifies the command for
-which a shortcut is requested. There are several fields you have to specify in
-the returned javascript object:
-<itemizedlist>
-<listitem><para><literal>a.text</literal> [required]: The text appears in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>. Make sure to use <literal>i18n</literal> for translation.</para></listitem>
-<listitem><para><literal>a.icon</literal> [optional]: The icon appears next to the text in the menu. All KDE icon names can be used here.</para></listitem>
-<listitem><para><literal>a.category</literal> [optional]: If a category is specified, the script appears in a submenu. Make sure to use <literal>i18n</literal> for translation.</para></listitem>
-<listitem><para><literal>a.interactive</literal> [optional]: If the script needs user input, set this to <literal>true</literal>.</para></listitem>
-<listitem><para><literal>a.shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: Ctrl+Alt+t. See the <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum">Qt documentation</ulink> for further details.</para></listitem>
-</itemizedlist>
-</para>
-
-
-<para>
-Developing a command line script requires to reload the scripts to see whether
-the changes behave appropriately. Instead of restarting the application, simply
-switch to the command line and invoke the command <command>reload-scripts</command>.
-</para>
-
-<para>
-If you develop useful scripts please consider contributing to the &kappname; Project
-by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>.
-</para>
-
-</sect4>
-</sect3>
-</sect2>
-
-<sect2 id="advanced-editing-tools-scripting-api">
-<title>Scripting API</title>
-
-<para>
-The scripting API presented here is available in all scripts, i.e. indentation
-scripts and command line commands.
-The <classname>Cursor</classname> and <classname>Range</classname> are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>.
-If you want to use them in your script, which is required to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the needed library by using:
-
-<programlisting>
-// required katepart js libraries, e.g. range.js if you use Range
-require ("range.js");
-</programlisting>
-</para>
-
-<para>
-To extend the standard scripting API with own functions and prototypes simply
-create a new file in the KDE's local configuration folder
-<filename>$KDEHOME/share/apps/katepart/libraries</filename> and include it into your script using:
-
-<programlisting>
-require ("myscriptnamehere.js");
-</programlisting>
-
-</para>
-
-<para>
-To extend existing prototypes like <classname>Cursor</classname> or
-<classname>Range</classname>, the recommended way is to
-<emphasis>not</emphasis> modify the global <filename>*.js</filename> files.
-Instead, change the <classname>Cursor</classname> prototype in JavaScript after the <filename>cursor.js</filename> is included into your
-script via <literal>require</literal>.
-</para>
-
-<sect3 id="advanced-editing-tools-scripting-api-prototypes">
-<title>Cursors and Ranges</title>
-
-<para>
-As &kappname; is a text editor, all the scripting API is based on cursors and
-ranges whenever possible. A Cursor is a simple <literal>(line, column)</literal>
-tuple representing a text position in the document. A Range spans text from a
-starting cursor position to an ending cursor position. The API is explained in
-detail in the next sections.
-</para>
-
-<sect4 id="advanced-editing-tools-scripting-api-cursors">
-<title>The Cursor Prototype</title>
-
-<variablelist><varlistentry>
-<term><synopsis>
-Cursor();
-</synopsis></term>
-<listitem><para>
-Constructor. Returns a Cursor at position <literal>(0, 0)</literal>.</para>
-<para>Example: <function>var cursor = new Cursor();</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Constructor. Returns a Cursor at position (line, column).
-</para>
-<para>Example: <function>var cursor = new Cursor(3, 42);</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor(<parameter>Cursor <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Copy constructor. Returns a copy of the cursor <replaceable>other</replaceable>.
-</para>
-<para>Example: <function>var copy = new Cursor(other);</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor Cursor.clone();
-</synopsis></term>
-<listitem><para>
-Returns a clone of the cursor.</para>
-<para>Example: <function>var clone = cursor.clone();</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor.setPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Sets the cursor position to <replaceable>line</replaceable> and <replaceable>column</replaceable>.</para>
-<para>
-Since: KDE 4.11
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Cursor.isValid();
-</synopsis></term>
-<listitem><para>
-Check whether the cursor is valid. The cursor is invalid, if line and/or
-column are set to <literal>-1</literal>.
-</para>
-<para>
-Example: <function>var valid = cursor.isValid();</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor Cursor.invalid();
-</synopsis></term>
-<listitem><para>
-Returns an new invalid cursor located at <literal>(-1, -1)</literal>.
-</para>
-<para>Example: <function>var invalidCursor = cursor.invalid();</function>
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-int Cursor.compareTo(<parameter>Cursor <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Compares this cursor to the cursor <replaceable>other</replaceable>. Returns
-<itemizedlist>
-<listitem><para><literal>-1</literal>, if this cursor is located before the cursor <replaceable>other</replaceable>,</para></listitem>
-<listitem><para><literal>0</literal>, if both cursors equal and</para></listitem>
-<listitem><para><literal>+1</literal>, if this cursor is located after the cursor <replaceable>other</replaceable>.</para></listitem>
-</itemizedlist>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Cursor.equals(<parameter>Cursor <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if this cursor and the cursor <replaceable>other</replaceable> are
-equal, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String Cursor.toString();
-</synopsis></term>
-<listitem><para>
-Returns the cursor as a string of the form <quote><literal>Cursor(line, column)</literal></quote>.
-</para></listitem>
-</varlistentry></variablelist>
-
-</sect4>
-
-
-<sect4 id="advanced-editing-tools-scripting-api-ranges">
-<title>The Range Prototype</title>
-
-<variablelist><varlistentry>
-<term><synopsis>
-Range();
-</synopsis></term>
-<listitem><para>
-Constructor. Calling <literal>new Range()</literal> returns a Range at (0, 0) - (0, 0).
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range(<parameter>Cursor <replaceable>start</replaceable></parameter>, <parameter>Cursor <replaceable>end</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Constructor. Calling <literal>new Range(<replaceable>start</replaceable>, <replaceable>end</replaceable>)</literal> returns the Range (<replaceable>start</replaceable>, <replaceable>end</replaceable>).
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>startColumn</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>, <parameter>int <replaceable>endColumn</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Constructor. Calling <literal>new Range(<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>, <replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>)</literal>
-returns the Range from (<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>) to (<replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>).
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range(<parameter>Range <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Copy constructor. Returns a copy of Range <replaceable>other</replaceable>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range Range.clone();
-</synopsis></term>
-<listitem><para>
-Returns a clone of the range.
-</para>
-<para>Example: <function>var clone = range.clone();</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.isEmpty();
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if the start and end cursors are equal.
-</para>
-<para>Example: <function>var empty = range.isEmpty();</function>
-</para>
-<para>
-Since: KDE 4.11
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.isValid();
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if both start and end cursor are valid, otherwise <literal>false</literal>.
-</para>
-<para>Example: <function>var valid = range.isValid();</function>
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range Range.invalid();
-</synopsis></term>
-<listitem><para>
-Returns the Range from (-1, -1) to (-1, -1).
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.contains(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if this range contains the cursor position, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.contains(<parameter>Range <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if this range contains the Range <replaceable>other</replaceable>,
-otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.containsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the half open interval
-<literal>[start.column, end.column)</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.containsLine(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the half open interval
-<literal>[start.line, end.line)</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.overlaps(<parameter>Range <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if this range and the range <replaceable>other</replaceable> share
-a common region, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.overlapsLine(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the interval
-<literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.overlapsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the interval
-<literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.onSingleLine();
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if the range starts and ends at the same line,
-i.e. if <replaceable>Range.start.line == Range.end.line</replaceable>.
-</para>
-<para>
-Since: KDE 4.9
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool Range.equals(<parameter>Range <replaceable>other</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if this range and the Range <replaceable>other</replaceable> are
-equal, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String Range.toString();
-</synopsis></term>
-<listitem><para>
-Returns the range as a string of the form <quote><literal>Range(Cursor(line, column), Cursor(line, column))</literal></quote>.
-</para></listitem>
-</varlistentry></variablelist>
-
-</sect4>
-</sect3>
-
-<sect3 id="advanced-editing-tools-scripting-api-global">
-<title>Global Functions</title>
-<para>This section lists all global functions.</para>
-
-
-<sect4 id="advanced-editing-tools-scripting-api-includes">
-<title>Reading & Including Files</title>
-
-<variablelist><varlistentry>
-<term><synopsis>
-String read(<parameter>String <replaceable>file</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/files</literal> directory and return its content as a string.
-</para></listitem>
-</varlistentry></variablelist>
-
-<variablelist><varlistentry>
-<term><synopsis>
-void require(<parameter>String <replaceable>file</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/libraries</literal> directory and evaluate it.
-<literal>require</literal> is internally guarded against multiple inclusions of the same <replaceable>file</replaceable>.
-</para>
-<para>
- Since: KDE 4.10
-</para>
-</listitem>
-</varlistentry></variablelist>
-
-</sect4>
-
-<sect4 id="advanced-editing-tools-scripting-api-debug">
-<title>Debugging</title>
-
-<variablelist><varlistentry>
-<term><synopsis>
-void debug(<parameter>String <replaceable>text</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Prints <replaceable>text</replaceable> to <literal>stdout</literal> in the
-console launching the application.
-</para></listitem>
-</varlistentry></variablelist>
-
-</sect4>
-
-<sect4 id="advanced-editing-tools-scripting-api-i18n">
-<title>Translation</title>
-
-<para>In order to support full localization, there are several functions to translate
-strings in scripts, namely <literal>i18n</literal>, <literal>i18nc</literal>,
-<literal>i18np</literal> and <literal>i18ncp</literal>. These functions behave
-exactly like <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n">
-KDE's translation functions</ulink>.
-</para>
-
-<para>The translation functions translate the wrapped strings through KDE's
-translation system to the language used in the application. Strings in scripts
-being developed in the official &kappname; sources are automatically extracted and
-translatable. In other words, as a &kappname; developer you do not have to bother with
-message extraction and translation. However, for 3rd-party scripts developed
-outside of KDE, you have to extract and translate the messages yourself. Along
-with your scripts you have to also distribute a translation catalog, that
-includes all translated strings. Further, your script header then must
-explicitly state the catalog to load by specifying
-<literal>i18n-catalog</literal>.
-</para>
-
-<variablelist><varlistentry>
-<term><synopsis>
-void i18n(<parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
-</synopsis></term>
-<listitem><para>
-Translates <replaceable>text</replaceable> into the language used by the application.
-The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
-replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-void i18nc(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
-</synopsis></term>
-<listitem><para>
-Translates <replaceable>text</replaceable> into the language used by the
-application. Additionally, the string <replaceable>context</replaceable> is
-visible to translators so they can provide a better translation.
-The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
-replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-void i18np(<parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
-</synopsis></term>
-<listitem><para>
-Translates either <replaceable>singular</replaceable> or
-<replaceable>plural</replaceable> into the language used by the application,
-depending on the given <replaceable>number</replaceable>.
-The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
-replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-void i18ncp(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
-</synopsis></term>
-<listitem><para>
-Translates either <replaceable>singular</replaceable> or
-<replaceable>plural</replaceable> into the language used by the application,
-depending on the given <replaceable>number</replaceable>. Additionally, the
-string <replaceable>context</replaceable> is visible to translators so they
-can provide a better translation. The arguments <replaceable>arg1</replaceable>,
-..., are optional and used to replace the placeholders <literal>%1</literal>,
-<literal>%2</literal>, etc.</para></listitem>
-</varlistentry></variablelist>
-
-</sect4>
-</sect3>
-
-<sect3 id="advanced-editing-tools-scripting-api-view">
-<title>The View API</title>
-<para>Whenever a script is being executed, there is a global variable
-<quote><literal>view</literal></quote> representing the current active editor
-view. The following is a list of all available View functions.
-
-<variablelist><varlistentry>
-<term><synopsis>
-<function>Cursor view.cursorPosition()</function>
-</synopsis></term>
-<listitem><para>Returns the current cursor position in the view.</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.setCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-void view.setCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Set the current cursor position to either (line, column) or to the given cursor.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor view.virtualCursorPosition();
-</synopsis></term>
-<listitem><para>
-Returns the virtual cursor position with each tab counting the corresponding amount of spaces depending on the current tab width.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.setVirtualCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-void view.setVirtualCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Set the current virtual cursor position to (line, column) or to the given cursor.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String view.selectedText();
-</synopsis></term>
-<listitem><para>
-Returns the selected text. If no text is selected, the returned string is empty.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool view.hasSelection();
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if the view has selected text, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Range view.selection();
-</synopsis></term>
-<listitem><para>
-Returns the selected text range. The returned range is invalid if there is no
-selected text.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.setSelection(<parameter>Range <replaceable>range</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Set the selected text to the given range.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.removeSelectedText();
-</synopsis></term>
-<listitem><para>
-Remove the selected text. If the view does not have any selected text, this
-does nothing.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.selectAll();
-</synopsis></term>
-<listitem><para>
-Selects the entire text in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void view.clearSelection();
-</synopsis></term>
-<listitem><para>
-Clears the text selection without removing the text.
-</para></listitem>
-</varlistentry></variablelist>
-</para>
-</sect3>
-
-<sect3 id="advanced-editing-tools-scripting-api-document">
-<title>The Document API</title>
-<para>
-Whenever a script is being executed, there is a global variable
-<quote><literal>document</literal></quote> representing the current active
-document. The following is a list of all available Document functions.
-
-<variablelist><varlistentry>
-<term><synopsis>
-String document.fileName();
-</synopsis></term>
-<listitem><para>
-Returns the document's filename or an empty string for unsaved text buffers.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.url();
-</synopsis></term>
-<listitem><para>
-Returns the document's full url or an empty string for unsaved text buffers.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.mimeType();
-</synopsis></term>
-<listitem><para>
-Returns the document's mime type or the mime type <literal>application/octet-stream</literal>
-if no appropriate mime type could be found.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.encoding();
-</synopsis></term>
-<listitem><para>
-Returns the currently used encoding to save the file.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-String document.highlightingMode();
-</synopsis></term>
-<listitem><para>
-Returns the global highlighting mode used for the whole document.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-String document.highlightingModeAt(<parameter>Cursor <replaceable>pos</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Returns the highlighting mode used at the given position in the document.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-Array document.embeddedHighlightingModes();
-</synopsis></term>
-<listitem><para>
-Returns an array of highlighting modes embedded in this document.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><synopsis>
-bool document.isModified();
-</synopsis></term>
-<listitem><para>
-Returns <literal>true</literal>, if the document has unsaved changes (modified), otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.text();
-</synopsis></term>
-<listitem><para>
-Returns the entire content of the document in a single text string. Newlines
-are marked with the newline character <quote><literal>\n</literal></quote>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.text(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>);
-String document.text(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>);
-String document.text(<parameter>Range <replaceable>range</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the text in the given range. It is recommended to use the cursor
- and range based version for better readability of the source code.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.line(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the given text line as string. The string is empty if the requested
- line is out of range.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.wordAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-String document.wordAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the word at the given cursor position.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term>
-<synopsis>
-Range document.wordRangeAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-Range document.wordRangeAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis>
-</term>
-<listitem><para>
-Return the range of the word at the given cursor position. The returned range
-is invalid (see Range.isValid()), if the text position is after the end of a
-line. If there is no word at the given cursor, an empty range is returned.
-</para>
-<para>
- Since: KDE 4.9
-</para>
-</listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.charAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-String document.charAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the character at the given cursor position.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.firstChar(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the first character in the given <replaceable>line</replaceable>
- that is not a whitespace. The first character is at column 0. If the line
- is empty or only contains whitespace characters, the returned string is
- empty.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.lastChar(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the last character in the given <replaceable>line</replaceable>
- that is not a whitespace. If the line is empty or only contains whitespace
- characters, the returned string is empty.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isSpace(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isSpace(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the character at the given cursor position is a whitespace,
- otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.matchesAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
-bool document.matchesAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the given <replaceable>text</replaceable> matches at the
- corresponding cursor position, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.startsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the line starts with <replaceable>text</replaceable>, otherwise <literal>false</literal>.
- The argument <replaceable>skipWhiteSpaces</replaceable> controls whether leading whitespaces are ignored.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.endsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the line ends with <replaceable>text</replaceable>, otherwise <literal>false</literal>.
- The argument <replaceable>skipWhiteSpaces</replaceable> controls whether trailing whitespaces are ignored.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.setText(<parameter>String <replaceable>text</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Sets the entire document text.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.clear();
-</synopsis></term>
-<listitem><para>
- Removes the entire text in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.truncate(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.truncate(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Truncate the given line at the given column or cursor position. Returns <literal>true</literal>
- on success, or <literal>false</literal> if the given line is not part of the document range.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.insertText(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
-bool document.insertText(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Inserts the <replaceable>text</replaceable> at the given cursor position.
- Returns <literal>true</literal> on success, or <literal>false</literal>, if the document is in read-only mode.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.removeText(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>);
-bool document.removeText(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>);
-bool document.removeText(<parameter>Range <replaceable>range</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Removes the text in the given range. Returns <literal>true</literal> on success, or <literal>false</literal>, if
- the document is in read-only mode.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.insertLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Inserts text in the given line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the
- document is in read-only mode or the line is not in the document range.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.removeLine(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Removes the given text line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the
- document is in read-only mode or the line is not in the document range.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.wrapLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.wrapLine(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
-Wraps the line at the given cursor position. Returns <literal>true</literal> on success,
-otherwise <literal>false</literal>, e.g. if line < 0.
-</para>
-<para>
- Since: KDE 4.9
-</para>
-</listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void document.joinLines(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Joins the lines from <replaceable>startLine</replaceable> to <replaceable>endLine</replaceable>.
- Two succeeding text lines are always separated with a single space.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.lines();
-</synopsis></term>
-<listitem><para>
- Returns the amount of lines in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.length();
-</synopsis></term>
-<listitem><para>
- Returns the number of characters in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.lineLength(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the <replaceable>line</replaceable>'s length.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void document.editBegin();
-</synopsis></term>
-<listitem><para>
- Starts an edit group for undo/redo grouping. Make sure to always call
- <function>editEnd()</function> as often as you call
- <function>editBegin()</function>. Calling <function>editBegin()</function>
- internally uses a reference counter, i.e., this call can be nested.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-void document.editEnd();
-</synopsis></term>
-<listitem><para>
- Ends an edit group. The last call of <function>editEnd()</function> (i.e.
- the one for the first call of <function>editBegin()</function>) finishes
- the edit step.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.firstColumn(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the first non-whitespace column in the given <replaceable>line</replaceable>.
- If there are only whitespaces in the line, the return value is <literal>-1</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.lastColumn(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the last non-whitespace column in the given <replaceable>line</replaceable>.
- If there are only whitespaces in the line, the return value is <literal>-1</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.prevNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-int document.prevNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the column with a non-whitespace characters starting at the given
- cursor position and searching backwards.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.nextNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-int document.nextNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the column with a non-whitespace characters starting at the given
- cursor position and searching forwards.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.prevNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the next non-empty line containing non-whitespace characters
- searching backwards.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.nextNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the next non-empty line containing non-whitespace characters
- searching forwards.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isInWord(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the
- given <replaceable>attribute</replaceable> can be part of a word, otherwise
- <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.canBreakAt(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the given
- <replaceable>attribute</replaceable> is suited to wrap a line, otherwise
- <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.canComment(<parameter>int <replaceable>startAttribute</replaceable></parameter>, <parameter>int <replaceable>endAttribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if a range starting and ending with the given attributes is
- suited to be commented out, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.commentMarker(<parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the comment marker for single line comments for a given <replaceable>attribute</replaceable>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.commentStart(<parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the comment marker for the start of multi-line comments for a given
- <replaceable>attribute</replaceable>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.commentEnd(<parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the comment marker for the end of multi-line comments for a given
- <replaceable>attribute</replaceable>.
-</para></listitem>
-</varlistentry>
-
-
-
-<varlistentry>
-<term><synopsis>
-int document.attribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-int document.attribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the attribute at the given cursor position.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isAttribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
-bool document.isAttribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute at the given cursor position equals <replaceable>attribute</replaceable>,
- otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.attributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-String document.attributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the attribute name as human readable text. This equals to the
- <literal>itemData</literal> name in the syntax highlighting files.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isAttributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>);
-bool document.isAttributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute name at a certain cursor position matches
- the given <replaceable>name</replaceable>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.variable(<parameter>String <replaceable>key</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the value of the requested document variable <replaceable>key</replaceable>.
- If the document variable does not exist, the return value is an empty string.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-String document.setVariable(<parameter>String <replaceable>key</replaceable></parameter>, <parameter>String <replaceable>value</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Set the value of the requested document variable <replaceable>key</replaceable>.
- Returns the value of set variable.
-</para>
-<para>
- See also: <link linkend="config-variables">Kate document variables</link>
-</para>
-<para>
- Since: KDE 4.8
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.firstVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the virtual column of the first non-whitespace character in the given
- line or <literal>-1</literal>, if the line is empty or contains only whitespace characters.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.lastVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the virtual column of the last non-whitespace character in the given
- line or <literal>-1</literal>, if the line is empty or contains only whitespace characters.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.toVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-int document.toVirtualColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-Cursor document.toVirtualCursor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Converts the given <quote>real</quote> cursor position to a virtual cursor position,
- either returning an int or a Cursor object.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.fromVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>virtualColumn</replaceable></parameter>);
-int document.fromVirtualColumn(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>);
-Cursor document.fromVirtualCursor(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Converts the given virtual cursor position to a <quote>real</quote> cursor position,
- either returning an int or a Cursor object.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor document.anchor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>);
-Cursor document.anchor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Searches backward for the given character starting from the given cursor.
- As example, if '(' is passed as character, this function will return the
- position of the opening '('. This reference counting, i.e. other '(...)'
- are ignored.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor document.rfind(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>);
-Cursor document.rfind(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>);
-</synopsis></term>
-<listitem><para>
- Find backward the given text with the appropriate <replaceable>attribute</replaceable>.
- The argument <replaceable>attribute</replaceable> is ignored if it is set to
- <literal>-1</literal>. The returned cursor is invalid, if the text could not be found.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-int document.defStyleNum(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-int document.defStyleNum(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns the default style used at the given cursor position.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isCode(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isCode(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute at the given cursor position is not equal
- to all of the following styles: <literal>dsComment</literal>,
- <literal>dsString</literal>, <literal>dsRegionMarker</literal>,
- <literal>dsChar</literal>, <literal>dsOthers</literal>.
-</para></listitem>
-</varlistentry>
-
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isComment(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isComment(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute of the character at the cursor position
- is <literal>dsComment</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isString(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isString(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute of the character at the cursor position
- is <literal>dsString</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isRegionMarker(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isRegionMarker(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute of the character at the cursor position
- is <literal>dsRegionMarker</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isChar(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isChar(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute of the character at the cursor position
- is <literal>dsChar</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isOthers(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the attribute of the character at the cursor position
- is <literal>dsOthers</literal>, otherwise <literal>false</literal>.
-</para></listitem>
-</varlistentry></variablelist>
-</para>
-
-</sect3>
-</sect2>
-</sect1>
</chapter>
diff --git a/doc/kate/development.docbook b/doc/kate/development.docbook
index fabd96c..aa23036 100644
--- a/doc/kate/development.docbook
+++ b/doc/kate/development.docbook
@@ -26,6 +26,1712 @@ enhancements with the world!</para>
<sect1 id="dev-scripting">
<title>Scripting with JavaScript</title>
+<para>
+Since &kappname; 3.4 in KDE 4.4 the &kappname; editor component is easily extensible by
+writing scripts. The scripting language is ECMAScript (widely known as JavaScript).
+&kappname; supports two kinds of scripts: indentation and command line scripts.
+</para>
+
+<sect2 id="dev-scripting-indentation">
+<title>Indentation Scripts</title>
+
+<para>
+Indentation scripts - also referred as indenters - automatically indent the
+source code while typing text. As example, after hitting the return-key code
+the indentation level often increases.
+</para>
+
+<para>
+The following sections describe step by step how to create the skeleton for a
+simple indenter. As first step, create a new <filename>*.js</filename> file
+called e.g. <filename>javascript.js</filename> in the local home folder
+<filename>$KDEHOME/share/apps/katepart/script/indentation</filename>.
+</para>
+
+<sect3 id="dev-scripting-indentation-header">
+<title>The Indentation Script Header</title>
+<para>
+The header of the file <filename>javascript.js</filename> is embedded in a
+comment and is of the following form
+
+<programlisting>
+/* kate-script
+ * name: JavaScript
+ * author: Example Name <example.name at some.address.org>
+ * license: BSD
+ * revision: 1
+ * kate-version: 3.4
+ * required-syntax-style: javascript
+ * indent-languages: javascript
+ * priority: 0
+ * i18n-catalog: mycatalog
+ *
+ * A line without colon ':' stops header parsing. That is, you can add optional
+ * text here such as a detailed license.
+ */
+</programlisting>
+
+Each entry is explained in detail now:
+<itemizedlist>
+<listitem><para>
+<literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.
+</para></listitem>
+<listitem><para>
+<literal>name</literal> [required]: This is the indenter name that appears in the menu
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Indentation</guimenuitem></menuchoice>
+and in the configuration dialog.
+</para></listitem>
+<listitem><para>
+<literal>author</literal> [optional]: The author's name and contact information.
+</para></listitem>
+<listitem><para>
+<literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.
+</para></listitem>
+<listitem><para>
+<literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.
+</para></listitem>
+<listitem><para>
+<literal>kate-version</literal> [required]: Minimal required &kappname; version.
+</para></listitem>
+<listitem><para>
+<literal>required-syntax-style</literal> [optional]: Comma separated list of required syntax highlighting styles. This is important for indenters that rely on specific highlight information in the document. If a required syntax style is specified, the indenter is available only when the appropriate highlighter is active. This prevents <quote>undefined behavior</quote> caused by using the indenter without the expected highlighting schema. For instance, the Ruby indenter makes use of this in the files <filename>ruby.js</filename> and <filename>ruby.xml</filename>.
+</para></listitem>
+<listitem><para>
+<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, e.g.: c++, java.
+</para></listitem>
+<listitem><para>
+<literal>priority</literal> [optional]: If several indenters are suited for a certain highlighted file, the priority decides which indenter is chosen as default indenter.
+</para></listitem>
+<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party indenters.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+&kappname; reads all pairs of the form
+<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote>
+until it cannot find a colon anymore. This implies that the header can contain
+arbitrary text such as a license as shown in the example.
+</para>
+
+</sect3>
+
+<sect3 id="dev-scripting-indentation-body">
+<title>The Indenter Source Code</title>
+<para>
+Having specified the header this section explains how the indentation scripting
+itself works. The basic skeleton of the body looks like this:
+
+<programlisting>
+// required katepart js libraries, e.g. range.js if you use Range
+require ("range.js");
+
+triggerCharacters = "{}/:;";
+function indent(line, indentWidth, ch)
+{
+ // called for each newline (ch == '\n') and all characters specified in
+ // the global variable triggerCharacters. When calling <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>
+ // the variable ch is empty, i.e. ch == ''.
+ //
+ // see also: Scripting API
+ return -2;
+}
+</programlisting>
+
+The function <function>indent()</function> has three parameters:
+<itemizedlist>
+<listitem><para><literal>line</literal>: the line that has to be indented</para></listitem>
+<listitem><para><literal>indentWidth</literal>: the indentation width in amount of spaces</para></listitem>
+<listitem><para><literal>ch</literal>: either a newline character (<literal>ch == '\n'</literal>), the trigger character specified in <literal>triggerCharacters</literal> or empty if the user invoked the action <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>.</para></listitem>
+</itemizedlist>
+The return value of the <function>indent()</function> function specifies how
+the line will be indented. If the return value is a simple integer number, it
+is interpreted as follows:
+<itemizedlist>
+<listitem><para>return value <literal>-2</literal>: do nothing</para></listitem>
+<listitem><para>return value <literal>-1</literal>: keep indentation (searches for previous non-blank line)</para></listitem>
+<listitem><para>return value <literal> 0</literal>: numbers >= 0 specify the indentation depth in spaces</para></listitem>
+</itemizedlist>
+Alternatively, an array of two elements can be returned:
+<itemizedlist>
+<listitem><para><literal>return [ indent, align ];</literal></para></listitem>
+</itemizedlist>
+In this case, the first element is the indentation depth like above with the
+same meaning of the special values. However, the second element is an absolute
+value representing a column for <quote>alignment</quote>. If this value is higher than the
+indent value, the difference represents a number of spaces to be added after
+the indentation of the first parameter. Otherwise, the second number is ignored.
+Using tabs and spaces for indentation is often referred to as <quote>mixed mode</quote>.
+</para>
+
+<para>
+Consider the following example: Assume using tabs to indent, and tab width is set
+to 4. Here, <tab> represents a tab and '.' a space:
+<programlisting>
+1: <tab><tab>foobar("hello",
+2: <tab><tab>......."world");
+</programlisting>
+When indenting line 2, the <function>indent()</function> function returns [8, 15]. As result, two
+tabs are inserted to indent to column 8, and 7 spaces are added to align the
+second parameter under the first, so that it stays aligned if the file is viewed
+with a different tab width.
+</para>
+
+<para>
+A default KDE installation ships &kappname; with several indenters. The
+corresponding JavaScript source code can be found in <filename>$KDEDIR/share/apps/katepart/script/indentation</filename>.
+</para>
+
+<para>
+Developing an indenter requires to reload the scripts to see whether the changes
+behave appropriately. Instead of restarting the application, simply switch to
+the command line and invoke the command <command>reload-scripts</command>.
+</para>
+
+<para>
+If you develop useful scripts please consider contributing to the &kappname; Project
+by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>.
+</para>
+
+</sect3>
+</sect2>
+
+<sect2 id="dev-scripting-command-line">
+<title>Command Line Scripts</title>
+
+<para>
+As it is hard to satisfy everyone's needs, &kappname; supports little helper tools
+for quick text manipulation through the
+<link linkend="advanced-editing-tools-commandline">built-in command line</link>.
+For instance, the command
+<command>sort</command> is implemented as script. This section explains how to create
+<filename>*.js</filename> files to extend &kappname; with arbitrary helper scripts.
+</para>
+
+<para>
+Command line scripts are located in the same folder as indentation scripts.
+So as first step, create a new <filename>*.js</filename> file called
+<filename>myutils.js</filename> in the local home folder
+<filename>$KDEHOME/share/apps/katepart/script/commands</filename>.
+</para>
+
+<sect3 id="dev-scripting-command-line-header">
+<title>The Command Line Script Header</title>
+<para>
+The header of each command line script is embedded in a comment and is of the
+following form
+
+<programlisting>
+/* kate-script
+ * author: Example Name <example.name at some.address.org>
+ * license: BSD
+ * revision: 1
+ * kate-version: 3.4
+ * functions: sort, format-paragraph
+ * i18n-catalog: mycatalog
+ *
+ * A line without colon ':' stops header parsing. That is, you can add optional
+ * text here such as a detailed license.
+ */
+</programlisting>
+
+Each entry is explained in detail now:
+<itemizedlist>
+<listitem><para><literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.</para></listitem>
+<listitem><para><literal>author</literal> [optional]: The author's name and contact information.</para></listitem>
+<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.</para></listitem>
+<listitem><para><literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.</para></listitem>
+<listitem><para><literal>kate-version</literal> [required]: Minimal required &kappname; version.</para></listitem>
+<listitem><para><literal>functions</literal> [required]: Comma separated list of commands in the script.</para></listitem>
+<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+&kappname; reads all pairs of the form
+<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote>
+until it cannot find a colon
+anymore. This implies that the header can contain arbitrary text such as a license
+as shown in the example. The value of the key functions is a comma separated list
+of command line commands. This means a single script contains an arbitrary amount
+of command line commands. Each function is available through &kappname;'s
+<link linkend="advanced-editing-tools-commandline">built-in command line</link>.
+</para>
+</sect3>
+
+<sect3 id="dev-scripting-command-line-body">
+<title>The Script Source Code</title>
+
+<para>
+All functions specified in the header have to be implemented in the script.
+For instance, the script file from the example above needs to implement the two
+functions <command>sort</command> and <command>format-paragraph</command>.
+All functions have the following syntax:
+
+<programlisting>
+// required katepart js libraries, e.g. range.js if you use Range
+require ("range.js");
+
+function <name>(arg1, arg2, ...)
+{
+ // ... implementation, see also: Scripting API
+}
+</programlisting>
+</para>
+
+<para>
+Arguments in the command line are passed to the function as
+<parameter>arg1</parameter>, <parameter>arg2</parameter>, etc.
+In order to provide documentation for each command, simply implement the
+'<function>help</function>' function as follows:
+
+<programlisting>
+function help(cmd)
+{
+ if (cmd == "sort") {
+ return i18n("Sort the selected text.");
+ } else if (cmd == "...") {
+ // ...
+ }
+}
+</programlisting>
+
+Executing <command>help sort</command> in the command line then calls this help function with
+the argument <parameter>cmd</parameter> set to the given command, i.e.
+<parameter>cmd == "sort"</parameter>. &kappname; then presents the returned text as
+documentation to the user. Make sure to
+<link linkend="dev-scripting-api-i18n">translate the strings</link>.
+</para>
+
+<sect4 id="dev-scripting-command-line-shortcuts">
+<title>Binding Shortcuts</title>
+<para>In order to be able to assign shortcuts, the script needs to provide a
+function called <literal>action</literal> as follows:
+<programlisting>
+function action(cmd)
+{
+ var a = new Object();
+ if (cmd == "sort") {
+ a.text = i18n("Sort Selected Text");
+ a.icon = "";
+ a.category = "";
+ a.interactive = false;
+ a.shortcut = "";
+ } else if (cmd == "moveLinesDown") {
+ // same for next action
+ }
+ return a;
+}
+</programlisting>
+The parameter <literal>cmd</literal> of the function specifies the command for
+which a shortcut is requested. There are several fields you have to specify in
+the returned javascript object:
+<itemizedlist>
+<listitem><para><literal>a.text</literal> [required]: The text appears in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>. Make sure to use <literal>i18n</literal> for translation.</para></listitem>
+<listitem><para><literal>a.icon</literal> [optional]: The icon appears next to the text in the menu. All KDE icon names can be used here.</para></listitem>
+<listitem><para><literal>a.category</literal> [optional]: If a category is specified, the script appears in a submenu. Make sure to use <literal>i18n</literal> for translation.</para></listitem>
+<listitem><para><literal>a.interactive</literal> [optional]: If the script needs user input, set this to <literal>true</literal>.</para></listitem>
+<listitem><para><literal>a.shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: Ctrl+Alt+t. See the <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum">Qt documentation</ulink> for further details.</para></listitem>
+</itemizedlist>
+</para>
+
+
+<para>
+Developing a command line script requires to reload the scripts to see whether
+the changes behave appropriately. Instead of restarting the application, simply
+switch to the command line and invoke the command <command>reload-scripts</command>.
+</para>
+
+<para>
+If you develop useful scripts please consider contributing to the &kappname; Project
+by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>.
+</para>
+
+</sect4>
+</sect3>
+</sect2>
+
+<sect2 id="dev-scripting-api">
+<title>Scripting API</title>
+
+<para>
+The scripting API presented here is available in all scripts, i.e. indentation
+scripts and command line commands.
+The <classname>Cursor</classname> and <classname>Range</classname> are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>.
+If you want to use them in your script, which is required to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the needed library by using:
+
+<programlisting>
+// required katepart js libraries, e.g. range.js if you use Range
+require ("range.js");
+</programlisting>
+</para>
+
+<para>
+To extend the standard scripting API with own functions and prototypes simply
+create a new file in the KDE's local configuration folder
+<filename>$KDEHOME/share/apps/katepart/libraries</filename> and include it into your script using:
+
+<programlisting>
+require ("myscriptnamehere.js");
+</programlisting>
+
+</para>
+
+<para>
+To extend existing prototypes like <classname>Cursor</classname> or
+<classname>Range</classname>, the recommended way is to
+<emphasis>not</emphasis> modify the global <filename>*.js</filename> files.
+Instead, change the <classname>Cursor</classname> prototype in JavaScript after the <filename>cursor.js</filename> is included into your
+script via <literal>require</literal>.
+</para>
+
+<sect3 id="dev-scripting-api-prototypes">
+<title>Cursors and Ranges</title>
+
+<para>
+As &kappname; is a text editor, all the scripting API is based on cursors and
+ranges whenever possible. A Cursor is a simple <literal>(line, column)</literal>
+tuple representing a text position in the document. A Range spans text from a
+starting cursor position to an ending cursor position. The API is explained in
+detail in the next sections.
+</para>
+
+<sect4 id="dev-scripting-api-cursors">
+<title>The Cursor Prototype</title>
+
+<variablelist><varlistentry>
+<term><synopsis>
+Cursor();
+</synopsis></term>
+<listitem><para>
+Constructor. Returns a Cursor at position <literal>(0, 0)</literal>.</para>
+<para>Example: <function>var cursor = new Cursor();</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Constructor. Returns a Cursor at position (line, column).
+</para>
+<para>Example: <function>var cursor = new Cursor(3, 42);</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor(<parameter>Cursor <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Copy constructor. Returns a copy of the cursor <replaceable>other</replaceable>.
+</para>
+<para>Example: <function>var copy = new Cursor(other);</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor Cursor.clone();
+</synopsis></term>
+<listitem><para>
+Returns a clone of the cursor.</para>
+<para>Example: <function>var clone = cursor.clone();</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor.setPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Sets the cursor position to <replaceable>line</replaceable> and <replaceable>column</replaceable>.</para>
+<para>
+Since: KDE 4.11
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Cursor.isValid();
+</synopsis></term>
+<listitem><para>
+Check whether the cursor is valid. The cursor is invalid, if line and/or
+column are set to <literal>-1</literal>.
+</para>
+<para>
+Example: <function>var valid = cursor.isValid();</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor Cursor.invalid();
+</synopsis></term>
+<listitem><para>
+Returns an new invalid cursor located at <literal>(-1, -1)</literal>.
+</para>
+<para>Example: <function>var invalidCursor = cursor.invalid();</function>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+int Cursor.compareTo(<parameter>Cursor <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Compares this cursor to the cursor <replaceable>other</replaceable>. Returns
+<itemizedlist>
+<listitem><para><literal>-1</literal>, if this cursor is located before the cursor <replaceable>other</replaceable>,</para></listitem>
+<listitem><para><literal>0</literal>, if both cursors equal and</para></listitem>
+<listitem><para><literal>+1</literal>, if this cursor is located after the cursor <replaceable>other</replaceable>.</para></listitem>
+</itemizedlist>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Cursor.equals(<parameter>Cursor <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if this cursor and the cursor <replaceable>other</replaceable> are
+equal, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String Cursor.toString();
+</synopsis></term>
+<listitem><para>
+Returns the cursor as a string of the form <quote><literal>Cursor(line, column)</literal></quote>.
+</para></listitem>
+</varlistentry></variablelist>
+
+</sect4>
+
+
+<sect4 id="dev-scripting-api-ranges">
+<title>The Range Prototype</title>
+
+<variablelist><varlistentry>
+<term><synopsis>
+Range();
+</synopsis></term>
+<listitem><para>
+Constructor. Calling <literal>new Range()</literal> returns a Range at (0, 0) - (0, 0).
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range(<parameter>Cursor <replaceable>start</replaceable></parameter>, <parameter>Cursor <replaceable>end</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Constructor. Calling <literal>new Range(<replaceable>start</replaceable>, <replaceable>end</replaceable>)</literal> returns the Range (<replaceable>start</replaceable>, <replaceable>end</replaceable>).
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>startColumn</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>, <parameter>int <replaceable>endColumn</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Constructor. Calling <literal>new Range(<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>, <replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>)</literal>
+returns the Range from (<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>) to (<replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>).
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range(<parameter>Range <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Copy constructor. Returns a copy of Range <replaceable>other</replaceable>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range Range.clone();
+</synopsis></term>
+<listitem><para>
+Returns a clone of the range.
+</para>
+<para>Example: <function>var clone = range.clone();</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.isEmpty();
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if the start and end cursors are equal.
+</para>
+<para>Example: <function>var empty = range.isEmpty();</function>
+</para>
+<para>
+Since: KDE 4.11
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.isValid();
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if both start and end cursor are valid, otherwise <literal>false</literal>.
+</para>
+<para>Example: <function>var valid = range.isValid();</function>
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range Range.invalid();
+</synopsis></term>
+<listitem><para>
+Returns the Range from (-1, -1) to (-1, -1).
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.contains(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if this range contains the cursor position, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.contains(<parameter>Range <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if this range contains the Range <replaceable>other</replaceable>,
+otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.containsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the half open interval
+<literal>[start.column, end.column)</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.containsLine(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the half open interval
+<literal>[start.line, end.line)</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.overlaps(<parameter>Range <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if this range and the range <replaceable>other</replaceable> share
+a common region, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.overlapsLine(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the interval
+<literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.overlapsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the interval
+<literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.onSingleLine();
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if the range starts and ends at the same line,
+i.e. if <replaceable>Range.start.line == Range.end.line</replaceable>.
+</para>
+<para>
+Since: KDE 4.9
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool Range.equals(<parameter>Range <replaceable>other</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if this range and the Range <replaceable>other</replaceable> are
+equal, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String Range.toString();
+</synopsis></term>
+<listitem><para>
+Returns the range as a string of the form <quote><literal>Range(Cursor(line, column), Cursor(line, column))</literal></quote>.
+</para></listitem>
+</varlistentry></variablelist>
+
+</sect4>
+</sect3>
+
+<sect3 id="dev-scripting-api-global">
+<title>Global Functions</title>
+<para>This section lists all global functions.</para>
+
+
+<sect4 id="dev-scripting-api-includes">
+<title>Reading & Including Files</title>
+
+<variablelist><varlistentry>
+<term><synopsis>
+String read(<parameter>String <replaceable>file</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/files</literal> directory and return its content as a string.
+</para></listitem>
+</varlistentry></variablelist>
+
+<variablelist><varlistentry>
+<term><synopsis>
+void require(<parameter>String <replaceable>file</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/libraries</literal> directory and evaluate it.
+<literal>require</literal> is internally guarded against multiple inclusions of the same <replaceable>file</replaceable>.
+</para>
+<para>
+ Since: KDE 4.10
+</para>
+</listitem>
+</varlistentry></variablelist>
+
+</sect4>
+
+<sect4 id="dev-scripting-api-debug">
+<title>Debugging</title>
+
+<variablelist><varlistentry>
+<term><synopsis>
+void debug(<parameter>String <replaceable>text</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Prints <replaceable>text</replaceable> to <literal>stdout</literal> in the
+console launching the application.
+</para></listitem>
+</varlistentry></variablelist>
+
+</sect4>
+
+<sect4 id="dev-scripting-api-i18n">
+<title>Translation</title>
+
+<para>In order to support full localization, there are several functions to translate
+strings in scripts, namely <literal>i18n</literal>, <literal>i18nc</literal>,
+<literal>i18np</literal> and <literal>i18ncp</literal>. These functions behave
+exactly like <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n">
+KDE's translation functions</ulink>.
+</para>
+
+<para>The translation functions translate the wrapped strings through KDE's
+translation system to the language used in the application. Strings in scripts
+being developed in the official &kappname; sources are automatically extracted and
+translatable. In other words, as a &kappname; developer you do not have to bother with
+message extraction and translation. However, for 3rd-party scripts developed
+outside of KDE, you have to extract and translate the messages yourself. Along
+with your scripts you have to also distribute a translation catalog, that
+includes all translated strings. Further, your script header then must
+explicitly state the catalog to load by specifying
+<literal>i18n-catalog</literal>.
+</para>
+
+<variablelist><varlistentry>
+<term><synopsis>
+void i18n(<parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
+</synopsis></term>
+<listitem><para>
+Translates <replaceable>text</replaceable> into the language used by the application.
+The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
+replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+void i18nc(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
+</synopsis></term>
+<listitem><para>
+Translates <replaceable>text</replaceable> into the language used by the
+application. Additionally, the string <replaceable>context</replaceable> is
+visible to translators so they can provide a better translation.
+The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
+replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+void i18np(<parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
+</synopsis></term>
+<listitem><para>
+Translates either <replaceable>singular</replaceable> or
+<replaceable>plural</replaceable> into the language used by the application,
+depending on the given <replaceable>number</replaceable>.
+The arguments <replaceable>arg1</replaceable>, ..., are optional and used to
+replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+void i18ncp(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...);
+</synopsis></term>
+<listitem><para>
+Translates either <replaceable>singular</replaceable> or
+<replaceable>plural</replaceable> into the language used by the application,
+depending on the given <replaceable>number</replaceable>. Additionally, the
+string <replaceable>context</replaceable> is visible to translators so they
+can provide a better translation. The arguments <replaceable>arg1</replaceable>,
+..., are optional and used to replace the placeholders <literal>%1</literal>,
+<literal>%2</literal>, etc.</para></listitem>
+</varlistentry></variablelist>
+
+</sect4>
+</sect3>
+
+<sect3 id="dev-scripting-api-view">
+<title>The View API</title>
+<para>Whenever a script is being executed, there is a global variable
+<quote><literal>view</literal></quote> representing the current active editor
+view. The following is a list of all available View functions.
+
+<variablelist><varlistentry>
+<term><synopsis>
+<function>Cursor view.cursorPosition()</function>
+</synopsis></term>
+<listitem><para>Returns the current cursor position in the view.</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.setCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+void view.setCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Set the current cursor position to either (line, column) or to the given cursor.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor view.virtualCursorPosition();
+</synopsis></term>
+<listitem><para>
+Returns the virtual cursor position with each tab counting the corresponding amount of spaces depending on the current tab width.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.setVirtualCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+void view.setVirtualCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Set the current virtual cursor position to (line, column) or to the given cursor.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String view.selectedText();
+</synopsis></term>
+<listitem><para>
+Returns the selected text. If no text is selected, the returned string is empty.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool view.hasSelection();
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if the view has selected text, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Range view.selection();
+</synopsis></term>
+<listitem><para>
+Returns the selected text range. The returned range is invalid if there is no
+selected text.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.setSelection(<parameter>Range <replaceable>range</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Set the selected text to the given range.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.removeSelectedText();
+</synopsis></term>
+<listitem><para>
+Remove the selected text. If the view does not have any selected text, this
+does nothing.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.selectAll();
+</synopsis></term>
+<listitem><para>
+Selects the entire text in the document.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void view.clearSelection();
+</synopsis></term>
+<listitem><para>
+Clears the text selection without removing the text.
+</para></listitem>
+</varlistentry></variablelist>
+</para>
+</sect3>
+
+<sect3 id="dev-scripting-api-document">
+<title>The Document API</title>
+<para>
+Whenever a script is being executed, there is a global variable
+<quote><literal>document</literal></quote> representing the current active
+document. The following is a list of all available Document functions.
+
+<variablelist><varlistentry>
+<term><synopsis>
+String document.fileName();
+</synopsis></term>
+<listitem><para>
+Returns the document's filename or an empty string for unsaved text buffers.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.url();
+</synopsis></term>
+<listitem><para>
+Returns the document's full url or an empty string for unsaved text buffers.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.mimeType();
+</synopsis></term>
+<listitem><para>
+Returns the document's mime type or the mime type <literal>application/octet-stream</literal>
+if no appropriate mime type could be found.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.encoding();
+</synopsis></term>
+<listitem><para>
+Returns the currently used encoding to save the file.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+String document.highlightingMode();
+</synopsis></term>
+<listitem><para>
+Returns the global highlighting mode used for the whole document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+String document.highlightingModeAt(<parameter>Cursor <replaceable>pos</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Returns the highlighting mode used at the given position in the document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+Array document.embeddedHighlightingModes();
+</synopsis></term>
+<listitem><para>
+Returns an array of highlighting modes embedded in this document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+bool document.isModified();
+</synopsis></term>
+<listitem><para>
+Returns <literal>true</literal>, if the document has unsaved changes (modified), otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.text();
+</synopsis></term>
+<listitem><para>
+Returns the entire content of the document in a single text string. Newlines
+are marked with the newline character <quote><literal>\n</literal></quote>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.text(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>);
+String document.text(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>);
+String document.text(<parameter>Range <replaceable>range</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the text in the given range. It is recommended to use the cursor
+ and range based version for better readability of the source code.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.line(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the given text line as string. The string is empty if the requested
+ line is out of range.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.wordAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+String document.wordAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the word at the given cursor position.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>
+<synopsis>
+Range document.wordRangeAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+Range document.wordRangeAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis>
+</term>
+<listitem><para>
+Return the range of the word at the given cursor position. The returned range
+is invalid (see Range.isValid()), if the text position is after the end of a
+line. If there is no word at the given cursor, an empty range is returned.
+</para>
+<para>
+ Since: KDE 4.9
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.charAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+String document.charAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the character at the given cursor position.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.firstChar(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the first character in the given <replaceable>line</replaceable>
+ that is not a whitespace. The first character is at column 0. If the line
+ is empty or only contains whitespace characters, the returned string is
+ empty.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.lastChar(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the last character in the given <replaceable>line</replaceable>
+ that is not a whitespace. If the line is empty or only contains whitespace
+ characters, the returned string is empty.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isSpace(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isSpace(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the character at the given cursor position is a whitespace,
+ otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.matchesAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
+bool document.matchesAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the given <replaceable>text</replaceable> matches at the
+ corresponding cursor position, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.startsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the line starts with <replaceable>text</replaceable>, otherwise <literal>false</literal>.
+ The argument <replaceable>skipWhiteSpaces</replaceable> controls whether leading whitespaces are ignored.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.endsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the line ends with <replaceable>text</replaceable>, otherwise <literal>false</literal>.
+ The argument <replaceable>skipWhiteSpaces</replaceable> controls whether trailing whitespaces are ignored.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.setText(<parameter>String <replaceable>text</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Sets the entire document text.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.clear();
+</synopsis></term>
+<listitem><para>
+ Removes the entire text in the document.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.truncate(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.truncate(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Truncate the given line at the given column or cursor position. Returns <literal>true</literal>
+ on success, or <literal>false</literal> if the given line is not part of the document range.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.insertText(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
+bool document.insertText(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Inserts the <replaceable>text</replaceable> at the given cursor position.
+ Returns <literal>true</literal> on success, or <literal>false</literal>, if the document is in read-only mode.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.removeText(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>);
+bool document.removeText(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>);
+bool document.removeText(<parameter>Range <replaceable>range</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Removes the text in the given range. Returns <literal>true</literal> on success, or <literal>false</literal>, if
+ the document is in read-only mode.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.insertLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Inserts text in the given line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the
+ document is in read-only mode or the line is not in the document range.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.removeLine(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Removes the given text line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the
+ document is in read-only mode or the line is not in the document range.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.wrapLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.wrapLine(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Wraps the line at the given cursor position. Returns <literal>true</literal> on success,
+otherwise <literal>false</literal>, e.g. if line < 0.
+</para>
+<para>
+ Since: KDE 4.9
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void document.joinLines(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Joins the lines from <replaceable>startLine</replaceable> to <replaceable>endLine</replaceable>.
+ Two succeeding text lines are always separated with a single space.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.lines();
+</synopsis></term>
+<listitem><para>
+ Returns the amount of lines in the document.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.length();
+</synopsis></term>
+<listitem><para>
+ Returns the number of characters in the document.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.lineLength(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the <replaceable>line</replaceable>'s length.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void document.editBegin();
+</synopsis></term>
+<listitem><para>
+ Starts an edit group for undo/redo grouping. Make sure to always call
+ <function>editEnd()</function> as often as you call
+ <function>editBegin()</function>. Calling <function>editBegin()</function>
+ internally uses a reference counter, i.e., this call can be nested.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+void document.editEnd();
+</synopsis></term>
+<listitem><para>
+ Ends an edit group. The last call of <function>editEnd()</function> (i.e.
+ the one for the first call of <function>editBegin()</function>) finishes
+ the edit step.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.firstColumn(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the first non-whitespace column in the given <replaceable>line</replaceable>.
+ If there are only whitespaces in the line, the return value is <literal>-1</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.lastColumn(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the last non-whitespace column in the given <replaceable>line</replaceable>.
+ If there are only whitespaces in the line, the return value is <literal>-1</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.prevNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+int document.prevNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the column with a non-whitespace characters starting at the given
+ cursor position and searching backwards.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.nextNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+int document.nextNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the column with a non-whitespace characters starting at the given
+ cursor position and searching forwards.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.prevNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the next non-empty line containing non-whitespace characters
+ searching backwards.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.nextNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the next non-empty line containing non-whitespace characters
+ searching forwards.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isInWord(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the
+ given <replaceable>attribute</replaceable> can be part of a word, otherwise
+ <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.canBreakAt(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the given
+ <replaceable>attribute</replaceable> is suited to wrap a line, otherwise
+ <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.canComment(<parameter>int <replaceable>startAttribute</replaceable></parameter>, <parameter>int <replaceable>endAttribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if a range starting and ending with the given attributes is
+ suited to be commented out, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.commentMarker(<parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the comment marker for single line comments for a given <replaceable>attribute</replaceable>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.commentStart(<parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the comment marker for the start of multi-line comments for a given
+ <replaceable>attribute</replaceable>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.commentEnd(<parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the comment marker for the end of multi-line comments for a given
+ <replaceable>attribute</replaceable>.
+</para></listitem>
+</varlistentry>
+
+
+
+<varlistentry>
+<term><synopsis>
+int document.attribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+int document.attribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the attribute at the given cursor position.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isAttribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
+bool document.isAttribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute at the given cursor position equals <replaceable>attribute</replaceable>,
+ otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.attributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+String document.attributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the attribute name as human readable text. This equals to the
+ <literal>itemData</literal> name in the syntax highlighting files.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isAttributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>);
+bool document.isAttributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute name at a certain cursor position matches
+ the given <replaceable>name</replaceable>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.variable(<parameter>String <replaceable>key</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the value of the requested document variable <replaceable>key</replaceable>.
+ If the document variable does not exist, the return value is an empty string.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+String document.setVariable(<parameter>String <replaceable>key</replaceable></parameter>, <parameter>String <replaceable>value</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Set the value of the requested document variable <replaceable>key</replaceable>.
+ Returns the value of set variable.
+</para>
+<para>
+ See also: <link linkend="config-variables">Kate document variables</link>
+</para>
+<para>
+ Since: KDE 4.8
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.firstVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the virtual column of the first non-whitespace character in the given
+ line or <literal>-1</literal>, if the line is empty or contains only whitespace characters.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.lastVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the virtual column of the last non-whitespace character in the given
+ line or <literal>-1</literal>, if the line is empty or contains only whitespace characters.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.toVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+int document.toVirtualColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+Cursor document.toVirtualCursor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Converts the given <quote>real</quote> cursor position to a virtual cursor position,
+ either returning an int or a Cursor object.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.fromVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>virtualColumn</replaceable></parameter>);
+int document.fromVirtualColumn(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>);
+Cursor document.fromVirtualCursor(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Converts the given virtual cursor position to a <quote>real</quote> cursor position,
+ either returning an int or a Cursor object.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor document.anchor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>);
+Cursor document.anchor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Searches backward for the given character starting from the given cursor.
+ As example, if '(' is passed as character, this function will return the
+ position of the opening '('. This reference counting, i.e. other '(...)'
+ are ignored.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+Cursor document.rfind(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>);
+Cursor document.rfind(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>);
+</synopsis></term>
+<listitem><para>
+ Find backward the given text with the appropriate <replaceable>attribute</replaceable>.
+ The argument <replaceable>attribute</replaceable> is ignored if it is set to
+ <literal>-1</literal>. The returned cursor is invalid, if the text could not be found.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+int document.defStyleNum(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+int document.defStyleNum(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns the default style used at the given cursor position.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isCode(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isCode(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute at the given cursor position is not equal
+ to all of the following styles: <literal>dsComment</literal>,
+ <literal>dsString</literal>, <literal>dsRegionMarker</literal>,
+ <literal>dsChar</literal>, <literal>dsOthers</literal>.
+</para></listitem>
+</varlistentry>
+
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isComment(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isComment(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute of the character at the cursor position
+ is <literal>dsComment</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isString(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isString(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute of the character at the cursor position
+ is <literal>dsString</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isRegionMarker(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isRegionMarker(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute of the character at the cursor position
+ is <literal>dsRegionMarker</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isChar(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isChar(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute of the character at the cursor position
+ is <literal>dsChar</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><synopsis>
+bool document.isOthers(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
+bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+ Returns <literal>true</literal>, if the attribute of the character at the cursor position
+ is <literal>dsOthers</literal>, otherwise <literal>false</literal>.
+</para></listitem>
+</varlistentry></variablelist>
+</para>
+
+</sect3>
+</sect2>
+
</sect1>
<sect1 id="dev-part">
diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook
index 2d7fb4a..36ab004 100644
--- a/doc/kate/menus.docbook
+++ b/doc/kate/menus.docbook
@@ -864,7 +864,7 @@ enabled by default.</para>
</menuchoice></term>
<listitem><para>This opens a tool view that allows you to run Javascript code
interactively. For more information, see
-<link linkend="advanced-editing-tools-scripting">Extending &kate; with Scripts</link>.
+<link linkend="dev-scripting">Extending &kate; with Scripts</link>.
</para></listitem>
</varlistentry>
@@ -1363,7 +1363,7 @@ the endianness (byte order) of a text file or stream, for more information see
<guisubmenu>Scripts</guisubmenu></menuchoice></term>
<listitem>
<para>This submenu contains a list of all scripted actions. The list can easily be
-modified by <link linkend="advanced-editing-tools-scripting-command-line">writing
+modified by <link linkend="dev-scripting-command-line">writing
own scripts</link>. This way, &kate; can be extended with user-defined tools.
</para>
@@ -1396,7 +1396,7 @@ that with <computeroutput><div></div></computeroutput>.
</menuchoice></term>
<listitem><para>
Wraps the selected text with the tag provided on the
-<link linkend="advanced-editing-tools-scripting-command-line">command line</link>.
+<link linkend="dev-scripting-command-line">command line</link>.
</para></listitem>
</varlistentry>
diff --git a/doc/kwrite/menus.docbook b/doc/kwrite/menus.docbook
index 55235a3..5a88bc4 100644
--- a/doc/kwrite/menus.docbook
+++ b/doc/kwrite/menus.docbook
@@ -520,7 +520,7 @@ Component Command Line</ulink>.</para>
</menuchoice> (Power user mode)</term>
<listitem><para>This opens a tool view that allows you to run Javascript code
interactively. For more information, see
-<ulink url="help:/kate/advanced-editing-tools-scripting.html">Extending &kate; with Scripts</ulink>
+<ulink url="help:/kate/dev-scripting.html">Extending &kate; with Scripts</ulink>
</para></listitem>
</varlistentry>
diff --git a/part/snippet/editsnippet.cpp b/part/snippet/editsnippet.cpp
index 08c6de0..5090e06 100644
--- a/part/snippet/editsnippet.cpp
+++ b/part/snippet/editsnippet.cpp
@@ -196,7 +196,7 @@ void EditSnippet::slotSnippetDocumentation()
void EditSnippet::slotScriptDocumentation()
{
- KToolInvocation::invokeHelp("advanced-editing-tools-scripting-api", "kate");
+ KToolInvocation::invokeHelp("dev-scripting-api", "kate");
}
void EditSnippet::reject()
More information about the kde-doc-english
mailing list