[kde-doc-english] New user guide: new section for "Hand Editing Config Files"

[Nicolas Goutte]

Attached is a text for the (empty) section "Hand Editing Config Files" of the 
new KDE user guide.

Have a nice day!
-------------- next part --------------
*** Hand Editing Configuration Files ***
Nicolas GOUTTE <goutte at kde.org>

In KDE, the configuration files are easy to edit with a simple editor like Kate
as the configuration files are text files.

An example of a text file:

[General]
AutoSave=1
LastFile=/var/tmp/test.txt

The configuration files are for a user in .kde/share/config (replace .kde with your $KDEHOME setting)
and the global ones are in the share/config sub-directory depending where KDE has been installed.
Their filenames typically ends in rc (without a dot).

* Warning *

However editing configuration files by hand can risk the stability of your KDE. Mostly applications
are not checking much what they read from the configuration files and can therefore be disturbed by what they
get as configuration and so the application might even crash.

* Backups *

So the first rule is to make a backup of your file before modifiying it. The backup is better stored outside any .kde subdirectory
(or the corresponding $KDEHOME directory). Backups are anyway a good idea in case of a major failure of KDE that would
destroy important configuration files (for example your KMail settings, which are in in the file kmailrc).
(Such a major failure should not happen but it still can happen.)

* Editing *

So why touching the configuration files then? Well, first you need it when you want to enforce the KIOSK mode.
Perhaps a developer has asked you to add an entry to help him to debug a bug. Perhaps you want to recover from
a problem without having to remove all the .kde directory. Perhaps you want to learn more about the depths of KDE.

Anyway, whatever your reason, you want to modify by hand a configuration file.

When planning to edit such a file, make sure that the application using it is not running. If it is one of the
basic configuration files, consider editing the file while KDE is not running at all.

Ready? So make a backup of the file (Did I told you it already?), start you favorite editor
(Let us assume it is Kate), load the file (Be careful to load as UTF-8, Kate displays it as "utf8").

Now you have a file like:

[Group]
Key1=Value1
Key2=Value2
Key3=Value3

You can now modify it (with care!) and then save it (Be sure that it is as UTF-8 again).

Now you can test the application and if the application does not run correctly anymore, close the application
and restore the backuped configuration file.