1 files changed, 248 insertions, 0 deletions
diff --git a/src/kconf_update/README.kconf_update b/src/kconf_update/README.kconf_update
new file mode 100644
index 00000000..281fb9e5
--- /dev/null
+++ b/src/kconf_update/README.kconf_update
@@ -0,0 +1,248 @@
+README kconf_update
+
+Version: 1.1
+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 honored.
+
+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 separated 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 and executed sequentially 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>. Note that if the file does not exist
+at the time kconf_update first checks, no related update will be performed
+(script won't be run at all, etc.).
+
+
+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]".
+
+<script> should be installed into $(kde_datadir)/kconf_update, or
+kconf_update will not be able to find it. It's also possible to install
+kconf_update applications in $(kde_bindir)/kconf_update_bin, which opens the
+door to kconf_update applications that are written in C++ and use Qt's
+powerful string API instead.
+
+If Script was issued after a "Group" command the behavior 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".
+
+It is also possible to have a Script without specifying <oldfile> or
+<newfile>. In that case the script is run but it will not be fed any input
+and its output will simply be discarded.
+
+ScriptArguments=<arguments>
+
+If specified, the arguments will be passed to <script>.
+IMPORTANT: It has to be specified before Script=.
+
+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.
+A group may be written either as "group" or as "[group]". The latter syntax
+makes it possible to specify subgroups: "[group][subgroup]".
+
+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 "Script",
+"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 an 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.
+
+
+Debugging and testing
+=====================
+
+If you are developing a kconf_update script and want to test or debug it you
+need to make sure kconf_update runs again after each of your changes. There
+are a number of ways to achieve this.
+
+The easiest is to not install the kconf_update script in the first place, but
+manually call it through a pipe. If you want to test the update script for
+your application KHello's config file khellorc, you can test by using
+
+    cat ~/.kde/share/config/khellorc | khello_conf_update.sh
+
+(assuming khello_conf_update.sh is the kconf_update script and ~/.kde is your
+$KDEHOME). This is easier than making install every time, but has the obvious
+downside that you need to 'parse' your script's output yourself instead of
+letting kconf_update do it and check the resulting output file.
+
+After 'make install' the kconf_update script is run by kded, but it does so
+only once. This is of course the idea behind it, but while developing it can
+be a problem. You can increase the revision number for each subsequent run
+of 'make install' to force a new kconf_update run, but there's a better
+approach that doesn't skyrocket the version number for a mediocre debug
+session.
+
+kded doesn't really ignore scripts that it has already run right away.
+Instead it checks the affected config file every time a .upd file is added
+or changed. The reason it still doesn't run again on your config file lies
+in the traces kconf_update leaves behind: it adds a special config group
+'[$Version]' with a key 'update_info'. This key lists all kconf_update
+scripts that have already been run on this config file. It also adds a group
+for the script to $KDEHOME/share/config/kconf_updaterc. Just remove your
+script entries from both your rcfile and kconf_updaterc, 'make install',
+and kconf_update will happily run your script again, without you having to
+increase the version number.
+
+If you want to know what kconf_update has been up to lately, have a look
+at $KDEHOME/share/apps/kconf_update/log/update.log
+
+
+Common Problems
+===============
+
+* kconf_update refuses to update an entry
+If you change the value of an entry without changing the key or file,
+make sure to tell kconf_update that it should overwrite the old entry
+by adding "Options=overwrite". 
+
+
+Have fun,
+Waldo