<chapter id="configuring-kate">
<title>Configuring &kate;</title>

<sect1>
<title>Overview</title>
<para>
<anchor id="settings"/>
<anchor id="configure"/>
<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>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>The Settings Menu</term>
<listitem><para>Allows you to change often used settings, and to launch the configuration dialogs.</para></listitem>
</varlistentry>
<varlistentry>
<term>The View 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 Control Center, and may be
configured clicking the right mouse 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. The tree groups the pages of the dialog into logical
groups.</para>

<sect2 id="config-dialog">
<title>The &kate; group</title>
<para>This group contains pages to configure the main &kate; application</para>

<sect3 id="config-dialog-general">
<title>The General Page</title>
<para>Global options for &kate;</para>

<variablelist>
<varlistentry>
<term>Application Mode</term>
<listitem>
<para>This group lets you choose between &kate; <acronym>MDI</acronym> and
&kate; <acronym>SDI</acronym> mode, selecting the appropriate button.</para>
 <para>&kate; <acronym>MDI</acronym>
(Multiple Document Interface), which is the default mode, makes &kate; use a
single window for all open files. You can choose the document to edit from the
File List (docked into the &kate; window on the left by default) or by
selecting the document from the <guimenu>Document</guimenu> menu.</para>
<para>&kate; <acronym>SDI</acronym> (Single Document Interface) will make &kate; open each
document in a window of its own, and the File List/File Selector will have a
separate window.</para>
 <para>If you change this setting, you will need to
restart &kate; for it to take effect.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>At Startup</term> 
<listitem><para>These options determine how
and if &kate; will restore your editing session when launched anfer a
normal shutdown (if restored by the session manager, &kate; will
always attempt to restore your session as close as possible to what it
was when you last used &kate;).</para>

<variablelist>
<varlistentry>
<term>
<anchor id="config-dialog-general-reopen-files"/>
<guibutton>Reopen Files</guibutton></term>
<listitem><para>If this option is enabled, files open when you last
closed &kate; will be reopened. Bookmarks will be restored, and the
cursor position, icon border and line numbers settings for the last
editor used with the document will be reestablished</para></listitem> 
</varlistentry>
<varlistentry>
<term><guibutton>Restore View Configuration</guibutton></term>
<listitem><para>If this option is enabled, &kate; will attempt to restore your frames exactly as
you left them.</para></listitem>
</varlistentry>
</variablelist>

</listitem>

</varlistentry>

<varlistentry>
<term><guibutton>Restrict to single instance</guibutton></term>
<listitem><para>Enabling this means you can only have one running
instance of &kate; running at any given time. If you attempt to start
another one, the current instance will take over and also open files
as requested. For example, if you use &kate; for displaying sources
for web pages in Konqueror, they will all be opened in an existing
instance of &kate; if this option is enabled.</para></listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Show Contents While Resizing
Frames</guibutton></term> <listitem><para>If this option is enabled,
the windows will be fully repainted while dragging the frame
splitters. A nice way to use some extra <acronym>CPU</acronym> cycles
:). If unchecked, a so-called <quote>rubber band</quote> (indicating
the new size of the frame) will be used instead.</para></listitem>
</varlistentry>

<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><guibutton>Number of Recent Files</guibutton></term>
<listitem><para>Unsurprisingly, this allows you to decide how long the
<guimenu>Open Recent</guimenu> files menu should grow.</para></listitem>
</varlistentry>

</variablelist>
</sect3>


</sect2>

<sect2 id="config-dialog-editor">
<title>The Editor Group</title>
<para>This group contains all pages related to the editor component of
&kate;</para>

<sect3 id="config-dialog-editor-colors">
<title>The <guilabel>Colors</guilabel> Page</title> <para>This page allows you
to change the background and selection background colors of the editor.
Initially, &kate; will use the colors as set in the &kcontrolcenter;
<menuchoice><guimenu>Look'n'Feel</guimenu><guimenuitem>Colors</guimenuitem>
</menuchoice>
page.</para>

<para>To change a color, press the associated button and select
the desired color in the color chooser.</para>

<note><para>Choosing the background color may render Syntax
Highlighted text unreadable.  You should use a light color for the
background, and a dark color for the selection background.
</para>
<para>Otherwise, you will probably need to change the <link linkend="config-dialog-editor-highlight-default-styles">Default Styles</link>.</para>
</note>
</sect3>

<sect3 id="config-dialog-editor-fonts">
<title>The Fonts Page</title> <!-- FIXME LINKS //-->

<para>This page allows you to choose the default fonts for &kate;. The
settings will be used for the &kwrite; and for viewing text files in
&konqueror; as well.</para>

