Difference between revisions of "KDE System Administration/Configuration Files"

Jump to: navigation, search
m (Text replace - "</code>" to "</syntaxhighlight>")
(Replaced content with "{{Moved To Userbase}}")
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|KDE System Administration/Configuration Files}}
+
{{Moved To Userbase}}
== File Format ==
+
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.
+
 
+
==== Example: A Simple Config File ====
+
The following example shows a configuration file that consists of two groups.
+
The first group contains the keys "<tt>LargeCursor</tt>" and
+
"<tt>SingleClick</tt>", the second group contains the keys
+
"<tt>Show hidden files</tt>" and "<tt>Sort by</tt>".
+
<syntaxhighlight lang="ini">
+
[KDE]
+
LargeCursor=false
+
SingleClick=true
+
 
+
[KFileDialog Settings]
+
Show hidden files=false
+
Sort by=Name
+
</syntaxhighlight>
+
 
+
Entries in a group consists of a key and value separated by an equal sign.
+
The key can contain spaces and may be followed by options placed in
+
square brackets.
+
 
+
The part after the equal sign is the value of the entry. Any white space
+
surrounding the equal sign is ignored, as is any trailing white space.
+
 
+
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 the complete list:
+
 
+
* "<tt>\s</tt>" can be used as space
+
* "<tt>\t</tt>" can be used to include a tab
+
* "<tt>\r</tt>" for a carriage return character
+
* "<tt>\n</tt>" for a linefeed character (new line)
+
* "<tt>\\</tt>" to include the backslash itself
+
 
+
==== Example: Whitespace ====
+
The following config file fragment is equivalent to the one in the
+
previous example. Whitespace surrounding the key and value is ignored.
+
<syntaxhighlight lang="ini">
+
[KDE]
+
LargeCursor=          false
+
SingleClick = true
+
 
+
[KFileDialog Settings]
+
  Show hidden files  = false
+
Sort by =Name
+
</syntaxhighlight>
+
 
+
==== Example: Preserving Whitespace ====
+
In the following example the value of the "<tt>Caption</tt>" entry starts
+
with two spaces while the "<tt>Description</tt>" entry contains three lines
+
of text. Linefeeds in backslash notation are used to separate the different lines.
+
<syntaxhighlight lang="ini">
+
[Preview Image]
+
Caption=\s My Caption
+
Description=This is\na very long\ndescription.
+
</syntaxhighlight>
+
 
+
Empty lines in configuration files are ignored, just as lines that
+
start with a hash mark '#'. The hash mark can be used to add comments to
+
configuration files but it should be noted that when a KDE application
+
updates a configuration file the comments are not
+
preserved.
+
 
+
== Configuration ==
+
There can be multiple configuration files with the same name in the
+
share/config sub-directory of the various
+
[[../KDE Filesystem Hierarchy#Location_of_the_Directory_Trees|KDE Directory Trees]].
+
In that 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.
+
 
+
KDE's cascading configuration scheme can be used to provide users with
+
system or organisation-wide default settings while still allowing the users
+
to make individual changes to these settings. KDE will not write entries to
+
the user's configuration file under $KDEHOME that match any default settings
+
provided this way. This way changes made to the default settings will
+
immediately be propagated to the user. Note that differs from the traditional
+
way of providing default settings for users through the use of {{path|/etc/skel}},
+
changes to {{path|/etc/skel}} will only be propagated when creating a new user account.
+
 
+
When it is undesirable that individual users can make changes to default
+
settings, the default setting can be locked down.
+
 
+
== Shell Expansion ==
+
 
+
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 <tt>[$e]</tt>. Normally the expanded form is written into the users
+
configuration file after first use. To prevent that, it is recommend to lock
+
the configuration entry down by using <tt>[$ie]</tt>.
+
 
+
==== Example: Dynamic Entries ====
+
In the following example the value for the "<tt>Host</tt>" entry
+
is determined by the output of the ''hostname'' program. This setting is
+
also locked down to ensure that the value is always determined dynamically.
+
 
+
The value for the "<tt>Email</tt>" entry is determined by filling in
+
the values of the $USER and $HOST environment variables. When ''joe''
+
is logged in on ''joes_host'' this will result in a value equal to
+
"<tt>joe@joes_host</tt>". The setting is not locked down.
+
 
+
<syntaxhighlight lang="ini">
+
[Mail Settings]
+
Host[$ie]=$(hostname)
+
Email[$e]=${USER}@${HOST}
+
</syntaxhighlight>
+
 
+
== Localization ==
+
 
+
All 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.
+
 
+
==== Example: UTF-8 In Keys ====
+
In the following example the value of the "<tt>Caption</tt>" entry
+
depends on the language. If the user has selected french as language (language
+
code <tt>fr</tt>) the value of the entry will be "<tt>Ma Légende</tt>".
+
In all other cases the value "<tt>My Caption</tt>" will be used.
+
<syntaxhighlight lang="ini">
+
[Preview Image]
+
Caption=My Caption
+
Caption[fr]=Ma Légende
+
</syntaxhighlight>
+
 
+
== Lock Down ==
+
 
+
To prevent users from overriding default settings, you can lock
+
these settings down in the system-wide config files. Settings can be locked down individually, per group,
+
or per file. An individual entry can be locked down by adding <tt>[$i]</tt>
+
behind the key. A group of entries can be locked down by placing
+
<tt>[$i]</tt> behind the group name. To lock down the entire file, start
+
the file with <tt>[$i]</tt> on a single line.
+
 
+
==== Example: Using [$i] ====
+
In the following example the "<tt>Caption</tt>" entry has been locked
+
down. All entries in the "<tt>Mail Settings</tt>" group have been
+
locked down as well.
+
<syntaxhighlight lang="text">
+
[Preview Image]
+
Caption[$i]=My Caption
+
 
+
[Mail Settings][$i]
+
Host[$e]=$(hostname)
+
Email=wal&#100;o&#x40;&#00107;&#x64;e&#x2e;or&#x67;
+
</syntaxhighlight>
+
 
+
If an entry has been locked down, entries that would otherwise take
+
precedence over the default setting will now be ignored.
+
 
+
Any changes that applications make to settings that have been locked
+
down will be silently dropped. Applications may respond differently to locked down settings. Some applications
+
recognize when a setting has been locked down and will remove the
+
elements from its user interface. Other applications will continue
+
to offer these options in their user interface even though the option
+
does not have any effect any more. It is also possible that it is actually
+
still possible to change the setting in the running program. In that case the
+
changed setting will be effective for the time the program remains running.
+
When the program is restarted it will then return to the locked-down default
+
settings.
+
 
+
== Editors ==
+
If you do not want to use a text editor then
+
[http://extragear.kde.org/apps/kconfigeditor/ KConfigEditor]
+
offers a convenient way to edit KDE configuration files.
+
 
+
For scripts or modifying files from the command line, the command line app <tt>kwriteconfig</tt> is very useful. <tt>kwriteconfig</tt> expects a configuration file name, a group, a key, an optional type and a value, such as:
+
 
+
<syntaxhighlight lang="text">kwriteconfig --file kickerrc \
+
            --group General \
+
            --key AutoHidePanel \
+
            --type bool \
+
            true</syntaxhighlight>
+

Latest revision as of 13:19, 11 March 2016

This page is now on the Userbase wiki.


This page was last modified on 11 March 2016, at 13:19. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2 unless otherwise noted.