[kde-doc-english] [kate/frameworks] doc: add stub development chapter to katepart
T.C. Hollingsworth
tchollingsworth at gmail.com
Sun Feb 23 03:16:11 UTC 2014
Git commit 74956b9dfe3c9125165086433f12f2955313ac6f by T.C. Hollingsworth.
Committed on 19/02/2014 at 23:57.
Pushed by hollingsworth into branch 'frameworks'.
add stub development chapter to katepart
M +2 -1808 doc/kate/development.docbook
C +8 -43 doc/katepart/development.docbook [from: doc/kate/development.docbook - 097% similarity]
http://commits.kde.org/kate/74956b9dfe3c9125165086433f12f2955313ac6f
diff --git a/doc/kate/development.docbook b/doc/kate/development.docbook
index 0f23b0d..415c563 100644
--- a/doc/kate/development.docbook
+++ b/doc/kate/development.docbook
@@ -26,1820 +26,14 @@ 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 an example, after hitting the return key
-the indentation level often increases.
-</para>
-
-<para>
-The following sections describe step by step how to create the skeleton for a
-simple indenter. As a first step, create a new <filename>*.js</filename> file
-called ⪚ <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 a 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]: Minimum 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, ⪚: 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 number 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 as 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 reloading 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 a 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 a 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 a 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]: Minimum 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 number
-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, &ie;
-<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://qt-project.org/doc/qt-4.8/qt.html#Key-enum">Qt documentation</ulink> for further details.</para></listitem>
-</itemizedlist>
-</para>
-
-
-<para>
-Developing a command line script requires reloading 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 to all scripts, &ie; indentation
-scripts and command line commands.
-The <classname>Cursor</classname> and <classname>Range</classname> classes are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>.
-If you want to use them in your script, which needs to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the necessary 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 your own functions and prototypes simply
-create a new file in &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 a 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,
-&ie; 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>, ⪚ 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 number of lines in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isLineModified(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if <replaceable>line</replaceable> currently contains unsaved data.
-</para>
-<para>
- Since: &kde; 5.0
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isLineSaved(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if <replaceable>line</replaceable> was changed, but the document was saved.
- Hence, the line currently does not contain any unsaved data.
-</para>
-<para>
- Since: &kde; 5.0
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.isLineTouched(<parameter>int <replaceable>line</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if <replaceable>line</replaceable> currently contains unsaved data or was changed before.
-</para>
-<para>
- Since: &kde; 5.0
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool document.findTouchedLine(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>bool <replaceable>down</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Search for the next touched line starting at <replaceable>line</replaceable>.
- The search is performed either upwards or downwards depending on the search direction specified in <replaceable>down</replaceable>.
-</para>
-<para>
- Since: &kde; 5.0
-</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, &ie;, 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> (&ie;
- 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 character 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 character 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>
-Range document.documentRange();
-</synopsis></term>
-<listitem><para>
- Returns a range that encompasses the whole document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-Cursor documentEnd();
-</synopsis></term>
-<listitem><para>
- Returns a cursor positioned at the last column of the last line in the document.
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><synopsis>
-bool isValidTextPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
-bool isValidTextPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
-</synopsis></term>
-<listitem><para>
- Returns <literal>true</literal>, if the given cursor position is positioned at a valid text position.
- A text position is valid only if it locate at the start, in the middle, or the end of a valid line.
- Further, a text position is invalid if it is located in a Unicode surrogate.
-</para><para>
- Since: &kde; 5.0
-</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 is equal 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 the 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 an example, if '(' is passed as character, this function will return the
- position of the opening '('. This reference counting, &ie; 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 searching backwards 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>
+<!--FIXME: link to katepart js api doc-->
</sect1>
<sect1 id="dev-part">
<title>Editor Component Extensions</title>
-<para><link linkend="editor-component-plugins">Editor Component Extensions</link>
-extend KatePart, the Advanced Text Editor component used within many &kde;
-applications, such as &kate;, &kwrite;, Kile, and KDevelop. Creating an Editor
-Component Plugin will allow you to extend the editor's functionality in any and
-all of these programs.</para>
-
-<para>To get started, see the
-<ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins">
-KTextEditor Plugin Tutorial on &kde; TechBase</ulink>. For even more, see the
-<ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins_Advanced">
-Advanced Tutorial, also on TechBase</ulink>.</para>
-
-<para>You can find the
-<ulink url="http://api.kde.org/4.10-api/kdelibs-apidocs/interfaces/ktexteditor/html/">
-complete API documentation in the &kde; API Reference</ulink>.</para>
+<!--FIXME: link to katepart ece doc-->
</sect1>
diff --git a/doc/kate/development.docbook b/doc/katepart/development.docbook
similarity index 97%
copy from doc/kate/development.docbook
copy to doc/katepart/development.docbook
index 0f23b0d..69b0090 100644
--- a/doc/kate/development.docbook
+++ b/doc/katepart/development.docbook
@@ -5,21 +5,18 @@
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</chapterinfo>
-<title>Extending &kate;</title>
+<title>Extending &katepart;</title>
<sect1 id="dev-intro">
<title>Introduction</title>
-<para>Like any advanced text editor, &kate; offers a variety of ways to extend
-its functionality. You can <link linkend="dev-scripting">write simple scripts
-to add functionality with JavaScript</link>, add enhanced functionality to the
-editor component with <link linkend="dev-part">Editor Component Plugins</link>,
-or add even more functionality to the editor itself with
-<link linkend="dev-app">&kate; Application Plugins written in C++</link> or
-<link linkend="dev-pate">&pate; Plugins written in Python</link>. Finally, once
-you have extended &kate;, you are welcome to
-<ulink url="http://kate-editor.org/join-us/">join us</ulink> and share your
-enhancements with the world!</para>
+<para>Like any advanced text editor component, &katepart; offers a variety of
+ways to extend its functionality. You can <link linkend="dev-scripting">write
+simple scripts to add functionality with JavaScript</link> or add enhanced
+functionality to the editor component with <link linkend="dev-part">Editor
+Component Plugins</link>. Finally, once you have extended &katepart;, you are
+welcome to <ulink url="http://kate-editor.org/join-us/">join us</ulink>
+and share your enhancements with the world!</para>
</sect1>
@@ -1843,36 +1840,4 @@ complete API documentation in the &kde; API Reference</ulink>.</para>
</sect1>
-<sect1 id="dev-app">
-<title>&kate; (C++) Application Plugins</title>
-
-<para><link linkend="kate-application-plugins">Kate Application Plugins</link>
-extend the functionality of the &kate; editor itself in any way you can imagine,
-using the same programming language &kate; is written in, C++.</para>
-
-<para>To get started, see the
-<ulink url="http://kate-editor.org/2004/01/06/writing-a-kate-plugin/">Writing a
-&kate; Plugin tutorial on the &kate; website</ulink>. There is also
-<ulink url="http://quickgit.kde.org/?p=kate.git&a=tree&f=addons%2Fkate%2Fhelloworld">
-a classic <quote>Hello, world!</quote> example plugin included with the &kate;
-source code</ulink>.</para>
-
-</sect1>
-
-<sect1 id="dev-pate">
-<title>&pate; Python Plugins</title>
-
-<para><link linkend="pate">&pate; Plugins</link> also allow you to extend the
-functionality of &kate; in any way you like, using the Python programming
-language.</para>
-
-<para>To get started, see the
-<ulink url="http://kate-editor.org/2012/07/01/python-plugin-developer-guide-part-1/">
-Python plugin developer guide on the &kate; website</ulink>.</para>
-
-<para>You can also access the API reference in the
-<link linkend="pate-config">&pate; Configuration</link> screen.</para>
-
-</sect1>
-
</chapter>
More information about the kde-doc-english
mailing list