<chapter id="tinkering-under-the-hood">
<!-- Uncomment the <*info> below and add your name to be -->
<!-- credited for writing this section. -->

<!--
<chapterinfo>
<authorgroup>
<author>
<firstname>Your First Name here</firstname>
<surname>Your Surname here </surname>
</author>
</authorgroup>
</chapterinfo>
-->

<title>Tinkering Under the Hood of &kde;</title>

<sect1 id="hand-editing-config-files">

<sect1info>
<author>
<personname>
<firstname>Nicolas</firstname>
<surname>Goutte</surname>
</personname>
<email>goutte@kde.org</email>
</author>
</sect1info>

<title>Hand-Editing Configuration Files</title>

<sect2 id="hand-editing-intro">
<title>Introduction</title>
<para>In &kde;, the configuration files are easy to edit with a simple
editor like &kate; as the configuration files are text files.</para>

<para>An example of a text file:</para>

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

<para>The user-specific configuration files are stored in <filename
class="directory">.kde/share/config</filename> (replace 
<filename>.kde</filename> with your $<envar>KDEHOME</envar> setting) and
the global ones are in the <filename
class="directory">share/config</filename> sub-directory of &kde;'s
installation path. (You can find this path by running the command
<command>kde-config --prefix</command>.) Their filenames typically
end in rc (without an initial period), for example <filename>kopeterc</filename>.</para>

<warning><para>
Editing configuration files by hand can risk the stability of your
&kde; installation. Applications usually do  not check what they read from the
configuration files. This means that they can be disturbed by what they
get as configuration and might even
crash.</para></warning>

</sect2>

<sect2 id="hand-editing-backups">
<title>Backups</title>

<para>So the first rule is to make a backup of your file before modifying
it. The backup is better stored outside any
<filename class="directory">.kde</filename> subdirectory 
(or the corresponding $<envar>KDEHOME</envar> 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 <filename>kmailrc</filename>).
(Such a major failure should not happen but it still can happen.)</para>
</sect2>

<sect2 id="hand-editing">
<title>Editing</title>

<para>So why would you want to touch the configuration files at all? 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 solve a problem with the application. Perhaps you want to recover from
a problem without having to remove all the <filename
class="directory">.kde</filename> directory. Perhaps you want to learn more
about the depths of &kde;.</para>

<para>Anyway, whatever your reason, you want to modify by hand a
configuration file.</para>

<para>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.</para>

<para>Ready? So make a backup of the file (Did I tell you this 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
<quote>utf8</quote>).</para>

<para>Now you have a file like:</para>

<programlisting>[Group]
Key1=Value1
Key2=Value2
Key3=Value3</programlisting>

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

<para>Now you can test the application and if the application does not run
correctly anymore, close the application and restore the backup of the
configuration file.</para>

<itemizedlist>
<title>Related Information</title>


<listitem><para><xref linkend="kde-for-administrators"/> has more
information about &kde;'s directory structure, to help you find the
file you need to edit.</para>
</listitem>

</itemizedlist>

</sect2>

</sect1>

<sect1 id="scripting-the-desktop">
<title>Scripting the Desktop</title>
<para>A brief introduction to DCOP scripting. kdcop.</para>
</sect1>

<sect1 id="adding-extra-keys">
<title>Adding Extra Keybindings to &kde;</title>

<para>Many modern keyboards contain extra keys that are not by default
assigned to any action.</para>

<para><quote>Multimedia</quote> keys often generate a signal, and can simply
be chosen as a keybinding within an application just like choosing any other
key. Some keys however, are not detected and pressing them in a
<guilabel>Configure Shortcuts</guilabel> has no effect.</para>

<para>Some IBM laptops, for instance, have extra keys about the left and right
arrows, which look like <guiicon>page left</guiicon> and <guiicon>page
right</guiicon>.</para>

<procedure>
<step><para>Use <command>xev</command> to find the code of the keys.  In
this case, they are 233 and 234 <!-- TODO: Very briefly how to use xev here -->
</para></step>
<step><para>Choose key symbols. There are quite a range of these that are not
used by default, so many are free.  You can find the list in
<filename>/usr/X11R6/include/X11/keysymdef.h</filename> (or its equivalent
on your system).</para></step>
<step><para>Create a file in your home directory called
<filename>.Xmodmap</filename>, and add to it the following:</para>
<screen>keycode 233 = Next_Virtual_Screen
keycode 234 = Prev_Virtual_Screen</screen>
</step>
<step><para>Run the command <userinput><command>xmodmap</command>
<filename>~/.Xmodmap</filename></userinput></para></step>
</procedure>

<para>At this point, you should be able to run <command>xev</command> again
and see that the keys now generate the keysym that you assigned.  You can now
simply assign them to any action as normal.</para>

<itemizedlist>
<title>Related Information</title>
<listitem><para>The <command>xev</command> manpage.  You can see this by typing
<userinput>man:/xev</userinput> into a &konqueror; window or by typing
<userinput><command>man</command> xev</userinput> into a terminal.</para></listitem>
</itemizedlist>

</sect1>

<sect1 id="keys-for-scripts">
<title>Adding Keybindings for New Actions</title>

<para>Most actions in either the desktop or in applications are readily
available to assign a keybinding to.  If the action you want a
shortcut for is something you wrote yourself, or is otherwise not available,
you can still assign a shortcut.</para>

