README kconf_update

Version: 1.0
Author: Waldo Bastian <bastian@kde.org>, <bastian@suse.com>

What it does
============

kconf_update is a tool designed to update config files. Over time applications
sometimes need to rearrange the way configuration options are stored. Since 
such an update shouldn't influence the configuration options that the user
has selected, the application must take care that the options stored in the
old way will still be honoured.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has 
several drawbacks:
* The application may need to read more configuration files than strictly
needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update 
configuration files without adding code to the application itself.


How it works
============

Applications can install so called "update files" under 
$KDEDIR/share/apps/kconf_update. An update file has ".upd" as extension and
contains instructions for transferring/converting configuration information 
from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are seperated into sections. Each section has an Id. When a 
section describing a configuration change has been applied, the Id will be 
stored in the file "kconf_updaterc". This information is used to make sure
that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a 
new section, only the update instructions from this extra section will be 
performed.

File format of the update file
==============================

Empty lines or lines that start with '#' are considered comments.
Commas (,) are used to seperate fields and may not occur as part 
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed from top to bottom. Each line can contain
one entry. The following entries are recognized:


Id=<id>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.


File=<oldfile>,<newfile>
File=<oldfile>

Specifies that configuration information is read from <oldfile> and written 
to <newfile>. If you only specify <oldfile>, the information is read from
as well as written to <oldfile>.

Script=<script>[,<interpreter>]

All entries from <oldfile> are piped into <script>. The output of script
is used as new entries for <newfile>. Existing entries can be deleted by 
adding lines with "# DELETE [group]key" in the output of the script. 
To delete a whole group use "# DELETEGROUP [group]".

If Script was issued after a "Group" command the behaviour is slightly
different:
All entries from <oldfile>/<oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile>/<newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script. 
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl".

Group=<oldgroup>,<newgroup>
Group=<oldgroup>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

RemoveGroup=<oldgroup>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

Options=<option1>, <option2>, ....

With this entry you can specify options that apply to the next 
"Key" or "AllKeys" entry (only to the first!). Possible options are:

- "copy" Copy the configuration item instead of moving it. This means that 
         the configuration item will not be deleted from <oldfile>/<oldgroup>.

- "overwrite" Normally, a configuration item is not moved if a item with the
         new name already exists. When this option is specified the old 
         configuration item will overwrite any existing item.


Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.


AllKeys

Specifies that all configuration information in the selected group should
be moved (All keys).

AllGroups

Specifies that all configuration information from all keys in ALL 
groups should be moved.


RemoveKey=<oldkey>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.


Example update file
===================

# This is comment
Id=kde2.2
File=kioslaverc,kio_httprc
Group=Proxy Settings
Key=NoProxyFor
Key=UseProxy
Key=httpProxy,Proxy
Group=Cache Settings,Cache
Key=MaxCacheSize
Key=UseCache
Group=UserAgent
AllKeys
RemoveGroup=KDE
# End of file


The above update file extracts config information from the file "kioslaverc" 
and stores it into the file "kio_httprc". 

It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group 
"Proxy Settings" in the "kioslaverc" file. If any of these options are present
they are written to the keys "NoProxyFor", "UseProxy" and "Proxy" (!) in
the group "Proxy Settings" in the "kio_httprc" file.

It also reads the keys "MaxCacheSize" and "UseCache" from the group 
"Cache Settings" in the "kioslaverc" file and writes this information to the
keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the 
"kio_httprc" file.

Then it takes all keys in the "UserAgent" group of the file "kioslaverc" 
and moves then to the "UserAgent" group in the "kio_httprc" file.

Finally it removes the entire "KDE" group in the kioslaverc file.

Have fun,
Waldo
