Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

19 files changed, 7923 insertions, 0 deletions

diff --git a/doc/kate/Makefile.am b/doc/kate/Makefile.am
new file mode 100644
index 000000000..17a314c39
--- /dev/null
+++ b/doc/kate/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+KDE_MANS = AUTO
diff --git a/doc/kate/TODO b/doc/kate/TODO
new file mode 100644
index 000000000..d41ed4b80
--- /dev/null
+++ b/doc/kate/TODO
@@ -0,0 +1,6 @@
+Fill empty sections.
+Rewrite intro chapter.
+Write regexp appendix.
+Add Misc Tools chapter, ao Find in Files.
+Go over everything and make sure it reflects the practial truuth ;)
+Add links to foreign documentation.
diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook
new file mode 100644
index 000000000..b9b0cda91
--- /dev/null
+++ b/doc/kate/advanced.docbook
@@ -0,0 +1,1242 @@
+<chapter id="advanced-editing-tools">
+<chapterinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>Advanced Editing Tools</title>
+
+<sect1 id="advanced-editing-tools-comment">
+
+<title>Comment/Uncomment</title>
+
+<para>The Comment and Uncomment commands, available from the
+<guimenu>Tools</guimenu> menu allow you to add or remove comment
+markers to the selection, or the current line if no text is selected,
+if comments are supported by the format of the text you are
+editing.</para>
+
+<para>The rules for how commenting is done are defined in the syntax
+definitions, so if syntax highlighting is not used, commenting/uncommenting
+is not possible. </para>
+
+<para>Some formats define single line comment markers, some multiline
+markers and some both.  If multiline markers are not available,
+commenting out a selection that does not fully include its last line
+is not possible.</para>
+
+<para>If a single line marker is available, commenting single lines is
+preferred where applicable, as this helps to avoid problems with
+nested comments.</para>
+
+<para>When removing comment markers, no uncommented text should be
+selected. When removing multiline comment markers from a selection,
+any whitespace outside the comment markers is ignored.</para>
+
+<para><indexterm><primary>comment</primary></indexterm>
+To place comment markers, use the
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice>
+menu item or the related keyboard shortcut sequence, default is
+<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para>
+
+<para><indexterm><primary>uncomment</primary></indexterm>
+To remove comment markers, use the
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>
+menu item or the related keyboard shortcut, default is <keycombo
+action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para>
+
+</sect1>
+
+<sect1 id="advanced-editing-tools-commandline">
+<title>The Editor Component Command Line</title>
+
+<para>Kate's editor component has an internal command line, allowing you to
+perform various actions from a minimal GUI. The command line is a text entry
+in the bottom of the editor area, to show it select
+<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice>
+or use the shortcut (default is
+<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides
+a set of commands as documented below, and additional commands can be provided
+by plugins.</para>
+
+<para>To execute a command, type the comand then press the return key. The
+command line will indicate wether it succeded and possibly display a message. If
+you entered the command line by pressing <keycap>F7</keycap> it will
+automatically hide after a few seconds. To clear the message and enter a new
+command, press <keycap>F7</keycap> again.</para>
+
+<para>The command line has a built-in help system, issue the command
+<command>help</command> to get started. To see a list of all available commands
+issue <command>help list</command>, to view help for a specific command, do
+<command>help <replaceable>command</replaceable></command>.</para>
+
+<para>The command line has a built in history, so you can reuse commands already
+typed. To navigate the history, use the <keycap>Up</keycap> and
+<keycap>Down</keycap> keys. When showing historical commands, the argument part
+of the command will be selected, allowing you to easily overwrite the
+arguments.</para>
+
+<sect2 id="advanced-editing-tools-commandline-commands">
+<title>Standard Command Line Commands</title>
+
+<sect3 id="advanced-editing-tools-commandline-commands-configure">
+<title>Commands for Configuring the Editor</title>
+
+<para>These commands are provided by the editor component, and allows you to
+configure the active document and view only. This is handy if you want to use
+a setting different from the default settings, for example for indentation.
+</para>
+
+<variablelist>
+<title>Argument types</title>
+
+<varlistentry>
+<term>BOOLEAN</term>
+<listitem><para>This is used with commands that turns things on or off.
+Legal values are <userinput>on</userinput>, <userinput>off</userinput>,
+<userinput>true</userinput>, <userinput>false</userinput>,
+<userinput>1</userinput> or <userinput>0</userinput></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>INTEGER</term>
+<listitem><para>An integer number</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>STRING</term>
+<listitem><para>A string</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<variablelist>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER width</arg></cmdsynopsis></term>
+<listitem><para>Sets the tab width to the number <userinput>width</userinput></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER width</arg></cmdsynopsis></term>
+<listitem><para>Sets the indentation width to the number
+<userinput>width</userinput>. Used only if you are indenting with
+spaces.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER width</arg></cmdsynopsis></term>
+<listitem><para>Sets the line width for hard wrapping to
+<userinput>width</userinput>. This is used if you are having your text wrapped
+automatically.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN enable</arg>
+</cmdsynopsis></term>
+<listitem><para>Sets the visibility of the icon border.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>Sets the visibility of the folding markers pane.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>Sets the visibility of the line numbers pane.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>If enabled, tabs are replaced with spaces as you type.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>If enabled, trailing whitespace are removed whenever the cursor
+leaves a line.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>If enabled, TAB characters and trailing whitespace will be
+visualized by a small dot.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>If enabled, the editor will indent with
+<option>indent-width</option> spaces for each indentation level, rather than
+with one TAB character.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>If enabled, kate will use a mix of TAB and spaces for
+indentation. Each indentation level will be <option>indent-width</option> wide,
+and more indentation levels will be optimized to use as many TAB characters as
+possible.</para>
+<para>When executed, this command will additionally set space indentation enabled,
+and if the indent width is unspecified it will be set to half of the
+<option>tab-width</option> for the document at the time of execution.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN 
+enable</arg></cmdsynopsis></term>
+<listitem><para>Enables dynamic word wrap according to
+<userinput>enable</userinput></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable
+</arg></cmdsynopsis></term>
+<listitem><para>When enabled, tabs will be replaced with whitespace whenever
+ the document is saved.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN enable</arg></cmdsynopsis></term>
+<listitem><para>When enabled, trailing space will be removed from each line
+whenever the document is saved.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-indent-mode</command><arg>name</arg></cmdsynopsis></term>
+<listitem><para>Sets the autoindentation mode to <userinput>name</userinput>.
+If <userinput>name</userinput> is not known, the mode is set to 'none'. Valid
+modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>set-highlight</command><arg>highlight</arg></cmdsynopsis></term>
+<listitem><para>Sets the syntax highlighting system for the document. The
+argument must be a valid highlight name, as seen in the
+<menuchoice><guimenu>Tools</guimenu><guisubmenu>Highlighting</guisubmenu></menuchoice>
+menu. This command provides an autocompletion list for its
+argument.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+<sect3 id="advanced-editing-tools-commandline-commands-edit">
+<title>Commands for editing</title>
+
+<para>These commands modify the current document.</para>
+
+<variablelist>
+<varlistentry>
+<term><cmdsynopsis><command>indent</command></cmdsynopsis></term>
+<listitem><para>Indents the selected lines or the current line.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term>
+<listitem><para>Unindents the selected lines or current line.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term>
+<listitem><para>Cleans up the indentation of the selected lines or current line
+according to the indentation settings in the document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>comment</command></cmdsynopsis></term>
+<listitem><para>Inserts comment markers to make the selection or selected lines
+or current line a comment according to the text format as defined by the syntax
+highlight definition for the document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term>
+<listitem><para>Removes comment markers from the selection or selected lines
+or current line according to the text format as defined by the syntax highlight
+definition for the document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term>
+<listitem><para>Deletes the current line.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>replace</command><arg>pattern</arg><arg>replacement</arg></cmdsynopsis></term>
+<listitem><para>Replaces text matching <userinput>pattern</userinput> with
+<userinput>replacement</userinput>. If you want to include whitespace in the
+<userinput>pattern</userinput>, you must quote both the <userinput>pattern</userinput>
+and <userinput>replacement</userinput> with single or double quotes. If the
+arguments are unquoted, the first word is used as <userinput>pattern</userinput>
+and the rest for <userinput>replacement</userinput>. If
+<userinput>replacement</userinput> is empty, each occurrence of
+<userinput>pattern</userinput> is removed.</para>
+<para>You can set flags to configure the search by adding a colon, followed
+by one or more letters each representing a configuration, giving the form
+<userinput>replace:options pattern replacement</userinput>. Available options
+are:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>b</userinput></term>
+<listitem><para>Search backwards.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>c</userinput></term>
+<listitem><para>Search from cursor position.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>e</userinput></term>
+<listitem><para>Search in the selection only.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>r</userinput></term>
+<listitem><para>Do regular expression search. If set, you may use
+<userinput>\N</userinput> where N is a number to represent captures in the
+replacement string.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>s</userinput></term>
+<listitem><para>Do case sensitive search.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>p</userinput></term>
+<listitem><para>Prompt for permission to replace the next occurence.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>w</userinput></term>
+<listitem><para>Match whole words only.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term>
+<listitem><para>Inserts a date/time string as defined by the specified
+<userinput>format</userinput>, or the format <quote>yyyy-MM-dd hh:mm:ss</quote>
+if none is specified. The following translations are done when interpreting
+<userinput>format</userinput>:
+
+<informaltable>
+<tgroup cols="2">
+<tbody>
+<row><entry><literal>d</literal></entry><entry>The day as number without a leading zero (1-31).</entry></row>
+<row><entry><literal>dd</literal></entry><entry>The day as number with a leading zero (01-31).</entry></row>
+<row><entry><literal>ddd</literal></entry><entry>The abbreviated localized day name (e.g. 'Mon'..'Sun').</entry></row>
+<row><entry><literal>dddd</literal></entry><entry>The long localized day name (e.g. 'Monday'..'Sunday').</entry></row>
+<row><entry><literal>M</literal></entry><entry>The month as number without a leading zero (1-12).</entry></row>
+<row><entry><literal>MM</literal></entry><entry>The month as number with a leading zero (01-12).</entry></row>
+<row><entry><literal>MMM</literal></entry><entry>The abbreviated localized month name (e.g. 'Jan'..'Dec').</entry></row>
+<row><entry><literal>yy</literal></entry><entry>The year as two digit number
+(00-99).</entry></row>
+<row><entry><literal>yyyy</literal></entry><entry>The year as four digit number (1752-8000).</entry></row>
+<row><entry><literal>h</literal></entry><entry>The hour without a leading zero (0..23 or 1..12 if AM/PM display).</entry></row>
+<row><entry><literal>hh</literal></entry><entry>The hour with a leading zero (00..23 or 01..12 if AM/PM display).</entry></row>
+<row><entry><literal>m</literal></entry><entry>The minute without a leading zero (0..59).</entry></row>
+<row><entry><literal>mm</literal></entry><entry>The minute with a leading zero (00..59).</entry></row>
+<row><entry><literal>s</literal></entry><entry>The second without a leading zero (0..59).</entry></row>
+<row><entry><literal>ss</literal></entry><entry>The second with a leading zero (00..59).</entry></row>
+<row><entry><literal>z</literal></entry><entry>The milliseconds without leading zeroes (0..999).</entry></row>
+<row><entry><literal>zzz</literal></entry><entry>The milliseconds with leading zeroes (000..999).</entry></row>
+<row><entry><literal>AP</literal></entry><entry>Use AM/PM display. AP will be replaced by either "AM" or "PM".</entry></row>
+<row><entry><literal>ap</literal></entry><entry>Use am/pm display. ap will be replaced by either "am" or "pm".</entry></row>
+
+</tbody>
+</tgroup>
+</informaltable>
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>char</command><arg>identifier</arg></cmdsynopsis></term>
+<listitem>
+<para>This command allows you to insert literal characters by their
+numerical identifier, in decimal, octal or hexadecimal form.
+To use it launch the Editing Command dialog and type <userinput>char:
+[number]</userinput> in the entry box, then hit
+<guibutton>OK</guibutton>.</para>
+
+<example>
+<title><command>char</command> examples</title>
+
+<para>Input: <userinput>char:234</userinput></para>
+<para>Output: <computeroutput>&#234;</computeroutput></para>
+<para>Input: <userinput>char:0x1234</userinput></para>
+<para>Output: <computeroutput>&#x1234;</computeroutput></para>
+</example>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<indexterm><primary>replace, sed style</primary>
+<secondary>search, sed style</secondary></indexterm>
+<command>s///[ig]</command> <command>%s///[ig]</command></term>
+
+<listitem>
+<para>This command does a sed-like search/replace operation on the
+current line, or on the whole file (<command>%s///</command>).</para>
+
+<para>In short, the text is searched for text matching the
+<emphasis>search pattern</emphasis>, the regular expression between
+the first and the second slash, and when a match is found, the
+matching part of the text is replaced with the expression between the
+middle and last part of the string. Parentheses in the search pattern
+create <emphasis>back references</emphasis>, that is the command
+remembers which part of the match matched in the parentheses; these
+strings can be reused in the replace pattern, referred to as
+<userinput>\1</userinput> for the first set of parentheses,
+<userinput>\2</userinput> for the second and so on.</para>
+
+<para>To search for a literal <literal>(</literal> or
+<literal>)</literal>, you need to <emphasis>escape</emphasis> it using
+a backslash character: <userinput>\(\)</userinput></para>
+
+<para>If you put an <userinput>i</userinput> at the end of the
+expression, the matching will be case insensitive. If you put a
+<userinput>g</userinput> at the end, all occurrences of the pattern will be
+replaced, otherwise only the first occurrence is replaced.</para>
+
+<example>
+
+<title>Replacing text in the current line</title>
+
+<para>Your friendly compiler just stopped, telling you that the class
+<classname>myClass</classname> mentioned in line 3902 in your source file
+is not defined.</para>
+
+<para>&quot;Buckle!&quot; you think, it is of course
+<classname>MyClass</classname>. You go to line 3902, and instead of trying
+to find the word in the text, you launch the Editing Command Dialog,
+enter <userinput>s/myclass/MyClass/i</userinput>, hit the
+<guibutton>OK</guibutton> button, save the file and compile &ndash;
+successfully without the error.</para>
+
+</example>
+
+<example>
+<title>Replacing text in the whole file</title>
+
+<para>Imagine that you have a file, in which you mention a <quote>Miss
+Jensen</quote> several times, when someone comes in and tells you that
+she just got married to <quote>Mr Jones</quote>. You want, of course,
+to replace each and every occurrence of <quote>Miss Jensen</quote>
+with <quote>Ms Jones</quote>.</para>
+
+<para>Enter the command line and issue the command
+<userinput>%s/Miss Jensen/Ms Jones/</userinput> and hit return, you
+are done.</para>
+
+</example>
+
+<example>
+<title>A More Advanced Example</title>
+
+<para>This example makes use of <emphasis>back references</emphasis>
+as well as a <emphasis>character class</emphasis> (if you do not know what
+that is, please refer to the related documentation mentioned
+below).</para>
+
+<para>Suppose you have the following line:
+
+<programlisting>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar String *p, int  &amp;a, int &amp;b )</programlisting>
+</para>
+<para>Now you realize that this is not nice code, and decide that you
+want to use the <constant>const</constant> keyword for all
+<quote>address of</quote> arguments, those characterized by the &amp;
+operator in front of the argument name. You would also like to
+simplify the white space, so that there is only 1 whitespace character
+between each word.</para>
+
+<para>Launch the Editing Command Dialog, and enter:
+<userinput>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput> and hit the
+<guibutton>OK</guibutton> button. The <userinput>g</userinput> at the end of the expression makes
+the regular expression recompile for each match to save the <emphasis>backreferences</emphasis>.</para>
+
+<para>Output:
+
+<computeroutput>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar String *p, const int &amp;a, const int &amp;b )</computeroutput></para>
+
+<para>Mission completed! Now, what happened? Well, we looked for some
+white space (<literal>\s+</literal>) followed by one or more
+alphabetic characters (<literal>\w+</literal>) followed by some more
+whitespace (<literal>\s+</literal>) followed by an ampersand, and in
+the process saved the alphabetic chunk and the ampersand for reuse in
+the replace operation. Then we replaced the matching part of our line
+with one whitespace followed by <quote>const</quote> followed by one
+whitespace followed by our saved alphabetical chunk
+(<literal>\1</literal>) followed by one whitespace followed by our
+saved ampersand (<literal>\2</literal>)</para>
+
+<para>Now in some cases the alphabetical chunk was
+<quote>String</quote>, in some <quote>int</quote>, so using the
+character class <literal>\w</literal> and the <literal>+</literal>
+quantifier proved a valuable asset.</para>
+
+</example>
+
+</listitem>
+
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+<sect3 id="advanced-editing-tools-commandline-commands-navigation">
+<title>Commands for navigation</title>
+
+<variablelist>
+
+<varlistentry>
+<term><cmdsynopsis><command>goto</command><arg>INT line</arg></cmdsynopsis></term>
+<listitem><para>This command navigates to the specified line.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>find</command><arg>pattern</arg></cmdsynopsis></term>
+<listitem><para>This command navigates to the first occurrence of
+<userinput>pattern</userinput> according to the configuration. Following
+occurrences can be found using
+<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice>
+(the default shortcut is <keycap>F3</keycap>).</para>
+<para>The find command can be configured by appending a colon followed by one or
+more options, the form is
+<userinput>find:options pattern</userinput>. The
+following options are supported:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>b</userinput></term>
+<listitem><para>Search backwards.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>c</userinput></term>
+<listitem><para>Search from cursor position.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>e</userinput></term>
+<listitem><para>Search in the selection only.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>r</userinput></term>
+<listitem><para>Do regular expression search. If set, you may use
+<userinput>\N</userinput> where N is a number to represent captures in the
+replacement string.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>s</userinput></term>
+<listitem><para>Do case sensitive search.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>w</userinput></term>
+<listitem><para>Match whole words only.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+</listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term>
+<listitem><para>This command provides <quote>as-you-type</quote> searching. You
+can configure the behavior of the search by appending a colon
+followed by one or more options, like this:
+<userinput>ifind:options pattern</userinput>. Allowed options are
+
+<variablelist>
+<varlistentry>
+<term><userinput>b</userinput></term>
+<listitem><para>Search backwards.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>r</userinput></term>
+<listitem><para>Do regular expression search.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>s</userinput></term>
+<listitem><para>Do case sensitive search.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>c</userinput></term>
+<listitem><para>Search from cursor position.</para></listitem>
+</varlistentry>
+
+</variablelist>
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="advanced-editing-tools-code-folding">
+<title>Using Code Folding</title>
+
+<para>Code folding allows you to hide parts of a document in the editor, making
+it easier to overview large documents. In &kate; the foldable regions are
+calculated using rules defined in the syntax highlight definitions, and
+therefore it is only available in some formats - typically program source code,
+XML markup and similar. Most highlight definitions supporting code folding
+also lets you manually define foldable regions, typically using the
+<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para>
+
+<para>To use the code folding feature, activate the folding markers using
+<menuchoice><guimenu>View</guimenu><guimenuitem>Show Folding
+Markers</guimenuitem></menuchoice> menu item if they are not already visible.
+The Folding Markers Pane in the left side of the screen displays a graphical
+view of the foldable regions, with +/- signs to indicate the possible operation
+on a given region: a - means that the region is expanded, clicking the - will
+collapse the region and a + will be displayed instead.</para>
+
+<para>Four commands are provided to manipulate the state of folding regions,
+see the <link linkend="view-code-folding">menu documentation</link>.
+</para>
+
+<para>If you do not want to use the code folding feature, you can disable
+the <guilabel>Show folding markers (if available)</guilabel> option in the
+<link linkend="config-dialog-editor-appearance">Appearance page of the editor
+configuration</link></para>
+
+</sect1>
+
+<sect1 id="advanced-editing-tools-scripting">
+
+<title>Scripting the editor component with Javascript</title>
+
+<sect2 id="advanced-editing-tools-scripting-introduction">
+
+<title>Introduction</title>
+
+<para>Starting with version 2.5, the &kate; editor component supports
+scripting with ECMA script, also known as JavaScript.</para>
+
+<para>Scripts can be used through <link
+linkend="advanced-editing-tools-commandline">the built in command line</link>
+only. The requirements is that the script is placed in a folder where &kate;
+can find it, along with an optional .desktop file that defines the related
+properties. The valid folder are named <filename>katepart/scripts</filename>
+in the &kde; data folders. You can find the data folders by running the command
+<command>kde-config <option>--path</option> <parameter>data</parameter></command>
+You will usually have at least a system and a personal data folder. Of course
+scripts in the system data folder are available to all users on the system,
+while those in the personal folder are available for you only.</para>
+
+<note><para>This feature is experimental and will most likely change during
+future development.</para>
+<para>We know that many of you will be disappointed because you can't add
+your scripts to the menu or assign shortcuts to them. Sorry, sometime
+in the future that will likely be possible.</para>
+<para>It is also not possible to pass any arguments to your scripts yet. Be
+patient, and that may be added in the bright future ;)</para>
+</note>
+
+</sect2>
+
+<sect2 id="advanced-editing-tools-scripting-reference">
+
+<title>The Kate JavaScript API</title>
+
+<para>Here is listed the complete set of functions and properties available
+in the <type>document</type> and <type>view</type> objects.
+In addition you can of course use all the standard objects such as
+<type>Math</type>, <type>String</type> <type>Regex</type> and so forth.</para>
+
+<para>When a script is run, the <classname>document</classname> object is the
+current document, and the <classname>view</classname> object is the current
+view.</para>
+
+<note><para>The types of arguments are of course not used in JavaScript at
+this time, they are there solely to indicate what sort of value the funcitons
+expect.</para></note>
+
+<variablelist id="advanced-editing-tools-scripting-global">
+<title>Global Functions</title>
+<varlistentry>
+<term><function>debug( <parameter><replaceable>string</replaceable></parameter>)
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>parameters</title>
+<listitem><para><parameter>string</parameter> the string to output</para>
+</listitem>
+</itemizedlist>
+<para>Outputs the string to <acronym>STDERR</acronym> using
+<function>kdDebug()</function>. A dedicated output area is used for the output,
+which will be prefixed <computeroutput>Kate (KJS Scripts):</computeroutput>
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist id="advanced-editing-tools-scripting-document">
+<title>The <classname>document</classname> API</title>
+
+<varlistentry>
+<term><function>document.attribute( <parameter><replaceable>line</replaceable>
+</parameter>, <parameter><replaceable>column</replaceable></parameter> );
+ [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>uint line</parameter> The line of the position for which
+to find the attribute.</para></listitem>
+<listitem><para><parameter>uint column</parameter> The column of the position for
+which to find the attribute.</para></listitem>
+</itemizedlist>
+<para>Returns the numeric ID of the attribute for the document position
+[<parameter>line</parameter>,<parameter>column</parameter>]. The attribute
+represents the visual appearance or style of the text, and is also used to
+calculate the syntax highlight for a specific part of the text in mixed formats
+like HTML or PHP.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.canBreakAt( <parameter>Char c</parameter>,
+<parameter>uint attribute</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>c</parameter> The character to test</para></listitem>
+<listitem><para><parameter>attribute</parameter> The attribute at the position
+of <parameter>c</parameter>.</para></listitem>
+</itemizedlist>
+<para>Returns whether it is allowed to break the line at a character c with
+attribute attribute. The result is decided by querying the highlight owning
+attribute for which characters allow breaking the line.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.canComment( <parameter>uint start_attribute</parameter>,
+<parameter>uint end_attribute</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>start_attribute</parameter> The attribute at the
+start of the range to turn into a comment.</para></listitem>
+<listitem><para><parameter>end_attribute</parameter> The attribute at end of
+the range to turn into a comment.</para></listitem>
+</itemizedlist>
+<para>Returns whether start_attribute and end_attribute belongs to the same
+syntax highlight system. If they do, it is sane.
+</para>
+<example>
+<title>using canComment</title>
+<programlisting>
+if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
+    // 1,0 and 5,0 belongs to the same syntax highlighting system
+}
+</programlisting>
+</example>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.clear(); [function]</function></term>
+<listitem><para>Clears the document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.commentStart( <parameter>uint attribute</parameter> );
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>attribute</parameter> The attribute of the text for
+which to get the commentStart string.</para></listitem>
+</itemizedlist>
+<para>Returns the string required to start a multiline comment for a text with
+attribute, or an empty string if multiline comments are not supported for that
+text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.commentMarker( <parameter>uint attribute</parameter> );
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>attribute</parameter> The attribute of the text for
+which to get the commentMarker string</para></listitem>
+</itemizedlist>
+<para>Returns the string used to mark the rest of the line as a comment for a
+text with attribute or an empty string if single line comments are not supported
+for that text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.commentEnd( <parameter>uint attribute</parameter> );
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>attribute</parameter> The attribute of the text for
+which to get the commentEnd string</para></listitem>
+</itemizedlist>
+<para>Returns the string required to end a multiline comment for a text with
+attribute, or an empty string if multiline comments are not supported for that
+text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.editBegin(); [function]</function></term>
+<listitem>
+<para>Start an editing group. All actions done until the call of editEnd() will
+be grouped as one undo-action.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.editEnd(); [function]</function></term>
+<listitem>
+<para>Finish an editing group.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.highlightMode; [property:read only]</function></term>
+<listitem>
+<para>The name of the document's highlight mode, such as JavaScript or C++.
+If no syntax highlight mode is set for the document, the value is None. Notice
+that you need to use the English name in cases where it differs from the
+translated one.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.indentMode; [property:read only]</function></term>
+<listitem>
+<para>The name of the document indent mode, such as
+<literal>normal</literal> or <literal>cstyle</literal>.
+Remember that if no indent mode is set, the value is <literal>none</literal>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.indentWidth; [property:read only]</function></term>
+<listitem>
+<para>The indentation width set for the document. This is used if space
+indenting is enabled.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.insertLine( <parameter>uint line</parameter>,
+<parameter>string text</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> document line number</para>
+</listitem>
+<listitem><para><parameter>text</parameter> text to insert</para></listitem>
+</itemizedlist>
+<para>Inserts a new line with the text <parameter>text</parameter> at the
+line <parameter>line</parameter>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.insertText( <parameter>uint line</parameter>,
+<parameter>uint column</parameter>, <parameter>string text</parameter> );
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> the line number</para></listitem>
+<listitem><para><parameter>column</parameter> the column</para></listitem>
+<listitem><para><parameter>text</parameter> the text which is to be
+inserted</para></listitem>
+</itemizedlist>
+<para>Inserts the text <parameter>text</parameter> in line
+<parameter>line</parameter> and column <parameter>column</parameter>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>document.length(); [function]</term>
+<listitem>
+<para>Returns the document's size in bytes.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.lines(); [function]</function></term>
+<listitem>
+<para>Returns the number of lines in the document.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>document.mixedIndent; [property:read only]</term>
+<listitem>
+<para>A boolean telling whether the mixed-indent setting is enabled for the
+document. If so, indentation is optimized to contain a mix of tab characters and
+spaces like used by the Emacs editor.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>document.removeLine( <parameter>uint line</parameter> ); [function]</term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> line number</para></listitem>
+</itemizedlist>
+<para>Removes the document line line.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.removeText( <parameter>uint startLine</parameter>,
+<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
+<parameter>uint endColumn</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>startLine</parameter> specifies the beginning
+line</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning
+column</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending
+line</para></listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending
+column</para></listitem>
+</itemizedlist>
+<para>Removes the text range from line <parameter>startLine</parameter> and
+column <parameter>startColumn</parameter> up to line
+<parameter>endLine</parameter> and column <parameter>endColumn</parameter>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.setText( <parameter>string text</parameter> );
+[function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>text</parameter> document text</para></listitem>
+</itemizedlist>
+<para>Sets the entire document content to <parameter>text</parameter>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.spaceIndent; [property:read only]</function></term>
+<listitem>
+<para>A boolean telling whether space-indent is enabled for the document.
+If so, the document is indented with indentWidth spaces pr level, otherwise
+indentation is one tab character pr. level.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.textFull(); [function]</function></term>
+<listitem>
+<para>Returns the full document text. If the text spans over multiple lines the
+linefeed character is <constant>\n</constant>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.textLine( uint line ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> the line</para></listitem>
+</itemizedlist>
+<para>Returns the text of line <parameter>line</parameter>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>document.textRange( <parameter>uint startLine</parameter>,
+<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
+<parameter>uint endColumn</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>startLine</parameter> specifies the beginning
+line</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning
+column</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending line</para>
+</listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending
+column</para></listitem>
+</itemizedlist>
+<para>Returns the specified text range. If the range spans over multiple lines
+the linefeed character is <constant>\n</constant>.</para>
+</listitem>
+</varlistentry>
+
+</variablelist><!--/ document API -->
+
+<variablelist id="advanced-editing-tools-scripting-view">
+<title>The <classname>view</classname> API</title>
+
+<varlistentry>
+<term><function>view.clearSelection(); [function]</function></term>
+<listitem>
+<para>Deselects all text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.cursorColumn(); [function]</function></term>
+<listitem>
+<para>Returns the current cursor column (TAB characters are expanded).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.cursorColumnReal(); [function]</function></term>
+<listitem>
+<para>Returns the current real cursor column (TAB characters counts one).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.cursorLine(); [function]</function></term>
+<listitem>
+<para>Returns the current cursor line.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.hasSelection(); [function]</function></term>
+<listitem>
+<para>Returns <constant>true</constant> if the view contains selected text,
+otherwise <constant>false</constant>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.removeSelectedText(); [function]</function></term>
+<listitem>
+<para>Removes the selected text, if the view has a selection.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selectAll(); [function]</function></term>
+<listitem>
+<para>Selects all text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selection(); [function]</function></term>
+<listitem>
+<para>Returns the selected text. If the selection spans over multiple lines the
+linefeed character is <constant>\n</constant>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selectionEndColumn; [property:read only]</function></term>
+<listitem>
+<para>Returns the ending column of the selection.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selectionEndLine; [property:read only]</function></term>
+<listitem>
+<para>Returns the ending line of the selection.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selectionStartColumn; [property:read only]</function></term>
+<listitem>
+<para>Returns the starting column of the selection.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.selectionStartLine; [property:read only]</function></term>
+<listitem>
+<para>Returns the starting line of the selection.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.setCursorPosition( <parameter>uint line</parameter>,
+<parameter>uint column</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> Specifies the line for the
+cursor.</para></listitem>
+<listitem><para><parameter>column</parameter> Specifies the column for the
+cursor.</para></listitem>
+</itemizedlist>
+<para>Sets the input cursor position in the view to [<parameter>line</parameter>,
+<parameter>col</parameter>]. This sets the cursor position by visual means,
+that is the a TAB character counts up to <replaceable>tabwidth</replaceable>
+depending on the position inside the line. The cursor position is made visible.
+Both line and column are zero-based.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.setCursorPositionReal( <parameter>uint line</parameter>,
+<parameter>uint column</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>line</parameter> Specifies the line for the
+cursor.</para></listitem>
+<listitem><para><parameter>column</parameter> Specifies the column for the
+cursor.</para></listitem>
+</itemizedlist>
+<para>Sets the input cursor position to [<parameter>line</parameter>,
+<parameter>col</parameter>]. This sets the string position, that is a TAB
+character counts for 1. The cursor position is made visible. Both line and
+column are zero-based.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><function>view.setSelection( <parameter>uint startLine</parameter>,
+<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>,
+<parameter>uint endColumn</parameter> ); [function]</function></term>
+<listitem>
+<itemizedlist>
+<title>Parameters</title>
+<listitem><para><parameter>startLine</parameter> specifies the beginning line</para></listitem>
+<listitem><para><parameter>startColumn</parameter> specifies the beginning column</para></listitem>
+<listitem><para><parameter>endLine</parameter> specifies the ending line</para></listitem>
+<listitem><para><parameter>endColumn</parameter> specifies the ending column</para></listitem>
+</itemizedlist>
+<para>Sets a selection from line <parameter>startLine</parameter> and column
+<parameter>startColumn</parameter> up to line <parameter>endLine</parameter>
+and column <parameter>endColumn</parameter>.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<example id="advanced-editing-tools-scripting-example">
+
+<title>A sample script</title>
+<para>As an example we will create a small script that uppercases the selection.
+It is obvious that we first need to check whether a selection exists, if so we
+get the text, change the case and then replace it with the new one. An
+implementation could look like this:</para>
+
+<programlisting>
+if ( view.hasSelection() )
+{
+  // uppercase selection
+  column = view.selectionStartColumn;
+  line = view.selectionStartLine;
+
+  selection = view.selection().toUpperCase();
+
+  document.editBegin();
+  view.removeSelectedText();
+  document.insertText( line, column, selection );
+  document.editEnd();
+}
+</programlisting>
+
+<para>To group this action together so that they will be reverted by a single
+activation of <guimenuitem>Undo</guimenuitem> we encapsulate the lines
+<programlisting>view.removeSelectedText()</programlisting> and
+<programlisting>document.insertText()</programlisting> with a
+<programlisting>document.editBegin()</programlisting> and
+<programlisting>document.editEnd()</programlisting>.</para>
+
+</example>
+
+<example id="advanced-editing-tools-desktop-example">
+<title>A sample <filename>.desktop</filename> file</title>
+
+<para>Here is a sample .desktop file that accompanies the above script.</para>
+
+<programlisting>
+# Example of a .desktop file
+[Desktop Entry]
+Encoding=UTF-8
+Name=Kate Part JavaScript Uppercase
+Comment=Script to uppercase the selection
+X-Kate-Command=uppercase-selection
+X-Kate-Help=&lt;p&gt;Usage: &lt;code&gt;uppercase-selection&lt;/code&gt;&lt;/p&gt;
+</programlisting>
+
+<para>As you can see you can define the Encoding, set a Name, a Comment, a help
+text using X-Kate-Help and the command line name via X-Kate-Command. The entries
+Name, Comment and X-Kate-Help are automatically translated into other languages
+by the KDE translation teams, if the files are in KDE's SVN repository.</para>
+
+</example>
+
+<sect3>
+<title>Putting it togeather</title>
+
+<para>&kate; will search the script folders (see <link
+linkend="advanced-editing-tools-scripting-introduction">above</link>)  for
+<filename>*.js</filename> files. For every file it checks whether there is a
+corresponding <filename>.desktop</filename> file, like for uppercase.js it
+would look for uppercase.desktop. </para>
+<para>If a <filename>.desktop</filename> file can not be found the script will
+be registered in katepart's command line with the filename without the ending
+.js, so in our example this would be <literal>uppercase</literal>. If the
+command-name is fine and you don't need the extra features a
+<filename>.desktop</filename> file provides you do not need a
+<filename>.desktop</filename> file at all. </para>
+<para>If a <filename>.desktop</filename> file exists katepart will read the name
+under which the script will be registered from the .desktop-entry
+X-Kate-Command, for example X-Kate-Command=uppercase-selection.</para>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/configdialog01.png b/doc/kate/configdialog01.png
new file mode 100644
index 000000000..751066792
--- /dev/null
+++ b/doc/kate/configdialog01.png
diff --git a/doc/kate/configdialog02.png b/doc/kate/configdialog02.png
new file mode 100644
index 000000000..70a7ecaed
--- /dev/null
+++ b/doc/kate/configdialog02.png
diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook
new file mode 100644
index 000000000..14642c74c
--- /dev/null
+++ b/doc/kate/configuring.docbook
@@ -0,0 +1,1595 @@
+<chapter id="configuring-kate">
+<chapterinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>Configuring &kate;</title>
+
+<sect1 id="configuring-overview">
+<title>Overview</title>
+<para>
+<indexterm>
+<primary>configure</primary>
+<secondary>settings</secondary>
+<tertiary>preferences</tertiary></indexterm>
+<anchor id="find"/>
+<anchor id="find-again"/>
+<!-- <anchor id="print"/> -->
+<anchor id="replace"/>
+<!-- <anchor id="save"/> -->
+<anchor id="undo"/>
+<anchor id="redo"/>
+&kate; offers several means of tweaking the application to behave as desired.
+The most important ones are:
+</para>
+
+<variablelist>
+<varlistentry>
+<term id="configure">The Configuration Dialog</term>
+<listitem><para>The main configuration tool, allowing you to configure the &kate; application,
+the editor component and the usage of plugins.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term id="settings">The <guimenu>Settings</guimenu> Menu</term>
+<listitem><para>Allows you to change often used settings, and to
+launch the configuration dialogs.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>The <guimenu>View</guimenu> Menu</term>
+<listitem><para>Allows you to split the current frame, as well as to
+display the icons and line numbers pane for the currently edited
+document.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>The embedded &konsole; is using the configuration defined in the
+&kcontrolcenter;, and may be configured by clicking the
+<mousebutton>right</mousebutton> mouse button and choosing from the
+<guimenuitem>Settings</guimenuitem> sub menu.</para>
+
+</sect1>
+
+<sect1 id="configuring-kate-configdialog">
+<title>The Main Configuration Dialog</title>
+
+<mediaobject>
+<imageobject>
+<imagedata format="PNG" fileref="configdialog01.png"/>
+</imageobject>
+</mediaobject>
+
+<para>The &kate; configuration dialog displays a tree of topics on the
+left, and a configuration page corresponding to the selected topic on
+the right.</para>
+
+<para>The configuration is divided into two groups, namely
+<itemizedlist>
+<listitem><para><link linkend="config-dialog">Application configuration</link>
+</para></listitem>
+<listitem><para><link linkend="config-dialog-editor">Editor component configuration</link></para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</sect1>
+
+<sect1 id="config-dialog">
+<title>The &kate; Application Configuration</title>
+<para>This group contains pages to configure the main &kate; application</para>
+
+<sect2 id="config-dialog-general">
+<title>The General Page</title>
+<para>This section contains a few global options for &kate;</para>
+
+<variablelist>
+
+<varlistentry>
+<term><anchor id="config-dialog-general-show-full-path" />
+<guilabel>Show Full Path in Title</guilabel></term>
+<listitem><para>When enabled, Kate will display the full URL of your
+current document in the window title, rather than just the file name.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="config-general-behavior"/>
+<guilabel>Behavior</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term>
+<anchor id="config-dialog-general-sync-konsole"/>
+<guibutton>Sync Konsole with Active Document</guibutton></term>
+<listitem><para>This will cause the built-in &konsole; to
+<command>cd</command> into the directory of the active document when
+launched and when a new document gets the focus. If not enabled, you
+have to do all your navigation in the &konsole; on your own.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="config-dialog-general-warn-mod"/>
+<guilabel>Warn about files modified by foreign processes</guilabel></term>
+<listitem><para>When enabled, &kate; will notify you about files modified
+from outside the application whenever the main window receives input focus.
+You will be able to deal with several modified files at once, you
+can reload, save or discard changed files in groups.</para>
+<para>If not enabled, &kate; will prompt you for action when a externally
+modified file receives focus within the application.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry><!-- /behavior group -->
+
+<varlistentry>
+<term><anchor id="config-general-meta-data"/>
+<guilabel>Meta Data</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><anchor id="config-general-keep-meta-information"/>
+<guilabel>Keep meta-information past sessions</guilabel></term>
+<listitem><para>When enabled, &kate; will store meta data such as bookmarks
+and session configuration even when you close your documents. The data
+will be used if the document is unchanged when reopened.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="config-general-delete-meta-information-after"/>
+<guilabel>Delete unused meta information after</guilabel></term>
+<listitem><para>Set the maximum number of days to keep meta information
+for unopen files. This helps keeping the database of meta information
+reasonably sized.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</listitem>
+</varlistentry><!-- /meta data group -->
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-sessions">
+<title>The Sessions Page</title>
+
+<para>This section contains options related to <link
+linkend="fundamentals-using-sessions">using sessions</link>.</para>
+
+<variablelist>
+
+<varlistentry>
+<term><anchor id="config-dialog-sessions-elements"/>
+<guilabel>Elements of Sessions</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Include window configuration</guilabel></term>
+<listitem><para>If enabled, &kate; will save the window configuration
+with each session.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry><!-- /elements of sessions -->
+
+<varlistentry>
+<term><anchor id="config-dialog-sessions-startup-behavior"/>
+<guilabel>Behavior on Application Startup</guilabel></term>
+<listitem>
+<para>Select how you want &kate; to behave at startup. This setting can be
+overridden by specifying what to do on the <link
+linkend="command-line-options">command line</link>.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Start new session</guilabel></term>
+<listitem><para>With this option, &kate; will start a new, unnamed session
+when you start it.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Load last used session</guilabel></term>
+<listitem><para>&kate; will use the most recently opened session at
+startup. This is good if you want to use the same session always or switch
+rarely.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Manually choose a session</guilabel></term>
+<listitem><para>&kate; will display a small dialog that lets you choose
+your preferred session. This is the default behavior. Nice if you use a lot of
+different sessions frequently.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry><!-- /startup behavior -->
+
+<varlistentry>
+<term><anchor id="config-dialog-sessions-exit-behavior"/>
+<guilabel>Behavior on Application Exit or Session Switch</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Do not save session</guilabel></term>
+<listitem><para>The changes to the session data (open files and if enabled,
+window configuration) will not be saved. You will of course be prompted if you
+have unsaved files. With this option, your can configure your sessions once, and
+not worry about closing extra files that you opened and do not want to see
+next time you use the session.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Save Session</guilabel></term>
+<listitem><para>&kate; will save session data, except if the session is unnamed.
+With this option, your sessions are allways restored just like you left them.
+This is the default behavior.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Ask user</guilabel></term>
+<listitem><para>You will be asked if you want to save the session every time a
+named session is closed.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry><!-- /exit/switch behavior -->
+
+</variablelist>
+
+</sect2>
+
+<sect2 id="config-dialog-fileselector">
+<title>The <guilabel>Filesystem Browser</guilabel> Page</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Toolbar</guilabel></term>
+<listitem><para>Configure the buttons on the file system browser toolbar
+by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel>
+list, and order them using the arrow buttons at the side of the list.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Auto Synchronization</guilabel></term>
+<listitem><para>You can have the filesystem browser automatically navigate to
+the directory containing the current document on certain events:
+<itemizedlist>
+<listitem><para>When a new document becomes the active one.</para></listitem>
+<listitem><para>When the filesystem browser becomes visible.</para></listitem>
+</itemizedlist>
+Even if you select not to use this feature, you can manually synchronize the
+browser with the current document by pressing the
+<guilabel>Synchronize</guilabel> toolbar button.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Remember locations</guilabel></term>
+<listitem><para>Select how long a browsing history you want. The browser does
+only remember individual locations, duplicates are removed.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Remember filters</guilabel></term>
+<listitem><para>Select how many filters you want remembered. Only individually
+distinct filters are remembered, duplicates are removed.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Session</guilabel></term>
+<listitem>
+<para>Configure wether the file system browser should remember its location and
+filter over sessions.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2 id="config-dialog-documentlist">
+<title>The <guilabel>Doucment List</guilabel> Page</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Backgound Shading</guilabel></term>
+<listitem><para>This section allows you to enable or disable the background
+shading visualization of your recent activity, and chose which colors to use if
+enabled. See the section about <link
+linkend="kate-mdi-tools-file-list">The Document List</link> for more about
+this feature.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Sort By</guilabel></term>
+<listitem><para>Set how you want the document list sorted. This can be set
+from the &RMB; menu in the document list as well.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="config-dialog-plugins">
+<title>The <guilabel>Plugins</guilabel> Page</title>
+
+<para>This page provides a list of installed plugins for the &kate;
+application. Each plug-in is represented with its name and a short description.
+You can check the checkbox with an item to enable the plug-in it represents.
+</para>
+
+<para>If a plug-in provides configuration options, a section to access those
+will appear as a child of this page.</para>
+
+</sect2>
+
+
+<sect2 id="config-dialog-externaltools">
+<title>External Tools</title>
+
+<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled
+<guisubmenu>External Tools</guisubmenu>. These tools invokes external
+applications with data related to the current document, for example its URL,
+directory, text or selection. This page allows you to manage the menu and edit,
+remove or add new tools.</para>
+
+<para>Each external tool is a shell command which contains macros representing
+the document data. When activated, the macros are substituted with data from the
+active document.</para>
+
+<variablelist>
+<title>External Tools Properties</title>
+<varlistentry>
+<term>Label</term>
+<listitem><para>A friendly label for the External Tools menu.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Script</term>
+<listitem><para>The script to execute when the tool is activated. Before passing
+the script to the shell, the following macros are substituted:
+
+<variablelist>
+<varlistentry>
+<term>%URL</term>
+<listitem><para>The full URL of the current document, or an empty string if the
+document is unsaved.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%URLS</term>
+<listitem><para>A space seperated list of the URLs of all open documents
+(except unsaved ones).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%directory</term>
+<listitem><para>The directory part of the current documents URL or an empty
+string if the current document is unsaved.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%filename</term>
+<listitem><para>the filename of the current document without the path, or an
+empty string if the current document is unsaved.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%line</term>
+<listitem><para>The line number of the insertion cursor is in the current
+document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%column</term>
+<listitem><para>The column number of the insertion cursor in the current
+document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%selection</term>
+<listitem><para>The selected text in the current document, or an empty string
+if no text is selected</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%text</term>
+<listitem><para>The full text of the current document. Beware that this will
+potentially exceed the maximum command length allowed on your system.
+Use with care.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Executable</term>
+<listitem><para>The main executable is the script. This is mandatory, and is used
+to test if the command can be run at all. A fully qualified path is allowed
+in case the executable is not in your <envar>PATH</envar> variable.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Mimetypes</term>
+<listitem><para>A semicolon separated list of mimetypes for which this command
+should be enabled. This is currently unused.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Save</term>
+<listitem><para>You can optionally select to have the current or all documents
+saved prior to executing the script. This is handy if your script reads the file
+from disk.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Command Line Name</term>
+<listitem><para>If you fill this, the tool will be available in the
+<link linkend="advanced-editing-tools-commandline">editors command line</link> as
+<command>exttool-<replaceable>Command Line Name</replaceable></command>
+(the string you enter here prepended <quote>exttool-</quote>).</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="config-dialog-editor">
+<title>The Editor Component Configuration</title>
+<para>This group contains all pages related to the editor component of
+&kate;. Most of the settings here are defaults, they can be overridden by
+<link linkend="config-dialog-editor-filetypes">defining a filetype</link>,
+by <link linkend="config-variables">Document Variables</link> or by changing
+them pr. document during an editing session.</para>
+
+
+<sect2 id="config-dialog-editor-appearance">
+<title>Appearance</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Word Wrap</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry id="appearance-settings">
+<term><guilabel>Dynamic word wrap</guilabel></term>
+<listitem><para>If this option is checked, the text lines
+will be wrapped at the view border on the screen.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Dynamic word wrap indicators</guilabel></term>
+<listitem><para>Choose when the Dynamic word wrap indicators
+should be displayed.
+</para></listitem></varlistentry>
+<varlistentry>
+<term><guilabel>Vertically align dynamically wrapped lines
+to indentation depth:
+</guilabel></term>
+<listitem><para>Enables the start of dynamically wrapped
+lines to be aligned  vertically to the indentation level of the first
+line.  This can help to make code and markup more
+readable.</para><para>Additionally, this allows you to
+set a maximum width of the screen, as a percentage,
+after which dynamically wrapped lines will no longer be vertically aligned.
+For example, at 50%, lines whose indentation levels are deeper than 50% of the
+width of the screen will not have vertical alignment applied to subsequent
+wrapped lines.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Code Folding</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Show folding markers (if available)
+</guilabel></term>
+<listitem><para>If this option is checked, the current view will display marks
+for code folding, if code folding is available.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Borders</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Show icon border
+</guilabel></term>
+<listitem><para>If this is checked, you will see an icon border on the left
+hand side. The icon border shows bookmark signs for instance.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show line numbers
+</guilabel></term>
+<listitem><para>If this is checked, you will see line numbers on the left
+hand side.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show scrollbar marks
+</guilabel></term>
+<listitem><para>If this option is checked the current view
+will show marks on the vertical scrollbar. These marks will
+for instance show bookmarks.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Sort Bookmarks Menu
+</guilabel></term>
+<listitem><para>
+<variablelist>
+<varlistentry>
+<term><guilabel>By position
+</guilabel></term>
+<listitem><para>The bookmarks will be ordered by the line
+numbers they are placed at.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>By creation
+</guilabel></term>
+<listitem><para>Each new bookmark will be added to the bottom,
+independently from where it is placed in the document.</para></listitem>
+</varlistentry>
+</variablelist>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Show identation lines
+</guilabel></term>
+<listitem><para>If this is checked, the editor wil display
+vertical lines to help identifying indent lines.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-colors">
+<title>Fonts &amp; Colors</title>
+
+<para>This section of the dialog lets you configure all fonts and colors in
+any color scheme you have, as well creating new schemes or deleting existing
+ones. Each scheme has settings for colors, fonts and normal and highlight text
+styles.
+</para>
+
+<para>&kate; will preselect the currently active scheme for you, if you want to
+work on a different scheme start by selecting that from the
+<guilabel>Schema</guilabel> combobox.</para>
+
+<sect3 id="config-dialog-editor-colors-colors">
+<title>Colors</title>
+
+<variablelist>
+<varlistentry id="config-dialog-editor-colors-colors-text-background">
+<term><guilabel>Text Area Background</guilabel></term>
+<listitem>
+
+<variablelist>
+
+<varlistentry id="config-dialog-editor-colors-normal-text">
+<term><guilabel>Normal text</guilabel></term>
+<listitem><para>This is the default background for the editor area, it will be
+the dominant color on the editor area.</para></listitem>
+</varlistentry>
+
+<varlistentry id="config-dialog-editor-colors-selected-text">
+<term><guilabel>Selected Text</guilabel></term>
+<listitem><para>This is the background for selected text. The default is
+the global selection color, as set in your &kde; color preferences.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="config-dialog-editor-colors-current-line">
+<term><guilabel>Current Line</guilabel></term>
+<listitem><para>Set the color for the current line. Setting this a bit different
+from the Normal text background helps to keep focus on the current line.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="config-dialog-editor-colors-marks">
+<term><guilabel>Bookmark</guilabel></term>
+<listitem><para>This combo lets you set overlay colors for various mark types.
+The color is mixed into the background color of a marked line, so that a line
+with more marks or a marked line that is current has a background that is a mix
+of more colors. The mark colors are also used if you enable display of scrollbar
+marks.</para></listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry id="config-dialog-editor-colors-colors-other-elements">
+<term><guilabel>Other Elements</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Left Border Background</guilabel></term>
+<listitem><para>This color is used for the marks, line numbers and folding
+marker borders in the left side of the editor view when they are displayed.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Line Numbers</guilabel></term>
+<listitem><para>This color is used to draw the line numbers on the left side of
+the view when displayed.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Bracket Highlight</guilabel></term>
+<listitem><para>This color is used to draw the background of matching brackets.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Word Wrap Markers</guilabel></term>
+<listitem><para>This color is used to draw a pattern to the left of dynamically
+wrapped lines when those are aligned vertically, as well as for the static word
+wrap marker.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Tab Markers</guilabel></term>
+<listitem><para>This color is used to draw white space indicators when enabled.
+</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect3>
+
+<sect3 id="config-dialog-editor-colors-fonts">
+<title>Fonts</title>
+<para>
+Here you can choose the font for the schema.  You can choose from
+any font available on your system, and set a default size. A sample text
+displays at the bottom of the dialog, so you can see the effect of your choices.
+</para>
+</sect3>
+
+<sect3 id="config-dialog-editor-colors-normal-text-styles">
+<title>Normal Text Styles</title>
+<para>The normal text styles are inherited by the highlight text styles,
+allowing the editor to present text in a very consistent way, for example comment
+text is using the same style in allmost all of the text formats that kate can
+highlight.</para>
+<para>The name in the list of styles is using the style configured for
+the item, providing you with an immediate preview when configuring a style.
+</para>
+<para>Each style lets you select common attributes as well as foreground
+and background colors. To unset a background color, rightclick to use the
+context menu.</para>
+</sect3>
+
+<sect3 id="config-dialog-editor-colors-highlighting-text-styles">
+<title>Highlighting Text Styles</title>
+<para>Here you can edit the text styles used by a specific highlight definition.
+The editor preselects the highlight used by your current document. To work on a
+different highlight, select one in the <guilabel>Highlight</guilabel> combobox
+above the style list.
+</para>
+<para>The name in the list of styles is using the style configured for
+the item, providing you with an immediate preview when configuring a style.
+</para>
+<para>Each style lets you select common attributes as well as foreground
+and background colors. To unset a background color, rightclick to use the
+context menu. In addition you can see if a style is equal to the default style
+used for the item, and set it to that if not.</para>
+<para>You will notice that many highlights contain other highlights represented
+by groups in the style list. For example most highlights import the Alert
+highlight, and many source code formats imports the Doxygen highlight. Editing
+colors in those groups only affects the styles when used in the edited highlight
+format.
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="config-dialog-editor-cursor-selection">
+<title>Cursor &amp; Selection</title>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Text Cursor Movement</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Smart home</guilabel></term>
+<listitem>
+<para>When selected, pressing the home key will cause the cursor to
+skip white space and go to the start of a line's text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Wrap cursor</guilabel></term>
+<listitem>
+<para>When on, moving the insertion cursor using the <emphasis
+role="bold">Left</emphasis> and <emphasis role="bold">Right</emphasis> keys will
+go on to previous/next line at beginning/end of the line, similar to most
+editors.</para><para>When off, the insertion cursor cannot be moved left of the
+line start, but it can be moved off the line end, which can be very handy for
+programmers. When this option is chosen, moving the cursor with the arrow keys
+off the end of a line (to the right) causes it to jump down to the beginning of
+the next line. Likewise when the cursor is moved past the beginning of a line
+(to the left) it jumps up to the end of the preceding line. When this option is
+not selected, moving the cursor right past the end of a line merely causes it to
+continue horizontally in the same line and trying to move it left past the
+beginning does nothing.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Page Up/Page Down moves cursor</guilabel></term>
+<listitem>
+<para>This option changes the behavior of the cursor when the user presses
+the <keycap>Page Up</keycap> or <keycap>Page Down</keycap> key. If unselected
+the text cursor will maintain its relative position within the visible text in
+&kate; as new text becomes visible as a result of the operation.  So if the
+cursor is in the middle of the visible text when the operation occurs it will
+remain there (except when one reaches the beginning or end.)  With this option
+selected, the first key press will cause the cursor to move to either the top or
+bottom of the visible text as a new page of text is displayed.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Autocenter cursor (lines):</guilabel></term>
+<listitem>
+<para>Sets the number of lines to maintain visible above and below the cursor
+when possible.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Selection Mode</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Normal</guilabel></term>
+<listitem>
+<para>Selections will be overwritten by typed text and will be lost on
+cursor movement.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Persistent</guilabel></term>
+<listitem>
+<para>Selections will stay even after cursor movement and typing.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-edit">
+<title>Editing</title>
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Tabulators</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Insert spaces instead of tabulators</guilabel></term>
+<listitem>
+<para>When this is enabled the editor will insert a calculated number of spaces
+according to the position in the text and the <option>tab-width</option> setting
+when you press the <keycap>TAB</keycap> key.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show tabulators</guilabel></term>
+<listitem>
+<para>When this is enabled &kate; will display a small dot as a visual
+representation of tabulator characters.</para>
+<note><para>This also causes dots to be drawn to indicate trailing white space.
+This will be fixed in a future version of &kate;</para></note>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term id="config-dialog-editor-tab-width">Tab Width</term> <listitem><para>If the
+<link  linkend="config-dialog-editor-word-wrap"><guilabel>Replace Tabs By
+Spaces</guilabel></link>
+option is selected this entry determines the number of
+spaces with which the editor will automatically replace
+tabs.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="config-dialog-editor-word-wrap"><guilabel>Static Word Wrap</guilabel></term>
+<listitem><para>
+Word wrap is a feature that causes the editor to automatically start a new line
+of text and move (wrap) the cursor to the beginning of that new line.  &kate;
+will automatically start a new line of text when  the current line reaches the
+length specified by the <link linkend="config-dialog-editor-wrap-words-at">Wrap Words
+At:</link> option.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Enable static word wrap</guilabel></term>
+<listitem>
+<para>Turns static word wrap on or off.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show static word wrap markers
+(if applicable)</guilabel></term>
+<listitem>
+<para>If this option is checked, a vertical line will be drawn at the word wrap
+column as defined in the <menuchoice> <guimenu>Settings</guimenu>
+<guimenuitem>Configure Editor...</guimenuitem></menuchoice> in the Editing tab.
+Please note that the word wrap marker is only drawn if you use a fixed pitch
+font.</para>
+</listitem>
+</varlistentry>
+<varlistentry id="config-dialog-editor-wrap-words-at">
+<term><guilabel>Wrap words at:</guilabel></term>
+<listitem>
+<para>If the <link linkend="config-dialog-editor-word-wrap">Word Wrap</link> option is selected
+this entry  determines the length (in characters) at which the editor will
+automatically start a new line.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Remove Trailing Spaces</guilabel></term>
+<listitem><para>&kate; will automatically eliminate extra spaces
+at the ends of lines of text.</para></listitem> </varlistentry>
+
+<varlistentry>
+<term><guilabel>Auto Brackets</guilabel></term> <listitem><para>When
+the user types a left bracket ([, (, or {) &kate; automatically enters the
+right bracket (}, ), or ]) to the right of the cursor.</para></listitem>
+</varlistentry>
+
+<varlistentry> <term>Maximum <link linkend="undo">undo</link> steps:</term>
+<listitem><para>Here the user may specify the number of steps &kate; will
+retain in memory for purposes of undoing entries and actions. This means that
+the higher the number of steps set the more memory &kate; will use for this.
+Setting  this entry to 10 would mean that the user would be be able reverse the
+last ten operations, <abbrev>i.e.</abbrev> click the <guibutton>undo</guibutton>
+button 10 times and obtain results.</para></listitem> </varlistentry>
+
+<varlistentry> <term>Smart search text from:</term>
+<listitem><para>This determines where &kate; will get the search
+text from (this will be automatically entered into the Find Text
+dialog):
+<itemizedlist>
+<listitem><para><emphasis role="bold">Nowhere:</emphasis> Don't guess the search
+text.</para></listitem>
+<listitem><para><emphasis role="bold">Selection Only:</emphasis> Use
+    the current text selection, if available. </para></listitem>
+<listitem><para><emphasis role="bold">Selection, then Current Word:</emphasis>
+Use the current selection if available, otherwise use the current word.
+</para></listitem>
+<listitem><para><emphasis role="bold">Current Word
+Only:</emphasis> Use the word that    the cursor is currently resting on, if
+available. </para></listitem>
+<listitem><para><emphasis role="bold">Current Word, then Selection:</emphasis>
+Use the current word if    available, otherwise use the current selection.
+</para></listitem>
+</itemizedlist>
+Note that, in all the above modes, if a
+search string has not been or cannot be determined, then the Find Text Dialog
+will fall back to the last search text.
+</para></listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-indent">
+<title>Indentation</title>
+<variablelist>
+<varlistentry>
+<term><guilabel>Automatic indentation</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Indentation mode:</guilabel></term>
+<listitem>
+<para>Select the automatic indentation mode you want to use as default. It is
+strongly recommended to use <userinput>None</userinput> or
+<userinput>Normal</userinput>here, and use filetype configurations to set other
+indentation modes for text formats like C/C++ code or &XML;.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Insert leading Doxygen "*" when typing</guilabel></term>
+<listitem>
+<para>Automatically insert a leading "*" while typing within a doxygen
+style comment. This setting is only enabled when applicable.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Indentation with Spaces</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Use spaces instead of tabs to indent</guilabel></term>
+<listitem>
+<para>This  replaces tabs with the number of spaces set in <guilabel>Number of
+spaces:</guilabel> below.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Emacs style mixed mode</guilabel></term>
+<listitem>
+<para>Use a mix of tabs and space characters for indentation.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Number of spaces:</guilabel></term>
+<listitem>
+<para>Set the number of spaces you want to use for indentation when you
+check <guilabel>Use spaces instead of tabs to indent</guilabel>
+above.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Keep Indent Profile</guilabel></term>
+<listitem><para>When this is enabled, the editor will not unindent lines in a
+selection further when the line with the least indentation becomes unindented.
+If you sometimes unindent blocks of indented code, this may be helpful.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Keep Extra Spaces</guilabel></term>
+<listitem><para>Indentations of more than the selected number of spaces
+will not be shortened.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Keys to use</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Tab key indents</guilabel></term>
+<listitem>
+<para>This  allows the <keycombo
+action="simul"><keycap>tab</keycap></keycombo> key to be used to indent.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Backspace key indent</guilabel></term>
+<listitem>
+<para>This allows the <keycombo
+action="simul"><keycap>backspace</keycap></keycombo> key to be used to
+indent.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Tab Key Mode if Nothing Selected</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Insert indent characters</guilabel></term>
+<listitem>
+<para>This allows the <keycombo
+action="simul"><keycap>Tab</keycap></keycombo> key insert indent
+characters.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Insert tab character</guilabel></term>
+<listitem>
+<para>This allows the <keycombo
+action="simul"><keycap>Tab</keycap></keycombo> key insert a tab.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Indent current line</guilabel></term>
+<listitem>
+<para>This allows the <keycombo
+action="simul"><keycap>Tab</keycap></keycombo> key indent the current
+line.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-open-save">
+<title>Open &amp; Save</title>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>File Format</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Encoding:</guilabel></term>
+<listitem>
+<para>This sets the default character encoding for your files.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>End of line:</guilabel></term>
+<listitem>
+<para>Choose your prefered end of line mode for your active
+document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Automatic end of line detection</guilabel></term>
+<listitem>
+<para>Check this if you want the editor to autodetect the end of line
+type. The first found end of line type will be used for the whole file.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Memory Usage</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Maximum loaded blocks per file:</guilabel></term>
+<listitem>
+<para>The editor will load given number of blocks (of around 2048 lines) of
+text into memory;  if the filesize is bigger than this the other blocks
+are swapped to disk and loaded transparently as-needed.</para>
+<para>This can cause little delays while navigating in the document; a
+larger block count increases the editing speed at the cost of memory.
+</para><para>For normal usage, just choose the highest possible block count:
+limit it only if you have problems with the memory usage.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Automatic Cleanups on Load/Save</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Remove trailing spaces</guilabel></term>
+<listitem>
+<para>The editor will automatically eliminate extra spaces at the ends of lines
+of text while loading/saving the file.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Folder Config File</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Search depth for config file:</guilabel></term>
+<listitem>
+<para>The editor will search the given number of folder levels upwards
+for &kate; config file and load the settings line from it.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Backup on Save</guilabel></term>
+<listitem><para>Backing up on save will cause &kate; to copy the disk file to
+&lt;prefix&gt;&lt;filename&gt;&lt;suffix&gt;' before saving changes.
+The suffix defaults to <emphasis role="bold">~</emphasis> and prefix is empty by
+default. </para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Local files</guilabel></term>
+<listitem>
+<para>Check this if you want backups of local files when
+saving.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Remote files</guilabel></term>
+<listitem>
+<para>Check this if you want backups of remote files when saving.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Prefix</guilabel></term>
+<listitem>
+<para>Enter the prefix to prepend to the backup file names.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Suffix</guilabel></term>
+<listitem>
+<para>Enter the suffix to add to the backup file names.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-highlighting">
+<title>Highlighting</title>
+<para>This group of options is used to customize the highlighting styles for
+each programming language type. Any changes you made in other areas of this
+dialog apply only to this type.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Highlight:</guilabel></term>
+<listitem><para>This is used to choose the language type to
+configure.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Informations</guilabel></term>
+<listitem>
+<para>
+View the properties of the chosen language highlighting rules:
+author name and license.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Properties</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>File extensions:</guilabel></term>
+<listitem><para>This is the list of file extensions used to determine which
+files to highlight using the current syntax highlight mode.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>MIME types:</guilabel></term>
+<listitem><para>Clicking the wizard button will display a dialog with a list of
+all available mime types to choose from.</para><para>The <emphasis
+role="bold">File Extensions</emphasis> entry will automatically be edited as
+well.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Priority:</guilabel></term>
+<listitem><para>Set the priority of the highlight rule.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Download...</guibutton></term>
+<listitem>
+<para>
+Click this button to download new or updated syntax highlight descriptions
+from the &kate; website.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-filetypes">
+<title>Filetypes</title>
+<para>This page allows you to override the default configuration for documents
+of specified mimetypes. When the editor loads a document, it will try if it
+matches the file masks or mimetypes for one of the defined filetypes, and if so
+apply the variables defined. If more filetypes match, the one with the highest
+priority will be used.
+</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Filetype:</guilabel></term>
+<listitem><para>The filetype with the highest priority is the one displayed in
+the first drop down box. If more filetypes were found, they are
+also listed.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>New</guilabel></term>
+<listitem><para>This is used to create a new filetype. After
+you click on this button, the fields below get empty and you
+can fill the properties you want for the new filetype.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Delete</guilabel></term>
+<listitem><para>To remove an existing filetype, select it from the drop down
+box and press the Delete button.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem> </varlistentry>
+
+<varlistentry>
+<term><guilabel>Properties of current filetype</guilabel></term>
+<listitem><para>The filetype with the highest priority is the one displayed in
+the first drop down box. If more filetypes were found, they are also
+listed.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Name:</guilabel></term>
+<listitem><para>The name of the filetype will be the text of the corresponding
+menu item. This name is displayed in the
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem>
+</menuchoice ></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Section:</guilabel></term>
+<listitem><para>The section name is used to organize the file types in
+menus. This is also used in the
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem>
+</menuchoice> menu.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Variables:</guilabel></term>
+<listitem><para>This string allows you to configure &kate;'s settings for the
+files selected by this mimetype using &kate; variables. You can set almost any
+configuration option, such as highlight, indent-mode, encoding,
+etc.</para><para>For a full list of known variables, see the
+manual.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>File extensions:</guilabel></term>
+<listitem><para>The wildcards mask allows you to select files by filename. A
+typical mask uses an asterisk and the file extension, for example
+<filename>*.txt; *.text</filename>. The string is a semicolon-separated list of
+masks.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>MIME types:</guilabel></term>
+<listitem><para>Displays a wizard that helps you easily select
+mimetypes.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Priority:</guilabel></term>
+<listitem><para>Sets a priority for this file type. If more than one file type
+selects the same file, the one with the highest priority will be
+used.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem> </varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="config-dialog-editor-shortcuts">
+<title>Shortcuts</title>
+<para>You can change here the shortcut keys configuration. Select an
+action and click on <guilabel>Custom</guilabel> if you want a different shortcut
+for this action.</para>
+<para>The search line alllows you to look for a specific action and see
+its associated shortcut.</para>
+</sect2>
+
+<sect2 id="config-dialog-editor-plugins">
+<title>Plugins</title>
+<para>This tab lists all available plugins and you can check those you
+want to use. Once a plugin is checked, the
+<guibutton>Configure</guibutton> button is enabled and you can click it
+in order to configure the highlighted plugin.</para>
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="config-variables">
+
+<title>Configuring With Document Variables</title>
+
+<para>Kate variables is kateparts implementation of document variables, similar
+to emacs and vi modelines. In katepart, the lines have the format
+
+<userinput>kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]</userinput>
+
+the lines can of course be in a comment, if the file is in a format with comments.
+Variable names are single words (no whitespace), and anything up to the next
+semicolon is the value. The semicolon is required.</para>
+
+<para>Here is an example variable line, forcing indentation settings for a C++,
+java or javascript file:
+
+<programlisting>// kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;</programlisting>
+</para>
+
+<note><para>Only the first and last 10 lines are searched for variable lines.</para></note>
+
+<para>There are variables to support almost all configurations in katepart, and
+aditionally plugins can use variables, in which case it should be documented in
+the plugin's documentation.</para>
+
+<sect2 id="config-variables-howto">
+<title>How kate uses variables</title>
+
+<para>When reading configuration, katepart looks in the following places
+(in that order):
+
+<itemizedlist>
+<listitem><para>The global configuration.</para></listitem>
+<listitem><para>Optional session data.</para></listitem>
+<listitem><para>The "Filetype" configuration.</para></listitem>
+<listitem><para>Document variables in the document itself.</para></listitem>
+<listitem><para>Settings made during editing from menu or command line.</para></listitem>
+</itemizedlist>
+
+As you can understand document variables has the next highest precedence.
+Whenever a document is saved, the document variables are reread, and will
+overwrite changes made using menu items or the command line.</para>
+
+<para>Any variable not listed below is stored in the document and can be queried
+by other objects such as plugins, which can use them for their own purpose.
+For example the variable indent mode uses document variables for its
+configuration.</para>
+
+<para>The variables listed here documents &kate; version 2.4. More variables
+may be added in the future. There are 3 possible types of values for variables,
+with the following valid expressions:
+<itemizedlist>
+<listitem><para>BOOL - on|off|true|false|1|0</para></listitem>
+<listitem><para>INTEGER - any integer number</para></listitem>
+<listitem><para>STRING - anything else</para></listitem>
+</itemizedlist>
+</para>
+
+<variablelist>
+<title>Available Variables</title>
+
+<varlistentry>
+<term><cmdsynopsis><command>auto-brackets</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set auto insertion of brackets on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>auto-center-lines</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the number of autocenter lines.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>auto-insert-doxygen</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Turn insertion of the leading asterisk in doxygen comments on or
+off. This has no effect unless you use the cstyle auto-indenter. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>background-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the document background color. The value must be something
+that can be evaluated to a valid color, for example "#ff0000".</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>backspace-indents</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Turn backspace indenting on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>block-selection</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Turn block selection on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>bracket-highlight-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the color for the bracket highlight. The value must be
+something that can be evaluated to a valid color, for example "#ff0000" </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>current-line-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the color for the current line. The  value must be
+something that can be evaluated to a valid color, for example "#ff0000".</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>dynamic-word-wrap</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Turns dynamic word wrap on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>eol | end-of-line</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the end of line mode. Valid settings are
+<quote>unix</quote>, <quote>mac</quote> and <quote>dos</quote></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>encoding</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the document encoding. The value must be a valid encoding
+name, like <quote>utf-8</quote>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>font-size</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the point size of the document font.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>font</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the font of the document. The value should be a valid font
+name, for example <quote>courier</quote>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>icon-bar-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the icon bar color. The  value must be something that can
+be evaluated to a valid color, for example <literal>#ff0000</literal>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>icon-border</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set the display of the icon border on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>folding-markers</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set the display of folding markers on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>indent-mode</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the auto-indentation mode. The options <quote>none</quote>,
+<quote>normal</quote>, <quote>cstyle</quote>, <quote>csands</quote>,
+<quote>python</quote>, <quote>xml</quote> are recognized. See the section
+<xref linkend="kate-part-autoindent"/> for details.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>indent-width</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the indentation width.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>keep-extra-spaces</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set wheather to keep extra spaces when calculating indentation width.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>keep-indent-profile</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>If enabled, prevents unindenting a block if at least one line
+has no indentation.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>line-numbers</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set the display of line numbers on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>mixed-indent</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set mixed indentation ala Emacs on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>overwrite-mode</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set overwrite mode on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>persistent-selection</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set persistent selection on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>remove-trailing-space</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set dynamic end of line cleanup on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>replace-tabs-save</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set tab-&gt;space conversion on save on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>replace-tabs</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set dynamic tab-&gt;space conversion on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>replace-trailing-space-save</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set end of line cleanup on save on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>scheme</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the color scheme. The string must be the name of a color
+scheme that exists in your configuration to have any effect.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>selection-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the selection color. The  value must be something that can
+be evaluated to a valid color, for example "#ff0000".</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>show-tabs</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set the visual TAB character on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>smart-home</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set smart home navigation on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>space-indent</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set indentation with spaces on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>tab-indents</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set the TAB key indentation on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>tab-width</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the tab display width.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>undo-steps</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the number of undo steps to remember.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>word-wrap-column</command><arg>INT</arg></cmdsynopsis></term>
+<listitem><para>Set the hard word wrap width.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>word-wrap-marker-color</command><arg>STRING</arg></cmdsynopsis></term>
+<listitem><para>Set the word wrap marker color. The  value must be something
+that can be evaluated to a valid color, for example "#ff0000".</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>word-wrap</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set hard word wrapping on or off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><cmdsynopsis><command>wrap-cursor</command><arg>BOOL</arg></cmdsynopsis></term>
+<listitem><para>Set cursor wrapping on or off.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook
new file mode 100644
index 000000000..e6beaac58
--- /dev/null
+++ b/doc/kate/fundamentals.docbook
@@ -0,0 +1,621 @@
+<chapter id="fundamentals">
+<chapterinfo>
+<authorgroup>
+<author><personname><firstname></firstname></personname></author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>The Fundamentals</title>
+
+<para>
+If you have ever used a text editor, you will have no problem using
+&kate;. In the next two sections, <link linkend="starting-kate">Starting
+&kate; </link> and in <link linkend="working-with-kate">Working with
+&kate;</link>, we'll show you everything you need to get up and running
+quickly.
+</para>
+
+<sect1 id="starting-kate">
+<title>Starting &kate;</title>
+
+<para>
+You can start &kate; from the <guimenu>K menu</guimenu> or from the
+command line.
+</para>
+
+<sect2 id="starting-from-the-menu">
+<title>From the Menu</title>
+<para>
+Open the &kde; program menu by clicking on the
+<guiicon>big K</guiicon> icon on the toolbar at the bottom left of your
+screen. This will raise the <guimenu>program menu</guimenu>. Move your
+cursor up the menu to the <menuchoice><guimenu>Utilities</guimenu>
+<guimenuitem>Editors</guimenuitem></menuchoice> menu item. A list
+of available editors will appear. Choose
+<guimenuitem>&kate;</guimenuitem>.
+</para>
+
+<para>
+Unless you configure &kate; not to, it will load the last files you
+edited. See <link linkend="configure">Configuring &kate;</link> to learn
+how to toggle this feature on and off.
+</para>
+
+</sect2>
+
+<sect2 id="starting-from-the-command-line">
+<title>From the Command Line</title>
+
+<para>
+You can start &kate; by typing its name on the command line. If you give
+it a file name, as in the example below, it will open or create that
+file.
+</para>
+
+<informalexample>
+<screen>
+<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>myfile.txt</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<para>
+If you have an active connection, and permission, you can take advantage
+of &kde;'s network transparency to open files on the internet.
+</para>
+
+<informalexample>
+<screen>
+<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/README_FIRST</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<sect3 id="command-line-options">
+<title>Command Line Options</title>
+<para>&kate; accepts following command line options:</para>
+
+<variablelist>
+<varlistentry>
+<term><userinput><command>kate</command> <option>--help</option></userinput></term>
+<listitem>
+<para>
+This lists the most basic options available at the command line.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--help-qt</option></userinput></term>
+<listitem>
+<para>
+This lists the options available for changing the way &kate; interacts
+with &Qt;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command> <option>--help-kde</option></userinput></term>
+<listitem>
+<para>
+This lists the options available for changing the way &kate; interacts
+with &kde;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>-s</option> <option>--start</option> <parameter>name</parameter></userinput></term>
+<listitem>
+<para>
+Starts kate with the session <parameter>name</parameter>. The session is created
+if it does not exist already. If a &kate; instance running the specified session
+exists, the specified files are loaded in that instance. When used with the
+<option>--use</option> option, an instance running this session will be used as
+well.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>-u</option> <option>--use</option> <parameter>URL</parameter></userinput></term>
+<listitem>
+<para>
+Causes &kate; to use and existing instance if there is one. If you want all
+documents to open in one kate instance, you can add this option to the default
+command in your kde application configuration, as well as create a shell alias
+in your command intepreter if it supports that.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>-p</option> <option>--pid</option> <parameter>PID</parameter></userinput></term>
+<listitem>
+<para>
+Only reuses an instance with the specified PID (Process ID). Used with the
+<option>--use</option> option.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--encoding</option> <parameter>encoding</parameter>
+<parameter>URL</parameter></userinput></term>
+<listitem><para>Uses the specified encoding for the document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--line</option> <parameter>line</parameter>
+<parameter>URL</parameter></userinput></term>
+<listitem><para>Navigates to the specified line after opening the document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--column</option> <parameter>column</parameter>
+<parameter>URL</parameter></userinput></term>
+<listitem><para>Navigates to the specified column after opening the document.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--stdin</option></userinput></term>
+<listitem><para>Reads the document content from STDIN. This
+is similar to the common option <option>-</option> used in many command line
+programs, and allows you to pipe command output into &kate;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--tempfile</option></userinput></term>
+<listitem><para>Since &kate; 2.5.1 this standard &kde; option is supported.
+When used, the specified files are treated as temporary files and
+deleted (if they are local files and you have sufficient permissions) when
+closed, unless they are modified since they were opened.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--help-all</option></userinput></term>
+<listitem>
+<para>
+This lists all of the command line options.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--author</option></userinput></term>
+<listitem>
+<para>
+Lists &kate;'s authors in the terminal window.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>-v</option> <option>--version</option></userinput></term>
+<listitem>
+<para>
+Lists version information for &Qt;, &kde;, and &kate;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput><command>kate</command>
+<option>--license</option></userinput></term>
+<listitem>
+<para>
+Shows license information.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+<sect2 id="drag-and-drop">
+<title>Drag and Drop</title>
+<para>
+&kate; uses the &kde; Drag and Drop protocol. Files may be dragged and
+dropped onto &kate; from the Desktop, &konqueror; or some remote ftp
+site opened in one of &konqueror;'s windows.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="working-with-kate">
+<title>Working with &kate;</title>
+<para>
+<link linkend="quick-start">Quick Start</link> will show you how to
+toggle four simple options that will let you configure some of &kate;'s
+more powerful features right away. <link linkend="keystroke-commands">
+Shortcuts</link> lays out some of the default keystroke
+shortcuts for those who can't or don't want to use a mouse.
+</para>
+
+<sect2 id="quick-start">
+<title>Quick Start</title>
+
+<para>
+This section will describe some of the items on the
+<guimenu>Settings</guimenu> menu so that you can quickly configure
+&kate; to work the way you want it.
+</para>
+
+<para> When you start &kate; for the first time you'll see two windows
+with white backgrounds. Above the two windows is a toolbar with the
+usual labeled icons. And above that, a menubar.
+</para>
+
+<para>
+The left-hand window is a side bar. It combines the Documents
+and Filesystem Browser windows. Switch between the two by clicking on the tabs
+to the left of the window. </para>
+
+<para>
+If you've started &kate; with a file, the right-hand window will show
+the file you are editing and the Documents on the side bar will show the
+name of the file. Use the Filesystem Browser window to open files.
+</para>
+
+<para>
+You can toggle the Documents and Filesystem Browser window on and off in
+<menuchoice><guimenu>Window</guimenu><guimenu>Tool Views</guimenu></menuchoice>
+menu. This menu offers you your first glimpse into &kate;'s power and
+flexibility.  In this section we'll look at three items:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenuitem>Show/Hide Documents</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+Toggles the Documents on and off. If the Documents/Filesystem Browser window is
+not open, &kate; launches the side bar as a separate, undocked,
+window. To dock the window grab the two thin parallel lines above the
+tabs by clicking on them with your &LMB; and holding the button
+down. Drag the the window into &kate;'s editing window and release the
+&LMB; when you have positioned the Documents/Filesystem Browser window as you
+prefer.
+</para>
+
+<tip>
+<para>
+If you have grabbed the two parallel lines successfully your mouse
+pointer will turn into two crossed arrows as you drag.
+</para>
+</tip>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenuitem>Show/Hide
+Filesystem Browser</guimenuitem></menuchoice></term>
+<listitem>
+<para>
+Toggles the Filesystem Browser on and off. This menu item is the same as
+<guimenuitem>Show Documents</guimenuitem> with one difference.  Toggling
+it on launches the window with the Filesystem Browser on top.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Show/Hide
+Terminal</guimenuitem></menuchoice></term>
+<listitem>
+<para>
+Toggles a terminal emulator on and off at the bottom of &kate;'s
+window. In other words, it gives you a command line within the
+application.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="keystroke-commands">
+<title>Shortcuts</title>
+
+<para>
+Many of &kate;'s keystroke commands (shortcuts) are configurable by
+way of the <link linkend="settings">Settings</link> menu.  By default
+&kate; honors the following key bindings.
+</para>
+
+<informaltable>
+<tgroup cols="2">
+<tbody>
+
+<row><entry><para><keycap>Insert</keycap></para></entry>
+<entry><para>
+Toggle between Insert and Overwrite mode. When in insert mode the editor
+will add any typed characters to the text and push any previously typed
+data to the right of the text cursor. Overwrite mode causes the entry of
+each character to eliminate the current character.</para></entry>
+</row>
+<row>
+<entry><para><keycombo><keycap>Left Arrow</keycap></keycombo></para></entry>
+<entry><para>Move the cursor one character to the left </para></entry>
+</row>
+<row>
+<entry><para><keycombo><keycap>Right Arrow</keycap></keycombo></para></entry>
+<entry><para> Move the cursor one character to the right </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Up Arrow</keycap></keycombo></para></entry>
+<entry><para> Move the cursor up one line  </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Down Arrow</keycap></keycombo></para></entry>
+<entry><para> Move the cursor down one line </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Page Up</keycap></keycombo></para></entry>
+<entry><para> Move the cursor up one page  </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Page Down</keycap></keycombo></para></entry>
+<entry><para>Move the cursor down one page  </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Backspace</keycap></keycombo></para></entry>
+<entry><para> Delete the character to the left of the cursor </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Home</keycap></keycombo></para></entry>
+<entry><para> Move the cursor to the beginning of the line </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>End</keycap></keycombo></para></entry>
+<entry><para> Move the cursor to the end of the line </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>Delete</keycap></keycombo></para></entry>
+<entry><para>Delete the character to the right of the cursor (or any selected
+text)</para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Shift;<keycap>Left Arrow</keycap></keycombo></para></entry>
+<entry><para> Mark text one character to the left </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Shift;<keycap>Right Arrow</keycap></keycombo></para></entry>
+<entry><para> Mark text one character to the right </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>F1</keycap></keycombo></para></entry>
+<entry><para> Help</para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></para></entry>
+<entry><para><link linkend="whats-this">What's this?</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></para></entry>
+<entry><para><link linkend="find"> Find</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul"><keycap>F3</keycap></keycombo></para></entry>
+<entry><para><link linkend="find-again"> Find again</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></para></entry>
+<entry><para>Set a Bookmark</para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></para></entry>
+<entry><para> Copy the marked text to the clipboard. </para></entry>
+</row>
+
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></para></entry>
+<entry><para> <link linkend="new">New</link> document</para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></para></entry>
+<entry><para><link linkend="print">Print</link> </para></entry>
+</row>
+<row>
+
+<entry><para><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></para></entry>
+<entry><para>Quit - close active copy of editor </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></para></entry>
+<entry><para><link linkend="replace"> Replace</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></para></entry>
+<entry><para>Save your file.</para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></para></entry>
+<entry><para> Paste.</para></entry>
+</row>
+
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></para></entry>
+<entry><para>Delete the marked text and copy it to the clipboard. </para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></para></entry>
+<entry><para><link linkend="undo">Undo</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></para></entry>
+<entry><para><link linkend="redo">Redo</link></para></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</sect2>
+
+</sect1>
+
+<sect1 id="fundamentals-using-sessions">
+<title>Using Sessions</title>
+
+<para>Sessions is how &kate; lets you keep more than one list of files and
+GUI configuration around. You can have as many named sessions as you want,
+and you can use unnamed or anonymous sessions for files you want to use only
+once. Currently &kate; can save the list of open files, and the general window
+configuration in the session, future versions of &kate; may add more features
+that can be saved in sessions. With the introduction of sessions, &kate; also
+allows you to open any number of instances of the application instead of just
+one as it used to do as the default behavior.</para>
+
+<para>Sessions are supported in three areas:
+
+<itemizedlist>
+<listitem><para><link linkend="command-line-options"><emphasis>Command line
+options</emphasis></link> that lets you select and start sessions when launching
+kate from the command line.</para>
+</listitem>
+<listitem><para><link linkend="sessions-menu"><emphasis>The Sessions
+menu</emphasis></link> that lets you switch, save, start and manage your
+sessions</para></listitem>
+<listitem><para><link linkend="config-dialog-sessions"><emphasis>Configuration
+options</emphasis></link> that lets you decide how sessions generally should
+behave.</para></listitem>
+</itemizedlist>
+
+</para>
+
+<para>When starting a new session, the GUI configuration of <guilabel>Default
+Session</guilabel> is loaded. To save window configuration in the default
+session, you need to enable saving window configuration in the sessions
+configuration page of the configuration dialog and then load the default
+session, set up the window as desired and save the session again.</para>
+
+<para>When a named session is loaded, &kate; will display the session name at
+the start of the window title, which then have the form
+&quot;<replaceable>Session Name</replaceable>: <replaceable>Document name or
+&URL;</replaceable> - &kate;&quot;</para>
+
+<para>When opening files on the command line with <option>--start
+<replaceable>name</replaceable></option> or if a session is selected using the
+session chooser, the specified session is loaded prior to the files specified
+on the command line. To open files from the commandline in a new, unnamed
+session, configure kate to start a new session pr default in the session page of
+the configuration dialog or use <option>--start</option> with an empty string:
+<replaceable>''</replaceable>.</para>
+
+<para>Since &kate; 2.5.1 the <acronym>PID</acronym> of the current instance is
+exported to the environment variable <envar>KATE_PID</envar>. When opening files
+from the built in terminal Kate will automatically select the current instance
+if nothing else is indicated on the command line.</para>
+
+<sect2 id="old-behavior">
+<title>Restoring old style &kate; behavior</title>
+
+<para>When you get used to using sessions you will hopefully see that they
+provide a very simple and efficient tool for working in different areas.
+However, if you prefer the old &kate; behavior (one instance opens all files),
+you can easily achieve that by following this simple strategy:
+
+<itemizedlist>
+<listitem><para>Make kate allways start with the <option>--use</option>
+parameter by adding that to the command in the application preferences,
+and additionally using a shell alias.</para></listitem>
+<listitem><para>Configure &kate; to load the last used session at startup.</para>
+</listitem>
+<listitem><para>Configure &kate; to save the file list when closing a session.
+</para></listitem>
+<listitem><para>Load the default session once</para></listitem>
+</itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="fundamentals-getting-help">
+
+<title>Getting Help</title>
+
+<sect2>
+
+<title>With &kate;</title>
+<variablelist>
+
+<varlistentry>
+<term>This manual</term>
+
+<listitem>
+<para>Offers detailed documentation on all menu commands,
+configuration options, tools, dialogs, plugins &etc; as well as
+descriptions of of the &kate; window, the editor and various concepts
+used in the application.</para>
+
+<para>Press <keycap>F1</keycap> or use the
+<menuchoice><guimenu>Help</guimenu></menuchoice>
+<guisubmenu>Contents</guisubmenu> menu topic to view this
+manual.</para></listitem>
+
+</varlistentry>
+
+<varlistentry id="whats-this">
+<term>What's This Help</term>
+<listitem>
+<para>What's This help offers immediate help with single elements of
+graphical windows, such as buttons or other window areas.</para>
+
+<para>We strive to provide What's This help for any elements for which
+it makes sense. It is available throughout the configuration dialog,
+and in many other dialogs as well.</para>
+
+<para>To employ What's This help, press
+<keycombo>&Shift;<keycap>F1</keycap></keycombo> or use the
+<menuchoice><guimenu>Help</guimenu><guimenuitem>What's
+This</guimenuitem></menuchoice> menu item to enable What's This
+mode. The cursor will turn into an arrow with a question mark, and you
+can now click any element in the window to read the What's This help
+for that element, if it is available.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Help Buttons in Dialogs</term>
+<listitem>
+<para>Some dialogs have a <guibutton>Help</guibutton> Button. Pressing
+it will start the &khelpcenter; and open the relevant
+documentation.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>With Your Text Files</title>
+
+<para>&kate; does not (yet!) provide any means for reading document
+related documentation. Depending on the file you are editing, you may
+find the <link linkend="kate-mdi-tools-konsole">Built in
+&konsole;</link> helpful for viewing related &UNIX; manual pages or
+info documentation, or you can use &konqueror;.</para>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/highlighted.png b/doc/kate/highlighted.png
new file mode 100644
index 000000000..ffb95ec48
--- /dev/null
+++ b/doc/kate/highlighted.png
diff --git a/doc/kate/highlighting.docbook b/doc/kate/highlighting.docbook
new file mode 100644
index 000000000..76952d26a
--- /dev/null
+++ b/doc/kate/highlighting.docbook
@@ -0,0 +1,931 @@
+<appendix id="highlight">
+<appendixinfo>
+<authorgroup>
+<author><personname><firstname></firstname></personname></author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</appendixinfo>
+<title>Working with Syntax Highlighting</title>
+
+<sect1 id="highlight-overview">
+
+<title>Overview</title>
+
+<para>Syntax Highlighting is what makes the editor automatically
+display text in different styles/colors, depending on the function of
+the string in relation to the purpose of the file.  In program source
+code for example, control statements may be rendered bold, while data
+types and comments get different colors from the rest of the
+text. This greatly enhances the readability of the text, and thus
+helps the author to be more efficient and productive.</para>
+
+<mediaobject>
+<imageobject><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
+<textobject><phrase>A Perl function, rendered with syntax
+highlighting.</phrase></textobject>
+<caption><para>A Perl function, rendered with syntax highlighting.</para>
+</caption>
+</mediaobject>
+
+<mediaobject>
+<imageobject><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
+<textobject><phrase>The same Perl function, without
+highlighting.</phrase></textobject>
+<caption><para>The same Perl function, without highlighting.</para></caption>
+</mediaobject>
+
+<para>Of the two examples, which is easiest to read?</para>
+
+<para>&kate; comes with a flexible, configurable and capable system
+for doing syntax highlighting, and the standard distribution provides
+definitions for a wide range of programming, scripting and markup
+languages and other text file formats. In addition you can
+provide your own definitions in simple &XML; files.</para>
+
+<para>&kate; will automatically detect the right syntax rules when you
+open a file, based on the &MIME; Type of the file, determined by its
+extension, or, if it has none, the contents. Should you experience a
+bad choice, you can manually set the syntax to use from the
+<menuchoice><guimenu>Documents</guimenu><guisubmenu>Highlight
+Mode</guisubmenu></menuchoice> menu.</para>
+
+<para>The styles and colors used by each syntax highlight definition
+can be configured using the <link
+linkend="config-dialog-editor-appearance">Appearance</link> page of the
+<link linkend="config-dialog">Config Dialog</link>, while the &MIME; Types
+it should be used for, are handeled by the <link
+linkend="config-dialog-editor-highlighting">Highlight</link>
+page.</para>
+
+<note>
+<para>Syntax highlighting is there to enhance the readability of
+correct text, but you cannot trust it to validate your text. Marking
+text for syntax is difficult depending on the format you are using,
+and in some cases the authors of the syntax rules will be proud if 98%
+of text gets correctly rendered, though most often you need a rare
+style to see the incorrect 2%.</para>
+</note>
+
+<tip>
+<para>You can download updated or additional syntax highlight
+definitions from the &kate; website by clicking the
+<guibutton>Download</guibutton> button in the <link
+linkend="config-dialog-editor-highlighting">Highlight Page</link> of the <link
+linkend="config-dialog">Config Dialog</link>.</para>
+</tip>
+
+</sect1>
+
+<sect1 id="katehighlight-system">
+
+<title>The &kate; Syntax Highlight System</title>
+
+<para>This section will discuss the &kate; syntax highlighting
+mechanism in more detail. It is for you if you want to know about
+it, or if you want to change or create syntax definitions.</para>
+
+<sect2 id="katehighlight-howitworks">
+
+<title>How it Works</title>
+
+<para>Whenever you open a file, one of the first things the &kate;
+editor does is detect which syntax definition to use for the
+file. While reading the text of the file, and while you type away in
+it, the syntax highlighting system will analyze the text using the
+rules defined by the syntax definition and mark in it where different
+contexts and styles begin and end.</para>
+
+<para>When you type in the document, the new text is analyzed and marked on the
+fly, so that if you delete a character that is marked as the beginning or end
+of a context, the style of surrounding text changes accordingly.</para>
+
+<para>The syntax definitions used by the &kate; Syntax Highlighting System are
+&XML; files, containing
+<itemizedlist>
+<listitem><para>Rules for detecting the role of text, organized into context blocks</para></listitem>
+<listitem><para>Keyword lists</para></listitem>
+<listitem><para>Style Item definitions</para></listitem>
+</itemizedlist>
+</para>
+
+<para>When analyzing the text, the detection rules are evaluated in
+the order in which they are defined, and if the beginning of the
+current string matches a rule, the related context is used. The start
+point in the text is moved to the final point at which that rule
+matched and a new loop of the rules begins, starting in the context
+set by the matched rule.</para>
+
+</sect2>
+
+<sect2 id="highlight-system-rules">
+<title>Rules</title>
+
+<para>The detection rules are the heart of the highlighting detection
+system. A rule is a string, character or <link
+linkend="regular-expressions">regular expression</link> against which
+to match the text being analyzed. It contains information about which
+style to use for the matching part of the text. It may switch the
+working context of the system either to an explicitly mentioned
+context or to the previous context used by the text.</para>
+
+<para>Rules are organized in context groups. A context group is used
+for main text concepts within the format, for example quoted text
+strings or comment blocks in program source code. This ensures that
+the highlighting system does not need to loop through all rules when
+it is not necessary, and that some character sequences in the text can
+be treated differently depending on the current context.
+</para>
+
+<para>Contexts may be generated dynamically to allow the usage of instance
+specific data in rules.</para>
+
+</sect2>
+
+<sect2 id="highlight-context-styles-keywords">
+<title>Context Styles and Keywords</title>
+
+<para>In some programming languages, integer numbers are treated
+differently than floating point ones by the compiler (the program that
+converts the source code to a binary executable), and there may be
+characters having a special meaning within a quoted string. In such
+cases, it makes sense to render them differently from the surroundings
+so that they are easy to identify while reading the text. So even if
+they do not represent special contexts, they may be seen as such by
+the syntax highlighting system, so that they can be marked for
+different rendering.</para>
+
+<para>A syntax definition may contain as many styles as required to
+cover the concepts of the format it is used for.</para>
+
+<para>In many formats, there are lists of words that represent a
+specific concept. For example in programming languages, the control
+statements is one concept, data type names another, and built in
+functions of the language a third. The &kate; Syntax Highlighting
+System can use such lists to detect and mark words in the text to
+emphasize concepts of the text formats.</para>
+
+</sect2>
+
+<sect2 id="kate-highlight-system-default-styles">
+<title>Default Styles</title>
+
+<para>If you open a C++ source file, a &Java; source file and an
+<acronym>HTML</acronym> document in &kate;, you will see that even
+though the formats are different, and thus different words are chosen
+for special treatment, the colors used are the same. This is because
+&kate; has a predefined list of Default Styles which are employed by
+the individual syntax definitions.</para>
+
+<para>This makes it easy to recognize similar concepts in different
+text formats. For example comments are present in almost any
+programming, scripting or markup language, and when they are rendered
+using the same style in all languages, you do not have to stop and
+think to identify them within the text.</para>
+
+<tip>
+<para>All styles in a syntax definition use one of the default
+styles. A few syntax definitions use more styles that there are
+defaults, so if you use a format often, it may be worth launching the
+configuration dialog to see if some concepts are using the same
+style. For example there is only one default style for strings, but as
+the Perl programming language operates with two types of strings, you
+can enhance the highlighting by configuring those to be slightly
+different. All <link linkend="kate-highlight-default-styles">available default styles</link>
+will be explained later.</para>
+</tip>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="katehighlight-xml-format">
+<title>The Highlight Definition &XML; Format</title>
+
+<sect2>
+<title>Overview</title>
+
+<para>This section is an overview of the Highlight Definition &XML;
+format. Based on a small example it will describe the main components
+and their meaning and usage. The next section will go into detail with
+the highlight detection rules.</para>
+
+<para>The formal definition, aka the <acronym>DTD</acronym> is stored
+in the file <filename>language.dtd</filename> which should be
+installed on your system in the folder
+<filename>$<envar>KDEDIR</envar>/share/apps/katepart/syntax</filename>.
+</para>
+
+<variablelist>
+<title>Main sections of &kate; Highlight Definition files</title>
+
+<varlistentry>
+<term>A highlighting file contains a header that sets the XML version and the doctype:</term>
+<listitem>
+<programlisting>
+&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+&lt;!DOCTYPE language SYSTEM &quot;language.dtd&quot;&gt;
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The root of the definition file is the element <userinput>language</userinput>.
+Available attributes are:</term>
+
+<listitem>
+<para>Required attributes:</para>
+<para><userinput>name</userinput> sets the name of the language. It appears in the menus and dialogs afterwards.</para>
+<para><userinput>section</userinput> specifies the category.</para>
+<para><userinput>extensions</userinput> defines file extensions, like &quot;*.cpp;*.h&quot;</para>
+
+<para>Optional attributes:</para>
+<para><userinput>mimetype</userinput> associates files &MIME; Type based.</para>
+<para><userinput>version</userinput> specifies the current version of the definition file.</para>
+<para><userinput>kateversion</userinput> specifies the latest supported &kate; version.</para>
+<para><userinput>casesensitive</userinput> defines, whether the keywords are casesensitiv or not.</para>
+<para><userinput>priority</userinput> is necessary if another highlight definition file uses the same extensions. The higher priority will win.</para>
+<para><userinput>author</userinput> contains the name of the author and his email-address.</para>
+<para><userinput>license</userinput> contains the license, usually LGPL, Artistic, GPL and others.</para>
+<para><userinput>hidden</userinput> defines, whether the name should appear in &kate;'s menus.</para>
+<para>So the next line may look like this:</para>
+<programlisting>
+&lt;language name=&quot;C++&quot; version=&quot;1.00&quot; kateversion=&quot;2.4&quot; section=&quot;Sources&quot; extensions=&quot;*.cpp;*.h&quot; /&gt;
+</programlisting>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>Next comes the <userinput>highlighting</userinput> element, which
+contains the optional element <userinput>list</userinput> and the required
+elements <userinput>contexts</userinput> and <userinput>itemDatas</userinput>.</term>
+<listitem>
+<para><userinput>list</userinput> elements contain a list of keywords. In
+this case the keywords are <emphasis>class</emphasis> and <emphasis>const</emphasis>.
+You can add as many lists as you need.</para>
+<para>The <userinput>contexts</userinput> element contains all contexts.
+The first context is by default the start of the highlighting. There are
+two rules in the context <emphasis>Normal Text</emphasis>, which match
+the list of keywords with the name <emphasis>somename</emphasis> and a
+rule that detects a quote and switches the context to <emphasis>string</emphasis>.
+To learn more about rules read the next chapter.</para>
+<para>The third part is the <userinput>itemDatas</userinput> element. It
+contains all color and font styles needed by the contexts and rules.
+In this example, the <userinput>itemData</userinput> <emphasis>Normal Text</emphasis>,
+<emphasis>String</emphasis> and <emphasis>Keyword</emphasis> are used.
+</para>
+<programlisting>
+  &lt;highlighting&gt;
+    &lt;list name=&quot;somename&quot;&gt;
+      &lt;item&gt; class &lt;/item&gt;
+      &lt;item&gt; const &lt;/item&gt;
+    &lt;/list&gt;
+    &lt;contexts&gt;
+      &lt;context attribute=&quot;Normal Text&quot; lineEndContext=&quot;#pop&quot; name=&quot;Normal Text&quot; &gt;
+        &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; String=&quot;somename&quot; /&gt;
+        &lt;DetectChar attribute=&quot;String&quot; context=&quot;string&quot; char=&quot;&amp;quot;&quot; /&gt;
+      &lt;/context&gt;
+      &lt;context attribute=&quot;String&quot; lineEndContext=&quot;#stay&quot; name=&quot;string&quot; &gt;
+        &lt;DetectChar attribute=&quot;String&quot; context=&quot;#pop&quot; char=&quot;&amp;quot;&quot; /&gt;
+      &lt;/context&gt;
+    &lt;/contexts&gt;
+    &lt;itemDatas&gt;
+      &lt;itemData name=&quot;Normal Text&quot; defStyleNum=&quot;dsNormal&quot; /&gt;
+      &lt;itemData name=&quot;Keyword&quot; defStyleNum=&quot;dsKeyword&quot; /&gt;
+      &lt;itemData name=&quot;String&quot; defStyleNum=&quot;dsString&quot; /&gt;
+    &lt;/itemDatas&gt;
+  &lt;/highlighting&gt;
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The last part of a highlight definition is the optional
+<userinput>general</userinput> section. It may contain information
+about keywords, code folding, comments and indentation.</term>
+
+<listitem>
+<para>The <userinput>comment</userinput> section defines with what
+string a single line comment is introduced. You also can define a
+multiline comments using <emphasis>multiLine</emphasis> with the
+additional attribute <emphasis>end</emphasis>. This is used if the
+user presses the corresponding shortcut for <emphasis>comment/uncomment</emphasis>.</para>
+<para>The <userinput>keywords</userinput> section defines whether
+keyword lists are casesensitive or not. Other attributes will be
+explained later.</para>
+<programlisting>
+  &lt;general&gt;
+    &lt;comments&gt;
+      &lt;comment name="singleLine" start="#"/&gt;
+    &lt;/comments&gt;
+    &lt;keywords casesensitive="1"/&gt;
+  &lt;/general&gt;
+&lt;/language&gt;
+</programlisting>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+
+</sect2>
+
+<sect2 id="kate-highlight-sections">
+<title>The Sections in Detail</title>
+<para>This part will describe all available attributes for contexts,
+itemDatas, keywords, comments, code folding and indentation.</para>
+
+<variablelist>
+<varlistentry>
+<term>The element <userinput>context</userinput> belongs into the group
+<userinput>contexts</userinput>. A context itself defines context specific
+rules like what should happen if the highlight system reaches the end of a
+line. Available attributes are:</term>
+
+
+<listitem>
+<para><userinput>name</userinput> the context name. Rules will use this name
+to specify the context to switch to if the rule matches.</para>
+<para><userinput>lineEndContext</userinput> defines the context the highlight
+system switches to if it reaches the end of a line. This may either be a name
+of another context, <userinput>#stay</userinput> to not switch the context
+(eg. do nothing) or <userinput>#pop</userinput> which will cause to leave this
+context. It is possible to use for example <userinput>#pop#pop#pop</userinput>
+to pop three times.</para>
+<para><userinput>lineBeginContext</userinput> defines the context if a begin
+of a line is encountered. Default: #stay.</para>
+<para><userinput>fallthrough</userinput> defines if the highlight system switches
+to the context specified in fallthroughContext if no rule matches.
+Default: <emphasis>false</emphasis>.</para>
+<para><userinput>fallthroughContext</userinput> specifies the next context
+if no rule matches.</para>
+<para><userinput>dynamic</userinput> if <emphasis>true</emphasis>, the context
+remembers strings/placeholders saved by dynamic rules. This is needed for HERE
+documents for example. Default: <emphasis>false</emphasis>.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>The element <userinput>itemData</userinput> is in the group
+<userinput>itemDatas</userinput>. It defines the font style and colors.
+So it is possible to define your own styles and colors, however we
+recommend to stick to the default styles if possible so that the user
+will always see the same colors used in different languages. Though,
+sometimes there is no other way and it is necessary to change color
+and font attributes. The attributes name and defStyleNum are required,
+the other optional. Available attributes are:</term>
+
+<listitem>
+<para><userinput>name</userinput> sets the name of the itemData.
+Contexts and rules will use this name in their attribute
+<emphasis>attribute</emphasis> to reference an itemData.</para>
+<para><userinput>defStyleNum</userinput> defines which default style to use.
+Available default styles are explained in detail later.</para>
+<para><userinput>color</userinput> defines a color. Valid formats are
+'#rrggbb' or '#rgb'.</para>
+<para><userinput>selColor</userinput> defines the selection color.</para>
+<para><userinput>italic</userinput> if <emphasis>true</emphasis>, the text will be italic.</para>
+<para><userinput>bold</userinput> if <emphasis>true</emphasis>, the text will be bold.</para>
+<para><userinput>underline</userinput> if <emphasis>true</emphasis>, the text will be underlined.</para>
+<para><userinput>strikeout</userinput> if <emphasis>true</emphasis>, the text will be stroked out.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>The element <userinput>keywords</userinput> in the group
+<userinput>general</userinput> defines keyword properties. Available attributes are:</term>
+
+<listitem>
+<para><userinput>casesensitive</userinput> may be <emphasis>true</emphasis>
+or <emphasis>false</emphasis>. If <emphasis>true</emphasis>, all keywords
+are matched casesensitive</para>
+<para><userinput>weakDeliminator</userinput> is a list of characters that
+do not act as word delimiters. For example the dot <userinput>'.'</userinput>
+is a word delimiter. Assume a keyword in a <userinput>list</userinput> contains
+a dot, it will only match if you specify the dot as a weak delimiter.</para>
+<para><userinput>additionalDeliminator</userinput> defines additional delimiters.</para>
+<para><userinput>wordWrapDeliminator</userinput> defines characters after which a
+line wrap may occur.</para>
+<para>Default delimiters and word wrap delimiters are the characters
+<userinput>.():!+,-&lt;=&gt;%&amp;*/;?[]^{|}~\</userinput>, space (<userinput>' '</userinput>)
+and tabulator (<userinput>'\t'</userinput>).</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>The element <userinput>comment</userinput> in the group
+<userinput>comments</userinput> defines comment properties which are used
+for <menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> and
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>.
+Available attributes are:</term>
+
+<listitem>
+<para><userinput>name</userinput> is either <emphasis>singleLine</emphasis>
+or <emphasis>multiLine</emphasis>. If you choose <emphasis>multiLine</emphasis>
+the attributes <emphasis>end</emphasis> and <emphasis>region</emphasis> are
+required.</para>
+<para><userinput>start</userinput> defines the string used to start a comment.
+In C++ this would be &quot;/*&quot;.</para>
+<para><userinput>end</userinput> defines the string used to close a comment.
+In C++ this would be &quot;*/&quot;.</para>
+<para><userinput>region</userinput> should be the name of the the foldable
+multiline comment. Assume you have <emphasis>beginRegion="Comment"</emphasis>
+... <emphasis>endRegion="Comment"</emphasis> in your rules, you should use
+<emphasis>region="Comment"</emphasis>. This way uncomment works even if you
+do not select all the text of the multiline comment. The cursor only must be
+in the multiline comment.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>The element <userinput>folding</userinput> in the group
+<userinput>general</userinput> defines code folding properties.
+Available attributes are:</term>
+
+<listitem>
+<para><userinput>indentationsensitive</userinput> if <emphasis>true</emphasis>, the code folding markers
+will be added indentation based, like in the scripting language Python. Usually you
+do not need to set it, as it defaults to <emphasis>false</emphasis>.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>The element <userinput>indentation</userinput> in the group
+<userinput>general</userinput> defines which indenter will be used, however we strongly
+recommend to omit this element, as the indenter usually will be set by either defining
+a File Type or by adding a mode line to the text file. If you specify an indenter though,
+you will force a specific indentation on the user, which he might not like at all.
+Available attributes are:</term>
+
+<listitem>
+<para><userinput>mode</userinput> is the name of the indenter. Available indenters
+right now are: <emphasis>normal, cstyle, csands, xml, python</emphasis> and
+<emphasis>varindent</emphasis>.</para>
+</listitem>
+</varlistentry>
+
+
+</variablelist>
+
+
+</sect2>
+
+<sect2 id="kate-highlight-default-styles">
+<title>Available Default Styles</title>
+<para>Default Styles were <link linkend="kate-highlight-system-default-styles">already explained</link>,
+as a short summary: Default styles are predefined font and color styles.</para>
+<variablelist>
+<varlistentry>
+<term>So here only the list of available default styles:</term>
+<listitem>
+<para><userinput>dsNormal</userinput>, used for normal text.</para>
+<para><userinput>dsKeyword</userinput>, used for keywords.</para>
+<para><userinput>dsDataType</userinput>, used for data types.</para>
+<para><userinput>dsDecVal</userinput>, used for decimal values.</para>
+<para><userinput>dsBaseN</userinput>, used for values with a base other than 10.</para>
+<para><userinput>dsFloat</userinput>, used for float values.</para>
+<para><userinput>dsChar</userinput>, used for a character.</para>
+<para><userinput>dsString</userinput>, used for strings.</para>
+<para><userinput>dsComment</userinput>, used for comments.</para>
+<para><userinput>dsOthers</userinput>, used for 'other' things.</para>
+<para><userinput>dsAlert</userinput>, used for warning messages.</para>
+<para><userinput>dsFunction</userinput>, used for function calls.</para>
+<para><userinput>dsRegionMarker</userinput>, used for region markers.</para>
+<para><userinput>dsError</userinput>, used for error highlighting and wrong syntax.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="kate-highlight-rules-detailled">
+<title>Highlight Detection Rules</title>
+
+<para>This section describes the syntax detection rules.</para>
+
+<para>Each rule can match zero or more characters at the beginning of
+the string they are test against. If the rule matches, the matching
+characters are assigned the style or <emphasis>attribute</emphasis>
+defined by the rule, and a rule may ask that the current context is
+switched.</para>
+
+<para>A rule looks like this:</para>
+
+<programlisting>&lt;RuleName attribute=&quot;(identifier)&quot; context=&quot;(identifier)&quot; [rule specific attributes] /&gt;</programlisting>
+
+<para>The <emphasis>attribute</emphasis> identifies the style to use
+for matched characters by name, and the <emphasis>context</emphasis>
+identifies the context to use from here.</para>
+
+<para>The <emphasis>context</emphasis> can be identified by:</para>
+
+<itemizedlist>
+<listitem>
+<para>An <emphasis>identifier</emphasis>, which is the name of the other
+context.</para>
+</listitem>
+<listitem>
+<para>An <emphasis>order</emphasis> telling the engine to stay in the
+current context (<userinput>#stay</userinput>), or to pop back to a
+previous context used in the string (<userinput>#pop</userinput>).</para>
+<para>To go back more steps, the #pop keyword can be repeated:
+<userinput>#pop#pop#pop</userinput></para>
+</listitem>
+</itemizedlist>
+
+<para>Some rules can have <emphasis>child rules</emphasis> which are
+then evaluated only if the parent rule matched. The entire matched
+string will be given the attribute defined by the parent rule. A rule
+with child rules looks like this:</para>
+
+<programlisting>
+&lt;RuleName (attributes)&gt;
+  &lt;ChildRuleName (attributes) /&gt;
+  ...
+&lt;/RuleName&gt;
+</programlisting>
+
+
+<para>Rule specific attributes varies and are described in the
+following sections.</para>
+
+
+<itemizedlist>
+<title>Common attributes</title>
+<para>All rules have the following attributes in common and are
+available whenever <userinput>(common attributes)</userinput> appears.
+<emphasis>attribute</emphasis> and <emphasis>context</emphasis>
+are required attributes, all others are optional.
+</para>
+
+<listitem>
+<para><emphasis>attribute</emphasis>: An attribute maps to a defined <emphasis>itemData</emphasis>.</para>
+</listitem>
+<listitem>
+<para><emphasis>context</emphasis>: Specify the context to which the highlighting system switches if the rule matches.</para>
+</listitem>
+<listitem>
+<para><emphasis>beginRegion</emphasis>: Start a code folding block. Default: unset.</para>
+</listitem>
+<listitem>
+<para><emphasis>endRegion</emphasis>: Close a code folding block. Default: unset.</para>
+</listitem>
+<listitem>
+<para><emphasis>lookAhead</emphasis>: If <emphasis>true</emphasis>, the
+highlighting system will not process the matches length.
+Default: <emphasis>false</emphasis>.</para>
+</listitem>
+<listitem>
+<para><emphasis>firstNonSpace</emphasis>: Match only, if the string is
+the first non-whitespace in the line. Default: <emphasis>false</emphasis>.</para>
+</listitem>
+<listitem>
+<para><emphasis>column</emphasis>: Match only, if the column matches. Default: unset.</para>
+</listitem>
+</itemizedlist>
+
+<itemizedlist>
+<title>Dynamic rules</title>
+<para>Some rules allow the optional attribute <userinput>dynamic</userinput>
+of type boolean that defaults to <emphasis>false</emphasis>. If dynamic is
+<emphasis>true</emphasis>, a rule can use placeholders representing the text
+matched by a <emphasis>regular expression</emphasis> rule that switched to the
+current context in its <userinput>string</userinput> or
+<userinput>char</userinput> attributes. In a <userinput>string</userinput>,
+the placeholder <replaceable>%N</replaceable> (where N is a number) will be
+replaced with the corresponding capture <replaceable>N</replaceable>
+from the calling regular expression. In a
+<userinput>char</userinput> the placeholer must be a number
+<replaceable>N</replaceable> and it will be replaced with the first character of
+the corresponding capture <replaceable>N</replaceable> from the calling regular
+expression. Whenever a rule allows this attribute it will contain a
+<emphasis>(dynamic)</emphasis>.</para>
+
+<listitem>
+<para><emphasis>dynamic</emphasis>: may be <emphasis>(true|false)</emphasis>.</para>
+</listitem>
+</itemizedlist>
+
+<sect2 id="highlighting-rules-in-detail">
+<title>The Rules in Detail</title>
+
+<variablelist>
+<varlistentry>
+<term>DetectChar</term>
+<listitem>
+<para>Detect a single specific character. Commonly used for example to
+find the ends of quoted strings.</para>
+<programlisting>&lt;DetectChar char=&quot;(character)&quot; (common attributes) (dynamic) /&gt;</programlisting>
+<para>The <userinput>char</userinput> attribute defines the character
+to match.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Detect2Chars</term>
+<listitem>
+<para>Detect two specific characters in a defined order.</para>
+<programlisting>&lt;Detect2Chars char=&quot;(character)&quot; char1=&quot;(character)&quot; (common attributes) (dynamic) /&gt;</programlisting>
+<para>The <userinput>char</userinput> attribute defines the first character to match,
+<userinput>char1</userinput> the second.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>AnyChar</term>
+<listitem>
+<para>Detect one character of a set of specified characters.</para>
+<programlisting>&lt;AnyChar String=&quot;(string)&quot; (common attributes) /&gt;</programlisting>
+<para>The <userinput>String</userinput> attribute defines the set of
+characters.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>StringDetect</term>
+<listitem>
+<para>Detect an exact string.</para>
+<programlisting>&lt;StringDetect String=&quot;(string)&quot; [insensitive=&quot;true|false&quot;] (common attributes) (dynamic) /&gt;</programlisting>
+<para>The <userinput>String</userinput> attribute defines the string
+to match. The <userinput>insensitive</userinput> attribute defaults to
+<emphasis>false</emphasis> and is passed to the string comparison
+function. If the value is <emphasis>true</emphasis> insensitive
+comparing is used.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>RegExpr</term>
+<listitem>
+<para>Matches against a regular expression.</para>
+<programlisting>&lt;RegExpr String=&quot;(string)&quot; [insensitive=&quot;true|false&quot;] [minimal=&quot;true|false&quot;] (common attributes) (dynamic) /&gt;</programlisting>
+<para>The <userinput>String</userinput> attribute defines the regular
+expression.</para>
+<para><userinput>insensitive</userinput> defaults to
+<emphasis>false</emphasis> and is passed to the regular expression
+engine.</para>
+<para><userinput>minimal</userinput> defaults to
+<emphasis>false</emphasis> and is passed to the regular expression
+engine.</para>
+<para>Because the rules are always matched against the beginning of
+the current string, a regular expression starting with a caret
+(<literal>^</literal>) indicates that the rule should only be
+matched against the start of a line.</para>
+<para>See <link linkend="regular-expressions">Regular Expressions</link>
+for more information on those.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>keyword</term>
+<listitem>
+<para>Detect a keyword from a specified list.</para>
+<programlisting>&lt;keyword String=&quot;(list name)&quot; (common attributes) /&gt;</programlisting>
+<para>The <userinput>String</userinput> attribute identifies the
+keyword list by name. A list with that name must exist.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Int</term>
+<listitem>
+<para>Detect an integer number.</para>
+<para><programlisting>&lt;Int (common attributes) (dynamic) /&gt;</programlisting></para>
+<para>This rule has no specific attributes. Child rules are typically
+used to detect combinations of <userinput>L</userinput> and
+<userinput>U</userinput> after the number, indicating the integer type
+in program code. Actually all rules are allowed as child rules, though,
+the <acronym>DTD</acronym> only allowes the child rule <userinput>StringDetect</userinput>.</para>
+<para>The following example matches integer numbers follows by the character 'L'.
+<programlisting>
+&lt;Int attribute="Decimal" context="#stay" &gt;
+  &lt;StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/&gt;
+&lt;/Int&gt;
+</programlisting></para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Float</term>
+<listitem>
+<para>Detect a floating point number.</para>
+<para><programlisting>&lt;Float (common attributes) /&gt;</programlisting></para>
+<para>This rule has no specific attributes. <userinput>AnyChar</userinput> is
+allowed as a child rules and typically used to detect combinations, see rule
+<userinput>Int</userinput> for reference.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>HlCOct</term>
+<listitem>
+<para>Detect an octal point number representation.</para>
+<para><programlisting>&lt;HlCOct (common attributes) /&gt;</programlisting></para>
+<para>This rule has no specific attributes.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>HlCHex</term>
+<listitem>
+<para>Detect a hexadecimal number representation.</para>
+<para><programlisting>&lt;HlCHex (common attributes) /&gt;</programlisting></para>
+<para>This rule has no specific attributes.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>HlCStringChar</term>
+<listitem>
+<para>Detect an escaped character.</para>
+<para><programlisting>&lt;HlCStringChar (common attributes) /&gt;</programlisting></para>
+<para>This rule has no specific attributes.</para>
+
+<para>It matches literal representations of characters commonly used in
+program code, for example <userinput>\n</userinput>
+(newline) or <userinput>\t</userinput> (TAB).</para>
+
+<para>The following characters will match if they follow a backslash
+(<literal>\</literal>):
+<userinput>abefnrtv&quot;'?\</userinput>. Additionally, escaped
+hexadecimal numbers like for example <userinput>\xff</userinput> and
+escaped octal numbers, for example <userinput>\033</userinput> will
+match.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>HlCChar</term>
+<listitem>
+<para>Detect an C character.</para>
+<para><programlisting>&lt;HlCChar (common attributes) /&gt;</programlisting></para>
+<para>This rule has no specific attributes.</para>
+
+<para>It matches C characters enclosed in a tick (Example: <userinput>'c'</userinput>).
+So in the ticks may be a simple character or an escaped character.
+See HlCStringChar for matched escaped character sequences.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>RangeDetect</term>
+<listitem>
+<para>Detect a string with defined start and end characters.</para>
+<programlisting>&lt;RangeDetect char=&quot;(character)&quot;  char1=&quot;(character)&quot; (common attributes) /&gt;</programlisting>
+<para><userinput>char</userinput> defines the character starting the range,
+<userinput>char1</userinput> the character ending the range.</para>
+<para>Usefull to detect for example small quoted strings and the like, but
+note that since the highlighting engine works on one line at a time, this
+will not find strings spanning over a line break.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>LineContinue</term>
+<listitem>
+<para>Matches at end of line.</para>
+<programlisting>&lt;LineContinue (common attributes) /&gt;</programlisting>
+<para>This rule has no specific attributes.</para>
+<para>This rule is useful for switching context at end of line, if the last
+character is a backslash (<userinput>'\'</userinput>). This is needed for
+example in C/C++ to continue macros or strings.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>IncludeRules</term>
+<listitem>
+<para>Include rules from another context or language/file.</para>
+<programlisting>&lt;IncludeRules context=&quot;contextlink&quot; [includeAttrib=&quot;true|false&quot;] /&gt;</programlisting>
+
+<para>The <userinput>context</userinput> attribute defines which context to include.</para>
+<para>If it a simple string it includes all defined rules into the current context, example:
+<programlisting>&lt;IncludeRules context=&quot;anotherContext&quot; /&gt;</programlisting></para>
+
+<para>
+If the string begins with <userinput>##</userinput> the highlight system
+will look for another language definition with the given name, example:
+<programlisting>&lt;IncludeRules context=&quot;##C++&quot; /&gt;</programlisting></para>
+<para>If <userinput>includeAttrib</userinput> attribute is
+<emphasis>true</emphasis>, change the destination attribute to the one of
+the source. This is required to make for example commenting work, if text
+matched by the included context is a different highlight than the host
+context.
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>DetectSpaces</term>
+<listitem>
+<para>Detect whitespaces.</para>
+<programlisting>&lt;DetectSpaces (common attributes) /&gt;</programlisting>
+
+<para>This rule has no specific attributes.</para>
+<para>Use this rule if you know that there can several whitespaces ahead,
+for example in the beginning of indented lines. This rule will skip all
+whitespace at once, instead of testing multiple rules and skipping one at the
+time due to no match.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>DetectIdentifier</term>
+<listitem>
+<para>Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*).</para>
+<programlisting>&lt;DetectIdentifier (common attributes) /&gt;</programlisting>
+
+<para>This rule has no specific attributes.</para>
+<para>Use this rule to skip a string of word characters at once, rather than
+testing with multiple rules and skipping one at the time due to no match.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Tips &amp; Tricks</title>
+
+<itemizedlist>
+<para>Once you have understood how the context switching works it will be
+easy to write highlight definitions. Though you should carefully check what
+rule you choose in what situation. Regular expressions are very mighty, but
+they are slow compared to the other rules. So you may consider the following
+tips.
+</para>
+
+<listitem>
+<para>If you only match two characters use <userinput>Detect2Chars</userinput>
+instead of <userinput>StringDetect</userinput>. The same applies to
+<userinput>DetectChar</userinput>.</para>
+</listitem>
+<listitem>
+<para>Regular expressions are easy to use but often there is another much
+faster way to achieve the same result. Consider you only want to match
+the character <userinput>'#'</userinput> if it is the first character in the
+line. A regular expression based solution would look like this:
+<programlisting>&lt;RegExpr attribute=&quot;Macro&quot; context=&quot;macro&quot; String=&quot;^\s*#&quot; /&gt;</programlisting>
+You can achieve the same much faster in using:
+<programlisting>&lt;DetectChar attribute=&quot;Macro&quot; context=&quot;macro&quot; char=&quot;#&quot; firstNonSpace=&quot;true&quot; /&gt;</programlisting>
+If you want to match the regular expression <userinput>'^#'</userinput> you
+can still use <userinput>DetectChar</userinput> with the attribute <userinput>column=&quot;0&quot;</userinput>.
+The attribute <userinput>column</userinput> counts character based, so a tabulator still is only one character.
+</para>
+</listitem>
+<listitem>
+<para>You can switch contexts without processing characters. Assume that you
+want to switch context when you meet the string <userinput>*/</userinput>, but
+need to process that string in the next context. The below rule will match, and
+the <userinput>lookAhead</userinput> attribute will cause the highlighter to
+keep the matched string for the next context.
+<programlisting>&lt;Detect2Chars attribute=&quot;Comment&quot; context=&quot;#pop&quot; char=&quot;*&quot; char1=&quot;/&quot; lookAhead=&quot;true&quot; /&gt;</programlisting>
+</para>
+</listitem>
+<listitem>
+<para>Use <userinput>DetectSpaces</userinput> if you know that many whitespaces occur.</para>
+</listitem>
+<listitem>
+<para>Use <userinput>DetectIdentifier</userinput> instead of the regular expression <userinput>'[a-zA-Z_]\w*'</userinput>.</para>
+</listitem>
+<listitem>
+<para>Use default styles whenever you can. This way the user will find a familiar environment.</para>
+</listitem>
+<listitem>
+<para>Look into other XML-files to see how other people implement tricky rules.</para>
+</listitem>
+<listitem>
+<para>You can validate every XML file by using the command
+<command>xmllint --dtdvalid language.dtd mySyntax.xml</command>.</para>
+</listitem>
+<listitem>
+<para>If you repeat complex regular expression very often you can use
+<emphasis>ENTITIES</emphasis>. Example:</para>
+<programlisting>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE language SYSTEM "language.dtd"
+[
+        &lt;!ENTITY myref    "[A-Za-z_:][\w.:_-]*"&gt;
+]&gt;
+</programlisting>
+<para>Now you can use <emphasis>&amp;myref;</emphasis> instead of the regular
+expression.</para>
+</listitem>
+</itemizedlist>
+</sect2>
+
+</sect1>
+
+</appendix>
diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook
new file mode 100644
index 000000000..fe409a83d
--- /dev/null
+++ b/doc/kate/index.docbook
@@ -0,0 +1,293 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
+"dtd/kdex.dtd" [
+  <!ENTITY kappname "&kate;">
+  <!ENTITY package "kdebase">
+  <!ENTITY configuring-chapter SYSTEM "configuring.docbook">
+  <!ENTITY highlighting-appendix SYSTEM "highlighting.docbook">
+  <!ENTITY advanced-chapter SYSTEM "advanced.docbook">
+  <!ENTITY fundamentals-chapter SYSTEM "fundamentals.docbook">
+  <!ENTITY mdi-chapter SYSTEM "mdi.docbook">
+  <!ENTITY menu-chapter SYSTEM "menus.docbook">
+  <!ENTITY part-chapter SYSTEM "part.docbook">
+  <!ENTITY plugins-chapter SYSTEM "plugins.docbook">
+  <!ENTITY regexp-appendix SYSTEM "regular-expressions.docbook">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+<title>The &kate; Handbook</title>
+
+<bookinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<author>&Seth.Rothberg; &Seth.Rothberg.mail;</author>
+<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000</year>
+<year>2001</year>
+<holder>&Seth.Rothberg;</holder>
+</copyright>
+<copyright>
+<year>2002</year><year>2003</year><year>2005</year>
+<holder>&Anders.Lund;</holder>
+</copyright>
+<copyright>
+<year>2005</year>
+<holder>&Dominik.Haumann;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-29</date>
+<releaseinfo>2.5.0</releaseinfo>
+
+<abstract>
+<para>&kate; is a programmer's text editor for &kde; 2.2 and above.</para>
+
+<para>This handbook documents &kate; Version 2.5.0</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdebase</keyword>
+<keyword>Kate</keyword>
+<keyword>text</keyword>
+<keyword>editor</keyword>
+<keyword>programmer</keyword>
+<keyword>programming</keyword>
+<keyword>projects</keyword>
+<keyword>MDI</keyword>
+<keyword>Multi</keyword>
+<keyword>Document</keyword>
+<keyword>Interface</keyword>
+<keyword>terminal</keyword>
+<keyword>console</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+Welcome to &kate;, a programmer's text editor for &kde; version 2.2 and
+above. Some of &kate;'s many features include configurable syntax
+highlighting for languages ranging from C and C++ to
+<acronym>HTML</acronym> to bash scripts, the ability to create and
+maintain projects, a multiple document interface
+(<acronym>MDI</acronym>), and a self-contained terminal emulator.
+</para>
+
+<para>
+But &kate; is more than a programmer's editor. Its ability to open
+several files at once makes it ideal for editing &UNIX;'s many
+configuration files.  This document was written in &kate;.
+</para>
+
+<para>
+<mediaobject>
+<imageobject><imagedata format="PNG" fileref="kate.png"/></imageobject>
+<caption><para>Editing this manual...</para></caption>
+</mediaobject>
+</para>
+
+</chapter>
+
+&fundamentals-chapter;
+
+&mdi-chapter;
+
+&part-chapter;
+
+&plugins-chapter;
+
+&advanced-chapter;
+
+&menu-chapter;
+
+&configuring-chapter;
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&kate;. Program copyright 2000, 2001, 2002 - 2005 by the &kate; developer team.
+</para>
+
+<variablelist>
+<title>The &kate; team:</title>
+<varlistentry>
+<term>&Christoph.Cullmann; &Christoph.Cullmann.mail;</term>
+<listitem><para>Project Manager &amp; Core Developer</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Anders.Lund; &Anders.Lund.mail;</term>
+<listitem><para>Core Developer, Perl syntax highlighting,
+documentation</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Joseph.Wenninger; &Joseph.Wenninger.mail;</term>
+<listitem><para>Core Developer, syntax highlighting</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Michael Bartl <email>michael.bartl1@chello.at</email></term>
+<listitem><para>Core Developer</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Phlip <email>phlip_cpp@my-deja.com</email></term>
+<listitem><para>The project compiler</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Waldo.Bastian; &Waldo.Bastian.mail;</term>
+<listitem><para>The cool buffer system</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Matt Newell <email>newellm@proaxis.com</email></term>
+<listitem><para>Testing...</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Michael McCallum <email>gholam@xtra.co.nz</email></term>
+<listitem><para>Core Developer</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Jochen Wilhemly <email>digisnap@cs.tu-berlin.de</email></term>
+<listitem><para>KWrite Author</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Michael.Koch; &Michael.Koch.mail;</term>
+<listitem><para>KWrite port to KParts</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Christian Gebauer <email>gebauer@bigfoot.com</email></term>
+<listitem><para>Unspecified</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Simon.Hausmann; &Simon.Hausmann.mail;</term>
+<listitem><para>Unspecified</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Glen Parker <email>glenebob@nwlink.com</email></term>
+<listitem><para>KWrite Undo History, KSpell integration</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Scott Manson <email>sdmanson@alltel.net</email></term>
+<listitem><para>KWrite XML syntax highlighting support</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&John.Firebaugh; &John.Firebaugh.mail;</term>
+<listitem><para>Various Patches</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Dominik.Haumann; &Dominik.Haumann.mail;</term>
+<listitem><para>Developer, Highlight wizard</para></listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<title>Many other people have contributed:</title>
+<varlistentry>
+<term>Matteo Merli <email>merlim@libero.it</email></term>
+<listitem><para>Highlighting for RPM Spec-Files, Diff and more</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Rocky Scaletta <email>rocky@purdue.edu</email></term>
+<listitem><para>Highlighting for VHDL</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Yury Lebedev </term>
+<listitem><para>Highlighting for SQL</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Chris Ross</term>
+<listitem><para>Highlighting for Ferite</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Nick Roux</term>
+<listitem><para>Highlighting for ILERPG</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>John Firebaugh</term>
+<listitem><para>Highlighting for Java, and much more</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Carsten Niehaus</term>
+<listitem><para>Highlighting for LaTeX</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Per Wigren</term>
+<listitem><para>Highlighting for Makefiles, Python</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Jan Fritz</term>
+<listitem><para>Highlighting for Python</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>&Daniel.Naber;</term>
+<listitem><para>Small bugfixes, XML plugin</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Documentation copyright 2000,2001 &Seth.Rothberg;
+&Seth.Rothberg.mail;</para>
+
+<para>Documentation copyright 2002, 2003, 2005 &Anders.Lund;
+&Anders.Lund.mail;</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+&underGPL;               <!-- GPL License -->
+
+</chapter>
+
+&highlighting-appendix;
+
+&regexp-appendix;
+
+<appendix id="installation">
+<title>Installation</title>
+
+&install.intro.documentation;
+
+&install.compile.documentation;
+
+</appendix>
+
+&documentation.index;
+
+<!--
+Index Word List:
+menu - context - syntax - markup - shortcuts - highlighting
+embedded terminal - editing - search - replace - regexp -> Regular Expression
+split window - selection - insert overwrite - selection -
+configure/customize/preferences - insert/overwrite - non-printing characters
+font - unicode - wordwrap/linewrap - project - bookmarks - docks - plugins
+block selection / rectangles - view - indenting - editor - word processor
+copy - paste - find - spelling - language (both kinds) - encoding -
+pretty printing - formatting - line numbers - icon border -
+folding - insert time - sed
+
+done
+comment / uncomment
+configure / settings / preferences
+
+-->
+
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-namecase-general: t
+sgml-namecase-entity: nil
+sgml-general-insert-case: lower
+sgml-minimize-attributes: nil
+sgml-omittag: nil
+End:
+-->
diff --git a/doc/kate/kate.png b/doc/kate/kate.png
new file mode 100644
index 000000000..dc1ee4c40
--- /dev/null
+++ b/doc/kate/kate.png
diff --git a/doc/kate/man-kate.1.docbook b/doc/kate/man-kate.1.docbook
new file mode 100644
index 000000000..80899a4fb
--- /dev/null
+++ b/doc/kate/man-kate.1.docbook
@@ -0,0 +1,165 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>KDE User's Manual</title>
+<author>&Lauri.Watts; &Lauri.Watts.mail;</author>
+<date>June 07, 2005</date>
+<productname>K Desktop Environment</productname>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kate</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kate</command></refname>
+<refpurpose>Advanced text editor for &kde;</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>kate</command>
+<group choice="opt"><option>-s, --start</option> <replaceable>
+name</replaceable> </group>
+<group choice="opt"><option>-u, --use</option></group>
+<group choice="opt"><option>-p, --pid</option><replaceable>
+pid</replaceable></group>
+<group choice="opt"><option>-e, --encoding</option> <replaceable>
+name</replaceable></group>
+<group choice="opt"><option>-l, --line</option> <replaceable>
+line</replaceable></group>
+<group choice="opt"><option>-c, --column</option>
+<replaceable> column</replaceable></group>
+<group choice="opt"><option>-i, --stdin</option></group>
+<arg choice="opt">KDE Generic Options</arg>
+<arg choice="opt">Qt Generic Options</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para>&kate; is the &kde; Advanced Text Editor. </para> 
+<para>&kate; also provides the editor part for various applications, under
+the name &kwrite;.</para>
+<para>Some of &kate;'s many features include configurable syntax
+highlighting for languages ranging from C and C++ to
+<acronym>HTML</acronym> to bash scripts, the ability to create and
+maintain projects, a multiple document interface
+(<acronym>MDI</acronym>), and a self-contained terminal emulator.
+</para>
+
+<para>
+But &kate; is more than a programmer's editor. Its ability to open
+several files at once makes it ideal for editing &UNIX;'s many
+configuration files.  This document was written in &kate;.
+</para>
+
+
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+
+<variablelist>
+<varlistentry>
+<term><option>-s</option>, <option>--start</option> <replaceable>name</replaceable></term>
+
+<listitem><para>Start &kate; with a given session.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-u, --use</option></term>
+<listitem><para>Use an already running &kate;</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-p, --pid</option> <replaceable>
+pid</replaceable></term>
+<listitem><para>Only try to reuse kate instance with this
+<replaceable>pid</replaceable></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-e, --encoding</option> <replaceable>
+name</replaceable></term>
+<listitem><para>Set encoding for the file to open</para><para>You can use
+this to force a file opened in utf-8 format, for instance.  (The command
+<command>iconv -l</command> provides a list of encodings, which may be
+helpful to you.)</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-l, --line</option> <replaceable> line</replaceable></term>
+<listitem><para>Navigate to this line</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-c, --column</option> <replaceable>
+column</replaceable></term>
+<listitem><para>Navigate to this column</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-i, --stdin</option></term>
+<listitem><para>Read the contents of
+<filename>stdin</filename></para></listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+
+<para>kwrite(1)</para>
+
+<para>More detailed user documentation is available from <ulink
+url="help:/kate">help:/kate</ulink>
+(either enter this <acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kate</parameter></userinput>).</para>
+
+<para>There is also further information available at <ulink
+url="http://kate.kde.org/">the &kate; website</ulink>.</para>
+</refsect1>
+
+<refsect1>
+<title>Examples</title>
+
+<para>To open a file named <filename>source.cpp</filename> at column 15,
+line 25, in an existing &kate; window, you could use:</para>
+<screen><userinput><command>kate</command> <option>-c 15</option> <option>-l
+25</option> <option>-u</option> <filename>source.cpp</filename></userinput> </screen>
+
+<para>If you have an active internet connection, you can take advantage of
+&kde;'s network transparency to open a file from an ftp site. If you do not
+have write permission on the remote server, the file will be opened read
+only and you will be prompted for a local filename to save to if you make
+changes.  If you do have write permission, changes will be saved
+transparently over the network.</para>
+<screen><userinput><command>kate</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/README_FIRST</replaceable></option></userinput></screen>
+
+<!-- FIXME: Some more useful examples would be cool, how about this snagged -->
+<!-- from a mail of anders (slightly edited /line/l to remove the double -->
+<!-- dashes:
+
+> /some/file/path/file.name:lineno
+> it would rock if Kate could understand that and not only open up file.name,
+> but jump to lineno after the file is opened.
+
+How bad is it to have to convert that into
+-l lineno /some/file/path/file.name 
+
+sed s,([^:]*):(\d+),-l \2 \1,
+
+will do that, for example.-->
+
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+<para>The maintainer of &kate; is &Christoph.Cullmann;
+&Christoph.Cullmann.mail;.  A comprehensive list of authors and contributors
+is available in the complete user manual mentioned above.</para>
+</refsect1>
+
+</refentry>
diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook
new file mode 100644
index 000000000..a6c6854db
--- /dev/null
+++ b/doc/kate/mdi.docbook
@@ -0,0 +1,266 @@
+<chapter id="kate-mdi">
+<chapterinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>Working With the &kate; <acronym>MDI</acronym></title>
+
+<sect1 id="kate-mdi-overview">
+<title>Overview</title>
+
+<para>Window, View, Document, Frame, Editor... What are they all in
+the terminology of &kate;, and how do you get the most out of it? This
+chapter will explain all of that, and even more.</para>
+
+<sect2 id="kate-mdi-overview-mainwindow">
+
+<title>The Main Window</title>
+
+<para><indexterm><primary>Main window</primary></indexterm>
+The &kate; Main Window is a standard &kde; application window,
+with the addition of side bars containing tool views. It has a
+Menubar with all the common menus, and some more, and a toolbar
+providing access to commonly used commands.</para>
+
+<para>The most important part of the window is the Editing Area, by
+default displaying a single text editor component, in which you can
+work with your documents.</para>
+
+<para>The docking capabilities of the window is used for the tool
+windows:</para>
+
+<itemizedlist>
+<listitem><para><link linkend="kate-mdi-tools-file-list">The File List</link></para></listitem>
+<listitem><para><link linkend="kate-mdi-tools-file-selector">The Filesystem
+Browser</link></para></listitem>
+<listitem><para><link linkend="kate-mdi-tools-konsole">The Built in Terminal Emulator</link></para></listitem>
+</itemizedlist>
+
+<para>And possibly other tool views, for example provided by
+plugins.</para>
+
+<para>Tool views can be positioned in any sidebar, to move a tool right click
+its sidebar button and select from the &RMB; menu</para>
+
+<para>A tool view can be marked as <emphasis>persistent</emphasis> in the &RMB;
+menu for its sidebar button. The sidebar can contain
+more tools at one time so that when a tool is persistant other tools can be
+shown simultaneously.</para>
+
+</sect2>
+
+
+</sect1>
+
+<sect1 id="kate-mdi-editor">
+
+<title>The Editor area</title>
+
+<para><indexterm><primary>Editing Area</primary></indexterm>
+&kate; is capable of having more than one document open at the
+same time, and also of splitting the editing area into any number of
+frames, similar to how for example &konqueror; or the popular
+<application>emacs</application> text editor works. This way you can
+view several documents at the same time, or more instances of the same
+document, handy for example if your document contains definitions in
+the top that you want to see often for reference. Or you could view a
+program source header in one frame, while editing the implementation
+file in another.</para>
+
+<para>When a document is available in more than one editor, changes
+made in one editor will immediately be reflected in the others as
+well. This includes changing the text as well as selecting
+text. Search operations or cursor movement is only reflected in the
+current editor.</para>
+
+<para>It is currently not possible to have more instances of the same
+document open in the sense that one instance will be edited while the
+other will not.</para>
+
+<para>When splitting an editor into two frames, it is divided into two
+equally sized frames, both displaying the current document of that
+editor. The new frame will be at the bottom (in the case of a
+horizontal split) or at the right (for a vertical split). The new
+frame gets the focus, which is visualized by a small green led in the
+focused frame.</para>
+
+</sect1>
+
+<sect1 id="kate-mdi-tools-file-list">
+<title>The Document List</title>
+
+<para><indexterm><primary>File list</primary></indexterm>
+The file list displays a list of all documents currently open in
+&kate;. Modified files will have a small <guiicon>floppy
+disk</guiicon> icon on their left to indicate that state.</para>
+
+<para>If two or more files with the same name (located in different
+folders) are open, the names of the second will be prepended
+<quote>&lt;2&gt;</quote> and so on. The tool-tip for the file will
+display its full name including the path, allowing you to choose the
+desired one.</para> <para>To display a document in the currently
+active frame, click the document name in the list.</para>
+
+<para>You can sort the list in a few different ways by rightclicking the
+list and selecting from the <guisubmenu>Sort By</guisubmenu> menu.
+
+The options are
+<variablelist>
+
+<varlistentry>
+<term><guimenuitem>Opening Order</guimenuitem></term>
+<listitem><para>Lists the documents in the order of opening</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>Document Name</guimenuitem></term>
+<listitem><para>Lists the documents alphabetically by their name.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>URL</guimenuitem></term>
+<listitem><para>Lists the documents alphabetically by URL.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>The document list will pr default visualize your history by shading the
+entries for the most recent documents with a background color. If the document
+was edited, an extra color is blended in. The most recent document has the
+strongest color, so that you can easily find the documents you are working on.
+This feature can be disabled in
+<link linkend="config-dialog-documentlist">The Document List Page</link>
+of the configuration dialog.</para>
+
+<para>The default location in the &kate; window is to the left of the
+editing area.</para>
+</sect1>
+
+<sect1 id="kate-mdi-tools-file-selector">
+<title>The Filesystem Browser</title>
+
+<para><indexterm><primary>Filesystem Browser</primary></indexterm>
+The Filesystem Browser is a folder viewer, allowing you to open
+files from a displayed folder in the current frame.</para>
+
+<para>From top down, the Filesystem Browser consist of the following
+elements:</para>
+
+<variablelist>
+<varlistentry>
+<term>A Toolbar</term>
+<listitem>
+<para>This contains standard navigations tool buttons:</para>
+<variablelist>
+<varlistentry>
+<term><guibutton>Home</guibutton></term>
+<listitem><para>Pressing it will cause the folder view to <command>cd</command> to your home folder.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Up</guibutton></term>
+<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed
+folder if possible.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Back</guibutton></term>
+<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history.
+This button is disabled, if there is no previous item.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Forward</guibutton></term>
+<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history.
+This button is disabled, if there is no next folder.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Sync</guibutton></term>
+<listitem><para>This button will cause the folder view to
+<command>cd</command> to the folder of the currently active
+document if possible. This button is disabled, if the active document
+is a new, unsaved file, or the folder in which it resides can not
+be decided.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>A &URL; entry</term>
+<listitem>
+<para>Here you can type the path of a folder to browse. The &URL;
+entry maintains a list of previously typed paths. To choose one use
+the arrow button to the right of the entry.</para>
+<tip><para>The &URL; entry has folder auto-completion. The completion
+method can be set using the &RMB; menu of the text
+entry.</para></tip>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>A Folder View</term>
+<listitem><para>This is a standard &kde; folder view.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>A Filter Entry</term>
+<listitem>
+<para>The Filter entry allows you to enter a filter for the files
+displayed in the folder view. The filter uses standard globs; patterns
+must be separated by white space. Example: <userinput>*.cpp *.h
+*.moc</userinput></para>
+<para>To display all files, enter a single asterisk
+<userinput>*</userinput>.</para>
+<para>The filter entry saves the last 10 filters entered between
+sessions, to use one, press the arrow button on the right of the entry
+and select the desired filter string.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+
+<sect1 id="kate-mdi-tools-konsole">
+<title>The Built in Terminal Emulator</title>
+
+<para><indexterm><primary>Terminal emulator</primary></indexterm>
+The built in Terminal Emulator is a copy of the &kde; &konsole;
+terminal application, for your convenience. It is available from the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Terminal
+Emulator</guimenuitem></menuchoice> menu item or by pressing the <keycombo
+action="simul"><keycap>F7</keycap></keycombo> key, and will get the focus
+whenever displayed. Additionally, if the <link
+linkend="config-dialog-general-sync-konsole">Sync &konsole; with
+active document</link> option is enabled, it will
+change into the directory of the current document if
+possible when it is displayed, or when the current document
+changes.</para>
+
+<para>The default location in the &kate; window is at the bottom,
+below the editing area.</para>
+
+<para>You can configure the &konsole; using its &RMB; menu, for more
+information, see the &konsole; manual.</para>
+
+</sect1>
+
+<sect1 id="kate-mdi-tools-externaltools">
+<title>External Tools</title>
+
+<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled
+<guisubmenu>External Tools</guisubmenu>. These tools invokes external
+applications with data related to the current document, for example its URL,
+directory, text or selection.</para>
+
+<para>External tools are user defined, you can add, edit or remove tools using
+the <link linkend="config-dialog-externaltools">External Tools configuration panel</link>.
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook
new file mode 100644
index 000000000..26ae7551e
--- /dev/null
+++ b/doc/kate/menus.docbook
@@ -0,0 +1,1438 @@
+<chapter id="menu-entries">
+<chapterinfo>
+<authorgroup>
+<author><personname><firstname></firstname></personname></author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>Menu Entries</title>
+
+<sect1 id="file-menu">
+<title>The <guimenu>File</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<anchor id="new"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>New</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command <action>starts a new document</action> in the editing
+window.  In the <guibutton>Documents</guibutton> list on the left the new file
+is named <emphasis>Untitled</emphasis>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="open"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Open...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Launches &kde;'s open file dialog box to let you open one or more files.
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="open-recent"/>
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Open Recent</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command allows you to <action>open a file</action> from a submenu
+that contains a list of recently edited files.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="open-with"/>
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Open With</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This submenu presents a list of applications known to handle the mime type
+of your current document. Activating an entry will open the current document
+with that application.</para>
+<para>In addition, a entry <guimenuitem>Other...</guimenuitem> command launches
+the open with dialog box that allows you to <action>select another application
+to open the active file</action>. Your file will still be open in &kate;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="save"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Save</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command <action>saves your file</action>. Use it often. If the file is
+<emphasis>Untitled</emphasis> then
+<guimenuitem>Save</guimenuitem> becomes
+<guimenuitem>Save As</guimenuitem>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="save-as"/>
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Save As...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Name and rename files</action> with this command.
+It launches the save file dialog box. This dialog works just as
+the open file dialog box does. You can use it to navigate through
+your file system, preview existing files, or filter your file
+view with file masks.
+</para>
+
+<para>
+Type the name you want to give the file you are saving in the
+Location combo box and press the
+<guibutton>OK</guibutton> button.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="save-all"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Save All</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command <action>saves all modified open files</action>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="reload"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul"><keycap>F5</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Reload</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Reloads the active file</action>.  This command is
+useful if another program or process has changed the file while you have
+it open in &kate;
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="print"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Print the active file</action>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="export-as-html">
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Export as HTML...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+Export your file in HTML format so your document can be viewed as a
+web page.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="mail">
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Mail...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+Open your mail client and attach the file in the mail.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="close"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Close</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Close the active file</action> with this command. If you
+have made unsaved changes, you will be prompted to save
+the file before &kate; closes it.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="close-all"/>
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Close All</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command <action>closes all the files you have open</action>
+in &kate;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="quit"/>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+This command <action>closes &kate;</action> and any files you were
+editing. If you have made unsaved changes to any of the files you were
+editing, you will be prompted to save them.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="edit-menu">
+<title>The <guimenu>Edit</guimenu> Menu</title>
+<para>The <guimenu>Edit</guimenu> menu contains a host of commands,
+all to work with the currently active document.</para>
+
+<variablelist>
+<title>Menu Entries</title>
+<varlistentry>
+<term>
+<anchor id="edit-undo"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Undo</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Undo the last editing command (typing, copying, cutting etc.)</para>
+<note><para>If grouped undo is enabled, this may undo several editing commands of the same type, like typing in characters.</para></note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-redo"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Redo</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Redo the last undo step.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-cut"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Cut</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Removes selected text if any, and places a copy of the removed text in the clipboard.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-copy"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Copy</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Copies selected text, if any, to the clipboard.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-copy-as-html"/>
+<menuchoice>
+<guimenu>Edit</guimenu>
+<guimenuitem>Copy as HTML</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Copies selected text with the syntax highlight as HTML text.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-paste" />
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Paste</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Copies the first item in the clipboard into the editor at cursor position.</para>
+<note><para>If Overwrite Selection is enabled, the pasted text will overwrite the selection, if any.</para></note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-select-all"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Select All</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Selects all text in the editor.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-deselect"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Deselect</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Deselects the selected text in the editor if any.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-toggle-block-selection"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>Shift</keycap>
+<keycap>B</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Block Selection Mode</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggles Selection Mode. When the Selection Mode is <quote>BLOCK</quote>, you can make vertical selections,
+ie select column 5 to 10 in lines 9 to 15.</para>
+<para>The status bar shows the current state of the Selection Mode, either <quote>NORM</quote> or <quote>BLK</quote>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-find"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Find...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Launch the Find Dialog to allow you to search for text in the edited document.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-find-next"/>
+<menuchoice>
+<shortcut><keycombo action="simul"><keycap>F3</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Find Next</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Go to the nearest downwards match of the last text or regular expression searched for, starting from cursor position</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-find-previous"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Shift;<keycap>F3</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Find Previous</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Go to the nearest upwards match of the last text or regular expression searched for, starting from cursor position</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-replace"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Replace...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Launch the Replace Dialog to replace one or more instances of a defined text with something else.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="edit-go-to-line"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Go to line...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Launches the Go To Line Dialog, allowing you to enter the number of a line to find in
+the document</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="document-menu">
+<title>The <guimenu>Document</guimenu> Menu</title>
+<para>The Document menu provides a menu entry for each open document.
+Clicking one of these will bring the requested document to focus. If you have
+multiple frames, an editor for that document will be displayed in the currently
+active frame.</para>
+<para>In addition, commands to browse your open documents are provided:
+<variablelist>
+<title>Menu items</title>
+
+<varlistentry>
+<term>
+<anchor id="document-back"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Alt;<keycap>Left</keycap></keycombo></shortcut>
+<guimenu>Document</guimenu>
+<guimenuitem>Back</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>This will bring the previous document in the stack in focus. If you have
+multiple frames, an editor for the document will be displayed in the currently
+active frame.</para> <para>The order is the order in which documents were
+opened, rather than a logical history.  This behavior may change in future
+versions of &kate;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="document-forward"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Alt;<keycap>Right</keycap></keycombo></shortcut>
+<guimenu>Document</guimenu>
+<guimenuitem>Forward</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>This will bring the next document in the stack in focus. If you have
+multiple frames, an editor for the document will be displayed in the currently
+active frame.</para>
+<para>The order is the order in which the documents were opened,
+rather than a logical history.  This behavior may change in future versions of
+&kate;.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+</sect1>
+
+<sect1 id="view-menu">
+<title>The <guimenu>View</guimenu> menu</title>
+
+<para>The <guimenu>View</guimenu> menu allows you to manage settings
+specific to the active editor, and to manage frames.</para>
+
+<variablelist>
+<title>Menu Items</title>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycap>F7</keycap></shortcut>
+<guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem>
+</menuchoice></term>
+<listitem><para>This command will toggle the display of the
+<link linkend="advanced-editing-tools-commandline">built in command line</link>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guisubmenu>Schema</guisubmenu>
+</menuchoice></term>
+<listitem><para>This menu lists the available schemas. You can change the schema
+for the current view here, to change the default schema you need to
+use the <link linkend="config-dialog-editor-colors">config dialog</link></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>F10</keycap>
+</keycombo></shortcut>
+<guimenu>View</guimenu><guimenuitem>Dynamic Word Wrap</guimenuitem></menuchoice>
+</term>
+<listitem><para>Toggles dynamic word wrap in the current view. Dynamic word
+wrap makes all the text in a view visible without the need for horizontal
+scrolling by rendering one actual line on more visual lines as needed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Static Word
+Wrap Marker</guimenuitem></menuchoice></term>
+<listitem><para>Toggles the display of a vertical line indicating the position
+of the wrap width as configured in the <link
+linkend="config-dialog-editor-wrap-words-at">config dialog</link>. This
+feature requires that you use a true fixed-width font.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="view-show-icon-border"/>
+<menuchoice>
+<shortcut><keycombo action="simul"><keycap>F6</keycap></keycombo></shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Show/Hide Icon Border</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>This is a toggle item. Setting it on checked will make the Icon Border
+visible in the left side of the active editor, and vice versa.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="view-show-line-numbers"/>
+<menuchoice>
+<shortcut><keycombo action="simul"><keycap>F11</keycap></keycombo></shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Show/Hide Line Numbers</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>This is a toggle Item. Setting it on checked will make a pane displaying
+the line numbers of the document visible in the left border of the active editor,
+and vice versa.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Scrollbar
+Marks</guimenuitem></menuchoice></term>
+<listitem><para>Toggles the visualization of bookmarks (and other marks) on the
+vertical scrollbar. When enabled, marks are represented by a thin line in the
+mark color at the scrollbar, middleclicking on the lines will scroll the view
+to a position near the mark.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>F9</keycap>
+</keycombo></shortcut>
+<guimenu>View</guimenu><guimenuitem>Show/Hide Folding Markers</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggles the display of the folding marker pane in the left
+side of the view. See <link linkend="advanced-editing-tools-code-folding">Using
+Code Folding</link>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="view-code-folding"/>
+<menuchoice>
+<guimenuitem>Code Folding</guimenuitem>
+</menuchoice>
+</term>
+
+<listitem>
+<variablelist>
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;
+<keycap>Shift</keycap><keycap>-</keycap></keycombo></shortcut>
+<guimenuitem>Collapse Toplevel</guimenuitem></menuchoice>
+</term>
+<listitem><para>Collapse all toplevel regions in the document.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;
+<keycap>Shift</keycap><keycap>+</keycap></keycombo></shortcut>
+<guimenuitem>Expand Toplevel</guimenuitem></menuchoice>
+</term>
+<listitem><para>Expand all toplevel regions in the document.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;
+<keycap>-</keycap></keycombo></shortcut>
+<guimenuitem>Collapse One Local Level</guimenuitem></menuchoice>
+</term>
+<listitem><para>Collapse the region closest to the cursor.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;
+<keycap>+</keycap></keycombo></shortcut>
+<guimenuitem>Expand One Local Level</guimenuitem></menuchoice>
+</term>
+<listitem><para>Expand the region closest to the cursor.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="bookmarks-menu">
+<title>The <guimenu>Bookmarks</guimenu> Menu</title>
+
+<para>The <guimenu>Bookmarks</guimenu> menu allows you to work with
+the bookmarks in the currently active document.</para>
+
+<para>Below the entries described here, one entry for each bookmark in
+the active document will be available. The text will be the first few
+words of the marked line. Choose an item to move the cursor to the
+start of that line. The editor will scroll as necessary to make that
+line visible.</para>
+
+<variablelist>
+
+<title>Menu Items</title>
+
+<varlistentry>
+<term>
+<anchor id="bookmarks-toggle-bookmark"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></shortcut>
+<guimenu>Bookmarks</guimenu>
+<guimenuitem>Set/Clear Bookmark</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Sets or removes a bookmark in the current line of the active document.
+(If it's there, it is removed, otherwise one is set.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="bookmarks-clear-bookmarks"/>
+<menuchoice>
+<guimenu>Bookmarks</guimenu>
+<guimenuitem>Clear All Bookmarks</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Clears (removes) all bookmarks in the active document.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="bookmarks-previous">
+<term><menuchoice><shortcut><keycombo action="simul">&Alt;
+<keycap>Page Up</keycap></keycombo></shortcut>
+<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice>
+</term>
+<listitem><para>This will move the cursor to beginning of the first above line
+with a bookmark. The menuitem text will include the line number and the first
+piece of text on the line. This item is only available when there is a bookmark
+in a line above the cursor.</para></listitem>
+</varlistentry>
+
+<varlistentry id="bookmarks-next">
+<term><menuchoice><shortcut><keycombo action="simul">&Alt;
+<keycap>Page Down</keycap></keycombo></shortcut>
+<guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem></menuchoice></term>
+<listitem><para>This will move the cursor to beginning of the next line with a
+bookmark. The menuitem text will include the line number and the first piece of
+text on the line. This item is only available when there is a bookmark in a line
+below the cursor.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="tools-menu">
+
+<title>The <guimenu>Tools</guimenu> Menu</title>
+
+<variablelist>
+
+<varlistentry>
+<term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Pipe to
+Console</guimenuitem></menuchoice></term>
+<listitem><para>Feed the currently selected text ito the built in terminal
+emulator. No newline is added after the text.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Tools</guimenu><guisubmenu>External
+Tools</guisubmenu></menuchoice></term>
+<listitem><para>This submenu contains all the <link
+linkend="kate-mdi-tools-externaltools">external tools</link>you have
+configured.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-read-only"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Read Only Mode</guimenuitem></menuchoice></term>
+<listitem>
+<para>Set the current document to Read Only mode. This prevents any text
+addition and any changes in the document formatting.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-filetype"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Filletype</guimenuitem></menuchoice></term>
+<listitem>
+<para>Choose the filetype scheme you prefer for the active document. This
+overwrites the global <link linkend="config-dialog-editor-filetypes">filetype</link>
+mode set in <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure
+Editor...</guimenuitem></menuchoice> in the Filetypes tab for your current
+document only.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-highlighting"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Highlighting</guimenuitem></menuchoice></term>
+ <listitem>
+<para>Choose the Highlighting scheme you prefer for the active document. This
+overwrites the global highlighting mode set in <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem>
+</menuchoice> for your current document only.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-indentation"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Indentation</guimenuitem></menuchoice></term>
+<listitem>
+<para>Choose the <link linkend="kate-part-autoindent">style of
+indentation</link> you want for your active document.
+This overwrites the global indentation mode set in <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem>
+</menuchoice> for your current document only.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-encoding"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Encoding</guimenuitem></menuchoice></term>
+<listitem>
+<para>You can overwrite the default encoding set in <menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure
+Editor...</guimenuitem></menuchoice> in the <guilabel>Open/Save</guilabel> tab
+to set a different encoding for your current document. The encoding you
+set here will be only valid for your current document.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-end-of-line"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>End of Line</guimenuitem></menuchoice></term>
+<listitem>
+<para>Choose your prefered end of line mode for your active
+document. This overwrites the global end of line mode set in <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem>
+</menuchoice> for your current document only.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-spelling"/><menuchoice>
+<guimenu>Tools</guimenu><guimenuitem>Spelling...</guimenuitem></menuchoice>
+</term>
+
+<listitem><para><action>This initiates the spellchecking program - a program
+designed to help the user catch and correct any spelling errors.</action>
+Clicking on this entry will start the checker and bring up the speller dialog
+box through which the user can control the process.  There are four settings
+lined up vertically in the center of the dialog with their corresponding labels
+just to the left.  Starting at the top they are:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Unknown word:</guilabel></term>
+<listitem><para>Here, the spellchecker indicates the word currently under
+consideration.  This happens when the checker encounters a word not in its
+dictionary - a file containing a list of correctly spelled words against which
+it compares each word in the editor.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Replace with:</guilabel></term>
+<listitem><para> If the checker has any similar words in its dictionary the
+first one will be listed here.  The user can accept the suggestion, type in his
+or her own correction, or choose a different suggestion from the next
+box.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Suggested Words:</guilabel></term>
+<listitem><para> The checker may list here a number of possible replacements for
+the word under consideration.  Clicking on any one of the suggestions will cause
+that word to be entered in the <guilabel>Replacement:</guilabel> box,
+above.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Language:</guilabel></term>
+<listitem><para> If you have installed multiple dictionaries, here you can
+select which dictionary/language should be used.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>On the right side of the dialog box are 5 buttons that allow the user to
+control the spellcheck process.  They are:</para>
+
+<variablelist>
+<varlistentry>
+<term><guibutton>Add to Dictionary</guibutton></term>
+<listitem><para>Pressing this button adds the word in the <guilabel>Misspelled
+Word:</guilabel> box to the checker's dictionary. This means that in the future
+the checker will always consider this word to be correctly
+spelled.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Replace</guibutton></term>
+<listitem><para> This button has the checker replace the word under
+consideration in the document with the word in the
+<guilabel>Replacement:</guilabel> box.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Replace All</guibutton></term>
+<listitem><para> This button causes the checker to replace not only the current
+<guilabel>Unknown word:</guilabel> but to automatically make the same
+substitution for any other occurrences of this <guilabel>Misspelled
+Word:</guilabel> in the document.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Ignore</guibutton></term>
+<listitem><para>Activating this button will have the checker move on without
+making any changes.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Ignore All</guibutton></term>
+<listitem><para> This button tells the checker to do nothing with the current
+<guilabel>Unknown word:</guilabel> and to pass over any other instances of
+the same word.</para> <note><para>This only applies to the current spellcheck
+run.  If the checker is run again later it will stop on this same
+word.</para></note></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Three more buttons are located horizontally along the bottom of the
+spellcheck dialog.  They are:</para>
+
+<variablelist>
+<varlistentry>
+<term><guibutton>Help</guibutton></term>
+<listitem><para> This invokes the &kde; help system starting at the &kate; help
+pages (this document).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Finished</guibutton></term>
+<listitem><para> This button ends the spellcheck process, and returns to the
+document.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Cancel</guibutton></term>
+<listitem><para> This button cancels the spellcheck process, all modifications
+are reverted, and you will return to your document.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<varlistentry>
+<term><anchor id="tools-spelling-from-cursor"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Spelling (from cursor)...</guimenuitem></menuchoice></term>
+ <listitem>
+<para>This initiates the spellchecking program but it starts where your cursor
+is instead of at the beginning of the document.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-spellcheck-selection"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Spellcheck Selection...</guimenuitem></menuchoice></term>
+ <listitem>
+<para>Spellchecks the current selection.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="indent"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu><guimenuitem>Indent</guimenuitem></menuchoice></term>
+<listitem>
+<para>This increases the paragraph's indentation by one step. The size of the
+step depends on the <link linkend="config-dialog-editor-indent">indentation
+settings</link>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-unindent"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu><guimenuitem>Unindent</guimenuitem></menuchoice></term>
+
+<listitem>
+<para>This reduces the paragraph's indentation by one step. The size of the step
+
+depends on the <link linkend="config-dialog-editor-indent">indentation settings</link>.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-cleanindent"/><menuchoice>
+<guimenu>Tools</guimenu><guimenuitem>Clean
+Indentation</guimenuitem></menuchoice></term>  <listitem>
+<para>This cleans the indentation for the current selection or for the
+line the cursor is currently in. Cleaning the indentation ensures that
+all your selected text follows the indentation mode you choose.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-align"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Align</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Causes a realign of the current line or selected lines using the
+indentation mode and indentation settings in the doucment.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-comment"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Comment</guimenuitem>
+</menuchoice></term>
+<listitem><para>This adds one space to the beginning of the line
+where the text cursor is located or to the beginning of any
+selected lines.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-uncomment"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Uncomment</guimenuitem>
+</menuchoice></term>
+<listitem><para>This removes one space (if any exist) from the beginning of the
+line where the text cursor is located or from the beginning of any
+selected lines.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-uppercase"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Uppercase</guimenuitem>
+</menuchoice></term>
+<listitem><para>Put the selected text or the letter after the cursor in
+uppercase.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-lowercase"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Shift;<keycap>U</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Lowercase</guimenuitem>
+</menuchoice></term>
+<listitem><para>Put the selected text or the letter after the cursor in
+lowercase.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-capitalize"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Capitalize</guimenuitem>
+</menuchoice></term>
+<listitem><para>Capitalize the selected text or the current
+word.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-join-lines"/><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo>
+</shortcut>
+<guimenu>Tools</guimenu>
+<guimenuitem>Join Lines</guimenuitem>
+</menuchoice></term>
+<listitem><para>Joins the selected lines, or the current line and the line below
+with one white space character as a separator. Leading/trailing white space on
+joined lines is removed in the affected ends.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><anchor id="tools-word-wrap-document"/><menuchoice>
+<guimenu>Tools</guimenu>
+<guimenuitem>Word Wrap Document</guimenuitem>
+</menuchoice></term>
+<listitem><para>Apply static word wrapping on all the document. That means that
+a new line of text will automatically start when the current
+line exceeds the length specified by the Wrap words at: option
+in the Editing tab in <menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure
+Editor...</guimenuitem></menuchoice></para></listitem>
+</varlistentry>
+
+</variablelist>
+
+
+</sect1>
+
+<sect1 id="sessions-menu">
+<title>The <guimenu>Sessions</guimenu> Menu</title>
+
+<para>This menu contains entries for using and managing &kate; sessions.
+For more information, read <link
+linkend="fundamentals-using-sessions">Using Sessions</link>.</para>
+
+<variablelist>
+
+<varlistentry id="sessions-new">
+<term><menuchoice><guimenu>Sessions</guimenu>
+<guimenuitem>New</guimenuitem></menuchoice></term>
+<listitem><para>Creates a new empty session. All currently open files will
+be closed.</para></listitem>
+
+</varlistentry>
+
+<varlistentry id="sessions-open">
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Open...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Open an existing session. The Session Chooser dialog is
+displayed to let you choose one.</para></listitem>
+</varlistentry>
+
+<varlistentry id="sessions-quick-open">
+<term><menuchoice><guimenu>Sessions</guimenu><guisubmenu>Quick Open</guisubmenu>
+</menuchoice></term>
+<listitem><para>This submenu lets you open an existing session.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="sessions-save">
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save</guimenuitem>
+</menuchoice></term>
+<listitem><para>Save the current session. If the session is anonymous, you will
+be prompted for a session name.</para></listitem>
+</varlistentry>
+
+<varlistentry id="sessions-save-as">
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save
+As...</guimenuitem></menuchoice></term>
+<listitem><para>Save the current session under a new name. You are prompted for
+a name to use.</para></listitem>
+</varlistentry>
+
+<varlistentry id="sessions-manage">
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Manage...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Displays the Session Manager dialog which allows you to rename
+and delete sessions.</para></listitem>
+</varlistentry>
+
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<para>The <guimenu>Settings</guimenu> menu allows you to change the properties
+of the main window, such as showing/hiding toolbars, and provides
+access to the configuration dialogs.</para>
+
+<variablelist>
+
+<varlistentry>
+<term>
+<anchor id="settings-toolbars"/>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Toolbars</guisubmenu>
+</menuchoice>
+</term>
+<listitem>
+<para>This submenu lists the available toolbars, each item toggles the display
+of the associated toolbar.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="settings-fullscreen">
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Full Screen
+Mode</guimenuitem></menuchoice></term>
+<listitem><para>Toggles full screen display.</para>
+<note><para>This commmand will be moved to the Window menu in a future
+version of &kate;</para></note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="settings-configure-shortcuts"/>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Display the familiar &kde; Keyboard Shortcut Configuration
+Dialog.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>
+<anchor id="settings-configure-toolbars"/>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Display the familiar &kde; Toolbar Configuration Dialog.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="settings-configure-kate"/>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kate;...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Launch the <link linkend="config-dialog">Main Configuration Dialog</link></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="window-menu">
+<title>the <guimenu>Window</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<anchor id="window-new"/>
+<menuchoice>
+<guimenu>Window</guimenu>
+<guimenuitem>New Window</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Opens another instance of &kate;</action>.
+The new instance will be identical to your previous instance.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-split-vertical"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>L</keycap></keycombo></shortcut>
+<guimenu>Window</guimenu>
+<guimenuitem>Split Vertical</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>This will split the frame (which may be the main editing area) in two equally sized frames,
+the new one to the left of the current one. The new frame gets the focus, and will display the
+same document as the old one.</para>
+<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-split-horizontal"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>T</keycap></keycombo></shortcut>
+<guimenu>Window</guimenu>
+<guimenuitem>Split Horizontal</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Splits the current frame (which may be the main editing area) in two equally sized frames,
+the new one at the bottom half. The new frame gets the focus, and displays the same document as
+the old one.</para>
+<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-close-current"/>
+<menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo></shortcut>
+<guimenu>Window</guimenu>
+<guimenuitem>Close Current</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Closes the active frame. This is disabled, if there is only one frame
+(the main editing area).</para> <para>No documents get closed by closing a
+frame &ndash; they will still be available in the <link
+linkend="document-menu"><guimenu>Documents</guimenu> Menu</link> as well as in
+the File List.</para> <para>See also <link linkend="kate-mdi">Working with the
+&kate; MDI</link></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="window-next-view">
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>F8</keycap>
+</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Next
+View</guimenuitem></menuchoice></term>
+<listitem><para>Focus the next document view, if you have split the editor area
+in more views.</para></listitem>
+</varlistentry>
+
+<varlistentry id="window-previous-view">
+<term><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F8</keycap>
+</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Previous
+View</guimenuitem></menuchoice></term>
+<listitem><para>Focus the previous document view, if you have split the editor
+area in more views.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+</menuchoice></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><anchor id="window-toolviews-show-sidebars"/>
+<menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show/Hide Sidebars</guimenuitem></menuchoice></term>
+<listitem><para>Toggles the display of the sidebar button rows. This command
+does not affect the display of the sidebar content widgets, any sidebar that
+is visible will stay visible, and if you assigned shortcuts to the below
+commands those will of course continue to work.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-toolviews-show-filelist"/>
+<menuchoice>
+<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show Documents</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggle the display of &kate;'s Documents list</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-toolviews-show-fileselector"/>
+<menuchoice>
+<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show/Hide Filesystem Browser</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggle the display of &kate;'s Filesystem Browser</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-toolviews-greptool"/>
+<menuchoice>
+<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show/Hide Find in Files</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggle the display of &kate;'s <guilabel>Find in Files</guilabel> tool.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<anchor id="window-toolviews-show-konsole"/>
+<menuchoice>
+<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show/Hide Terminal</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggles the display of the built in terminal emulator.</para>
+<para>When activated the first time, the terminal will be created.</para>
+<para>When the terminal emulator is displayed, it will get the focus, so that
+you can start typing in commands immediately. If the <link
+linkend="config-dialog-general-sync-konsole">Sync Konsole with Active
+Document</link> option is enabled in the <link
+linkend="config-dialog-general">General Page</link> of the <link
+linkend="config-dialog">Main configuration dialog</link> the shell session will
+change to the directory of the active document, if it is a local file.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="help-menu">
+
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+<para>Apart from standard &kde; <guimenu>Help</guimenu> menu items
+described below you will have menu entries to show the
+Plugins User Manuals for installed plugins.</para>
+
+&help.menu.documentation;
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/mimetypechooser.png b/doc/kate/mimetypechooser.png
new file mode 100644
index 000000000..45220f8a4
--- /dev/null
+++ b/doc/kate/mimetypechooser.png
diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook
new file mode 100644
index 000000000..e09725b31
--- /dev/null
+++ b/doc/kate/part.docbook
@@ -0,0 +1,671 @@
+<chapter id="kate-part">
+<chapterinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+<title>Working with the &kate; editor</title>
+
+<sect1 id="kate-part-overview">
+
+<title>Overview</title>
+
+<para>The &kate; editor is the editing area of the &kate; window. This
+editor is also used by &kwrite;, and it can be used in &konqueror; for
+displaying text files from your local computer, or from the
+network.</para>
+
+<para>The editor is composed of the following components:</para>
+
+<variablelist>
+
+<varlistentry>
+<term>The editing area</term>
+<listitem><para>This is where the text of your document is located.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The Scroll bars</term>
+<listitem>
+<para>The scroll bars indicate the  position of the visible part of
+the document text, and can be used to move around the
+document. Dragging the scrollbars will not cause the insertion cursor
+to be moved.</para>
+<para>The scroll bars are displayed and hidden as required.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The Icon Border</term>
+<listitem>
+<para>The icon border is a small pane on the left side of the editor,
+displaying a small icon next to marked lines.</para>
+<para>You can set or remove a <link
+linkend="kate-part-bookmarks">bookmark</link> in a visible line by
+clicking the &LMB; in the icon border next to that line.</para>
+<para>The display of the icon border can be toggled using the
+<menuchoice><guimenu>View</guimenu> <guimenuitem>Show Icon
+Border</guimenuitem></menuchoice> menu item.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The Line Numbers Pane</term>
+<listitem>
+<para>The Line numbers pane shows the line numbers of all visible
+lines in the document.</para>
+<para>The display of the Line Numbers Pane can be toggled using the
+<menuchoice><guimenu>View</guimenu> <guimenuitem>Show Line
+Numbers</guimenuitem></menuchoice> menu item.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The Folding Pane</term>
+<listitem>
+<para>The folding pane allows you to collapse or expand foldable blocks
+of lines. The calculation of the foldable regions are done according to
+rules in the syntax highlight definition for the document.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<itemizedlist>
+<title>Also in this Chapter:</title>
+<listitem><para><link linkend="kate-part-navigation">Navigating in the
+Text</link> </para></listitem>
+<listitem><para><link linkend="kate-part-selection">Working with the
+Selection</link></para></listitem>
+<listitem><para><link linkend="kate-part-copy-and-paste">Copying and
+Pasting Text</link></para></listitem>
+<listitem><para><link linkend="kate-part-find-replace">Finding and
+Replacing Text</link></para></listitem>
+<listitem><para><link linkend="kate-part-bookmarks">Using
+Bookmarks</link></para></listitem>
+<listitem><para><link linkend="kate-part-auto-wrap">Automatically
+Wrapping Text</link></para></listitem>
+<listitem><para><link linkend="kate-part-autoindent">Using automatic indenting</link></para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="kate-part-navigation">
+<title>Navigating in the Text</title>
+
+<para>Moving around in the text in &kate; is like in most graphical text
+editors. You move the cursor using the arrow keys and the
+<keycap>Page Up</keycap>, <keycap>Page Down</keycap>, <keycap>Home</keycap> and
+<keycap>End</keycap> keys in combination with the <keycap>Ctrl</keycap> and
+<keycap>Shift</keycap> modifiers. The <keycap>Shift</keycap> key is always used
+to generate a selection, while the <keycap>Ctrl</keycap> key have different
+effects on different keys:
+<itemizedlist>
+<listitem><para>For the <keycap>Up</keycap> and <keycap>Down</keycap> keys it
+means scroll rather than move the cursor.</para></listitem>
+<listitem><para>For the <keycap>Left</keycap> and <keycap>Right</keycap>
+keys it means skip words rather than characters.</para></listitem>
+<listitem><para>for the <keycap>Page Up</keycap> and <keycap>Page Down</keycap>
+keys it means move to the visible edge of the view rather than browse.</para>
+</listitem>
+<listitem><para>For the <keycap>Home</keycap> and <keycap>End</keycap> keys it
+means move to the beginning or end of the document rather than the beginning or
+end of the line.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>&kate; also provides you with a way to quickly jump to a matching brace
+or paranthese: Place the cursor on the inside of a parenthese or brace
+character, and press <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo>
+to jump to the matching parenthese or brace.</para>
+
+<para>In addition you can use
+<link linkend="kate-part-bookmarks">bookmarks</link> to quickly jump to
+positions that you define on your own.</para>
+
+</sect1>
+
+<sect1 id="kate-part-selection">
+<title>Working with the Selection</title>
+
+<para>There are two basic ways of selecting text in &kate;: using the
+mouse, and using the keyboard.</para>
+
+<para>To select using the mouse, hold down the &LMB; while dragging
+the mouse cursor from where the selection should start, to the desired
+end point. The text gets selected as you drag.</para>
+
+<para>Double-clicking a word will select that word.</para>
+
+<para>Triple-clicking in a line will select the entire line.</para>
+
+<para>If &Shift; is held down while clicking, text will be
+selected:</para>
+
+<itemizedlist>
+<listitem><para>If nothing is already selected, from the text cursor
+position to the mouse cursor position.</para></listitem>
+<listitem><para>If there is a selection, from and including that
+selection to the mouse cursor position</para></listitem>
+</itemizedlist>
+
+<note>
+<para>When selecting text by dragging the mouse, the
+selected text is copied to the clipboard, and can be pasted by
+clicking the middle mouse button in the editor, or in any other
+application to which you want to paste the text.
+</para>
+</note>
+
+<para>To select using the keyboard, hold down the &Shift; key while
+using the navigation keys (The Arrow keys, <keycap>Page Up</keycap>,
+<keycap>Page Down</keycap>, <keycap>Home</keycap> and
+<keycap>End</keycap>, possibly in combination with &Ctrl; to extend
+the move of the text cursor).</para>
+
+<para>See also the section <link
+linkend="kate-part-navigation">Navigating in the Text</link> in this
+Chapter.</para>
+
+<para>To <action>Copy</action> the current selection, use the
+<menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>Copy</guimenuitem></menuchoice> menu item or the keyboard
+shortcut (defaults to <keycombo
+action="simul">&Ctrl;<keycap>C</keycap></keycombo>).</para>
+
+<para>To <action>Deselect</action> the current selection, use the
+<menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>Deselect</guimenuitem></menuchoice> menu item, or the
+keyboard shortcut (default is <keycombo
+action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo>), or click
+with the &LMB; in the editor.</para>
+
+<sect2 id="kate-part-selection-block">
+<title>Using Block Selection</title>
+
+<para>When Block Selection is enabled, you can make <quote>vertical
+selections</quote> in the text, meaning selecting limited columns from
+multiple lines. This is handy for working with tab separated lines for
+example.</para>
+
+<para>Block Selection can be toggled using the
+<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Toggle Block
+Selection</guimenuitem></menuchoice> menu item. The default keyboard
+shortcut is <keycap>F4</keycap></para>
+
+</sect2>
+
+<sect2 id="kate-part-seleciton-overwrite">
+
+<title>Using Overwrite Selection</title>
+
+<para>If Overwrite Selection is enabled, typing or pasting text into
+the selection will cause the selected text to be replaced. If not
+enabled, new text will be added at the position of the text
+cursor.</para>
+
+<para>Overwrite Selection is enabled by default.</para>
+
+<para>To change the setting for this option, use the <link
+linkend="config-dialog-editor-cursor-selection">Select Page</link> of the <link
+linkend="config-dialog">Configuration Dialog</link>.</para>
+
+</sect2>
+
+<sect2 id="kate-part-selection-persistent">
+
+<title>Using Persistent Selection</title>
+
+<para>When Persistent selection is enabled, typing characters or
+moving the cursor will not cause the Selection to become
+deselected. This means that you can move the cursor away from the
+selection and type text.</para>
+
+<para>Persistent Selection is disabled by default.</para>
+
+<para>Persistent Selection can be enabled in the <link
+linkend="config-dialog-editor-cursor-selection">Select Page</link> of the <link
+linkend="config-dialog">Configuration Dialog</link>.</para>
+
+<warning>
+<para>If Persistent Selection and Overwrite Selection are both
+enabled, typing or pasting text when the text cursor is inside the
+selection will cause it to be replaced and deselected.</para>
+</warning>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="kate-part-copy-and-paste">
+
+<title>Copying and Pasting Text</title>
+
+<para>To copy text, select it and use the
+<menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>Copy</guimenuitem></menuchoice> menu item. Additionally,
+selecting text with the mouse will cause selected text to be copied to
+the X selection.</para>
+
+<para>To paste the text currently in the clipboard, use the
+<menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice>
+menu item.</para>
+
+<para>Additionally, text selected with the mouse may be pasted by
+clicking the <mousebutton>middle</mousebutton> mouse button at the
+desired position.</para>
+
+<tip>
+<para>If you are using the &kde; desktop, you can retrieve earlier
+copied text from any application using the &klipper; icon in the
+&kicker; icon tray.</para>
+</tip>
+
+</sect1>
+
+<sect1 id="kate-part-find-replace">
+<title>Finding and Replacing Text</title>
+
+<sect2 id="find-replace-dialog">
+<title>The <guilabel>Find Text</guilabel> and <guilabel>Replace
+Text</guilabel> Dialogs</title>
+
+
+<para>The Find and Replace Text dialogs in &kate; are very much the
+same, except the Replace Text dialog offers the means of entering a
+replacement string along with a few extra options.</para>
+
+<para>The dialogs offer the following common options:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Text to Find</guilabel></term>
+<listitem><para>This is where to enter the search string. The interpretation of the string
+depends on some of the options described below.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Regular Expression</guilabel></term>
+<listitem>
+<para>If checked, the search string is interpreted as a regular
+expression. A button for using a graphical tool to create or edit the
+expression will be enabled.</para>
+<para>See <link linkend="regular-expressions">Regular
+Expressions</link> for more on these.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Case Insensitive</guilabel></term>
+<listitem>
+<para>If enabled, the search will be case insensitive.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Whole Words Only</guilabel></term>
+<listitem>
+<para>If checked, the search will only match if there is a word
+boundary at both ends of the string matching, meaning not an
+alphanumeric character - either some other visible character or a line
+end.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>From cursor</guilabel></term>
+<listitem>
+<para>If checked, the search will start at cursor position, otherwise it will
+start at the beginning of the first line in the document.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Find Backwards</guilabel></term>
+<listitem>
+<para>If checked, the search will look for the first match above the
+starting point, either cursor position or the beginning of the
+document, if the <guilabel>From Beginning</guilabel> option is
+enabled.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>The <guilabel>Replace Text</guilabel> Dialog offers some
+additional options:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Replace With</guilabel></term>
+<listitem><para>This is where to enter the replacement
+string.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Selected Text</guilabel></term>
+<listitem>
+<para>This option is disabled if no text is selected, or if the
+<guilabel>Prompt on Replace</guilabel>
+option is enabled. If checked, all matches of the search string within
+the selected text will be replaced with the replace string.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Prompt on Replace</guilabel></term>
+<listitem><para>If checked, a small dialog will prompt you for what to
+do for each time a match is found. It offers the following options:
+<variablelist>
+
+<varlistentry>
+<term><guibutton>Yes</guibutton></term>
+<listitem><para>Activate this to replace the current match (which is
+selected in the editor).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>No</guibutton></term>
+<listitem><para>Activate to skip the current match, and try to find another one.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>All</guibutton></term>
+<listitem><para>Activate to cancel prompting, and just replace all
+matches.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Close</guibutton></term>
+<listitem><para>Activate this to skip the current match and end the
+searching.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<note>
+<para>There is currently no way to use minimal matching when searching
+for a regular expression. This will be added in a future version of
+&kate;</para>
+</note>
+
+</sect2>
+
+<sect2 id="finding-text">
+<title>Finding Text</title>
+
+<para>To find text, launch the <guilabel>Find Text</guilabel> Dialog
+with <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo>or
+from the <menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>Find...</guimenuitem></menuchoice> menu item, enter a
+search string, set the <link
+linkend="find-replace-dialog">options</link> as desired and hit
+<guibutton>Ok</guibutton>. If the search was started at cursor position and no
+match was found before reaching the end (or beginning if you are searching
+backward) of the document, you will be asked if you want to wrap the search.
+</para>
+
+<para>If a match is found it is selected and the <guilabel>Find
+Text</guilabel> Dialog is hidden, but stay tuned, finding further
+matches is very easy:</para>
+
+<para>To find the next match in the search direction, use the
+<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find
+Next</guimenuitem></menuchoice> command or press
+<keycap>F3</keycap>.</para>
+
+<para>To find the next match in the opposite direction, use the
+<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find
+Previous</guimenuitem></menuchoice> command or press <keycombo
+action="simul">&Shift;<keycap>F3</keycap></keycombo>.</para>
+
+<para>If no match is found before reaching the document end (or beginning if you
+are searching backward) , you will be asked if you want to wrap the search.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Replacing Text</title>
+
+<para>To replace text, launch the <guilabel>Replace text</guilabel>
+Dialog using the <menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>Replace</guimenuitem></menuchoice> command, or the
+<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo> shortcut,
+enter a search string and optionally a replace string (if the replace
+string is empty, each match will be removed), set
+the <link linkend="find-replace-dialog">options</link> as desired and
+hit the <guibutton>Ok</guibutton> button.</para>
+
+<tip>
+<para>If you are using a regular expression to find the text to replace, you can
+employ backreferences to reuse text captured in parenthesized subpatterns of the expression.</para>
+<para>See <xref linkend="regular-expressions"/><!-- xref to reg-exp appendix --> for more
+on those.</para>
+</tip>
+
+<tip><para>You can do <command>find</command>, <command>replace</command> and
+<command>ifind</command> (incremental search) from the
+<link linkend="advanced-editing-tools-commandline">command line</link>.</para>
+</tip>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="kate-part-bookmarks">
+<title>Using Bookmarks</title>
+
+<para>The bookmarks feature allows you to mark certain lines, to be
+able to easily find them again.</para>
+
+<para>You can set or remove a bookmark in a line in two ways:</para>
+
+<itemizedlist>
+<listitem>
+<para>Move the insertion cursor to the line and activate the
+<menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Toggle
+Bookmark</guimenuitem></menuchoice> (<keycombo
+action="simul">&Ctrl;<keycap>B</keycap></keycombo>) command.</para>
+</listitem>
+<listitem>
+<para>Click in the Icon Border next to the line.</para>
+</listitem>
+</itemizedlist>
+
+
+<para>Bookmarks are available in the <guimenu>Bookmarks</guimenu>
+menu. The individual bookmarks are available as menu items, labeled
+with the line number of the line with the bookmark, and the first few
+characters of the text in the line. To move the insertion cursor to
+the beginning of a bookmarked line, open the menu and select the
+bookmark.</para>
+
+<para>To quickly move between bookmarks or to the next/previous bookmark,
+use the <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem>
+</menuchoice> (<keycombo action="simul"><keycap>Ctrl</keycap>
+<keycap>Page Down</keycap></keycombo>)  or <menuchoice>
+<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice>
+(<keycombo action="simul"><keycap>Ctrl</keycap><keycap>Page Up</keycap>
+</keycombo>) commands.</para>
+
+</sect1>
+
+<sect1 id="kate-part-auto-wrap">
+
+<title>Automatically Wrapping text</title>
+
+<para>This feature allows you to have the text formatted in a very simple way: the text will be wrapped,
+so that no lines exceed a maximum number of characters per line, unless there is a longer string of
+non-whitespace characters.</para>
+
+<para>To enable/disable it, check/uncheck the <guibutton>Word Wrap</guibutton> checkbox in the
+<link linkend="config-dialog-editor-edit">edit page</link> of the <link linkend="config-dialog">configuration dialog</link>.</para>
+
+<para>To set the maximum line width (maximum characters per line), use the
+<link linkend="config-dialog-editor-wrap-words-at"><guibutton>Wrap Words At</guibutton></link>
+option in the <link linkend="config-dialog-editor-edit">edit page</link> of the <link linkend="config-dialog">configuration
+dialog</link>.</para>
+
+<para>If enabled,
+it has the following effects:
+
+<itemizedlist>
+<listitem><para>While typing, the editor will automatically insert a hard line break after
+the last whitespace character at a position before the maximum line width is reached.</para></listitem>
+<listitem><para>While loading a document, the editor will wrap the text in a similar way, so that
+no lines are longer than the maximum line width, if they contain any whitespace allowing that.</para></listitem>
+</itemizedlist>
+
+</para>
+
+<note><para>There is currently no way to set word wrap for document types, or even to enable or disable
+the feature on document level. This will be fixed in a future version of &kate;</para></note>
+
+</sect1>
+
+<sect1 id="kate-part-autoindent">
+<title>Using automatic indenting</title>
+
+<para>&kate;s editor component supports a variation of autoindenting modes,
+designed for different text formats. You can pick from the available modes using
+the <menuchoice><guimenu>Tools</guimenu><guisubmenu>Indentation</guisubmenu></menuchoice>
+menu. The autoindent modules also provides a function
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>
+which will recalculate the indentation of the selected or current line. Thus,
+you may reindent your entire document by selecting all the text and activating
+that action.</para>
+
+<para>All the indent modes use the indentation related settings in the active
+document.</para>
+
+<tip><para>You can set all sorts of configuration variables, including
+those related to indentation using <link linkend="config-variables">Document
+Variables</link> and <link linkend="config-dialog-editor-filetypes">File
+types</link>.</para></tip>
+
+<variablelist>
+
+<title>Available Autoindent Modes</title>
+
+<varlistentry>
+<term>None</term>
+<listitem><para>Selecting this mode turns automatic indenting off entirely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Normal</term>
+<listitem><para>This indenter simply keeps the indentation similar to the
+previous line with any content other than whitespace. You can combine this
+with using the indent and unindent actions for indenting to your own taste.
+</para></listitem>
+</varlistentry>
+
+<varlistentry><term>C Style</term>
+<listitem><para>An indenter for C and similar languages, such as
+C++, C#, java, javascript and so on. This indenter will not work with scripting
+languages such as Perl or PHP.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>SS C Style</term>
+<listitem><para>An alternative indenter for C and similar languages, with the
+same constraints.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Python Style</term>
+<listitem><para>An indenter specifically for the python scripting language.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>XML</term>
+<listitem><para>A very nice XML auto-indenter. However tempting, do not try to
+use this with HTML other than XHTML, because it fails with the old style
+HTML tags (open tags like for example &lt;br&gt;)</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Variable Indenter</term>
+<listitem>
+
+<note>
+<para>The variable indenter is experimental, and may change behavior or
+disappear in future versions.</para>
+</note>
+
+<para>
+The variable indenter is special in that it can be configured using variables in
+the document (or in a filetype configuration). The followwing variables are
+read:
+
+<variablelist>
+<varlistentry>
+<term>var-indent-indent-after</term>
+<listitem>
+<para>A regular expression which will cause a line to
+be indented by one unit, if the first non-whitespace-only line above matches.
+var-indent-indent: A regular expression, which will cause a matching line
+to be indented by one unit.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>var-indent-unindent</term>
+<listitem>
+<para>A regular expression which will cause the line to be
+unindented by one unit if matching.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>var-indent-triggerchars</term>
+<listitem>
+<para>A list of characters that should cause the
+indention to be recalculated immediately when typed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>var-indent-handle-couples</term>
+<listitem>
+<para>A list of parenthese sets to handle. Any combination
+of 'parens' 'braces' and 'brackets'. Each set type is handled
+the following way: If there are unmatched opening instances on the above line,
+one indent unit is added, if there are unmatched closing instances on the
+current line, one indent unit is removed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>var-indent-couple-attribute</literal></term>
+<listitem>
+<para>When looking for unmatched couple openings/closings,
+only characters with this attribute are considered. The value must be the
+attribute name from the syntax xml file, for example "Symbol". If it's not
+specified, attribute 0 is used (usually 'Normal Text').</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+</chapter>
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
new file mode 100644
index 000000000..a097cb526
--- /dev/null
+++ b/doc/kate/plugins.docbook
@@ -0,0 +1,28 @@
+<chapter id="plugins">
+
+<chapterinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</chapterinfo>
+
+<title>Working with Plug-ins</title>
+
+<para>Kate is using two different forms of plug-ins, namely plug-ins for the
+&kate; application and plug-ins for the &kate; editor component. The latter are
+available to any application using the editor component, such as KDevelop,
+Quanta, Kile, Kwrite and many others, while application plug-ins are specific
+to the &kate; application.</para>
+
+<para>You can enable both types of plug-ins in the <link
+linkend="configuring-kate-configdialog">configuration dialog</link>, which also
+provides access to additional configuration options for plug-ins that requires
+that.</para>
+
+<para>There are many plugins for various purposes available in the kdeaddons
+module, and you can search the web for more. A few plugins are shipped with the
+editor component, for doing word completion, automatic bookmarks, insert files,
+thesaurus and word spell checking and incremental search.</para>
+
+</chapter>
diff --git a/doc/kate/regular-expressions.docbook b/doc/kate/regular-expressions.docbook
new file mode 100644
index 000000000..c15685d75
--- /dev/null
+++ b/doc/kate/regular-expressions.docbook
@@ -0,0 +1,664 @@
+<appendix id="regular-expressions">
+<appendixinfo>
+<authorgroup>
+<author>&Anders.Lund; &Anders.Lund.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+</appendixinfo>
+
+<title>Regular Expressions</title>
+
+<synopsis> This Appendix contains a brief but hopefully sufficient and
+covering introduction to the world of <emphasis>regular
+expressions</emphasis>. It documents regular expressions in the form
+available within &kate;, which is not compatible with the regular
+expressions of perl, nor with those of for example
+<command>grep</command>.</synopsis>
+
+<sect1>
+
+<title>Introduction</title>
+
+<para><emphasis>Regular Expressions</emphasis> provides us with a way
+to describe some possible contents of a text string in a way
+understood by a small piece of software, so that it can investigate if
+a text matches, and also in the case of advanced applications with the
+means of saving pieces or the matching text.</para>
+
+<para>An example: Say you want to search a text for paragraphs that
+starts with either of the names <quote>Henrik</quote> or
+<quote>Pernille</quote> followed by some form of the verb
+<quote>say</quote>.</para>
+
+<para>With a normal search, you would start out searching for the
+first name, <quote>Henrik</quote> maybe followed by <quote>sa</quote>
+like this: <userinput>Henrik sa</userinput>, and while looking for
+matches, you would have to discard those not being the beginning of a
+paragraph, as well as those in which the word starting with the
+letters <quote>sa</quote> was not either <quote>says</quote>,
+<quote>said</quote> or so.  And then of cause repeat all of that with
+the next name...</para>
+
+<para>With Regular Expressions, that task could be accomplished with a
+single search, and with a larger degree of preciseness.</para>
+
+<para>To achieve this, Regular Expressions defines rules for
+expressing in details a generalization of a string to match. Our
+example, which we might literally express like this: <quote>A line
+starting with either <quote>Henrik</quote> or <quote>Pernille</quote>
+(possibly following up to 4 blanks or tab characters) followed by a
+whitespace followed by <quote>sa</quote> and then either
+<quote>ys</quote> or <quote>id</quote></quote> could be expressed with
+the following regular expression:</para> <para><userinput>^[
+\t]{0,4}(Henrik|Pernille) sa(ys|id)</userinput></para>
+
+<para>The above example demonstrates all four major concepts of modern
+Regular Expressions, namely:</para>
+
+<itemizedlist>
+<listitem><para>Patterns</para></listitem>
+<listitem><para>Assertions</para></listitem>
+<listitem><para>Quantifiers</para></listitem>
+<listitem><para>Back references</para></listitem>
+</itemizedlist>
+
+<para>The caret (<literal>^</literal>) starting the expression is an
+assertion, being true only if the following matching string is at the
+start of a line.</para>
+
+<para>The stings <literal>[ \t]</literal> and
+<literal>(Henrik|Pernille) sa(ys|id)</literal> are patterns. The first
+one is a <emphasis>character class</emphasis> that matches either a
+blank or a (horizontal) tab character; the other pattern contains
+first a subpattern matching either <literal>Henrik</literal>
+<emphasis>or</emphasis> <literal>Pernille</literal>, then a piece
+matching the exact string <literal> sa</literal> and finally a
+subpattern matching either <literal>ys</literal>
+<emphasis>or</emphasis> <literal>id</literal></para>
+
+<para>The string <literal>{0,4}</literal> is a quantifier saying
+<quote>anywhere from 0 up to 4 of the previous</quote>.</para>
+
+<para>Because regular expression software supporting the concept of
+<emphasis>back references</emphasis> saves the entire matching part of
+the string as well as sub-patterns enclosed in parentheses, given some
+means of access to those references, we could get our hands on either
+the whole match (when searching a text document in an editor with a
+regular expression, that is often marked as selected) or either the
+name found, or the last part of the verb.</para>
+
+<para>All together, the expression will match where we wanted it to,
+and only there.</para>
+
+<para>The following sections will describe in details how to construct
+and use patterns, character classes, assertions, quantifiers and
+back references, and the final section will give a few useful
+examples.</para>
+
+</sect1>
+
+<sect1 id="regex-patterns">
+
+<title>Patterns</title>
+
+<para>Patterns consists of literal strings and character
+classes. Patterns may contain sub-patterns, which are patterns enclosed
+in parentheses.</para>
+
+<sect2>
+<title>Escaping characters</title>
+
+<para>In patterns as well as in character classes, some characters
+have a special meaning.  To literally match any of those characters,
+they must be marked or <emphasis>escaped</emphasis> to let the regular
+expression software know that it should interpret such characters in
+their literal meaning.</para>
+
+<para>This is done by prepending the character with a backslash
+(<literal>\</literal>).</para>
+
+
+<para>The regular expression software will silently ignore escaping a
+character that does not have any special meaning in the context, so
+escaping for example a <quote>j</quote> (<userinput>\j</userinput>) is
+safe. If you are in doubt whether a character could have a special
+meaning, you can therefore escape it safely.</para>
+
+<para>Escaping of cause includes the backslash character it self, to
+literally match a such, you would write
+<userinput>\\</userinput>.</para>
+
+</sect2>
+
+<sect2>
+<title>Character Classes and abbreviations</title>
+
+<para>A <emphasis>character class</emphasis> is an expression that
+matches one of a defined set of characters. In Regular Expressions,
+character classes are defined by putting the legal characters for the
+class in square brackets, <literal>[]</literal>, or by using one of
+the abbreviated classes described below.</para>
+
+<para>Simple character classes just contains one or more literal
+characters, for example <userinput>[abc]</userinput> (matching either
+of the letters <quote>a</quote>, <quote>b</quote> or <quote>c</quote>)
+or <userinput>[0123456789]</userinput> (matching any digit).</para>
+
+<para>Because letters and digits have a logical order, you can
+abbreviate those by specifying ranges of them:
+<userinput>[a-c]</userinput> is equal to <userinput>[abc]</userinput>
+and <userinput>[0-9]</userinput> is equal to
+<userinput>[0123456789]</userinput>.  Combining these constructs, for
+example <userinput>[a-fynot1-38]</userinput> is completely legal (the
+last one would match, of cause, either of
+<quote>a</quote>,<quote>b</quote>,<quote>c</quote>,<quote>d</quote>,
+<quote>e</quote>,<quote>f</quote>,<quote>y</quote>,<quote>n</quote>,<quote>o</quote>,<quote>t</quote>,
+<quote>1</quote>,<quote>2</quote>,<quote>3</quote> or
+<quote>8</quote>).</para>
+
+<para>As capital letters are different characters from their
+non-capital equivalents, to create a caseless character class matching
+<quote>a</quote> or <quote>b</quote>, in any case, you need to write it
+<userinput>[aAbB]</userinput>.</para>
+
+<para>It is of cause possible to create a <quote>negative</quote>
+class matching as <quote>anything but</quote> To do so put a caret
+(<literal>^</literal>) at the beginning of the class: </para>
+
+<para><userinput>[^abc]</userinput> will match any character
+<emphasis>but</emphasis> <quote>a</quote>, <quote>b</quote> or
+<quote>c</quote>.</para>
+
+<para>In addition to literal characters, some abbreviations are
+defined, making life still a bit easier:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>\a</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> bell character (BEL, 0x07).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\f</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> form feed character (FF, 0x0C).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\n</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> line feed character (LF, 0x0A, Unix newline).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\r</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> carriage return character (CR, 0x0D).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\t</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> horizontal tab character (HT, 0x09).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\v</userinput></term>
+<listitem><para> This matches the <acronym>ASCII</acronym> vertical tab character (VT, 0x0B).</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput>\xhhhh</userinput></term>
+
+<listitem><para> This matches the Unicode character corresponding to
+the hexadecimal number hhhh (between 0x0000 and 0xFFFF). \0ooo (&ie;,
+\zero ooo) matches the <acronym>ASCII</acronym>/Latin-1 character
+corresponding to the octal number ooo (between 0 and
+0377).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>.</userinput> (dot)</term>
+<listitem><para> This matches any character (including newline).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\d</userinput></term>
+<listitem><para> This matches a digit. Equal to <literal>[0-9]</literal></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\D</userinput></term>
+<listitem><para> This matches a non-digit. Equal to <literal>[^0-9]</literal> or <literal>[^\d]</literal></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\s</userinput></term>
+<listitem><para> This matches a whitespace character. Practically equal to <literal>[ \t\n\r]</literal></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\S</userinput></term>
+<listitem><para> This matches a non-whitespace. Practically equal to <literal>[^ \t\r\n]</literal>, and equal to <literal>[^\s]</literal></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\w</userinput></term>
+<listitem><para>Matches any <quote>word character</quote> - in this case any letter or digit. Note that
+underscore (<literal>_</literal>) is not matched, as is the case with perl regular expressions.
+Equal to <literal>[a-zA-Z0-9]</literal></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\W</userinput></term>
+<listitem><para>Matches any non-word character - anything but letters or numbers.
+Equal to <literal>[^a-zA-Z0-9]</literal> or <literal>[^\w]</literal></para></listitem>
+</varlistentry>
+
+
+</variablelist>
+
+</para>
+
+<para>The abbreviated classes can be put inside a custom class, for
+example to match a word character, a blank or a dot, you could write
+<userinput>[\w \.]</userinput></para> 
+
+<note> <para>The POSIX notation of classes, <userinput>[:&lt;class
+name&gt;:]</userinput> is currently not supported.</para> </note>
+
+<sect3>
+<title>Characters with special meanings inside character classes</title>
+
+<para>The following characters has a special meaning inside the
+<quote>[]</quote> character class construct, and must be escaped to be
+literally included in a class:</para>
+
+<variablelist>
+<varlistentry>
+<term><userinput>]</userinput></term>
+<listitem><para>Ends the character class. Must be escaped unless it is the very first character in the
+class (may follow an unescaped caret)</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput>^</userinput> (caret)</term>
+<listitem><para>Denotes a negative class, if it is the first character. Must be escaped to match literally if it is the first character in the class.</para></listitem> 
+</varlistentry>
+<varlistentry>
+<term><userinput>-</userinput> (dash)</term>
+<listitem><para>Denotes a logical range. Must always be escaped within a character class.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput>\</userinput> (backslash)</term>
+<listitem><para>The escape character. Must always be escaped.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+
+<title>Alternatives: matching <quote>one of</quote></title>
+
+<para>If you want to match one of a set of alternative patterns, you
+can separate those with <literal>|</literal> (vertical bar character).</para>
+
+<para>For example to find either <quote>John</quote> or <quote>Harry</quote> you would use an expression <userinput>John|Harry</userinput>.</para>
+
+</sect2>
+
+<sect2>
+
+<title>Sub Patterns</title>
+
+<para><emphasis>Sub patterns</emphasis> are patterns enclosed in
+parentheses, and they have several uses in the world of regular
+expressions.</para>
+
+<sect3>
+
+<title>Specifying alternatives</title>
+
+<para>You may use a sub pattern to group a set of alternatives within
+a larger pattern. The alternatives are separated by the character
+<quote>|</quote> (vertical bar).</para>
+
+<para>For example to match either of the words <quote>int</quote>,
+<quote>float</quote> or <quote>double</quote>, you could use the
+pattern <userinput>int|float|double</userinput>. If you only want to
+find one if it is followed by some whitespace and then some letters,
+put the alternatives inside a subpattern:
+<userinput>(int|float|double)\s+\w+</userinput>.</para>
+
+</sect3>
+
+<sect3>
+
+<title>Capturing matching text (back references)</title>
+
+<para>If you want to use a back reference, use a sub pattern to have
+the desired part of the pattern remembered.</para>
+
+<para>For example, it you want to find two occurrences of the same
+word separated by a comma and possibly some whitespace, you could
+write <userinput>(\w+),\s*\1</userinput>. The sub pattern
+<literal>\w+</literal> would find a chunk of word characters, and the
+entire expression would match if those were followed by a comma, 0 or
+more whitespace and then an equal chunk of word characters.  (The
+string <literal>\1</literal> references <emphasis>the first sub pattern
+enclosed in parentheses</emphasis>)</para>
+
+<!-- <para>See also <link linkend="backreferences">Back references</link>.</para> -->
+
+</sect3>
+
+<sect3 id="lookahead-assertions">
+<title>Lookahead Assertions</title>
+
+<para>A lookahead assertion is a sub pattern, starting with either
+<literal>?=</literal> or <literal>?!</literal>.</para>
+
+<para>For example to match the literal string <quote>Bill</quote> but
+only if not followed by <quote> Gates</quote>, you could use this
+expression: <userinput>Bill(?! Gates)</userinput>.  (This would find
+<quote>Bill Clinton</quote> as well as <quote>Billy the kid</quote>,
+but silently ignore the other matches.)</para>
+
+<para>Sub patterns used for assertions are not captured.</para>
+
+<para>See also <link linkend="assertions">Assertions</link></para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="special-characters-in-patterns">
+<title>Characters with a special meaning inside patterns</title>
+
+<para>The following characters have meaning inside a pattern, and
+must be escaped if you want to literally match them:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>\</userinput> (backslash)</term>
+<listitem><para>The escape character.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>^</userinput> (caret)</term>
+<listitem><para>Asserts the beginning of the string.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>$</userinput></term>
+<listitem><para>Asserts the end of string.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>()</userinput> (left and right parentheses)</term>
+<listitem><para>Denotes sub patterns.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>{}</userinput> (left and right curly braces)</term>
+<listitem><para>Denotes numeric quantifiers.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>[]</userinput> (left and right square brackets)</term>
+<listitem><para>Denotes character classes.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>|</userinput> (vertical bar)</term>
+<listitem><para>logical OR. Separates alternatives.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>+</userinput> (plus sign)</term>
+<listitem><para>Quantifier, 1 or more.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>*</userinput> (asterisk)</term>
+<listitem><para>Quantifier, 0 or more.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>?</userinput> (question mark)</term>
+<listitem><para>An optional character. Can be interpreted as a quantifier, 0 or 1.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="quantifiers">
+<title>Quantifiers</title>
+
+<para><emphasis>Quantifiers</emphasis> allows a regular expression to
+match a specified number or range of numbers of either a character,
+character class or sub pattern.</para>
+
+<para>Quantifiers are enclosed in curly brackets (<literal>{</literal>
+and <literal>}</literal>) and have the general form
+<literal>{[minimum-occurrences][,[maximum-occurrences]]}</literal>
+</para>
+
+<para>The usage is best explained by example:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>{1}</userinput></term>
+<listitem><para>Exactly 1 occurrence</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>{0,1}</userinput></term>
+<listitem><para>Zero or 1 occurrences</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>{,1}</userinput></term>
+<listitem><para>The same, with less work;)</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>{5,10}</userinput></term>
+<listitem><para>At least 5 but maximum 10 occurrences.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>{5,}</userinput></term>
+<listitem><para>At least 5 occurrences, no maximum.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Additionally, there are some abbreviations:
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>*</userinput> (asterisk)</term>
+<listitem><para>similar to <literal>{0,}</literal>, find any number of occurrences.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>+</userinput> (plus sign)</term>
+<listitem><para>similar to <literal>{1,}</literal>, at least 1 occurrence.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>?</userinput> (question mark)</term>
+<listitem><para>similar to <literal>{0,1}</literal>, zero or 1 occurrence.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+<sect2>
+
+<title>Greed</title>
+
+<para>When using quantifiers with no maximum, regular expressions
+defaults to match as much of the searched string as possible, commonly
+known as <emphasis>greedy</emphasis> behavior.</para>
+
+<para>Modern regular expression software provides the means of
+<quote>turning off greediness</quote>, though in a graphical
+environment it is up to the interface to provide you with access to
+this feature. For example a search dialog providing a regular
+expression search could have a check box labeled <quote>Minimal
+matching</quote> as well as it ought to indicate if greediness is the
+default behavior.</para>
+
+</sect2>
+
+<sect2>
+<title>In context examples</title>
+
+<para>Here are a few examples of using quantifiers</para>
+
+<variablelist>
+
+<varlistentry>
+<term><userinput>^\d{4,5}\s</userinput></term>
+<listitem><para>Matches the digits in <quote>1234 go</quote> and <quote>12345 now</quote>, but neither in <quote>567 eleven</quote>
+nor in <quote>223459 somewhere</quote></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\s+</userinput></term>
+<listitem><para>Matches one or more whitespace characters</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>(bla){1,}</userinput></term>
+<listitem><para>Matches all of <quote>blablabla</quote> and the <quote>bla</quote> in <quote>blackbird</quote> or <quote>tabla</quote></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>/?&gt;</userinput></term>
+<listitem><para>Matches <quote>/&gt;</quote> in <quote>&lt;closeditem/&gt;</quote> as well as
+<quote>&gt;</quote> in <quote>&lt;openitem&gt;</quote>.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="assertions">
+<title>Assertions</title>
+
+<para><emphasis>Assertions</emphasis> allows a regular expression to
+match only under certain controlled conditions.</para>
+
+<para>An assertion does not need a character to match, it rather
+investigates the surroundings of a possible match before acknowledging
+it. For example the <emphasis>word boundary</emphasis> assertion does
+not try to find a non word character opposite a word one at its
+position, instead it makes sure that there is not a word
+character. This means that the assertion can match where there is no
+character, &ie; at the ends of a searched string.</para>
+
+<para>Some assertions actually does have a pattern to match, but the
+part of the string matching that will not be a part of the result of
+the match of the full expression.</para>
+
+<para>Regular Expressions as documented here supports the following
+assertions:
+
+<variablelist>
+
+<varlistentry> 
+<term><userinput>^</userinput> (caret: beginning of
+string)</term> 
+<listitem><para>Matches the beginning of the searched
+string.</para> <para>The expression <userinput>^Peter</userinput> will
+match at <quote>Peter</quote> in the string <quote>Peter, hey!</quote>
+but not in <quote>Hey, Peter!</quote> </para> </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>$</userinput> (end of string)</term>
+<listitem><para>Matches the end of the searched string.</para>
+
+<para>The expression <userinput>you\?$</userinput> will match at the
+last you in the string <quote>You didn't do that, did you?</quote> but
+nowhere in <quote>You didn't do that, right?</quote></para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\b</userinput> (word boundary)</term>
+<listitem><para>Matches if there is a word character at one side and not a word character at the
+other.</para>
+<para>This is useful to find word ends, for example both ends to find
+a whole word. The expression <userinput>\bin\b</userinput> will match
+at the separate <quote>in</quote> in the string <quote>He came in
+through the window</quote>, but not at the <quote>in</quote> in
+<quote>window</quote>.</para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term><userinput>\B</userinput> (non word boundary)</term>
+<listitem><para>Matches wherever <quote>\b</quote> does not.</para>
+<para>That means that it will match for example within words: The expression
+<userinput>\Bin\B</userinput> will match at in <quote>window</quote> but not in <quote>integer</quote> or <quote>I'm in love</quote>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>(?=PATTERN)</userinput> (Positive lookahead)</term>
+<listitem><para>A lookahead assertion looks at the part of the string following a possible match.
+The positive lookahead will prevent the string from matching if the text following the possible match
+does not match the <emphasis>PATTERN</emphasis> of the assertion, but the text matched by that will
+not be included in the result.</para>
+<para>The expression <userinput>handy(?=\w)</userinput> will match at <quote>handy</quote> in
+<quote>handyman</quote> but not in <quote>That came in handy!</quote></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><userinput>(?!PATTERN)</userinput> (Negative lookahead)</term>
+
+<listitem><para>The negative lookahead prevents a possible match to be
+acknowledged if the following part of the searched string does match
+its <emphasis>PATTERN</emphasis>.</para>
+<para>The expression <userinput>const \w+\b(?!\s*&amp;)</userinput>
+will match at <quote>const char</quote> in the string <quote>const
+char* foo</quote> while it can not match <quote>const QString</quote>
+in <quote>const QString&amp; bar</quote> because the
+<quote>&amp;</quote> matches the negative lookahead assertion
+pattern.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+</sect1>
+
+<!-- TODO sect1 id="backreferences">
+
+<title>Back References</title>
+
+<para></para>
+
+</sect1 -->
+
+</appendix>
diff --git a/doc/kate/unhighlighted.png b/doc/kate/unhighlighted.png
new file mode 100644
index 000000000..6361032f3
--- /dev/null
+++ b/doc/kate/unhighlighted.png