<para>The page presents two tabs, one for the editor font and one for
the printing font.  Select a tab and choose the desired font.  The
default is to use the &kde; global setting for fixed font.</para>

<tip><para>As it is not currently possible to use individual fonts for
documents, nor to change the font for printing from the print dialog,
be careful. A fixed-width font is strongly recommended.  </para></tip>
</sect3>

<sect3 id="config-dialog-editor-indent">
<title>The Indent Page</title>
<para>This page allows you to change the behavior of indentation.</para>

<variablelist>
<title>Indent Options</title>

<varlistentry>
<term>
<anchor id="config-dialog-editor-indent-auto-indent" />
<guibutton>Auto indent</guibutton>
</term>
<listitem>
<para>If checked, &kate; will automatically indent new lines equal to
the previous line.  If the previous line is blank, the nearest above
line with contents is used.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-indent-indent-with-spaces" />
<guibutton>Indent with Spaces</guibutton>
</term>
<listitem>
<para>If checked, &kate; will indent with spaces rather than tabs.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-indent-backspace-key-indents" />
<guibutton>Backspace key indents</guibutton>
</term>
<listitem>
<para>If this is checked, &kate; will unindent equal to the nearest
above line with contents when you press the <keycap>Backspace</keycap>
key if the part of the line preceding the cursor contains only
whitespace.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-indent-tab-key-indents" />
<guibutton>Tab key indents</guibutton>
</term>
<listitem>
<para>If this is checked, &kate; will indent the current line equal to
the nearest above line with content when you press the
<keycap>Tab</keycap> key, if the part of the line preceding the cursor
contains only whitespace.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-indent-keep-extra-spaces" />
<guibutton>Keep extra spaces</guibutton>
</term>
<listitem>
<para>With this behavior checked, &kate; will leave whitespace behind
the cursor after indenting.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="config-dialog-editor-select">
<title>The Select Page</title>

<para>This page provides options for fine tuning the select behavior
of &kate;</para>

<variablelist>
<title>Select Options</title>

<varlistentry>
<term>
<anchor id="config-dialog-editor-select-persistent-selections" />
<guibutton>Persistent Selections</guibutton>
</term>
<listitem>
<para>When Persistent Selections is enabled, key input will not cause
the selection to be removed/diminished.</para> 
<note><para>This option
partly conflicts with the Overwrite Selection option. If both are
enabled, pasting text or pressing any other keys than the arrow keys
will cause the selection to be overwritten.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-select-overwrite-selections" />
<guibutton>Overwrite Selection</guibutton>
</term>
<listitem>
<para>If this is enabled, any text insertion, whether typed or pasted will cause the selected
text to be deleted and replaced with the inserted text.</para>
</listitem>
</varlistentry>

<!-- NOTE this option has gone (anders)
<varlistentry>
<term>
<anchor id="config-dialog-editor-select-mouse-autocopy" />
<guibutton>Mouse Autocopy</guibutton>
</term>
<listitem>
<para>If enabled, any text selected by moving the mouse with the left button pressed will
be copied to the clipboard, ready for pasting.</para>
</listitem>
</varlistentry>
-->
</variablelist>

</sect3>

<sect3 id="config-dialog-editor-edit">
<title>The Edit Page</title>
<para>This page contains miscellaneous options for fine-tuning the behavior of the &kate;
editor component.</para>