<para>To bring together the two previous sections, perhaps you want to
assign an otherwise unused key on your keyboard to a script or dcop
command. Our example here will be to assign the two keys we added
in <xref linkend="adding-extra-keys"/> to go to the previous or
next virtual desktop, two functions for which you will need DCOP (as discussed in
<xref linkend="scripting-the-desktop"/>.</para>

<para>This can be achieved easily using the following method:</para>

<procedure>
<step>
<para>Open &kcontrol;, and in the <guilabel>Regional &amp; Accessibility</guilabel>
section, select <guilabel>KHotKeys</guilabel></para>
</step>
<step>
<para>Choose <guibutton>New Action</guibutton></para>
</step>
<step>
<para>Name the new action, &eg; <userinput>Next Virtual
Screen</userinput></para>
</step>
<step>
<para>Select <guilabel>Keyboard shortcut -> Command/URL (simple)</guilabel>
for the <guilabel>Action type:</guilabel></para>
</step>
<step>
<para>In the <guilabel>Keyboard Shortcut</guilabel> tab, click the button
you wish to use to trigger the command.  For this example, you would press
the one with the <guiicon>Next Page</guiicon> picture on it.
<keysym>Next_Virtual_Screen</keysym> will appear in the key image.</para>
</step>
<step>
<para>In the <guilabel>Command/URL Settings</guilabel> tab, enter the
command to run in the field: <userinput><command>dcop kwin default
nextDesktop</command></userinput></para>
</step>
</procedure>

<para>Repeat the above with the <keysym>Prev_Virtual_Screen</keysym> key and
<userinput><command>dcop kwin default
previousDesktop</command></userinput>.</para>

<para>Now pressing the <keysym>Prev_Virtual_Screen</keysym> or
<keysym>Next_Virtual_Screen</keysym> will switch you to the previous or next
virtual desktop, respectively.</para>

<para>Obviously you can assign any free key to any action.</para>

<itemizedlist>
<title>Related Information</title> 
<listitem><para>See the <application>KHotKeys</application> documentation by
looking it up in &khelpcenter;, or typing
<userinput>help:/khotkeys</userinput> in a &konqueror;
window.</para></listitem> 
<listitem><para><xref linkend="adding-extra-keys"/></para></listitem>
<listitem><para><xref linkend="scripting-the-desktop"/></para></listitem>
</itemizedlist>

</sect1>

<sect1 id="kdebugdialog">
<sect1info>
<authorgroup>
<author>
<personname>
<firstname>Adriaan</firstname>
<surname>de Groot</surname>
</personname>
<email>groot@kde.org</email>
</author>
</authorgroup>
</sect1info>

<title>&kdebugdialog;  - Controlling &kde;'s Debugging Output</title>

<sect2 id="kdebugdialog-basic-usage">
<title>Basic Usage</title>

<para>&kdebugdialog; is not in the &kmenu; by default. You will need to run
it from the shell or from the mini-CLI <!-- link to CLI, for sure --> with
the command <userinput><command>kdebugdialog</command></userinput>.
&kdebugdialog; pops up a window with a long list of debugging areas. Each
area has a checkbox that you can check or uncheck <!-- perhaps
select/deselect --> in order to enable or disable debugging output for
that part of &kde;.</para>

<para>The list of debugging areas is sorted numerically, not alphabetically,
so kio (127) comes before artskde (400). The numbers go up to 200000 or so,
but there are really only 400 areas. You don't have to scroll through the
entire list to find the area you need, though. There is a line edit <!--
text-entry ? --> box at the top of the dialog where you can enter a part of
the name of the area you want. The list of entries that is displayed is
filtered to include only those debug areas that contain the text you have
entered. &eg; entering <userinput>k</userinput> does not filter very much at
all, but entering <userinput>kont</userinput> <!-- that's "butt" in dutch,
haha --> will show you just the &kontact; debugging areas. As an even
quicker way of enabling or disabling debugging output, there are also
<guibutton>select all</guibutton> and <guibutton>deselect all</guibutton>
buttons which will cause &kde; to produce a mountain of debugging output, or
very little.</para>
</sect2>

<sect2 id="kdebugdialog-fullmode">
<title>KDebugDialog in full mode</title>

<!-- this text partly taken from the kdebugdialog handbook -->

<para>In full mode, which is what you get when you start kdebugdialog as
<userinput><command>kdebugdialog</command>
<option>--fullmode</option></userinput>, the same list of debugging areas
as in plain mode is available, but you can select only one at a time from a
drop-down <!-- combo? --> box. You may then  independently set the output
for various types of messages: Information, Warning, Error and Fatal Error.
For each of these types, you can choose where the messages are sent. The
choices are:</para>

<para>File, in which case you can enter a filename. This file is written into your
$<envar>HOME</envar> directory.</para>

<para>Message Box. Each debugging message is displayed in an information dialog,
which you must <guibutton>OK</guibutton> to continue with the
application.</para>

<para>Shell, the default entry. Messages are printed to stderr, and will appear
 either in the shell window where the application was started, or
in <filename>.xsession-errors</filename>.</para>

<para>Syslog. This sends each debugging message to the system's syslog facility,
which can perform its own processing of the message.</para>

<para>None. This suppresses the output of this type of message.</para>

<para>For messages generated by  fatal errors, it is generally a bad idea to choose
None or Syslog, since in both cases you most likely will not see the message
and the application that encounters the fatal error will vanish without
leaving a clue as to why it vanishes. Whether or not the application will
vanish on fatal errors can be controlled by the checkbox <guilabel>abort on
fatal errors</guilabel>, which is checked by default &mdash; but you might
expect an application to crash (in a messy fashion) if a fatal error is
encountered anyway.</para>

<!-- Add links to "further reading" here -->
<itemizedlist>
<title>Related Information</title>
<listitem><para></para>
</listitem>
</itemizedlist>



</sect2>
</sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "chapter")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
