&Anders.Lund; &Anders.Lund.mail;

# Configuring &kate;

## Overview

&kate; offers several means of tweaking the application to behave as desired. The most important ones are:

The Configuration Dialog

  The main configuration tool, allowing you to configure the &kate; application, the editor component and the usage of plugins.

The Settings Menu

  Allows you to change often used settings, and to launch the configuration dialogs.

The View Menu

  Allows you to split the current frame, as well as to display the icons and line numbers pane for the currently edited document.

The embedded terminal is using the configuration defined in the &systemsettings;, and may be configured by clicking the right mouse button to display a context menu.

## The Main Configuration Dialog

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 configuration is divided into two groups, namely

- Application configuration

- Editor component configuration

## The &kate; Application Configuration

This group contains pages to configure the main &kate; application

### General

This section contains a few global options for &kate;

Behavior
  Warn about files modified by foreign processes

    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.

    If not enabled, &kate; will prompt you for action when a externally modified file receives focus within the application.

Meta Information
  Keep meta-information past sessions

    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.

  Delete unused meta information after

    Set the maximum number of days to keep meta information for unopen files. This helps keeping the database of meta information reasonably sized.

Default text-editing component

  Select the text-editing component used by &kate;. By default, it is configured to use the system default text-editing component as configured in &systemsettings;.

### Sessions

This section contains options related to using sessions.

Elements of Sessions
  Include window configuration

    If enabled, &kate; will save the window configuration with each session.

Behavior on Application Startup

  Select how you want &kate; to behave at startup. This setting can be overridden by specifying what to do on the command line.

  Start new session

    With this option, &kate; will start a new, unnamed session when you start it.

  Load last-used session

    &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.

  Manually choose a session

    &kate; will display a small dialog that lets you choose your preferred session, or load the default session if none have been saved. This is the default behavior. Nice if you use a lot of different sessions frequently.

The changes to the session data (opened files and if enabled, window configuration) will always be saved.

### Tree View

Background Shading

  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 The Document List for more about this feature.

Sort By

  Set how you want the document list sorted. This can be set from the &RMB; menu in the document list as well.

Show Full Path

  When enabled, in tree mode, top level folders will show up with their full path rather than just the last folder name.

### Plugins

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.

If a plug-in provides configuration options, a section to access those will appear as a child of this page.

### Terminal

This page is only displayed by the Terminal Tool View plugin, which is enabled by default.

Automatically synchronize the terminal with the current document when possible

  This will cause the built-in terminal to `cd` 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 terminal on your own.

Set EDITOR environment variable to 'kate -b'

  This sets the `EDITOR` environment variable so programs run in the built-in terminal that automatically open a file in an editor will open them in &kate; instead of the default editor configured in your shell. You will not be able to continue using the terminal until you have closed the file in &kate;, so the calling program is aware you have finished editing the file.

&configuring-part-sections;

## Configuring With Document Variables

&kappname; variables is katepart's implementation of document variables, similar to emacs and vi modelines. In katepart, the lines have the following format:

`kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]`

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.

Here is an example variable line, forcing indentation settings for a C++, java or javascript file:

    // kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;

Only the first and last 10 lines are searched for variable lines.

Additionally, document variables can be placed in a file called `.kateconfig` in any directory, and the configured settings will be applied as if the modelines were entered on every file in the directory and its subdirectories, as far down as the configured search depth. Document variables in `.kateconfig` use the same syntax as in modelines.

There are variables to support almost all configurations in katepart, and additionally plugins can use variables, in which case it should be documented in the plugin's documentation.

### How &kappname; uses Variables

When reading configuration, katepart looks in the following places (in that order):

- The global configuration.

- Optional session data.

- The "Filetype" configuration.

- Document variables in `.kateconfig`.

- Document variables in the document itself.

- Settings made during editing from menu or command line.

As you see, document variables are only overriden by changes made at runtime. Whenever a document is saved, the document variables are reread, and will overwrite changes made using menu items or the command line.

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.

The variables listed here documents &kappname; version 3.7. More variables may be added in the future. There are 3 possible types of values for variables, with the following valid expressions:

- BOOL - on|off|true|false|1|0

- INTEGER - any integer number

- STRING - anything else

### Available Variables

    auto-bracketsBOOL

  Set auto insertion of brackets on or off.

    auto-center-linesINT

  Set the number of autocenter lines.

    auto-insert-doxygenBOOL

  Turn insertion of the leading asterisk in doxygen comments on or off. This has no effect unless you use the C-style auto-indenter.

    background-colorSTRING

  Set the document background color. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    backspace-indentsBOOL

  Enable or disable unindenting when &Backspace; is pressed.

    block-selectionBOOL

  Turn block selection on or off.

    bom | byte-order-markerBOOL

  Enable/disable the byte order marker when saving files in unicode format (utf8, utf16, utf32).

  Since: Kate 3.4 (KDE 4.4)

    bracket-highlight-colorSTRING

  Set the color for the bracket highlight. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    current-line-colorSTRING

  Set the color for the current line. The value must be something that can be evaluated to a valid color, for example `#ff0000`

    default-dictionarySTRING

  Sets the default dictionary used for spell checking.

  Since: Kate 3.4 (KDE 4.4)

    dynamic-word-wrapBOOL

  Turns dynamic word wrap on or off.

    eol | end-of-lineSTRING

  Set the end of line mode. Valid settings are `unix`, `mac` and `dos`

    folding-markersBOOL

  Set the display of folding markers on or off.

    font-sizeINT

  Set the point size of the document font.

    fontSTRING

  Set the font of the document. The value should be a valid font name, for example `courier`.

    hl | syntaxSTRING

  Set the syntax highlighting. Valid strings are all the names available in the menus. For instance, for C++ simply write `C++`.

    icon-bar-colorSTRING

  Set the icon bar color. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    icon-borderBOOL

  Set the display of the icon border on or off.

    indent-modeSTRING

  Set the auto-indentation mode. The options `none`, `normal`, `cstyle`, `haskell`, `lilypond`, `lisp`, `python`, `ruby` and `xml` are recognized. See the section for details.

    indent-widthINT

  Set the indentation width.

    keep-extra-spacesBOOL

  Set whether to keep extra spaces when calculating indentation width.

    line-numbersBOOL

  Set the display of line numbers on or off.

    mixed-indentBOOL

  Set mixed indentation ala Emacs on or off.

  Note: Deprecated since Kate 3 in KDE4. This variable is ignored, set `replace-tabs on;` instead for the future.

    overwrite-modeBOOL

  Set overwrite mode on or off.

    persistent-selectionBOOL

  Set persistent selection on or off.

    remove-trailing-spaceBOOL

  Set dynamic end of line cleanup on or off.

    replace-tabs-saveBOOL

  Set tab to space conversion on save on or off.

    replace-tabsBOOL

  Set dynamic tab to space conversion on or off.

    replace-trailing-space-saveBOOL

  Set end of line cleanup on save on or off.

    schemeSTRING

  Set the color scheme. The string must be the name of a color scheme that exists in your configuration to have any effect.

    selection-colorSTRING

  Set the selection color. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    show-tabsBOOL

  Set the visual tab character on or off.

    smart-homeBOOL

  Set smart home navigation on or off.

    space-indentBOOL

  Set indentation with spaces on or off.

  Note: Deprecated since Kate 3 in KDE4. Mixed indentation is the default behavior. Set `replace-tabs on;` to achieve space-only indentation.

    tab-indentsBOOL

  Set &Tab; key indentation on or off.

    tab-widthINT

  Set the tab character display width.

    undo-stepsINT

  Set the number of undo steps to remember.

  Note: Deprecated since Kate 3 in KDE4. This variable is ignored. The maximal count of undo steps is unlimited.

    word-wrap-columnINT

  Set the static word wrap width.

    word-wrap-marker-colorSTRING

  Set the word wrap marker color. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    word-wrapBOOL

  Set static word wrapping on or off.

    wrap-cursorBOOL

  Set cursor wrapping on or off.