<variablelist>
<title>Editor Options</title>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-word-wrap" />
<guibutton>Word Wrap</guibutton>
</term>
<listitem>
<para>Word Wrap as used here means dynamically format the text by breaking lines at an appropriate
place, rather than soft wrapping lines in the editor for easier reading.</para>
<para>If enabled, &kate; will insert a line break as defined by the <link linkend="document-end-of-line">End of Line</link>
setting for the document when the line extends the length set in
<link linkend="config-dialog-editor-edit-wrap-words-at">Wrap Words At</link> option described below.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-wrap-words-at" />
<guibutton>Wrap Words At</guibutton>
</term>
<listitem>
<para>This option decides the max length of lines if the
<link linkend="config-dialog-editor-edit-word-wrap">Word Wrap</link> option is enabled.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-replace-tabs-with-spaces" />
<guibutton>Replace Tabs with Spaces</guibutton>
</term>
<listitem>
<para>If enabled, &kate; will replace inserted <keycap>Tab</keycap>
characters with a number of single whitespace characters as defined in
<link linkend="config-dialog-editor-edit-tab-indent-width">Tab
Width</link>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-remove-trailing-spaces" />
<guibutton>Remove trailing spaces</guibutton>
</term>
<listitem>
<para>If enabled, &kate; will remove any whitespace at the rear end of
a line each time the cursor is moved off that line.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-tab-indent-width" />
<guibutton>Tab/Indent Width</guibutton>
</term>
<listitem>
<para>Sets the tab width, which is also used to decide the amount of indentation when
<link linkend="config-dialog-editor-indent-auto-indent">Auto Indent</link> is enabled, or
indentation is otherwise called for.</para>
<para>Depending on the <link linkend="config-dialog-editor-indent">Indent</link> settings indentation may be caused
by pressing the <keycap>Tab</keycap> and <keycap>Backspace</keycap> keys, and activating the
<link linkend="edit-indent"><guimenu>Edit</guimenu> <guimenuitem>Indent</guimenuitem></link>
menu entry will call for indent as well.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-auto-brackets" />
<guibutton>Auto Brackets</guibutton>
</term>
<listitem>
<para>If this is enabled, &kate; will automatically insert a right bracket immediately to the
right of the cursor when a left bracket is inserted from the keyboard. The supported bracket types
are <keycap>(</keycap>, <keycap>{</keycap>, <keycap>[</keycap>and <keycap>&lt;</keycap></para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-group-undos" />
<guibutton>Group undos</guibutton>
</term>
<listitem>
<para>If enabled, &kate; will group any number of similar editing
actions (for example typing, backspacing, pasting) in one entry in the
undo history, so they can all be undone at once.</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-show-tabs" />
<guibutton>Show Tabs</guibutton>
</term>
<listitem>
<para>If enabled, &kate; will draw a small dot at the start of a
<keycap>Tab</keycap> character in the editor to indicate its
presence.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-smart-home" />
<guibutton>Smart Home</guibutton>
</term>
<listitem>
<para>This will make &kate; move the cursor to the first
non-whitespace character of the current line rather than to the
absolute beginning, when the <keycap>Home</keycap> key (or other key
assigned to that function) is pressed.</para>
</listitem>
</varlistentry>

<!-- NOTE This option has gone (anders)
<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-page-up-down-moves-cursor" />
<guibutton>Page Up/Down moves cursor</guibutton>
</term>
<listitem>
<para>If enabled, the cursor will be moved to the first/last visible
line when <keycap>Page Up</keycap>/<keycap>Page Down</keycap> (or
other key assigned to those functions) is pressed, rather than being
kept at its relative position.</para>
</listitem>
</varlistentry>
-->
<varlistentry>
<term>
<anchor id="config-dialog-editor-edit-wrap-cursor" />
<guibutton>Wrap Cursor</guibutton>
</term>
<listitem>
<para>If enabled, moving the cursor past the end of a line will cause
it to continue to the next/previous line if any.</para>
<para>If not enabled, the cursor cannot be moved right of the
beginning of the line, but it may be moved past the end of line, and
when text is inserted &kate; will automatically insert whitespace up
to that position. This is sometimes very handy for programmers, for
example.</para> 
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="config-dialog-editor-keyboard">
<title>The Keyboard Page</title>

<para>Here you can configure the keyboard shortcuts for the internal
commands of the &kate; editor component. These includes commands for
moving around in the document and selecting text. For keys related to
copying and pasting text, see <!-- link linkend="" -->The Configure
Keys Dialog<!-- /link --></para>

<para>You may change the keys for a command, or add an alternate
key.</para>

<procedure>
<title>To change the key(s) for a command, follow this procedure:</title>
<step>
<para>Select the command for which you want to configure the keys.</para>
</step>
<step>
<para>Choose the <guibutton>None</guibutton> option in the pane below the list if you don't want a
key for this command.</para>
<para>Choose the <guibutton>Default</guibutton> option to use the default key(s) for the
command</para>
<para>Choose the <guibutton>Custom</guibutton> option to select a custom key for the command,
or set an alternate one.</para>
</step>
<step>
<para>If you choose the <guibutton>Custom</guibutton> option, the key
entering button at the right of the pane will be enabled. To set a
key, press it. The &kde; Define Shortcut Dialog will appear. In this
dialog:</para>
</step>
<step>
<procedure>
<step>
<para>Choose whether to set the default or alternate
key. <guilabel>Default</guilabel> does not mean that you change the
application default for this action, rather it sets the custom
standard key for it.</para>
</step>
<step>
<para>Press the desired key sequence, it will be visualized for you in
the dialog for your confirmation. </para>

<para>If you are of an adventurous nature, try playing around with the
<guibutton>Multikey</guibutton> option. Using it will allow you to
have &Emacs;-like key sequences (one key enters a group, the next
performs the action), apart from the fact that instead of just doing
the job, &kde; will pop up a menu to choose from in an undefined and
most likely inappropriate place. You will now be in no doubt as to
whether pressing the next key in the sequence will work, or you have
to type the menu accelerator (both will work).</para>
</step>
</procedure>
</step>
</procedure>
</sect3>

<sect3 id="config-dialog-editor-spelling">
<title>The Spelling Page</title>
<para>This page allows you to configure how &kspell; behaves with &kate;</para>
</sect3>

<sect3 id="config-dialog-editor-hl">
<title>The Highlighting Page</title>

<para>This page allows you to fine tune the color and syntax type selection of &kate;</para>
<para>
<mediaobject>
<imageobject><imagedata format="PNG" fileref="configdialog02.png" /></imageobject>
</mediaobject>
</para>
<para>For more in depth information on the syntax highlighting system, see ??</para>

<para>The page consists of two tabs, one for setting the
<guibutton>Default styles</guibutton> and one for managing the
<guibutton>Highlight Modes</guibutton>. Both tabs display a list of
contexts in which the default colors and font are used to visualize
the look of each style.  The context name is painted using the current
properties of the context.</para>

<para>The list has four or five columns, each with the following
purpose:</para>

<variablelist>

<varlistentry>
<term>Context</term>
<listitem><para>Displays the context name, painted using the style
properties for the context.</para></listitem>
</varlistentry>

<varlistentry>
<term>Bold</term>
<listitem><para>The state of this checkbox decides if the context should be
rendered using a boldface
font.</para></listitem>
</varlistentry>

<varlistentry>
<term>Italic</term>
<listitem><para>The state of this checkbox decides if the context should be rendered using italic
font.</para></listitem>
</varlistentry>

<varlistentry>
<term>Normal</term>
<listitem><para>This button displays the color for drawing the style in normal mode, when the text
is not selected that is. To change the color, click the button.</para></listitem>
</varlistentry>

<varlistentry>
<term>Selected</term>
<listitem><para>This button displays the color for drawing the style when the text
is selected. To change the color, click the button.</para></listitem>
</varlistentry>

<varlistentry>
<term>Using Default</term>
<listitem><para>This checkbox, only available in the
<guibutton>Highlight Modes</guibutton> tab shows if the style is using
its default values. It will automatically become unchecked if you
change any properties of the style. Check it to reset a style to using
defaults.</para></listitem> 
</varlistentry>

</variablelist>

<sect4 id="config-dialog-editor-highlight-default-styles">
<title>The Default Styles Tab</title>
<para>To change any of the default styles, set its properties as desired.</para>
</sect4>

<sect4 id="config-dialog-editor-highlight-highlight-modes">
<title>The Highlight Modes Tab</title> 

<para>Here you can change the most important properties of each
available highlight mode. First, use the
<guibutton>Highlight</guibutton> dropdown to choose a mode to work
on.</para> <para>Highlight modes are initially chosen based on the
&MIME; type and extension of the file. To change the list for the
current selection, edit the <guibutton>File Extensions</guibutton> and
<guibutton>Mime Types</guibutton> entries. Alternatively, press the
wizard button to the right of the <guibutton>Mime Types</guibutton>
entry. This will show a dialog displaying all available &MIME; types
to choose from. Using it will edit the &MIME; types as well as the
file extensions.</para>

<mediaobject>
<imageobject><imagedata format="PNG" fileref="mimetypechooser.png" /></imageobject>
</mediaobject>
<para>
The &MIME; type chooser dialog displays a tree of available &MIME; types, with
a description and the patterns for the &MIME; type. To include a &MIME; type,
check the box beside it.
</para>

<para>You can change the style properties of any context as described
above.</para> 

<para>At the bottom of the tab, below the highlight
properties, you see a button labeled
<guibutton>Download</guibutton>. Pressing it will attempt to connect
to the &kate; website and fetch a list of available syntax highlight
modes which you can update or add.</para>

</sect4>

</sect3>

</sect2>

<sect2 id="config-dialog-plugins">
<title>The Plugins Group</title> 

<para>This group contains pages related to plugins. Apart from the
Manager configuration page, some plugins provide individual
configuration options. For information on these, see the documentation
for the individual plugins.</para>

<sect3 id="config-dialog-plugins-manager">
<title>The Plugin Manager Page</title> 

<para>This page provides the means of loading/unloading plugins, and
minimal information about individual plugins.</para>

<para>To load an unloaded plugin, select it in the <guibutton>Available
Plugins</guibutton> pane and use the arrow buttons to move it to the
<guibutton>Loaded Plugins</guibutton> pane.</para>

<para>To unload a loaded plugin, select it in the <guibutton>Loaded
Plugins</guibutton> pane and use the arrow buttons to move it to the
<guibutton>Available buttons</guibutton> pane.</para>

<para>To view a minimal description and information about a plugin,
select it and the information will be available below the
lists.</para>
</sect3>

</sect2>

</sect1>

</chapter>