KDE uses a simple
text-based file format for all its configuration files. It consists of
key-value pairs that are placed in groups. All KDE configuration
files use UTF-8 encoding for text outside the
ASCII range.
The start of a group is indicated by a group name that is placed
in square brackets. All the key-value entries that follow belong to
the group. The group ends when either another group starts or when the
end of the file is reached. Entries at the top of the
file that are not preceded by a group name belong to the default
group.
Entries in a group consist of a key and value separated by an equals
sign. The key can contain spaces and may be followed by options placed in
square brackets. The part after the equals sign is the value of the
entry. Any white space surrounding the equals sign is ignored, as is any
trailing white space. Put more concisely, the format is:
entry
=
value
If a value is supposed to include a space at the begin or end
then this can be achieved by using a backslash followed by an
“s”.
There are several other backslash codes; here is a complete
list:
-
\s can be used as space
-
\t can be used to include a tab
-
\r for a carriage return character
-
\n for a linefeed character (new line)
-
\\ to include the backslash itself
Empty lines in configuration files are ignored, as are lines that
start with a hash mark (“#”). The hash mark can be used to add
comments to configuration files. It should be noted that when a KDE
application updates a configuration file the comments are
not
preserved.
There can be multiple configuration files with the same name in the
share/config sub-directory of the
various KDE directory trees. In this case the information of all these
configuration files is combined on a key-by-key basis. If the same key
within a certain group is defined in more than one place, the key value read
from the directory tree with the highest precedence will be used.
Configuration files under $
KDEHOME
always have the highest
precedence. If a key in a certain group is defined multiple times in a
single file, the value of the last entry is used.
To prevent users being able to override default settings,
settings can be marked immutable. Settings can be made immutable
individually, per group or per file. An individual entry can be locked
down by adding
[$i]
behind the key, e.g.:
Color[$i]=blue
A group of entries can be locked down by placing
[$i]
behind the group name, e.g.:
[MyGroup][$i]
To lock down the entire file, start the file with
[$i]
on a single line, i.e.:
[$i]
So-called “Shell Expansion” can be used to provide more
dynamic default values. With shell expansion the value of a configuration
key can be constructed from the value of an environment variable or from the
output of a shell command. To enable shell expansion for a configuration
entry, the key must be followed by [$e]. Normally the
expanded form is written into the user's configuration file after first use.
To prevent that, it is recommend to lock the configuration entry down by
using [$ie]. The user can't change it then of course.
Most configuration entries can be indexed with a language code. In
this case, the language that the user has selected for use on the desktop is
used to look up the key value. If the default language (American English)
has been selected or if there is no index that corresponds to the selected
language, the key entry without index is used.
In general the entries that can appear in a configuration file are not
documented. With KDE 3.2 a start has been made to change this. In
$
KDEDIR
/share/config.kcfg, files
can be found that provide a formal description of the possible entries in a
configuration file. These are used by the new KDE Configuration Editor
when available.
