Diffstat (limited to 'tdeconf_update/README.tdeconf_update')
1 files changed, 251 insertions, 0 deletions
diff --git a/tdeconf_update/README.tdeconf_update b/tdeconf_update/README.tdeconf_update
new file mode 100644
@@ -0,0 +1,251 @@
+Author: Waldo Bastian <firstname.lastname@example.org>, <email@example.com>
+What it does
+tdeconf_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
+* 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.
+tdeconf_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
+$TDEDIR/share/apps/tdeconf_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 "tdeconf_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
+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:
+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.
+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>.
+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)/tdeconf_update, or
+tdeconf_update will not be able to find it. It is not portable to install
+binary applications in $kde_datadir, so you have to stick with interpreted
+scripts like sh or perl scripts. From KDE 3.2 onwards it's also possible
+to install tdeconf_update applications in $(kde_bindir)/tdeconf_update_bin,
+which opens the door to tdeconf_update applications that are written in C++
+and use Qt's powerful string API instead.
+A workaround for KDE 3.1.x and older is to install a .sh script in
+$(kde_datadir) that contains a simple exec:
+ exec "`tde-config --prefix`/bin/tdeconf_update_bin/my_update_app"
+This is equivalent to what KDE 3.2 can do directly, but of course the .upd
+file now points to the .sh script instead of the binary application.
+If Script was issued after a "Group" command the behavior is slightly
+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".
+Since KDE 3.3 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.
+If specified, the arguments will be passed to <script>.
+IMPORTANT: It has to be specified before Script=.
+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.
+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.
+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>.
+Specifies that all configuration information in the selected group should
+be moved (All keys).
+Specifies that all configuration information from all keys in ALL
+groups should be moved.
+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
+# End of file
+The above update file extracts config information from the file "tdeioslaverc"
+and stores it into the file "kio_httprc".
+It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group
+"Proxy Settings" in the "tdeioslaverc" 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 "tdeioslaverc" file and writes this information to the
+keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the
+Then it takes all keys in the "UserAgent" group of the file "tdeioslaverc"
+and moves then to the "UserAgent" group in the "kio_httprc" file.
+Finally it removes the entire "KDE" group in the tdeioslaverc file.
+Debugging and testing
+If you are developing a tdeconf_update script and want to test or debug it you
+need to make sure tdeconf_update runs again after each of your changes. There
+are a number of ways to achieve this.
+The easiest is to not install the tdeconf_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 ~/.trinity/share/config/khellorc | khello_conf_update.sh
+(assuming khello_conf_update.sh is the tdeconf_update script and ~/.trinity is your
+$TDEHOME). 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 tdeconf_update do it and check the resulting output file.
+After 'make install' the tdeconf_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 tdeconf_update run, but there's a better
+approach that doesn't skyrocket the version number for a mediocre debug
+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 tdeconf_update leaves behind: it adds a special config group
+'[$Version]' with a key 'update_info'. This key lists all tdeconf_update
+scripts that have already been run on this config file. Just remove your
+file's entry, 'make install', and tdeconf_update will happily run your script
+again, without you having to increase the version number.
+If you want to know what tdeconf_update has been up to lately, have a look
+* tdeconf_update refuses to update an entry
+If you change the value of an entry without changing the key or file,
+make sure to tell tdeconf_update that it should overwrite the old entry
+by adding "Options=overwrite".