Move Administrator Guide from User Guide to standalone handbook.

4 files changed, 3398 insertions, 0 deletions

diff --git a/doc/adminguide/CMakeLists.txt b/doc/adminguide/CMakeLists.txt
new file mode 100644
index 000000000..ec8d87dac
--- /dev/null
+++ b/doc/adminguide/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_create_handbook( DESTINATION khelpcenter/adminguide )
diff --git a/doc/adminguide/Makefile.am b/doc/adminguide/Makefile.am
new file mode 100644
index 000000000..86108a74b
--- /dev/null
+++ b/doc/adminguide/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = khelpcenter/adminguide
+
diff --git a/doc/adminguide/groupware-kontact.docbook b/doc/adminguide/groupware-kontact.docbook
new file mode 100644
index 000000000..b18313931
--- /dev/null
+++ b/doc/adminguide/groupware-kontact.docbook
@@ -0,0 +1,614 @@
+<chapter id="groupware-with-kontact">
+
+<chapterinfo>
+<authorgroup>
+<author>
+<personname>
+<firstname>Marco</firstname>
+<surname>Menardi</surname>
+</personname>
+<email>gnu@kde.org</email>
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</chapterinfo>
+<title>Sharing data with &kontact; via <acronym>IMAP</acronym></title>
+
+<sect1 id="kontact-imap-intro">
+<title>Introduction</title>
+
+<para>For my small office, I was looking for a long time for a
+<acronym>PIM</acronym> solution that let me share data, so my secretary and
+I can share contacts, appointments and so on. Being a &tde; user, I've heard
+about the Kroupware project and wait its completion. But when I saw how
+complicated is the architecture and setup of the
+<application>Kolab</application> server 1.0 (the server side of the
+project), I gave up, waiting for an easier to deploy
+<application>Kolab</application> 2.0. In any case, the
+<application>Kolab</application> stuff was clearly too much for my
+needs. Fortunately in the &tde; wiki I've found some piece of
+<acronym>IRC</acronym> conversation where they were talking about sharing
+data without the <application>Kolab</application> infrastructure... mmm so
+interesting!</para>
+
+<para>For small offices and needs, you can have &kontact; use shared data
+without the need of installing the <application>Kolab</application> server
+or another groupware backend. It can work with just an
+<acronym>IMAP</acronym> server, that can be easily set up.</para>
+
+<para>My scenario is a server with Debian unstable and &tde; 3.4. I access
+&kontact; and other fabulous GNU/Linux apps from windows using Cygwin/X,
+while waiting Wine project to be able to run the last Windows programs I
+need (and that are not available under GNU/Linux). I want to share contacts,
+events, todo, notes with my secretary.</para>
+
+</sect1>
+
+<sect1 id="kontact-imap-whatis">
+<title>What is <acronym>IMAP</acronym></title>
+
+<para>This definition is from the <ulink
+url="http://computeruser.com">ComputerUser.com High-Tech Dictionary:</ulink>
+<blockquote><para>Internet Message Access Protocol. A protocol that allows a
+user to perform certain electronic mail functions on a remote server rather
+than on a local computer. Through IMAP the user can create, delete, or
+rename mailboxes; get new messages; delete messages; and perform search
+functions on mail. A separate protocol is required for sending mail. Also
+called Internet Mail Access Protocol.</para></blockquote> </para>
+
+<para>So it can be considered a data storage. To use it you you need an
+<acronym>IMAP</acronym> server, such as <application>Cyrus</application>,
+<application>Courier</application> or <application>UW</application>.</para>
+
+</sect1>
+
+<sect1 id="kontact-kolab-or-imap">
+<title><application>Kolab</application> or <acronym>IMAP</acronym>?</title>
+
+<para><application>Kolab</application> brings the ability to share data
+between different clients. It makes possible for your secretary to use
+<application>Outlook</application> and you use &kontact;, for
+instance.</para>
+
+<para>You will have a configuration interface which does user management, mail
+account setup, a central <acronym>LDAP</acronym> config data and addressbook
+server, spam and virus filtering, vacation scripts, free busy list handling,
+resource handling (rooms, cars), groups, distribution lists, automatic
+invitation handling, &etc;</para>
+
+<para>But that can cause initial setup troubles. For a newbie like me it
+means: a long long frustrating nightmare, and too much complexity to manage
+once working. So no, thanks, I'll go to simple
+<acronym>IMAP</acronym>.</para>
+
+</sect1>
+
+<sect1 id="kontact-imap-cyrus">
+<title>How to set up <acronym>IMAP</acronym> server <application>Cyrus</application></title>
+
+<para>My choice is <application>Cyrus</application>, that is part of the
+<application>Kolab</application> set of software, so if l will go for
+<application>Kolab</application> in the future, at least I'm acquainted with
+it.</para> <para>Let's start the installation and the setup!</para>
+
+<para>Become <systemitem class="username">root</systemitem>.</para>
+
+<screen># <userinput><command>apt-get</command> <command>install</command> cyrus21-imapd cyrus21-common cyrus21-admin cyrus21-client sasl-bin sasl2-bin</userinput>
+<computeroutput>Installing cyrus21-imapd...</computeroutput><lineannotation>The installer asks something I've not understood about an search address... I just pressed <keycap>Enter</keycap></lineannotation>.</screen>
+
+<para>The installer also created the user <systemitem
+class="username">cyrus</systemitem> that is in the (automatically created)
+group <systemitem class="groupname">sasl</systemitem>, that is the
+<quote>owner</quote> of all cyrus files. At the end with <command>ps
+<option>-A</option></command> you can find the new processes:
+<command>cyrmaster</command> and <command>notifyd</command>.</para>
+
+<para>The real problem in setting up <application>Cyrus</application> is the
+authentication, just because it's not trivial and I'm a newbie, with limited
+knowledge about what I'm doing.</para>
+
+<para><application>Cyrus</application> can use different
+<acronym>SASL</acronym> (Simple Authentication and Security Layer)
+mechanisms, the default being sasldb (it stores usernames and passwords in
+the SASL secrets file <filename>sasldb</filename>), but also getpwent,
+kerberos4, kerberos5, PAM, rimap, shadow and LDAP are supported.</para>
+
+<para> Since I don't want to define users/passwords different than the ones
+that access my &Linux; box I choose then <quote>shadow</quote> mechanism so
+<application>Cyrus</application> will use &Linux; passwords for
+authenticate.</para>
+
+<para>To do so we have to tell sasl to use <command>saslauthd</command> as
+password authentication method, and then setup <command>saslauthd</command>
+to use <quote>shadow</quote> (or <quote>getpwent</quote>) as the
+authentication mechanism.</para>
+
+<para>OK, let's start!</para>
+
+<para>As <systemitem class="username">root</systemitem>, change the Linux
+password of <systemitem class="username">cyrus</systemitem> user:</para>
+
+<screen># <userinput><command>passwd <option>cyrus</option></command></userinput></screen>
+
+<para>Enter the password you like (and you will remember) we will use for
+this example <quote>cyrus</quote> as the <application>cyrus</application>
+administrator password.</para>
+
+<screen># <command>vi</command> <filename>/etc/imapd.conf</filename></screen>
+
+<programlisting>sasl_pwcheck_method: <userinput>saslauthd</userinput> <lineannotation>instead of the default <literal>auxprop</literal></lineannotation></programlisting>
+
+<para>remove the <literal>#</literal> remark from the line:</para>
+
+<programlisting>#admins: cyrus</programlisting>
+
+<para>this way you can administer <application>cyrus</application> logging
+in as <systemitem class="username">cyrus</systemitem> user (what a fantasy I
+have!)</para>
+
+<screen># <userinput><command>vi</command> <filename>/etc/default/saslauthd</filename></userinput></screen>
+
+<para>Uncomment the line:</para>
+
+<programlisting># START=yes</programlisting>
+
+<para>(otherwise the <application>saslauthd</application> will not start at
+boot time, even if referenced in some <filename
+class="directory">/etc/rcx.d</filename>!)</para>
+
+<para>and instead of <literal>MECHANISMS="pam"</literal> put
+<userinput>MECHANISMS="shadow"</userinput> this way at the boot a
+<command>saslauthd</command> <option>-a
+<parameter>shadow</parameter></option> will be executed.</para>
+
+<para>Once exited from your editor, restart <application>sasl</application>
+and <application>cyrus</application>.</para>
+
+<para>To test <acronym>IMAP</acronym>:</para>
+
+<screen> <userinput><command>su</command> <option>cyrus</option></userinput>
+$ <userinput><command>imtest</command> <option>-m login -p imap localhost</option></userinput></screen>
+
+<para>You are prompted for the <systemitem
+class="username">cyrus</systemitem> (user) password, so enter it.</para>
+
+<para>If the user <systemitem class="username">cyrus</systemitem> is
+correctly authenticated, the following lines will appear:</para>
+
+<screen><computeroutput>S: L01 OK User logged in
+Authenticated.</computeroutput></screen>
+<para>To exit type <userinput>. logout</userinput> (&ie; dot space <quote>logout</quote>)</para>
+
+<para>Now add a user named <systemitem
+class="username">groupware</systemitem> and set a password for it, using
+your usual system tools. It should be in an unprivileged group such as
+<systemitem class="groupname">nobody</systemitem> and does not require a
+login shell or a home directory.</para>
+
+<para>Now I have to create the user and an <acronym>IMAP</acronym> in
+<application>cyrus</application> also:</para>
+
+<screen># <userinput><command>cyradm</command> <option>--user cyrus localhost</option></userinput>
+after entering the password for the admin user <systemitem class="username">cyrus</systemitem>, you get the prompt <prompt>localhost&gt;</prompt>
+<prompt>localhost&gt;</prompt> <userinput><command>cm</command> <option>user.groupware</option></userinput>
+<prompt>localhost&gt;</prompt> <userinput><command>lm</command></userinput> <lineannotation>lists the mailbox only just created</lineannotation>
+<computeroutput>user.groupware (\HasNoChildren))</computeroutput>
+<prompt>localhost&gt;</prompt> <userinput><command>quit</command></userinput></screen>
+
+<para>You can type <userinput><command>help</command></userinput> for a list
+of available commands.</para>
+
+<para>You can check what has happened with:</para>
+
+<screen># <userinput><command>ls</command> <option>-l</option> <filename class="directory">/var/spool/cyrus/mail/g/user/groupware</filename></userinput>
+<computeroutput>total 12
+-rw------- 1 cyrus mail          4 Oct 29 20:55 cyrus.cache
+-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header
+-rw------- 1 cyrus mail 76 Oct 29 20:55 cyrus.index</computeroutput></screen>
+
+<para>Now you should be able to connect with an <acronym>IMAP</acronym> client
+as the <systemitem class="username">groupware</systemitem> user and see the
+<literal>INBOX</literal>.</para>
+<note><para>In the <acronym>IMAP</acronym> protocol, selecting the mailbox
+<literal>INBOX</literal> is a magic word, a sort of <quote>alias</quote> for
+the above directory structure. The client sees <literal>INBOX</literal>, and
+the <acronym>IMAP</acronym> server maps it in the <filename
+class="directory">/var/spool/cyrus/mail/...</filename> folder and file
+structure.</para></note>
+
+</sect1>
+
+<sect1 id="kontact-imap-clients">
+<title>How to setup &kontact; clients</title>
+
+<para>I connect to my GNU/Linux office server PC (a sort of "black box"
+without monitor and keyboard) from 2 &Windows; 2000 PC with
+<application>Cygwin/X</application>, using them as a X-Window server (in the
+near future I hope to replace both with 2 mini-itx thin clients using the
+LTSP). With this setup every user runs &kontact; on the same machine where
+<application>Cyrus</application> is installed and running
+(localhost).</para>
+
+<para>To have &kontact; work with <acronym>IMAP</acronym>, there are these
+steps to complete:</para>
+
+<procedure>
+
+<step><para>Create an <acronym>IMAP</acronym> account on the
+<application>Cyrus</application> for fake <systemitem
+class="username">groupware</systemitem> user (already previously
+done!)</para></step>
+
+<step><para>Create/configure an <acronym>IMAP</acronym> account in &kmail;
+for login as that user</para></step> <step><para>Use tderesources to make
+&kontact; components work with data taken from <acronym>IMAP</acronym>
+source</para></step>
+
+<step><para>Enable groupware functionality and make related subfolders of
+that <acronym>IMAP</acronym> <literal>INBOX</literal> (if not
+already)</para></step>
+
+<step><para>Enjoy &kontact; and shared data through
+<application>Cyrus</application> IMAP</para></step>
+
+</procedure>
+
+<para>So login to &tde; with the first <quote>real user</quote> account you
+want to provide groupware functionality to.</para>
+
+<para>Let's create the IMAP account in &kmail;.</para>
+
+<para>Run &kontact; and select <guilabel>Mail</guilabel> (the &kmail;
+component). From the menu choose
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KMail
+</guimenuitem><guilabel>Accounts</guilabel><guilabel>Receiving</guilabel></menuchoice> tab, press the <guibutton>Add...</guibutton> button. You will then be
+prompted for the type of your email account, and select
+<guilabel>disconnected IMAP</guilabel> (not just
+<guilabel>IMAP</guilabel>). Then in the <guilabel>General</guilabel> tab
+enter the following data:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Account Name:</guilabel> <userinput>office_gwdata</userinput></term>
+<listitem>
+<para>A name that will be used for the <quote>local</quote> folder that
+points to this <acronym>IMAP</acronym> account.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Login:</guilabel> <userinput>groupware</userinput></term>
+<listitem>
+<para>The <application>Cyrus</application> user we have chosen as
+<quote>owner</quote> of all of the office data</para>
+</listitem>
+</varlistentry>
+<varlistentry><term><guilabel>Password:</guilabel></term>
+<listitem>
+<para>The password of the <systemitem
+class="username">groupware</systemitem> user.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Host:</guilabel> <userinput>localhost</userinput></term>
+<listitem>
+<para>Remember for our example, the &kontact; client runs on the same
+computer as the <acronym>IMAP</acronym> server</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Port:</guilabel> <userinput>143</userinput></term>
+<listitem>
+<para>The default</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>Check <guilabel>store IMAP password</guilabel>
+so you will not be asked for it next time you run &kontact;. Check the
+<guilabel>Enable interval mail checking</guilabel> and set a value in
+minutes.</para>
+
+<para>Note that we have checked the <guilabel>disconnected IMAP</guilabel>
+type account. This has the effect that a copy of the groupware data is
+stored <quote>locally</quote> to the client (under the home folder), and it
+is synchronized every time the client connects. This seems very inefficient,
+since your data is duplicated many times (&ie; if you have 10 users that use
+&kontact;, you have 10+1 times the data), but it is the only way to make
+things run fast, because at every connection &kontact; has to fetch all data
+and have &korganizer; and &kaddressbook; interpret it. If you use
+<quote>disconnected IMAP</quote> data is cached locally, and only the
+<quote>delta</quote> (&ie; the data that has changed) is sent.</para>
+
+<para>On the other end, if your users run &korganizer; on the same PC that
+runs the <acronym>IMAP</acronym> server, it seems reasonable to use
+<acronym>IMAP</acronym> (that is called <quote>online IMAP</quote>) to save
+space, since transfer speed should not be an issue. But unfortunately this
+does not work because &kontact; does not update automatically the
+<guilabel>Calendar</guilabel> folder in <quote>online IMAP</quote>, so you
+are not updated when someone adds events (you must manually switch to
+&kmail; application and click on the <guilabel>Calendar</guilabel>
+folder). In addition, at start up when it does read
+<guilabel>Calendar</guilabel> folders, you may see a tremendous flicker and
+slow data updates.</para>
+
+<para>Now we have to tell &kontact; to use <acronym>IMAP</acronym> as the
+data source for it's various components. From the &kmenu;, choose
+<guimenuitem>Run command</guimenuitem>, run <userinput><command>tdecmshell
+tderesources</command></userinput>. In the combo box select
+<guilabel>Contacts</guilabel>, then press the <guibutton>Add...</guibutton>
+button, and choose <guilabel>Addressbook on IMAP Server via KMail</guilabel>. Then select that new line and
+press <guibutton>Use as Standard</guibutton> button. Do the same for
+<guilabel>Calendar</guilabel> and <guilabel>Notes</guilabel>.</para>
+
+<para>Now we have to enable the &kmail; (and as a consequence, the whole
+&kontact;) groupware functionality:</para>
+
+<procedure>
+<step>
+<para>Choose from the menu
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+KMail</guimenuitem><guilabel>Misc</guilabel><guilabel>Groupware</guilabel></menuchoice></para>
+</step>
+<step>
+<para>Check <guilabel>Enable IMAP resource functionality</guilabel></para>
+</step>
+<step>
+<para>Choose <guilabel>English</guilabel> as <guilabel>Language of the
+groupware folders</guilabel> (this is in case you already have the folders
+in the <acronym>IMAP</acronym> server created by a different program in a
+different language).</para>
+</step>
+<step>
+<para>Now move to <guilabel>Resource folder are in account</guilabel> and
+select the the <guilabel>Inbox</guilabel> subfolder of the
+<guilabel>office_gwdata</guilabel> folder.</para>
+<para>Leave <guilabel>Hide groupware folders</guilabel> unchecked for now,
+so we can see that happens. You can return here and check it once everything
+is clear.</para>
+</step>
+<step>
+<para>When you press OK you are prompted with:
+<computeroutput>&kmail; will now create the required folders for the IMAP
+resource as subfolders of Inbox</computeroutput> </para>
+<para>If you do not want this, press <guibutton>No</guibutton>, and the
+<acronym>IMAP</acronym> resource will be disabled.  Press
+<guibutton>Yes</guibutton> (this happens only the first time with the first
+<quote>real user</quote>).  You will immediately see that in the &kmail;
+folder tree, under
+<menuchoice><guilabel>office_gwdata</guilabel><guilabel>Inbox</guilabel></menuchoice>
+these subfolders are created:</para>
+<simplelist>
+<member>Calendar</member>
+<member>Contacts</member>
+<member>Notes</member>
+<member>Tasks</member>
+<member>Journal</member>
+</simplelist>
+<para>if you now do a:</para>
+<screen># <command>ls</command> <option>-l /var/spool/cyrus/mail/g/user/groupware/</option>
+<computeroutput>drwx------ 2 cyrus mail 144 Oct 31 16:36 Calendar
+drwx------ 2 cyrus mail 144 Oct 31 16:36 Contacts
+drwx------ 2 cyrus mail 144 Oct 31 16:36 Journal
+drwx------ 2 cyrus mail 144 Oct 31 16:36 Notes
+drwx------ 2 cyrus mail 144 Oct 31 16:36 Tasks
+-rw------- 1 cyrus mail      4 Oct 31 15:28 cyrus.cache
+-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header
+-rw------- 1 cyrus mail 76 Oct 31 15:28 cyrus.index</computeroutput></screen>
+
+<para>As you see, the <guilabel>office_gwdata Inbox</guilabel> is stored not
+local to the &kontact; current user home, but in the <acronym>IMAP</acronym>
+<systemitem class="username">groupware</systemitem> user's folders.</para>
+</step>
+</procedure>
+
+<para>Now &kontact; is ready to work and store data there.  In the calendar
+application, if &kmail; <acronym>IMAP</acronym> account was of type
+<quote>disconnected</quote>, the <guilabel>resource</guilabel> window should
+display the item <guilabel>Imap resource</guilabel> with 3 subitems, that
+are paths to local home files. Instead, the <guilabel>Contacts</guilabel>
+application does not show subitems below the <guilabel>Imap
+resource</guilabel>.</para>
+
+<para>You can now login to &tde; with a different username and set up
+his/her &kontact; client in a very similar manner:</para>
+
+<procedure>
+<step>
+<para>Open &kontact; and in the <guilabel>Mail</guilabel> component add an
+<acronym>IMAP</acronym> account specifying as <guilabel>host</guilabel> the
+computer where <application>Cyrus</application> server runs (in my case:
+<literal>192.168.1.3</literal>).</para>
+
+<para>Remember to check the <guilabel>Enable interval mail
+checking</guilabel> and set a value in minutes. When  you confirm, you are
+not prompted for the subfolder creation (since they are found in the
+<acronym>IMAP</acronym> server), and you see them in the folder tree.</para>
+</step>
+<step>
+<para>Activate the groupware functionality to be able to save data in the
+<acronym>IMAP</acronym> server.</para>
+</step>
+</procedure>
+<para>Beware that in <quote>disconnected <acronym>IMAP</acronym></quote>,
+data are transmitted from a client to  <acronym>IMAP</acronym> server only
+when the clients connects to check for new mail. So if you have your
+&kontact; clients with an <guilabel>interval mail checking</guilabel> of,
+for instance, 5 minutes, in the worst  case you have a 10 minutes delay
+between the event being written and it's appearance to the other
+users.</para>
+</sect1>
+<sect1 id="kontact-imap-readonly">
+<title>How to have Read Only Access</title>
+
+<note><para>Beware that I've been confirmed that Notes
+<acronym>IMAP</acronym> implementation in &kontact; prior to version 1.01 is
+broken, so this setup will not work for them, so you want to use them, you
+need to use the previous setup.</para></note>
+
+<para>In the previous setup, we have the same <quote>fake</quote> user, named
+<systemitem class="username">groupware</systemitem>, that is used by all the
+<quote>real</quote> &kontact; users (&ie; <systemitem
+class="username">tony</systemitem>, <systemitem
+class="username">rohn</systemitem>, <systemitem
+class="username">amanda</systemitem>, &etc;) through the
+<acronym>IMAP</acronym> account with it's login and password. But this way
+every real user has the same read/write permissions of the others, since
+everyone connects as the user <systemitem
+class="username">groupware</systemitem> to the <acronym>IMAP</acronym>
+server.</para>
+
+<para>To limit access to some users (typically, providing read-only access),
+we can use the <acronym>ACL</acronym> (Access Control Lists).</para>
+
+<para>Select in &kmail; a subfolder of <guilabel>office_gwdata</guilabel>
+inbox, for instance <guilabel>Calendar</guilabel>, and right click the
+mouse. Select <guilabel>Properties</guilabel><guilabel>Access
+Control</guilabel> tab. Here you can enter the users you want give access to
+this folder and what they can do.</para>
+
+<para>Just to experiment trying to exchange events, we give
+<quote>All</quote> permission to the user <systemitem
+class="username">mary</systemitem></para>
+
+<para>At <application>cyrus</application> level (in the
+<acronym>PC</acronym> that runs <acronym>IMAP</acronym> server cyrus, with
+<application>cyrus</application> tools), we first need to add the user
+<systemitem class="username">mary</systemitem>, so it's an
+<acronym>IMAP</acronym> recognized user, and create an
+<acronym>IMAP</acronym> folder for her.</para>
+
+<para>Then we login to GNU/Linux as <systemitem
+class="username">mary</systemitem> and enter &kontact;. As previously shown,
+we will setup an <acronym>IMAP</acronym> account in &kmail; with the same
+data but the one of the user (instead of the fake user <systemitem
+class="username">groupware</systemitem> and it's password, we will use
+<systemitem class="username">mary</systemitem> and her password).</para>
+
+<para>In &kmail; folder tree, this time you will see this structure:
+<menuchoice><guimenu>office_gwdata</guimenu><guisubmenu>user</guisubmenu>
+<guisubmenu>groupware</guisubmenu><guimenuitem>Calendar and
+Tasks</guimenuitem></menuchoice>. Check the mail
+(<menuchoice><guimenu>File</guimenu><guimenuitem>Check
+Mail</guimenuitem></menuchoice>) and you will also have an
+<quote>inbox</quote> folder under <quote>office_gwdata</quote>.</para>
+
+<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource
+folders are subfolders of</guilabel> put the
+<guimenuitem>inbox</guimenuitem> that is subfolder of
+<quote>office_gwdata</quote>.</para>
+
+<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource
+folders are subfolders of</guilabel> put the
+<guimenuitem>inbox</guimenuitem> that is subfolder of
+<guisubmenu>office_gwdata</guisubmenu>.</para>
+
+<para>Now you have two branches of folder under
+<quote>office_gwdata</quote>:</para>
+
+<orderedlist>
+<listitem>
+<para><quote>inbox</quote> with Calendar, Contacts, Notes, Tasks and
+Journal, that are saved on <systemitem class="username">mary</systemitem>
+<acronym>IMAP</acronym> folders on the <acronym>IMAP</acronym> server</para>
+</listitem>
+<listitem>
+<para><quote>user</quote>, with the subfolder <quote>groupware</quote> and
+the subfolders to which <systemitem class="username">mary</systemitem> has
+access to (in this example, Calendar and Tasks)</para>
+</listitem>
+</orderedlist>
+<para>&RMB; click on the <quote>user</quote> <quote>Calendar</quote> and
+check if it's of type Calendar (if not, set it to be), and also if
+<quote>user</quote><quote>Tasks</quote> is of type Tasks.</para>
+<para>Now in Calendar you have two available <acronym>IMAP</acronym>
+resources to write against, so if you create a new event, you are prompted
+which one use (or if you left the local resources available, you have
+3!).</para>
+<para>You have go to the lower left small window in Calendar, the one that
+shows available resources, and uncheck the ones that don't point to
+<guilabel>.groupware.directory</guilabel> path (see the tail part of each
+resource path).</para>
+
+</sect1>
+
+<sect1 id="kontact-imap-credits">
+<title>Credits</title>
+
+<para>I'm a newbie, and for this howto I've only provided my time and my
+will. For the knowledge I have really to thank some guys in freenode
+channels for their competence, patience and helpfulness.</para>
+
+<itemizedlist>
+<title>Special thanks to:</title>
+<listitem>
+<para>For the <application>Cyrus</application> <acronym>IMAP</acronym> part
+in #cyrus channel:</para>
+<itemizedlist>
+<listitem>
+<para>[protagonist] Andy Morgan <email>morgan@orst.edu</email></para>
+</listitem>
+<listitem>
+<para>[plixed] Okke Timm <email>okke.timm@web.de</email></para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para>For the &kontact; part in #kontact channel:</para>
+<itemizedlist>
+<listitem>
+<para>[till] Till Adam <email>adam@kde.org</email></para>
+</listitem>
+<listitem>
+<para>[dfaure] David Faure <email>faure@kde.org</email></para>
+</listitem>
+<listitem>
+<para>[mdouhan] Matt Douhan <email>matt@fruitsalad.org</email></para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+<para>Thank a lot guys!</para>
+
+<para>Ah, and there is also me, [markit] Marco Menardi
+<email>mmenaz@mail.com</email></para>
+
+</sect1>
+
+<sect1 id="kontact-imap-further-reading">
+<title>Further Reading</title>
+
+<itemizedlist>
+<title>Reference</title>
+<listitem><para>KDE: <ulink url="http://www.kde.org">http://www.kde.org</ulink></para></listitem>
+<listitem><para>&kontact; website: <ulink url="http://www.kontact.org">http://www.kontact.org</ulink></para></listitem>
+<listitem><para>Kroupware project: <ulink url="http://www.kroupware.org">http://www.kroupware.org</ulink></para></listitem>
+<listitem><para>&kde; Community Wiki: <ulink url="http://wiki.kde.org">http://wiki.kde.org</ulink></para></listitem>
+<listitem><para>Wine project: <ulink url="http://www.winehq.org">http://www.winehq.org</ulink></para></listitem>
+<listitem><para>Cygwin/X project <ulink url="http://x.cygwin.com">http://x.cygwin.com</ulink></para></listitem>
+<listitem><para>LTSP project: <ulink url="http://www.ltsp.org">http://www.ltsp.org</ulink></para></listitem>
+</itemizedlist>
+
+</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:
+-->
diff --git a/doc/adminguide/index.docbook b/doc/adminguide/index.docbook
new file mode 100644
index 000000000..9b767ec4a
--- /dev/null
+++ b/doc/adminguide/index.docbook
@@ -0,0 +1,2772 @@
+<?xml version="1.0" ?>
+  <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY % addindex "INCLUDE">
+  <!ENTITY % imageobjectco.module "INCLUDE">
+  <!ENTITY groupware-with-kontact SYSTEM "groupware-kontact.docbook">
+  <!ENTITY % English "INCLUDE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+
+<title>The &tde; (Trinity Desktop Environment) Administrator Guide</title>
+
+<authorgroup>
+<corpauthor>&tde-team;</corpauthor>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2004-2005</year>
+<holder>The &kde; Team</holder>
+</copyright>
+<copyright>
+<year>&tde-copyright-date;</year>
+<holder>&tde-team;</holder>
+</copyright>
+
+<!-- <legalnotice>&FDLNotice;</legalnotice> -->
+
+<date>&tde-release-date;</date>
+<releaseinfo>&tde-release-version;</releaseinfo>
+
+<abstract>
+<para>A general administrator guide to the Trinity Desktop Environment.
+</para>
+
+<para>Please report problems with this document to
+<email>trinity-devel@lists.pearsoncomputing.net</email>.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>TDE</keyword>
+<keyword>desktop</keyword>
+<keyword>handbook</keyword>
+<keyword>tutorial</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="tde-for-admins-introduction">
+<title>&tde; for Administrators</title>
+
+<sect1 id="tde-for-admins-overview">
+<title>Overview</title>
+
+<para>This handbook is a reference guide to
+some &tde; features that are useful to administrators configuring
+multi-user systems. This part also has information that might be useful
+to &tde; users with single-user systems: where configuration files are
+stored, what environment variables affect &tde;, and so on. The KIOSK
+framework is the &tde; system which allows administrators to limit
+what users can do in &tde;. That framework is potentially useful in many
+situations, but especially for running single-function kiosks with,
+for example, only a web browser, hence the name.</para>
+
+</sect1>
+
+<sect1 id="directory-layout">
+<title>Directory Layout</title>
+
+<para>&tde; defines a filesystem hierarchy which is used by the &tde;
+environment itself as well as all &tde; applications. In general &tde;
+stores all its files in a directory tree with a fixed structure.
+</para>
+
+<para>By default &tde; uses two directory trees:</para>
+
+<itemizedlist>
+<listitem><para>One at the system level (for example <filename
+class="directory">/opt/trinity</filename>).</para></listitem>
+<listitem><para>One at the user level in the user's home directory
+(usually <filename class="directory">
+~/.trinity</filename>)</para></listitem>
+</itemizedlist>
+
+<para>As a system administrator you can create additional trees. Such
+additional trees can be used for <link
+linkend="user-profiles">profiles</link></para>
+
+<informalexample><para>&SuSE; &Linux; for example uses:</para>
+
+<itemizedlist>
+<listitem><para><filename
+class="directory">$<envar>HOME</envar>/.trinity</filename></para></listitem>
+<listitem><para><filename
+class="directory">/opt/trinity</filename>. (This is
+&SuSE;-specific; other distributions may use
+<filename class="directory">/usr</filename> or <filename
+class="directory">/usr/trinity</filename>)</para></listitem>
+<listitem><para><filename
+class="directory">/etc/opt/trinity</filename>. (This was added by
+&SuSE;).</para></listitem>
+</itemizedlist>
+
+<para>If you have the KIOSK Admin tool v0.7 or later installed you can
+check which directory trees are used with the following command:
+<userinput><command>kiosktool-tdedirs</command>
+<option>--check</option></userinput></para>
+</informalexample>
+
+<para>&tde; and &tde; applications look up files by scanning all the
+&tde; directory trees.  The directory trees are checked in order of
+precedence. When a file is present in multiple directory trees, the
+file from the last tree takes precedence.  Normally, the tree
+located in the user's home directory has the highest precedence. This
+is also the directory tree to which changes are written.</para>
+
+<informalexample>
+<para>For information about the <literal>text/plain</literal> &MIME; type
+the following files are searched:</para>
+
+<itemizedlist>
+<listitem><para><filename
+class="directory">$<envar>HOME</envar>/.trinity/share/mimelnk/text/plain.desktop</filename></para></listitem>
+<listitem><para><filename
+class="directory">/opt/trinity/share/mimelnk/text/plain.desktop</filename></para></listitem>
+<listitem><para><filename
+class="directory">/etc/opt/trinity/share/mimelnk/text/plain.desktop</filename></para></listitem>
+</itemizedlist>
+
+<para>If a user makes a change, the change is written to <filename
+class="directory">$<envar>HOME</envar>/.trinity/share/mimelnk/text/plain.desktop</filename></para>
+</informalexample>
+
+<para>For configuration files the story is slightly different. If
+there are multiple configuration files found in the directory trees
+with the same name, their content is combined. The precedence order of
+the directory trees plays a role here. When two files define the same
+configuration key, the file with the highest precedence determines
+which value is used for the key.</para>
+
+<informalexample><para>
+For example, if the following two files exist, with these contents:</para>
+<variablelist>
+<varlistentry><term><filename>$<envar>HOME</envar>/.trinity/share/config/foobar</filename></term>
+<listitem><programlisting>
+Color=red
+Shape=circle
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>/etc/opt/trinity/share/config/foobar</filename></term>
+<listitem><programlisting>
+Color=blue
+Position=10,10
+</programlisting>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>The files will be merged to result in:</para>
+
+<programlisting>
+Color=red
+Shape=circle
+Position=10,10
+</programlisting>
+
+</informalexample>
+</sect1>
+
+<sect1 id="specifying-directories">
+<title>Specifying Directories</title>
+
+<para>
+
+<segmentedlist>
+<segtitle>Environment Variable</segtitle>
+<segtitle>Example Setting(s)</segtitle>
+<segtitle>Comment</segtitle>
+
+<seglistitem>
+<seg><envar>TDEHOME</envar></seg>
+<seg><filename class="directory">~/.trinity</filename></seg>
+<seg></seg>
+</seglistitem>
+
+<seglistitem>
+<seg><envar>TDEROOTHOME</envar></seg>
+<seg><filename class="directory">/root/.trinity</filename></seg>
+<seg>Different variable to prevent
+root writing to $TDEHOME of the user after running
+<command>su</command>.</seg>
+</seglistitem>
+
+<seglistitem>
+<seg><envar>TDEDIR</envar></seg>
+<seg><filename class="directory">/opt/trinity</filename>, <filename
+class="directory">/usr</filename>, <filename
+class="directory">/usr/trinity</filename></seg>
+<seg>Vendor dependent. Used by &tde; 2. If not set, falls back to
+compiled-in default.</seg>
+</seglistitem>
+
+<seglistitem>
+<seg><envar>TDEDIRS</envar></seg>
+<seg><filename class="directory">/opt/trinity</filename>, <filename
+class="directory">/usr</filename>, <filename
+class="directory">/usr/trinity</filename></seg>
+<seg>New in &tde;3. Can list multiple locations separated by a
+colon. If not set, falls back to $<envar>TDEDIR</envar></seg>
+</seglistitem>
+
+</segmentedlist>
+</para>
+<para>Don't <emphasis>need</emphasis> to be set, defaults work just fine.</para>
+<para>Running &tde;2 next to &tde;3? Point $<envar>TDEDIR</envar> to
+&tde; 2 and $<envar>TDEDIRS</envar> to &tde; 3.</para>
+
+<informalexample>
+<para>A staff member at a university could have the following
+settings:</para>
+<programlisting>
+TDEHOME='~/.trinity'
+TDEROOTHOME='/root/.trinity'
+TDEDIRS='/opt/kde_staff:/opt/trinity'
+</programlisting>
+
+</informalexample>
+
+</sect1>
+
+<sect1 id="user-profiles">
+<title>User Profiles</title>
+
+<para>In the previous example <filename
+class="directory">/opt/kde_staff</filename> contained additional settings
+and applications for staff members. <quote>User Profiles</quote> allow you
+to add this directory only for certain users and not for others.  Add the
+following to <filename>/etc/tderc</filename>:</para>
+
+<programlisting>
+[Directories-staff]
+prefixes=/opt/kde_staff
+</programlisting>
+
+<para>This creates a profile named <quote>staff</quote> that adds the
+<filename class="directory">/opt/kde_staff</filename> directory
+tree. (Note that &SuSE; &Linux; uses
+<filename>/etc/kde3rc</filename> instead of
+<filename>/etc/tderc</filename>. Now that we have a named profile it
+can be assigned to users.</para>
+
+<para>To map profiles to users a mapping file needs to be specified in
+<filename>/etc/tderc</filename>:</para>
+
+<programlisting>
+[Directories]
+userProfileMapFile=/etc/kde-user-profile
+</programlisting>
+
+<para>It is now possible to assign a profile based on either the user name
+or based on the &UNIX; group the user is part of.</para>
+
+<para>To assign the staff profile to all users that are a member of the
+&UNIX; group staff_members add the following to
+<filename>/etc/kde-user-profile</filename>:</para>
+
+<programlisting>
+[General]
+groups=staff_members
+[Groups]
+staff_members=staff
+</programlisting>
+
+<para>It is also possible to assign a profile to a single user:</para>
+
+<programlisting>
+[Users]
+bastian=staff
+</programlisting>
+
+</sect1>
+
+<sect1 id="directory-layout-revisited">
+<title>Directory Layout Revisited</title>
+
+<para>Each directory tree used by &tde; has a fixed directory structure.
+Directories that are not relevant for a certain tree, or simply not used can
+be left out though. For example, directories used for temporary files are
+usually only found under <filename
+class="directory">$<envar>TDEHOME</envar></filename> but not in any other
+directory tree.</para>
+
+</sect1>
+
+<sect1 id="architecture-specific-directories">
+<title>Architecture-specific Directories</title>
+
+<para>Architecture (OS and CPU type) specific directories:</para>
+
+<variablelist>
+<varlistentry>
+<term><filename class="directory">bin</filename></term>
+<listitem><para>Used for &tde; executables.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">lib</filename></term>
+<listitem><para>Used for &tde; libraries.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">lib/trinity</filename></term>
+<listitem><para>This directory contains components, plugins, and other
+runtime loadable objects for use by &tde; 3.<replaceable>x</replaceable>
+applications.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="shared-directories">
+<title>Shared Directories</title>
+
+<para>Shared: Not architecture specific, can be shared between different
+archs.</para>
+
+<variablelist>
+<varlistentry>
+<term><filename class="directory">share/applnk</filename></term>
+<listitem><para><literal role="extension">.desktop</literal> files for
+&tde;-menu (old)</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/applications</filename></term>
+<listitem><para><literal role="extension">.desktop</literal> files for
+&tde;-menu</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/apps</filename></term>
+<listitem><para>Contains application-specific data files. Each
+application has a sub-directory here for storing additional data
+files.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/config</filename></term>
+<listitem><para>Configuration files. Configuration files are normally
+named after the application they belong to plus the letters
+<quote>rc</quote>. A special case is <filename>kdeglobals</filename>.
+This file is read by all &tde; applications.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename
+class="directory">share/config/session</filename></term>
+<listitem><para>This directory is used by session management and is
+normally only available under <filename
+class="directory">$<envar>TDEHOME</envar></filename>. At the end of a
+session &tde; applications store their state here. The file names
+consist of the name of the application followed by a number. The
+session manager <command>ksmserver</command> stores references to
+these numbers when saving a session in
+<filename>ksmserverrc</filename>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/doc/tde/HTML</filename></term>
+<listitem><para>This directory contains documentation for &tde;
+applications. Documentation is categorized by language and the
+application it belongs to. Normally at least two files can be found in
+a directory: <filename>index.docbook</filename>, which contains the
+documentation in the unformatted DocBook format, and
+<filename>index.cache.bz2</filename>, which contains the same
+documentation formatted as <command>bzip2</command>-compressed
+&HTML;. The &HTML; version is used by &khelpcenter;. If the &HTML;
+version is missing, &khelpcenter; will regenerate it from the DocBook
+version but this is a time-consuming process.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/icons</filename></term>
+<listitem><para>Under this directory icons are stored. Icons are
+categorized by theme, dimension and usage category.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/mimelnk</filename></term>
+<listitem><para>In this directory,<literal
+role="extension">.desktop</literal> files that describe &MIME; types
+are stored. &tde; uses &MIME; types to identify the type of a
+file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/services</filename></term>
+<listitem><para>This directory contains <literal
+role="extension">.desktop</literal> files that describe services. Services
+are like applications but are usually launched by other applications instead
+of the user. Services do not appear in the &tde; menu.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/servicetypes</filename></term>
+<listitem><para>This directory contains <literal
+role="extension">.desktop</literal> files that describe
+servicetypes. A servicetype usually represents a certain programming
+interface. Applications and Services include in their <literal
+role="extension">>.desktop</literal> files the servicetypes that they
+provide.</para> </listitem></varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/sounds</filename></term>
+<listitem><para>This directory contains sound files.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/templates</filename></term>
+<listitem><para>This directory contains templates for creating files
+of various types. A template consists of a <literal
+role="extension">.desktop</literal> file that describes the file and
+that includes a reference to a file in the <filename
+class="directory">.source</filename> sub-directory. The templates in
+this directory appear in the <guimenu>Create New</guimenu> menu
+available on the desktop and in the file browser. When a user selects
+a template from the menu its source file is copied.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename class="directory">share/wallpapers</filename></term>
+<listitem><para>This directory contains images that can be used as
+background picture</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="host-specific-directories">
+<title>Host-specific Directories</title>
+
+<para>There are three host-specific directories that are usually
+symlinked to other locations. If the directories do not already exist,
+the following symlinks and directories will be created using the
+<command>lnusertemp</command> utility:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><filename>$<envar>TDEHOME</envar>/socket-$<envar>HOSTNAME</envar></filename></term>
+<listitem><para>Usually <filename
+class="directory">/tmp/tdesocket-$<envar>USER</envar>/</filename>, this
+is used for various &UNIX; sockets.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>$<envar>TDEHOME</envar>/tmp-$<envar>HOSTNAME</envar></filename></term>
+<listitem><para>Usually	<filename
+class="directory">/tmp/kde-$<envar>USER</envar>/</filename>, this is used for temporary files.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>$<envar>TDEHOME</envar>/cache-$<envar>HOSTNAME</envar></filename></term>
+<listitem><para>Usually <filename
+class="directory">/var/tmp/tdecache-$<envar>USER</envar>/</filename>,
+this is used for cached files.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>Since both <filename class="directory">/tmp</filename> and
+<filename class="directory">/var/tmp</filename> are world writable,
+there is a possibility that one of the above directories already
+exists but is owned by another user. In that case the
+<command>lnusertemp</command> utility will create a new directory with
+an alternative name and link to that instead.</para>
+
+</sect1>
+
+<sect1 id="configuration-files">
+<title>Configuration Files</title> <para>&tde; uses a simple
+text-based file format for all its configuration files. It consists of
+key-value pairs that are placed in groups.  All &tde; configuration
+files use <acronym>UTF</acronym>-8 encoding for text outside the
+<acronym>ASCII</acronym> range.</para>
+
+<para>The start of a group is indicated by a group name that is placed
+in square brackets. All the key-value entries that follow belong to
+the group. The group ends when either another group starts or when the
+end of the file is reached. Entries at the top of the
+file that are not preceded by a group name belong to the default
+group.</para>
+
+<informalexample><para>The following example shows a configuration
+file that consists of two groups. The first group contains the keys
+<varname>LargeCursor</varname> and <varname>SingleClick</varname>, the
+second group contains the keys <varname>Show hidden files</varname>
+and <varname>Sort by</varname>:</para>
+
+<programlisting>
+[TDE]
+LargeCursor=false
+SingleClick=true
+</programlisting>
+
+<programlisting>
+[KFileDialog Settings]
+Show hidden files=false
+Sort by=Name
+</programlisting>
+</informalexample>
+
+<para>Entries in a group consist of a key and value separated by an equals
+sign. The key can contain spaces and may be followed by options placed in
+square brackets.  The part after the equals sign is the value of the
+entry. Any white space surrounding the equals sign is ignored, as is any
+trailing white space. Put more concisely, the format is:</para>
+
+<programlisting>
+<replaceable>entry</replaceable>=<replaceable>value</replaceable>
+</programlisting>
+
+<para>If a value is supposed to include a space at the begin or end
+then this can be achieved by using a backslash followed by an
+<quote>s</quote>.</para>
+
+<para>There are several other backslash codes; here is a complete
+list:
+<itemizedlist>
+<listitem><para><token>\s</token> can be used as space</para>
+</listitem>
+<listitem><para><token>\t</token> can be used to include a tab</para>
+</listitem>
+<listitem><para><token>\r</token> for a carriage return character</para>
+</listitem>
+<listitem><para><token>\n</token> for a linefeed character (new line)</para>
+</listitem>
+<listitem><para><token>\\</token> to include the backslash itself</para>
+</listitem>
+</itemizedlist></para>
+
+<informalexample><para>In the following example the value of the
+<varname>Caption</varname> entry starts with two spaces while the
+<varname>Description</varname> entry contains three lines of
+text. Linefeeds in backslash notation are used to separate the
+different lines.</para>
+
+<programlisting>
+[Preview Image]
+Caption=\s My Caption
+Description=This is\na very long\ndescription.
+</programlisting>
+</informalexample>
+
+<para>Empty lines in configuration files are ignored, as are lines that
+start with a hash mark (<quote>#</quote>). The hash mark can be used to add
+comments to configuration files. It should be noted that when a &tde;
+application updates a configuration file the comments are
+<emphasis>not</emphasis> preserved.</para>
+
+<para>There can be multiple configuration files with the same name in the
+<filename class="directory">share/config</filename> sub-directory of the
+various &tde; directory trees. In this case the information of all these
+configuration files is combined on a key-by-key basis.  If the same key
+within a certain group is defined in more than one place, the key value read
+from the directory tree with the highest precedence will be used.
+Configuration files under <filename
+class="directory">$<envar>TDEHOME</envar></filename> always have the highest
+precedence.  If a key in a certain group is defined multiple times in a
+single file, the value of the last entry is used.</para>
+
+<informalexample>
+<para>If <filename>$<envar>HOME</envar>/.trinity/share/config/foobar</filename>
+contains:
+<programlisting>
+[MyGroup]
+Color=red
+Shape=circle
+</programlisting>
+and <filename>/etc/opt/trinity/share/config/foobar</filename> contains
+<programlisting>
+[MyGroup]
+Color=blue
+Position=10,10
+</programlisting>
+the result will be:
+<programlisting>
+[MyGroup]
+Color=red
+Shape=circle
+Position=10,10
+</programlisting>
+</para>
+</informalexample>
+
+<informalexample>
+<para>If
+	<filename>$<envar>HOME</envar>/.trinity/share/config/foobar</filename>
+	contains
+<programlisting>
+[MyGroup]
+Color=red
+Shape=circle
+[MyGroup]
+Color=green
+</programlisting>
+and <filename>/opt/kde_staff/share/config/foobar</filename> contains
+<programlisting>
+[MyGroup]
+Color=purple
+Position=20,20
+</programlisting>
+and <filename>/etc/opt/trinity/share/config/foobar</filename> contains
+<programlisting>
+[MyGroup]
+Color=blue
+Position=10,10
+</programlisting>
+the result will be:
+<programlisting>
+[MyGroup]
+Color=green
+Shape=circle
+Position=20,20
+</programlisting>
+</para>
+</informalexample>
+
+<para>To prevent users being able to override default settings,
+settings can be marked immutable. Settings can be made immutable
+individually, per group or per file. An individual entry can be locked
+down by adding <userinput>[$i]</userinput> behind the key, &eg;:
+<programlisting>
+Color[$i]=blue
+</programlisting>
+</para>
+<para>A group of entries can be locked down by placing
+<userinput>[$i]</userinput> behind the group name, &eg;:
+<programlisting>
+[MyGroup][$i]
+</programlisting>
+</para>
+<para>To lock down the entire file, start the file with
+<userinput>[$i]</userinput> on a single line, &ie;:
+<programlisting>
+[$i]
+</programlisting>
+</para>
+
+<informalexample>
+<para>If
+	<filename>$<envar>HOME</envar>/.trinity/share/config/foobar</filename>
+	contains:
+<programlisting>
+[MyGroup]
+Color=red
+Shape=circle
+</programlisting>
+and <filename>/etc/opt/trinity/share/config/foobar</filename> contains:
+<programlisting>
+[MyGroup][$i]
+Color=blue
+Position=10,10
+</programlisting>
+the result will be:
+<programlisting>
+[MyGroup]
+Color=blue
+Position=10,10
+</programlisting>
+</para>
+</informalexample>
+
+<informalexample><para>If
+	<filename>$<envar>HOME</envar>/.trinity/share/config/foobar</filename>
+	contains:
+<programlisting>
+[MyGroup]
+Color=red
+Shape=circle
+</programlisting>
+and <filename>/opt/kde_staff/share/config/foobar</filename> contains
+<programlisting>
+[MyGroup]
+Color=purple
+Shape=rectangle
+</programlisting>
+and <filename>/etc/opt/trinity/share/config/foobar</filename> contains
+<programlisting>
+[MyGroup][$i]
+Color=blue
+Position=10,10
+</programlisting>
+the result will be
+<programlisting>
+[MyGroup]
+Color=purple
+Shape=rectangle
+Position=10,10
+</programlisting>
+</para>
+</informalexample>
+
+
+<para>So-called <quote>Shell Expansion</quote> can be used to provide more
+dynamic default values. With shell expansion the value of a configuration
+key can be constructed from the value of an environment variable or from the
+output of a shell command.  To enable shell expansion for a configuration
+entry, the key must be followed by <token>[$e]</token>.  Normally the
+expanded form is written into the user's configuration file after first use.
+To prevent that, it is recommend to lock the configuration entry down by
+using <token>[$ie]</token>.  The user can't change it then of course.</para>
+
+<informalexample>
+<para>In the following example the value for the <varname>Host</varname>
+entry is determined by the output of the <command>hostname</command>
+program. This setting is also locked down to ensure that the value is always
+determined dynamically.</para>
+
+<para>The value for the <varname>Email</varname> entry is determined by
+filling in the values of the $<envar>USER</envar> and $<envar>HOST</envar>
+environment variables. When <systemitem class="username">joe</systemitem> is
+logged in on <systemitem class="systemname">joes_host</systemitem> this will
+result in a value equal to <literal>joe@joes_host</literal>. The setting is
+not locked down.</para>
+
+<programlisting>
+[Mail Settings]
+Host[$ie]=$(hostname)
+Email[$e]=${USER}@${HOST}
+</programlisting>
+</informalexample>
+
+<para>Most configuration entries can be indexed with a language code. In
+this case, the language that the user has selected for use on the desktop is
+used to look up the key value. If the default language (American English)
+has been selected or if there is no index that corresponds to the selected
+language, the key entry without index is used.</para>
+
+<informalexample>
+<para>In the following example the value of the <varname>Caption</varname>
+entry depends on the language. If the user has selected French as language
+(language code <literal>fr</literal>) the value of the entry will be
+<quote>Ma L&eacute;gende</quote>. In all other cases the value <quote>My
+Caption</quote> will be used.</para>
+
+<programlisting>
+[Preview Image]
+Caption=My Caption
+Caption[fr]=Ma L&eacute;gende
+</programlisting>
+</informalexample>
+
+<informalexample>
+<para>In this example the value of the <varname>Caption</varname> entry
+depends on the language. If the user has selected French as language
+(language code <literal>fr</literal>) the value of the entry will be
+<quote>Ma L&eacute;gende.</quote> In all other cases the value <quote>My
+Caption</quote> will be used.</para>
+
+<programlisting>
+[Preview Image]
+Caption=My Caption
+Caption[fr]=Ma L&eacute;gende
+</programlisting>
+</informalexample>
+
+<para>In general the entries that can appear in a configuration file are not
+documented.  With &tde; 3.2 a start has been made to change this. In
+<filename
+class="directory">$<envar>TDEDIR</envar>/share/config.kcfg</filename>, files
+can be found that provide a formal description of the possible entries in a
+configuration file. These are used by the new &tde; Configuration Editor
+when available.</para>
+
+<informalexample>
+<para>Here is an example &XML; configuration file:
+<programlisting>
+<markup>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd"&gt;
+&lt;kcfg&gt;
+    &lt;kcfgfile name="korganizerrc"/&gt;
+    &lt;group name="General"&gt;
+         &lt;entry type="Bool" key="Auto Save"&gt;
+             &lt;label&gt;Enable automatic saving of calendar&lt;/label&gt;
+             &lt;default&gt;true&lt;/default&gt;
+         &lt;/entry&gt;
+         &lt;entry type="Int" key="Auto Save Interval"&gt;
+             &lt;default&gt;10&lt;/default&gt;
+         &lt;/entry&gt;
+    &lt;/group&gt;
+&lt;/kcfg&gt;
+</markup>
+</programlisting>
+</para>
+<para>It has the same effect as:
+<programlisting>
+[General]
+Auto Save=false
+Auto Save Interval=25
+</programlisting>
+</para>
+</informalexample>
+
+</sect1>
+
+<sect1 id="tde-startup-sequence">
+<title>&tde; Startup Sequence</title>
+
+<sect2 id="tdm">
+<title>&tdm;</title>
+
+<para>Always runs as <systemitem class="username">root</systemitem>! Uses
+<filename>$<envar>TDEDIR</envar>/share/config/tdmrc</filename> and
+<filename>/etc/X11/xdm/Xservers</filename>. The latter contains entries
+like:</para>
+
+<programlisting>
+:0 local /usr/X11R6/bin/X :0 vt07
+</programlisting>
+
+<para>Relevant startup files are also: </para>
+<simplelist>
+<member>
+[X-*-Core] section in <filename>tdmrc</filename>
+</member>
+<member>
+Setup - <filename>/etc/X11/xdm/Xsetup</filename>
+</member>
+<member>
+User enters username &amp; password
+</member>
+<member>
+Startup - <filename>/etc/X11/xdm/Xstartup</filename> - prepare as root
+</member>
+<member>
+Session - <filename>/etc/X11/xdm/Xsession</filename> - starts session as user
+</member>
+<member>
+= For a TDE session: <command>kde</command> or <command>starttde</command>
+</member>
+<member>
+= If present <filename>~/.xsession</filename> or <filename>~/.xinitrc</filename>
+</member>
+<member>
+Reset - <filename>/etc/X11/xdm/Xreset</filename> - after session finished
+</member>
+</simplelist>
+
+</sect2>
+
+<sect2 id="starttde">
+<title>The &tde; Startup Script: <command>starttde</command></title>
+
+<para>The &tde; startup sequence starts with the
+<filename>starttde</filename> script. In most cases this script gets called
+from the display manager (&tdm;) once the user has been authenticated. Their
+are two very important lines in the <filename>starttde</filename>
+script:</para>
+
+<programlisting>
+LD_BIND_NOW=true tdeinit +kcminit +knotify and kwrapper
+ksmserver $TDEWM
+</programlisting>
+
+<para>The first line starts the <command>tdeinit</command> master process.
+The <command>tdeinit</command> master process is used to start all other
+&tde; processes.  It show up in the output of <command>ps
+<option>aux</option></command> as <computeroutput>tdeinit:
+Running...</computeroutput>. The arguments after <command>tdeinit</command>
+are the names of additional processes to be started.  The <token>+</token>
+indicates that <command>tdeinit</command> needs to wait till the process has
+finished.  <command>tdeinit</command> also starts
+<command>dcopserver</command>, <command>tdelauncher</command> and
+<command>kded</command>.</para>
+
+<para>The second of the two lines asks <command>tdeinit</command> to start
+the <command>ksmserver</command> session manager process.  The session
+manager determines the lifetime of the session. When this process exits, the
+user is logged out.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="background-processes">
+<title>Background Processes</title>
+
+<para>All &tde; background services are user-specific: unlike system daemons
+they are not shared between users. As well as being unique per user they are
+also unique per X-server display. The processes are:</para>
+
+<variablelist>
+<varlistentry>
+<term><command>dcopserver</command></term>
+<listitem><para>Desktop communication</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kded</command></term>
+<listitem><para>Generic service daemon.</para>
+<para>Triggers <link linkend="tdesycoca">Sycoca</link> database updates when
+needed</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kcminit</command></term>
+<listitem><para>Initialization service</para>
+<para>See <xref linkend="kcminit"/> for more information.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>tdelauncher</command></term>
+<listitem><para>Program launch (this is <emphasis>not</emphasis> the
+<keycombo action="simul">&Alt;<keycap>F2</keycap>
+</keycombo>dialog!)</para>
+<para>See <xref linkend="tdelauncher"/> for more information.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>knotify</command></term>
+<listitem><para>User notifications.</para>
+<para>See <xref linkend="knotify"/> for more information.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>ksmserver</command></term>
+<listitem><para>Session management</para>
+<para>See <xref linkend="ksmserver"/> for more information.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<sect2 id="tdeinit">
+<title><command>tdeinit</command></title>
+<para><command>tdeinit</command> is used to start all other &tde;
+programs. <command>tdeinit</command> can start normal binary program files
+as well as <command>tdeinit</command> loadable modules
+(<acronym>KLM</acronym>s).  <acronym>KLM</acronym>s work just like binary
+program files but can be started more efficiently.  <acronym>KLM</acronym>s
+live in <filename
+class="directory">$<envar>TDEDIR</envar>/lib/trinity</filename></para>
+
+<para>The drawback is that programs started this way appear as
+<computeroutput><command>tdeinit</command></computeroutput> in the output of
+<command>top</command> and <command>ps</command>. Use <command>top
+<option>-c</option></command> or <command>ps <option>aux</option></command>
+to see the actual program name:</para>
+
+<screen>
+<prompt>%</prompt><userinput><command>ps <option>aux</option></command></userinput>
+<computeroutput>
+waba     23184  0.2  2.1 23428 11124 ?	S    21:41   0:00 tdeinit: Running...
+waba     23187  0.1  2.1 23200 11124 ?	S    21:41   0:00 tdeinit: dcopserver --nosid
+waba     23189  0.2  2.4 25136 12496 ?	S    21:41   0:00 tdeinit: tdelauncher
+waba     23192  0.7  2.8 25596 14772 ?	S    21:41   0:00 tdeinit: kded
+waba     23203  0.8  3.4 31516 17892 ?	S    21:41   0:00 tdeinit:
+knotify
+</computeroutput>
+</screen>
+
+<para><computeroutput>tdeinit: Running...</computeroutput> indicates the
+master <command>tdeinit</command> process. The other processes listed are
+programs started as <acronym>KLM</acronym>s.</para>
+
+<para>When <command>tdeinit</command> starts for the first time it will
+launch <command>dcopserver</command>, <command>tdelauncher</command>, and
+<command>kded</command>, as well as any additional programs specified on its
+command line in the <command>starttde</command> script, normally
+<command>kcminit</command> and <command>knotify</command>.</para>
+
+</sect2>
+
+<sect2 id="dcopserver">
+<title><command>dcopserver</command></title>
+
+<para><command>dcopserver</command> is a daemon which provides inter-process
+communication (&DCOP;) facilities to all &tde; applications. The &DCOP;
+facilities are accessible from the command shell via the
+<command>dcop</command> command line tool. &DCOP; is essential for all &tde;
+applications.</para>
+
+<para>Some related files:</para>
+
+<variablelist>
+<varlistentry>
+<term><filename>$<envar>HOME</envar>/.DCOPserver_$<envar>HOSTNAME</envar>_$<envar>DISPLAY</envar></filename></term>
+<listitem><para>&eg; <filename>.DCOPserver_linux__0</filename>.	Controlled by $<envar>DCOPAUTHORITY</envar></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>/tmp/.ICE-unix/dcop<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename></term>
+<listitem><para>&eg; <filename>dcop7634-1069677856</filename>. This is
+the file that the <filename>DCOPserver</filename> file above points to.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>$<envar>HOME</envar>/.ICEauthority</filename></term>
+<listitem><para>Authorization information controlled by
+$<envar>ICEAUTHORITY</envar></para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="kcminit">
+<title>kcminit</title>
+
+<para><command>kcminit</command> executes initialization services during
+startup. Initialization services are specified in the .desktop files of
+applications or services via the <varname>X-TDE-Init</varname> line:</para>
+
+<programlisting>
+[Desktop Entry]
+Encoding=UTF-8
+Exec=tdecmshell energy
+Icon=energy_star
+Type=Application
+X-TDE-Library=energy
+X-TDE-Init=energy
+</programlisting>
+
+<para>Initialization services are typically used for initializing
+hardware based on user-specified settings.</para>
+
+<para><userinput><command>kcminit
+<option>--list</option></command></userinput> can be used to show all
+initialization services and <userinput><command>kcminit
+<replaceable>service</replaceable></command></userinput> can be used to
+execute a single service explicitly. This can be useful when investigating
+startup problems.</para>
+
+</sect2>
+
+<sect2 id="tdelauncher">
+<title><command>tdelauncher</command></title>
+
+<para><command>tdelauncher</command> is a daemon which is responsible for
+service activation within &tde;. It operates in close connection with the
+<command>tdeinit</command> master process to start new processes. &tde;
+applications communicate with <command>tdelauncher</command> over &DCOP; in
+order to start new applications or services.</para>
+
+<para>Best known from the error message: <computeroutput><errortext>
+TDELauncher could not be reached via DCOP </errortext></computeroutput> which
+either indicates a serious problem with the <command>dcopserver</command> or
+that <command>tdelauncher</command> crashed.</para>
+
+<para><command>tdelauncher</command> can be restarted by restarting
+<command>tdeinit</command> from a console window. Make sure that
+$<envar>HOME</envar>, $<envar>DISPLAY</envar> and the various
+$<envar>TDEDIR(S)</envar> are set correctly when doing so!</para>
+
+</sect2>
+
+<sect2 id="knotify">
+<title><command>knotify</command></title>
+
+<para>The primary task of <command>knotify</command> is to relay sound
+notifications to the sound server, it also provides alternative notification
+methods.</para>
+
+</sect2>
+
+
+</sect1>
+
+<sect1 id="ksmserver">
+<title>KSMServer</title>
+
+<para><command>ksmserver</command> is &tde;'s session manager. On startup
+the session manager launches auto-start applications and restores
+applications from the previous session.  The applications to auto-start are
+indicated by <literal role="extension">.desktop</literal> files in the
+<filename
+class="directory">$<envar>TDEDIR</envar>/share/autostart</filename>
+directory.  Whether or not to auto-start an application can be made
+conditional upon some configuration entry determined by the
+<varname>X-TDE-autostart-condition</varname> entry in the <literal
+role="extension">.desktop</literal> file.</para>
+
+<informalexample>
+<para>The <filename>ktip.desktop</filename> file for example
+contains:</para>
+
+<programlisting>
+X-TDE-autostart-condition=ktiprc:TipOfDay:RunOnStart:true
+</programlisting>
+
+<para>This means that the <filename>ktiprc</filename> configuration
+file is checked for a <varname>RunOnStart</varname> entry in the
+<varname>[TipOfDay]</varname> section. If no such entry is found,
+<literal>true</literal> is assumed, which means that
+<application>ktip</application> is one of the applications that is
+auto-started by default.</para>
+</informalexample>
+
+<para>Some of the applications auto-started by <command>ksmserver</command>
+are:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><command>kdesktop</command></term>
+<listitem><para>The &tde; desktop</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>&kicker;</command></term>
+<listitem><para>The &tde; panel</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>ktip</command></term>
+<listitem><para>A tip of the day program</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kwrited</command></term>
+<listitem><para>A utility to receive system messages sent to the user</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>&klipper;</term>
+<listitem><para>A clipboard utility that docks in the panel</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><command>kalarm</command></term>
+<listitem><para>A utility that warns about upcoming events and appointments</para>
+</listitem>
+
+</varlistentry>
+</variablelist>
+
+<para><command>kdesktop</command> in its turn automatically starts
+applications stored in <filename
+class="directory">$<envar>TDEHOME</envar>/Autostart</filename>. <command>kdesktop</command>
+will automatically open any files stored in this directory including
+documents, binary files or applications in the form of <literal
+role="extension">.desktop</literal> files.</para>
+
+<para>The &tde; session manager also restores one of the previous
+sessions. A session contains a collection of applications as well as
+application-specific information that reflects the state of the applications
+at the time the session was saved.  Sessions are stored in the
+<filename>ksmserverrc</filename> configuration file which contains
+references to application-specific state information. The
+application-specific state information is saved in <filename
+class="directory">$<envar>TDEHOME</envar>/share/config/session</filename>.
+The state information of &twin; contains the location of the application
+windows of all the other applications in the session.
+</para>
+
+</sect1>
+
+<sect1 id="environment-variables">
+<title>Environment variables</title>
+
+<para>Some important environment variables used by &tde;:</para>
+
+<variablelist>
+
+<varlistentry>
+<term>$<envar>TDEDIR</envar></term>
+<listitem><para>Has to be set if
+<envar>TDEDIRS</envar> is not set and has to point to the root of the
+&tde; installation tree. Allows &tde; to find its data like icons,
+menus and libraries.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDEDIRS</envar></term>
+<listitem><para>Overrides <envar>TDEDIR</envar> and allows you to specify
+multiple directories where &tde; searches for its data. Useful if you want
+or have to install some programs to a different prefix than the rest of
+&tde;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><envar>$TDEHOME</envar></term><listitem><para>If
+not set, &tde; uses <filename class="directory">~/.trinity</filename> as
+the directory where personal data is stored.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDEROOTHOME</envar></term><listitem><para>If
+not set, &tde; uses <filename class="directory">~root/.trinity</filename>
+as the directory for <systemitem class="username">root</systemitem>'s
+personal data. Was introduced to prevent &tde; from accidently
+overwriting user data with root permissions when the user runs a &tde;
+program after switching with <command>su</command> to <systemitem
+class="username">root</systemitem>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDEWM</envar></term><listitem><para>If the
+<envar>TDEWM</envar> environment variable has been set, then it will
+be used as &tde;'s window manager within the
+<command>starttde</command> script instead of &twin;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_LANG</envar></term><listitem><para>Overrides
+the &tde; language configuration, &eg; <userinput>TDE_LANG=fr kprogram
+&amp;</userinput> starts a program with French translation if the
+necessary files are installed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_MULTIHEAD</envar></term><listitem><para>Set
+this variable to <literal>true</literal> to indicate that &tde; is running
+on a multi-head system.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_FORK_SLAVES</envar></term>
+<listitem><para>Set this variable to spawn
+<acronym>TDEIO</acronym>-slaves directly from the application process
+itself. By default <acronym>TDEIO</acronym>-slaves are spawned using
+<command>tdelauncher</command>/<command>tdeinit</command>. This option is
+useful if the <acronym>TDEIO</acronym>-slave should run in the same
+environment as the application. This can be the case with
+<application>Clearcase</application>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_HOME_READONLY</envar></term>
+<listitem><para>Set this variable to indicate that your home directory is
+mounted as read-only.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_NO_IPV6</envar></term><listitem><para>
+Set this variable to disable <acronym>IPv6</acronym>
+support and <acronym>IPv6</acronym> <acronym>DNS</acronym>
+lookups.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_IS_PRELINKED</envar></term><listitem><para>
+Set this variable to indicate that you have prelinked
+your &tde; binaries and libraries. This will turn off
+<command>tdeinit</command>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_UTF8_FILENAMES</envar></term><listitem><para>If
+this environment variable is set, &tde; assumes all filenames are in
+<acronym>UTF-8</acronym> encoding regardless of the current C
+locale.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDE_FULL_SESSION</envar></term><listitem><para>
+Automatically set to true by &tde; startup, it is used
+by &eg; &konqueror; to know if it should consider remaining in memory
+for future re-use when being closed. If not set, &konqueror; will exit
+after being closed (&eg; &tdesu; does that, it's also useful for
+debugging).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDESYCOCA</envar></term><listitem><para>Allows
+you to specify the path and the name of the generated &tde; system
+configuration cache file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDETMP</envar></term><listitem><para>Allows
+to specify another path than <filename
+class="directory">/tmp</filename> where &tde; stores its temporary
+files.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>TDEVARTMP</envar></term><listitem><para>Allows
+to specify another path than <filename
+class="directory">/var/tmp</filename> where &tde; stores its variable
+files.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>XDG_DATA_HOME</envar></term><listitem><para>
+Defines the base directory relative to which user-specific
+data files should be stored. Default is <filename
+class="directory">$<envar>HOME</envar>/.local/share</filename></para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>XDG_DATA_DIRS</envar></term><listitem><para>
+Defines the preference-ordered set of base directories to
+search for data files in addition to the <filename
+class="directory">$<envar>XDG_DATA_HOME</envar></filename> base
+directory. Default is
+<literal>/usr/local/share/:/usr/share/</literal></para>
+
+<para>&tde; adds locations from $<envar>TDEDIRS</envar> and profiles
+as well.  Used for <literal role="extension">.desktop</literal> and
+<literal role="extension">.directory</literal> menu files. <literal
+role="extension">.desktop</literal> files under <filename
+class="directory">$<envar>XDG_DATA_DIRS</envar>/applications</filename>.
+<literal
+role="extension">.directory</literal> files under
+$XDG_DATA_DIRS/desktop-directories
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>XDG_CONFIG_HOME</envar></term><listitem><para>
+(&tde; 3.2) - Defines the base directory relative to which user
+specific configuration files should be stored. Default is
+<filename class="directory">$<envar>HOME</envar>/.config</filename>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>$<envar>XDG_CONFIG_DIRS</envar></term><listitem><para>
+(&tde; 3.2) - Defines the preference-ordered set of base directories
+to search for configuration files in addition to the $<envar>XDG_CONFIG_HOME</envar>
+base directory. The default is <filename class="directory">/etc/xdg</filename> &tde; adds locations from
+$<envar>TDEDIRS</envar> and profiles as well. Used by <literal role="extension">.menu</literal> descriptions in
+<filename class="directory">$<envar>XDG_CONFIG_DIRS</envar>/menus</filename>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="the-tdeinit-mystery">
+<title>The tdeinit Mystery</title>
+
+<!-- FIXME: Add more words. Fix markup -->
+
+<para><command>tdeinit</command> is used to start all other &tde;
+programs. <command>tdeinit</command> can start normal binary program f iles
+as well as <command>tdeinit</command> loadable modules
+(<acronym>KLM</acronym>s).  <acronym>KLM</acronym>s work just like binary
+program files but can be started more efficiently.  <acronym>KLM</acronym>s
+live in <filename
+class="directory">$<envar>TDEDIR</envar>/lib/trinity</filename></para>
+
+<para>The drawback is that programs started this way appear as
+<computeroutput><command>tdeinit</command></computeroutput> in the
+output of <command>top</command> and <command>ps</command>. Use
+<command>top <option>-c</option></command> or <command>ps
+<option>aux</option></command> to see the actual program name:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>ps aux | grep bastian</command></userinput>
+<computeroutput>
+bastian  26061  0.0  2.2 24284 11492 ?       S    21:27   0:00 tdeinit: Running...
+bastian  26064  0.0  2.2 24036 11524 ?       S    21:27   0:00 tdeinit: dcopserver
+bastian  26066  0.1  2.5 26056 12988 ?       S    21:27   0:00 tdeinit: tdelauncher
+bastian  26069  0.4  3.2 27356 16744 ?       S    21:27   0:00 tdeinit: kded
+bastian  26161  0.2  2.7 25344 14096 ?       S    21:27   0:00 tdeinit: ksmserver
+bastian  26179  1.1  3.4 29716 17812 ?       S    21:27   0:00 tdeinit: kicker
+bastian  26192  0.4  3.0 26776 15452 ?       S    21:27   0:00 tdeinit: klipper
+bastian  26195  1.0  3.5 29200 18368 ?       S    21:27   0:00 tdeinit: kdesktop
+</computeroutput>
+</screen>
+<para>As you might have noticed, this has another side effect, making it
+difficult to kill a process that is causing trouble:</para>
+
+<screen><prompt>%</prompt> <userinput><command>killall kdesktop</command></userinput>
+<computeroutput>kdesktop: no process killed</computeroutput></screen>
+
+<para>You might be tempted to try <userinput><command>killall
+tdeinit</command></userinput>, but killing all tdeinit processes will have
+the effect of shutting down all of &tde;. In effect, total
+destruction!</para>
+
+<para>There are two simple solutions to this:</para>
+
+<screen><prompt>%</prompt> <userinput><command>tdekillall kdesktop</command></userinput>
+or good old
+<prompt>%</prompt> <userinput><command>kill 26195</command></userinput></screen>
+<para><command>tdekillall</command> is part of the &tde; <acronym>SDK</acronym>
+package.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="customizing-kde">
+<title>Customizing &tde;</title>
+
+
+<sect1 id="desktop-icons">
+<title>Desktop Icons</title>
+
+<para>&tde; uses several types of icons:</para>
+<itemizedlist>
+<listitem><para>Documents</para>
+</listitem>
+<listitem><para>Links to Websites (using <literal role="extension">.desktop</literal> file)</para>
+</listitem>
+<listitem><para>Links to Applications (using <literal role="extension">.desktop</literal> file)</para>
+</listitem>
+<listitem><para>Devices - Disks, Partitions &amp; Peripherals:
+<itemizedlist>
+<listitem><para>Explicit using <literal role="extension">.desktop</literal> file</para>
+</listitem>
+<listitem><para>Automatic via devices:// io-slave</para>
+</listitem>
+</itemizedlist>
+</para>
+</listitem>
+<listitem><para>Vendor-specific (&eg; &SuSE;'s My Computer)</para>
+</listitem>
+</itemizedlist>
+
+<sect2 id="desktop-icons-websites">
+<title>Websites</title>
+<para>
+Links to Websites using <literal role="extension">.desktop</literal>
+file: <menuchoice><guimenu>Create
+New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to
+Location (URL)</guimenuitem></menuchoice>. Change Icon using
+<guilabel>Properties</guilabel> dialogs.  The resulting <literal
+role="extension">.desktop</literal> file:
+<programlisting>
+[Desktop Entry]
+Encoding=UTF-8
+Icon=/opt/trinity/share/apps/kdesktop/pics/ksslogo.png
+Type=Link
+URL=http://www.kde.org/
+</programlisting>
+</para>
+</sect2>
+
+<sect2 id="desktop-icons-applications">
+<title>Applications</title>
+
+<para>Links to Applications using <literal
+role="extension">.desktop</literal> file: <menuchoice><guimenu>Create
+New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to
+Application</guimenuitem></menuchoice>. You must provide details
+yourself. Drag from &tde; Menu: Either copy or link (creates symlink),
+much easier</para>
+
+<!-- Perhaps legacy and translated should be the other way around, but -->
+<!-- this is how it appears in Waldo's presentation. Need to check -->
+<!-- this -->
+
+<programlisting>
+[Desktop Entry]<co id="boilerplate"/>
+Encoding=UTF-8
+GenericName=IRC Client<co id="generic-desc"/>
+GenericName[af]=Irc Kli&euml;t
+GenericName[de]=IRC Programm
+...
+GenericName[zu]=Umthengi we IRC<co id="legacy"/>
+SwallowExec=<co id="translated"/>
+Name=KSirc
+Name[af]=Ksirc
+Name[de]=KSirc
+...
+</programlisting>
+
+<calloutlist>
+<callout arearefs="boilerplate"><para>Boiler plate</para>
+</callout>
+<callout arearefs="generic-desc"><para>Translated generic description, not used on desktop</para>
+</callout>
+<callout arearefs="legacy"><para>Legacy, can be removed</para>
+</callout>
+<callout arearefs="translated"><para>Translated name as it appears on desktop</para>
+</callout>
+</calloutlist>
+
+<para>Desktop Icons</para>
+<programlisting>
+...
+Name[zu]=Ksirc
+MimeType=<co id="co-mimetype"/>
+Exec=ksirc %i %m<co id="co-exec"/>
+Icon=ksirc<co id="co-icon"/>
+TerminalOptions=<co id="co-terminaloptions"/>
+Path=<co id="co-path"/>
+Type=Application<co id="co-type"/>
+Terminal=0<co id="co-terminal"/>
+X-TDE-StartupNotify=true<co id="co-x-tde-startupnotify"/>
+X-DCOP-ServiceType=Multi<co id="co-x-dcop-servicetype"/>
+Categories=Qt;TDE;Network<co id="co-categories"/>
+</programlisting>
+
+<calloutlist>
+<callout arearefs="co-mimetype"><para>Supported &MIME; types, not used on
+desktop</para>
+</callout>
+<callout arearefs="co-exec"><para>The command line to execute</para>
+</callout>
+<callout arearefs="co-icon"><para>The icon, from icon theme or full path</para>
+</callout>
+<callout arearefs="co-terminaloptions"><para>Only used if terminal is
+needed</para>
+</callout>
+<callout arearefs="co-path"><para>Working directory for command</para>
+</callout>
+<callout arearefs="co-type"><para>More boiler plate</para>
+</callout>
+<callout arearefs="co-terminal"><para>Use true if terminal is needed,
+text application</para>
+</callout>
+<callout arearefs="co-x-tde-startupnotify"><para>Show bouncy cursor,
+disable if it doesn't work.</para>
+</callout>
+<callout arearefs="co-x-dcop-servicetype"><para>Has app started ok?
+Remove if it doesn't work</para>
+</callout>
+<callout arearefs="co-categories"><para>Categories for &tde; Menu, not
+used on desktop</para>
+</callout>
+</calloutlist>
+
+
+
+</sect2>
+
+<sect2 id="desktop-icons-exec">
+<title>The <varname>Exec</varname> option in <literal
+role="extension">.desktop</literal> files</title>
+
+<para>Following the command, you can have several place holders which will
+be replaced with the actual values when the actual program is run:
+<variablelist>
+<varlistentry>
+<term>%f</term> <listitem><para>A single file name; used when dropping
+file on icon, or with file associations.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%F</term>
+<listitem><para>A list of files; use for applications that can
+open several local files at once.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%u</term>
+<listitem><para>A single &URL;: if the app can
+handle &eg; &FTP; or &HTTP; &URL;s itself, otherwise &tde;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%U</term>
+<listitem><para>A list of
+&URL;s; will download the file first and pass a local file to the app
+(!!)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%d</term>
+<listitem><para>The folder of the file to open; useful if app needs to
+have file in current working directory.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%D</term>
+<listitem><para>A list of folders, not very practical.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%i</term>
+<listitem><para>The icon; <option>--icon</option> option; &tde; app
+will use icon from <varname>Icon</varname>= line in taskbar.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%m</term>
+<listitem><para>The mini-icon; legacy.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%c</term>
+<listitem><para>The caption; <option>--caption</option> option; &tde;
+app will use name from <varname>Name</varname>= line in
+taskbar.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+<informalexample>
+<para>Examples:
+<segmentedlist>
+<segtitle><varname>Exec</varname> line</segtitle>
+<segtitle>Command executed</segtitle>
+<seglistitem><seg>ksirc %i</seg><seg><command>ksirc --icon ksirc</command></seg>
+</seglistitem>
+<seglistitem><seg>cd %d; kedit $(basename %f)</seg><seg><command>cd /tmp; kedit file.txt</command></seg>
+</seglistitem>
+</segmentedlist>
+</para>
+</informalexample>
+
+<!--Dont' know what this refers to: -->
+<!--See What's This (Shift-F1) in Properties Dialog-->
+
+</sect2>
+
+<sect2 id="desktop-icons-devices">
+<title>Devices</title>
+<para>
+Links to Devices using <literal role="extension">.desktop</literal> file:
+o Create New -> Device
+
+</para>
+</sect2>
+
+<sect2 id="where-to-define">
+<title>Where to Define</title>
+
+<para>Many places to define Desktop Icons:
+<itemizedlist>
+
+<listitem><para><filename class="directory">~/Desktop</filename>:
+copied from <filename
+class="directory">/etc/skel/Desktop</filename></para></listitem>
+
+<listitem><para><filename
+class="directory">$<envar>TDEDIR</envar>/apps/kdesktop/Desktop</filename>
+(merged)</para></listitem>
+
+<listitem><para><filename
+class="directory">$<envar>TDEDIR</envar>/apps/kdesktop/DesktopLinks</filename>
+(copied)</para></listitem>
+
+<listitem><para>Device Icons (dynamically
+merged)</para></listitem>
+
+<listitem><para>Distribution Specific SUSE Linux copies certain icons
+in starttde.theme from <filename
+class="directory">/opt/trinity/share/config/SuSE/default/</filename></para></listitem>
+
+</itemizedlist>
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="tde-menu">
+<title>&tde; Menu</title>
+
+<sect2 id="how-it-works">
+<title>How it Works</title>
+
+<para>In &tde; 3.2 a common menu format is introduced at
+<ulink
+url="http://freedesktop.org/Standards/menu-spec/">http://freedesktop.org/Standards/menu-spec/</ulink></para>
+<para>Before &tde; 3.2:
+<itemizedlist>
+
+<listitem><para>Directory structure under <filename
+class="directory">share/applnk</filename></para></listitem>
+
+<listitem><para>Directory structure represents menu
+structure</para></listitem>
+
+<listitem><para>Each <literal role="extension">.desktop</literal> file
+represents a single application</para></listitem>
+
+</itemizedlist>
+</para>
+
+<para>It was difficult to rearrange the structure in &tde; 3.2 so the
+new menu format:
+<itemizedlist>
+<listitem><para>Defines structure in a single .menu file</para></listitem>
+<listitem><para>Is based on categories</para></listitem>
+<listitem><para>is shared between <acronym>GNOME</acronym> and &tde;</para></listitem>
+<listitem><para>Supports applnk style menus as well</para></listitem>
+</itemizedlist>
+</para>
+
+<informalexample>
+<para>Example from <filename>kde-applications.menu</filename>:
+<programlisting>
+<markup>
+	&lt;Menu&gt;
+	    &lt;Name&gt;Office&lt;/Name&gt;
+	    &lt;Directory&gt;suse-office.directory&lt;/Directory&gt;
+	    &lt;Include&gt;
+	        &lt;Filename&gt;Acrobat Reader.desktop&lt;/Filename&gt;
+	        &lt;Filename&gt;tde-kpresenter.desktop&lt;/Filename&gt;
+	        &lt;Filename&gt;tde-kword.desktop&lt;/Filename&gt;
+	    &lt;/Include&gt;
+	&lt;Menu&gt;
+</markup>
+</programlisting>
+</para>
+<para>Menu entry with 3 applications:
+<itemizedlist>
+
+<listitem><para><filename>/usr/share/applications/Acrobat
+Reader.desktop</filename></para></listitem>
+
+<listitem><para><filename>/opt/trinity/share/applications/tde/kpresenter.desktop</filename></para></listitem>
+
+<listitem><para><filename>/opt/trinity/share/applications/tde/kword.desktop</filename></para></listitem>
+
+</itemizedlist>
+</para>
+</informalexample>
+</sect2>
+
+<sect2 id="stored-where">
+<title>Stored Where?</title>
+
+<para><literal role="extension">.menu</literal> files describing the
+menu structure. The files are stored in <filename
+class="directory">$<envar>TDEDIR</envar>/etc/xdg/menus</filename> and
+<filename class="directory">/etc/xdg/menus</filename>. These store the
+system-wide menu structure and are controlled by
+$<envar>XDG_CONFIG_DIRS</envar>. <filename
+class="directory">$<envar>HOME</envar>/.config/menus</filename> stores
+user-specific changes to the menu structure and is controlled by
+$<envar>XDG_CONFIG_HOME</envar>. For more information, see <ulink
+url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink>.</para>
+
+<para><literal role="extension">.desktop</literal> files describe the
+applications and are stored in: <filename
+class="directory">$<envar>TDEDIR</envar>/share/applications</filename>,
+<filename class="directory">/usr/share/applications</filename>,
+<filename
+class="directory">/usr/local/share/applications</filename>. These are
+the system-wide application <literal
+role="extension">.desktop</literal> files which are controlled by
+$<envar>XDG_DATA_DIRS</envar>.</para>
+
+<para><filename
+class="directory">$<envar>HOME</envar>/.local/applications</filename>
+contains user-specific <literal role="extension">.desktop</literal>
+files and user-specific changes. It is controlled by
+$<envar>XDG_DATA_HOME</envar>. For more information, see <ulink
+url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para>
+
+
+<para><literal role="extension">.directory</literal> files describing
+the sub-menus are stored in: <filename
+class="directory">$<envar>TDEDIR</envar>/share/desktop-directories</filename>,
+<filename class="directory">/usr/share/desktop-directories</filename>, <filename
+class="directory">/usr/local/share/desktop-directories</filename>.
+These are the system-wide menu <literal
+role="extension">.directory</literal> files, controlled by
+$<envar>XDG_DATA_DIRS</envar>. The user-specific changes are stored in <filename class="directory">$<envar>HOME</envar>/.local/desktop-directories</filename>.
+These are controlled by $<envar>XDG_DATA_HOME</envar>. For more
+information, see <ulink url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para>
+
+<informalexample>
+<para>Example from <filename>kde-applications.menu</filename>:
+<programlisting>
+<markup>
+             &lt;Menu&gt;
+                        &lt;Name&gt;Art&lt;/Name&gt;
+                        &lt;Directory&gt;suse-edutainment-art.directory&lt;/Directory&gt;
+                        &lt;Include&gt;
+                                &lt;Category&gt;X-SuSE-Art&lt;/Category&gt;
+                        &lt;/Include&gt;
+                &lt;/Menu&gt;
+</markup>
+</programlisting>
+</para>
+
+<para><literal>Art</literal> is the internal name for this
+menu. <filename>suse-edutainment-art.directory</filename> defines the
+name and icon for this menu, and the menu includes all applications
+that have <literal>X-SuSE-Art</literal> listed as a category, &eg;:
+<programlisting>
+Categories=Qt;TDE;Education;X-SuSE-Art
+</programlisting></para>
+
+<para><filename>suse-edutainment-art.directory</filename> defines the
+name and icon for this menu:
+<programlisting>
+[Desktop Entry]
+Name=Art and Culture
+Icon=kcmsystem
+</programlisting>
+</para>
+</informalexample>
+</sect2>
+
+<sect2 id="common-pitfalls">
+<title>Common Pitfalls</title>
+
+<para>Applications <emphasis>not</emphasis> in the menu do
+<emphasis>not</emphasis> exist with regard to other applications or
+file associations: If you remove an application from the menu, &tde; assumes you don't want to use it.</para>
+
+<para>When applications are unwanted in the menu, either place them in
+<filename>.hidden</filename> menu or a dedicated menu with
+<programlisting>
+NoDisplay=true
+</programlisting> in the <literal
+role="extension">.directory</literal> file</para>
+</sect2>
+
+<sect2 id="essential-menus">
+<title>Essential Menus</title>
+
+<para><filename
+class="directory">$<envar>TDEDIR</envar>/etc/xdg/menus/applications-merged/</filename>
+contains <filename>kde-essential.menu</filename> which includes some
+essential menus that are normally not shown in the &tde; menu itself:
+<itemizedlist>
+<listitem><para>Control Center has a hidden Settings menu whose
+contents are defined by <filename>kde-settings.menu</filename> and
+whose icon and name are defined by <filename>kde-settings.directory</filename></para>
+</listitem>
+<listitem><para>Info Center has a hidden Information menu whose
+contents are defined by <filename>kde-information.menu</filename> and
+whose icon and  name are  defined by <filename>kde-information.directory</filename>.</para>
+</listitem>
+
+<listitem><para>Screensavers contains a hidden System/Screensavers menu,
+whose contents are defined by
+<filename>kde-screensavers.menu</filename> and whose icon and  name
+are defined by
+<filename>kde-system-screensavers.directory</filename>.
+<filename>$<envar>TDEDIR</envar>/share/desktop-directories/kde-system-screensavers.directory</filename>
+contains:
+<programlisting>
+NoDisplay=true
+</programlisting>
+</para>
+</listitem>
+</itemizedlist></para>
+</sect2>
+
+<sect2 id="old-style-menus">
+<title>Old-Style Menus</title>
+
+<para>&tde; continues to support old-style menus that are defined by
+the directory structures in <filename
+class="directory">$<envar>TDEDIR</envar>/share/applnk</filename>
+(system wide) and <filename
+class="directory">$<envar>HOME</envar>/.trinity/share/applnk</filename>
+(user specific). This is observed unless the <literal role="extension">.desktop</literal> file has a  <varname>Categories</varname>= line. In that case the categories determine the location in the menu.</para>
+</sect2>
+
+<sect2 id="tdesycoca">
+<title><application>KSycoca</application></title>
+<para><application>KSycoca</application> caches menu structure and
+information about all available applications. You can rebuild the
+database with
+<userinput><command>tdebuildsycoca</command></userinput>. The database
+which is built lives in <filename
+class="directory">/var/tmp/tdecache-${<envar>USER</envar>}/tdesycoca</filename>.
+It is automatically updated by <application>KDED</application>,
+checked during &tde; login, and <application>KDED</application>
+watches for changes while logged in.</para>
+
+<para>To disable watching for changes (since it may hurt over NFS) add
+the following to <filename>kdedrc</filename>:
+<programlisting>
+[General]
+CheckSycoca=false
+</programlisting>
+</para>
+
+<para>To force regeneration, run <userinput><command>touch $<envar>TDEDIR</envar>/share/services/update_tdesycoca</command></userinput>.</para>
+
+</sect2>
+
+<sect2 id="kmenuedit">
+<title>&kmenuedit;</title>
+
+<para>&kmenuedit; is aimed at a single user setup. Changes to menu
+structure are saved to
+<filename>~/.config/menus/applications-tdemenuedit.menu</filename>,
+changes to applications are saved in <filename
+class="directory">~/.local/share/applications/</filename> and changes
+to sub-menus (icon, name) are saved in <filename
+class="directory">~/.local/share/desktop-directories/</filename>. The
+KIOSK Admin Tool uses &kmenuedit; and copies the above changes to
+profile- or system-wide locations.
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- This section might be redundant. If it isn't, it needs some screenies -->
+<sect1 id="tde-panel">
+<title>&tde; Panel</title>
+
+<para>The &tde; panel is also known as &kicker;. It is modular and
+consists of the following components:
+<itemizedlist>
+<listitem><para>Applets</para></listitem>
+<listitem><para>Application buttons</para></listitem>
+<listitem><para>Special Buttons</para></listitem>
+</itemizedlist>
+</para>
+
+<para>By default, the panel contains the following applets:
+<itemizedlist>
+<listitem><para>Pager - shows the virtual desktops</para></listitem>
+<listitem><para>Taskbar</para></listitem>
+<listitem><para>System Tray</para></listitem>
+<listitem><para>Clock</para></listitem>
+</itemizedlist>
+and the following special buttons:
+<itemizedlist>
+<listitem><para>&tde; menu</para></listitem>
+<listitem><para>Desktop Button</para></listitem>
+</itemizedlist>
+</para>
+
+<para>Various application buttons are also added, space permitting:
+<itemizedlist>
+<listitem><para>Home Button</para></listitem>
+<listitem><para>Browser Button</para></listitem>
+<listitem><para>KMail Button</para></listitem>
+</itemizedlist>
+</para>
+</sect1>
+
+<sect1 id="file-associations">
+<title>File Associations</title>
+
+<para>File associations associate a file type with an application or
+applications. The type of a file is established by determining its
+&MIME; type. &MIME; types known by &tde; are stored in <filename
+class="directory">$<envar>TDEDIR</envar>/share/mimelnk</filename> and
+each application's <literal role="extension">.desktop</literal> file
+contains a list of &MIME; types supported by that application.</para>
+
+<informalexample>
+<para><filename>kview.desktop</filename>:
+<programlisting>
+MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg;
+image/x-bmp;image/png;image/x-ico;image/x-portable-bitmap;
+image/x-portable-pixmap;image/x-portable-greymap;
+image/tiff;image/jp2
+</programlisting>
+</para>
+
+<para><filename>kuickshow.desktop</filename>:
+<programlisting>
+MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg;
+image/png;image/tiff;image/x-bmp;image/x-psd;image/x-eim;
+image/x-portable-bitmap;image/x-portable-pixmap;
+image/x-portable-greymap
+</programlisting>
+</para>
+
+<para>Both can open image/gif Which one is used to open a <literal role="extension">.gif</literal> file?</para>
+
+<para>The application with highest
+preference!. <filename>kview.desktop</filename> contains
+<programlisting>
+InitialPreference=3
+</programlisting>
+whereas <filename>kuickshow.desktop</filename> contains
+<programlisting>
+InitialPreference=6
+</programlisting>
+Therefore, &kuickshow; will be used to open <literal
+role="extension">.gif</literal> files.
+</para>
+
+<para>How can we make &kview;  default?</para>
+
+<para>A user can change file association in the
+&kcontrolcenter;. These changes are stored in
+<filename>$<envar>HOME</envar>/.trinity/share/config/profilerc</filename>.
+To use the same settings for multiple users, store these settings in
+user profile directory or the global &tde; config directory to use as
+default for multiple users.</para>
+
+</informalexample>
+
+</sect1>
+
+</chapter>
+
+<chapter id="locking-down-kde">
+<title>Locking Down &tde;</title>
+
+<sect1 id="how-it-works-the-basics">
+<title>How It Works - The Basics</title>
+
+<para>&tde;'s lock down features are centered around the following
+options:</para>
+
+<itemizedlist>
+<listitem><para><link linkend="immutable-configuration-options">Make
+configuration options immutable</link></para></listitem>
+<listitem><para><link linkend="action-restrictions">Restriction of specific
+actions</link></para></listitem>
+<listitem><para><link linkend="url-restrictions">Restrict access to certain
+&URL;s</link></para></listitem>
+<listitem><para><link linkend="configuration-modules">Restrict access to
+certain configuration modules</link></para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="immutable-configuration-options">
+<title>Immutable Configuration Options</title>
+<subtitle>Locking Down &tde;</subtitle>
+
+<para>Immutable options allow system administrator to provide default
+settings that can not be changed by the user.</para>
+
+<para>Pre-existing configuration options of the user will be ignored once a
+configuration option is made immutable.</para>
+
+<para>Options can be controlled either on a per entry basis, per group of
+entries or on a file by file basis.</para>
+
+<para>If a file or group is immutable, all configuration options for that
+file or group are immutable, even those options for which the system
+administrator has no default provided.</para>
+
+<note><para>The support in applications for immutable options may vary from
+application to application. Although the user will not be able to make
+permanent changes to immutable configuration options, the user may still be
+presented with an user interface option to make such change.</para></note>
+
+</sect1>
+
+<sect1 id="action-restrictions">
+<title>Action Restrictions</title>
+
+<para>&tde; applications are built around the action-concept. Actions can be
+activated in various ways, typically via the menu-bar, one of the toolbars
+or a keyboard shortcut. <action>Save Document</action> is an example of an
+action.  If you know the internal action name it is possible to restrict an
+action. When an action is restricted it will no longer appear in the
+menu-bar or toolbar. The internal name for the <action>Save
+Document</action> action is <option>action/file_save</option>.  The lock
+down framework also provides a set of more abstract restrictions which can
+be used to disable functionality not covered by a single action. An example
+is the <option>shell_access</option> restriction which disables all
+functionality that would offer the user access to a &UNIX; shell.</para>
+
+<example>
+<title>Restrict User Access to Shells</title>
+
+<para>In order to prevent the user access to a command shell we can restrict
+the <option>shell_access</option> action by adding the following to
+<filename>kdeglobals</filename>:
+</para>
+
+<screen>[TDE Action Restrictions]
+shell_access=false</screen>
+
+<para>Since this affects the &tde; menu and the available applications, we
+must force an update of the sycoca database:</para>
+
+<screen><userinput><command>touch</command> <filename>$<envar>TDEDIR</envar>/share/services/update_tdesycoca</filename></userinput></screen>
+
+<para>Now re-login to &tde; and check the following points:</para>
+
+<itemizedlist>
+<listitem><para>The &kmenu;</para></listitem>
+<listitem><para>In &konqueror;,
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Open
+Terminal</guimenuitem></menuchoice></para></listitem>
+<listitem><para>The <keycombo
+action="simul">&Alt;<keycap>F2</keycap></keycombo> run
+command</para></listitem>
+</itemizedlist>
+</example>
+<para>Full documentation about available actions can be found on <ulink
+url="http://www.kde.org/areas/sysadmin/">http://www.kde.org/areas/sysadmin/</ulink>.</para>
+
+<para>A few of the more interesting actions are listed below:</para>
+
+<variablelist>
+<varlistentry>
+<term><option>action/options_configure</option></term>
+<listitem><para>The <guimenuitem>Configure</guimenuitem> option form the
+<guimenu>Settings</guimenu> menu</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>action/help_report_bug</option></term>
+<listitem><para>The <guimenuitem>Report Bug/Request Enhancement...</guimenuitem> option from the
+<guimenu>Help</guimenu> menu.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>action/kdesktop_rmb</option></term>
+<listitem><para>&RMB; mouse button menu on the desktop.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>action/kicker_rmb</option></term>
+<listitem><para>&RMB; mouse button menu on the panel.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>user/root</option></term>
+<listitem><para>Hide all actions or applications that require <systemitem
+class="username">root</systemitem> access.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>shell_access</option></term>
+<listitem><para>Hides all actions or applications that provide shell
+access.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>print/system</option></term>
+<listitem><para>Disables the option to select the printing system
+(backend).</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>lock_screen</option></term>
+<listitem><para>Whether the user will be able to lock the
+screen</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>start_new_session</option></term>
+<listitem><para>Whether the user may start a second X session (see also
+&tdm;)</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>opengl_screensavers</option></term>
+<listitem><para>Whether OpenGL screensavers are allowed to be
+used.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>manipulatescreen_screensavers</option></term>
+<listitem><para>Permit screensavers that do not hide the entire
+screen</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="url-restrictions">
+<title>&URL; Restrictions</title>
+
+<para>There are three types of restrictions that can be applied to
+&URL;s:</para>
+
+<variablelist>
+<varlistentry>
+<term>list</term>
+<listitem><para>To control whether a directory listing is
+allowed.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>open</term>
+<listitem><para>To control whether certain &URL;s can be
+opened</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Redirect</term>
+<listitem><para>To control whether one &URL; can open another &URL;, either
+automatically or via a hyperlink.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Rules are checked in the order in which they are defined.  The last
+rule that is applicable to a &URL; defines whether the &URL; may be
+accessed.</para>
+
+<para>The following rules disable opening http and https &URL;s outside
+<systemitem class="domainname">.ourcompany.com</systemitem>:</para>
+
+<screenco><areaspec>
+<area id="url_commas" coords="3"/>
+<area id="url_rule1" coords="3"/>
+<area id="url_rule2" coords="4"/>
+</areaspec>
+<screen>[TDE URL Restrictions]
+rule_count=2
+rule_1=open,,,,http,,,false
+rule_2=open,,,,http,*.ourcompany.com,,true</screen></screenco>
+
+<calloutlist>
+<callout arearefs="url_commas">
+<para>The first four commas skip over the selection criteria with respect to
+the originating &URL;. This part is only needed with redirect type
+rules.</para>
+</callout>
+<callout arearefs="url_rule1"><para><option>rule_1</option> forbids the
+opening of any http or https &URL;</para></callout>
+<callout arearefs="url_rule2"><para><option>rule_2</option> allows the
+opening of any http and https &URL; in the <systemitem
+class="domainname">.ourcompany.com</systemitem> domain.  Note the wildcard
+<token>*</token> is only allowed at the start of a domain.</para></callout>
+</calloutlist>
+
+<para>The following rules makes that the user can no longer browse
+directories on the local file system that are outside his
+$<envar>HOME</envar> directory:</para>
+
+<screenco><areaspec>
+<area id="home_rule1" coords="3"/>
+<area id="home_rule2" coords="4"/>
+</areaspec>
+<screen>[TDE URL Restrictions]
+rule_count=2
+rule_1=list,,,,file,,,false
+rule_2=list,,,,file,,$HOME,true</screen></screenco>
+
+<calloutlist>
+<callout arearefs="home_rule1"><para><option>rule_1</option> forbids the
+listing of any local directory</para></callout>
+<callout arearefs="home_rule2"><para><option>rule_2</option> allows listing
+directories under the users own $<envar>HOME</envar>
+directory.</para></callout>
+</calloutlist>
+
+<para>$<envar>HOME</envar> and $<envar>TMP</envar> are special values to
+indicate the users home directory and the &tde; temporary directory of the
+user, &eg; <filename class="directory">/tmp/kde-bastian</filename></para>
+
+<para>The following rules makes that the user can no longer open local files
+that are outside his $<envar>HOME</envar> directory:</para>
+
+<screenco><areaspec>
+<area id="local_rule1" coords="3"/>
+<area id="local_rule2" coords="4"/>
+<area id="local_rule3" coords="5"/>
+</areaspec>
+<screen>[TDE URL Restrictions]
+rule_count=3
+rule_1=open,,,,file,,,false
+rule_2=open,,,,file,,$HOME,true
+rule_3=open,,,,file,,$TMP,true</screen></screenco>
+
+<calloutlist>
+<callout arearefs="local_rule1"><para><option>rule_1</option> forbids the
+opening of any local file</para></callout>
+<callout arearefs="local_rule2"><para><option>rule_2</option> allows opening
+files under the users own $<envar>HOME</envar> directory.</para></callout>
+<callout arearefs="local_rule3"><para><option>rule_3</option> allows opening
+files in the &tde; temporary directory of the user.  This is needed by
+certain &tde; applications that first download a file or document to the
+temporary directory and then open it in an application.</para></callout>
+</calloutlist>
+
+
+<para>The redirection option controls whether documents from a certain
+location can refer, either automatically or manually via a hyperlink, to a
+certain other location.  A set of default rules is present as a general
+security measure. For example documents located on the Internet may not
+refer to locally stored documents.</para>
+
+<para>For example, if we want to give the intranet-server <systemitem
+class="systemname">www.mycompany.com</systemitem> the possibility to refer
+to local files we could add the following rule:</para>
+
+<screen>[TDE URL Restrictions]
+rule_count=1
+rule_1=redirect,http,www.mycompany.com,,file,,,true</screen>
+
+<para>Instead of listing a protocol by name, it is also possible to specify
+a whole group of protocols. For that the following groups have been
+defined:</para>
+
+<variablelist>
+<varlistentry>
+<term>:local</term>
+<listitem><para>Protocols that access locally stored information, examples
+are file:/, man:/, fonts:/, floppy:/</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>:internet</term>
+<listitem><para>Common internet protocols such as http and
+ftp</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Information about protocols is stored in <literal
+role="extension">*.protocol</literal> files stored in
+<filename
+class="directory">$<envar>TDEDIR</envar>/share/services</filename>.</para>
+
+<para>The <option>Class</option>= entry defines the group a protocol is part
+of:
+<userinput><command>grep</command> <option>Class=</option>
+<filename>$<envar>TDEDIR</envar>/share/services/*.protocol</filename></userinput></para>
+
+<para>General rules:</para>
+
+<itemizedlist>
+<listitem><para>The :local protocols may refer to any other
+protocol</para></listitem>
+<listitem><para>It's always allowed to refer to an :internet
+protocol</para></listitem>
+<listitem><para>Not all protocols are part of a group, fish:/ for
+example.</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="configuration-modules">
+<title>Configuration Modules</title>
+
+<para>&tde; has configuration modules to configure various aspects of the
+&tde; environment. Configuration modules appear in the Control Center, in the
+Configuration dialog of an application or in both.</para>
+
+<informalexample>
+<para>The proxy configuration module appears in the Control Center but also
+as part of the <guilabel>Configure Konqueror</guilabel> dialog in
+&konqueror;</para>
+
+<para>Individual configuration modules can be started with
+<command>tdecmshell</command> <replaceable>module</replaceable></para>
+
+<para>To start the Proxy module use:</para>
+<itemizedlist>
+<listitem><para><command>tdecmshell</command>
+<filename>tde-proxy.desktop</filename></para></listitem>
+<listitem><para><command>tdecmshell</command> proxy</para></listitem>
+</itemizedlist>
+
+<para><note><para>Not all applications use configuration modules, often the
+configuration dialog is an integral part of the application
+itself.</para></note></para>
+</informalexample>
+
+<para>All configuration modules are strictly speaking part of the &tde;
+menu.</para>
+
+<itemizedlist>
+<listitem>
+<para>The modules that are visible in the Control Center normally
+have a <literal role="extension">.desktop</literal> file in <filename
+class="directory">$<envar>TDEDIR</envar>/share/applications/tde</filename>
+and are sorted under the hidden <guimenu>Settings-Modules</guimenu> menu by
+the <filename>kde-settings.menu</filename>, included from
+<filename>kde-essential.menu</filename></para>
+<screen><userinput><command>tdebuildsycoca</command> <option>--menutest</option> 2&gt; /dev/null | <command>grep</command> Settings-Modules</userinput></screen>
+</listitem>
+<listitem>
+<para>Application specific modules normally have a <literal role="extension">.desktop</literal> file under
+<filename>$<envar>TDEDIR</envar>/share/applnk/.hidden</filename> which
+corresponds to the hidden .hidden menu, included as a result of
+<markup>&lt;KDELegacyDirs/&gt;</markup></para>
+<screen><userinput><command>tdebuildsycoca</command> <option>--menutest</option> 2&gt; /dev/null | <command>grep</command> .hidden</userinput></screen>
+</listitem>
+<listitem><para>In &tde; 3.3 it is possible to edit the Control Center with
+<application>kcontroledit</application>.
+<application>kcontroledit</application> works just like
+<application>kmenuedit</application>, changes for current user only. Use
+<application>kiosktool</application> to make changes for
+everyone.</para></listitem>
+</itemizedlist>
+
+<para>Individual configuration modules can be disables by adding the
+following to <filename>kdeglobals</filename>:</para>
+
+<screen>[TDE Control Module Restrictions]
+<replaceable>module-id</replaceable>=false</screen>
+<para>For example, to disable the proxy module use</para>
+<screen>[TDE Control Module Restrictions]
+tde-proxy.desktop=false</screen>
+<para>Check the Control Center and the <guilabel>Configure
+Konqueror</guilabel> dialog if the proxy configuration is still
+there.</para>
+
+</sect1>
+<!--
+<sect1 id="making-it-work">
+<title>Making it Work</title>
+
+Making It Work
+TDE 3.2: Set $TDEDIRS from starttde script
+Distribute profiles to all clients
+
+</para>
+</sect1>
+-->
+</chapter>
+
+<chapter id="the-lazy-admin">
+<title>The Lazy Admin</title>
+
+<!-- This section appears to need quite a lot of additional words to -->
+<!-- make sense. Perhaps it would be better to comment it out if it -->
+<!-- can't be updated before the next release (Phil) -->
+<!-- FIXME: Commented it out until it's got some more content fleshing it -->
+<!-- out (Lauri)
+
+<sect1 id="lazy-admin-overview">
+<title>Overview</title>
+
+<para>
+The Lazy Admin
+Overview
+Deployment
+	How to get &tde; available on many clients
+Remote Desktop Sharing
+Take a look at someone else desktop
+DCOP
+	The DCOP command line tool makes it possible to control &tde; applications from the command line
+KDialog
+	A versatile tool to use standard &tde; dialogs in your own scripts
+
+
+
+Deployment
+Thin Clients
+Installing Software
+= AutoYaST
+= KickStart
+Maintaining Settings
+= /etc/tderc, other settings
+= Use rsync to copy files around
+= Shared filesystem such as NFS
+o store profiles themselves on NFS
+
+
+
+http://www.suse.de/~nashif/autoinstall/index.html
+
+</para>
+</sect1>
+-->
+<sect1 id="remote-desktop-sharing">
+<title>Remote Desktop Sharing</title>
+
+<para>Remote desktop sharing allows remote users to view and optionally
+control the desktop of the current user.  The remote user needs to be sent
+an invitation, and it is possible to create a password protected standing
+invitation. This is ideal for tech support teams or administrators to gain
+access to users desktops in order to troubleshoot or remedy a problem or
+guide a user through a procedure.</para>
+
+<para>Remote desktop sharing involves two applications: &krfb; (&tde; remote
+frame buffer, a VNC server) and &krdc; (&tde; remote desktop connection; a
+VNC client.)</para>
+
+<para>&krfb; can be used by any user to create and manage invitations.
+Invitations create a one time password that allows the recipient to connect
+to your desktop.  By default it is valid for only one successful connection,
+and expires after one hour if not used.</para>
+
+<para>Incoming connections are handled by the kinetd kded module.  You can
+use the command <userinput><command>dcop</command> kded kinetd
+services</userinput> to see if it is running. &krfb; waits for connections
+on port 5900 by default.  When an incoming connection is made, a dialog will
+appear to ask for confirmation by the current user.</para>
+
+<!-- TODO: Write a bit more here, with a walk through maybe? -->
+
+</sect1>
+
+<sect1 id="tde-diy">
+<title>&tde; DIY - Building Your Own Tools</title>
+
+<sect2 id="dcop">
+<title>DCOP</title>
+
+<para>
+Desktop COmmunication Protocol, <acronym>DCOP</acronym>, is a lightweight mechanism for inter-process communication.
+<acronym>DCOP</acronym> allows the user to interact with programs that are currently running.
+&tde; supplies two programs to utilitize <acronym>DCOP</acronym>:
+<application>dcop</application>, a command-line program, and
+<application>kdcop</application>, a <acronym>GUI</acronym> program.
+</para>
+<para>
+A few notes about using <command>dcop</command>:
+</para>
+
+<para>
+<itemizedlist>
+<listitem>
+<para>
+<command>dcop</command> [options] [application [object [function [arg1] [arg2] ... ] ] ]
+</para>
+</listitem>
+<listitem>
+<para>
+Applications that can open more than one window at a time will be listed as
+&lt;application&gt;-<acronym>PID</acronym>
+</para>
+</listitem>
+<listitem>
+<para>
+All the arguments are case-sensitve.  setFullScreen and setfullscreen are two different functions.
+</para>
+</listitem>
+<listitem>
+<para>
+The regular expression token * can be used in the application and object arguments.
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> kon*</option></userinput>
+konqueror-16006
+konsole-8954
+</screen>
+</para>
+</listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>Some example commands and their output are below:
+</para>
+
+<informalexample>
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole*</option></userinput>
+konsole-8954
+</screen>
+<para>One &konsole; is running with a <acronym>PID</acronym> of 8954.</para>
+
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option></userinput>
+KBookmarkManager-.../share/apps/tdefile/bookmarks.xml
+KBookmarkManager-.../share/apps/konqueror/bookmarks.xml
+KBookmarkNotifier
+KDebug
+MainApplication-Interface
+konsole (default)
+konsole-mainwindow#1
+tdesycoca
+session-1
+session-2
+session-3
+session-4
+</screen>
+<para>Here you see that there are four sessions running.</para>
+
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option></userinput>
+QCStringList interfaces()
+QCStringList functions()
+int sessionCount()
+QString currentSession()
+QString newSession()
+QString newSession(QString type)
+QString sessionId(int position)
+void activateSession(QString sessionId)
+void nextSession()
+void prevSession()
+void moveSessionLeft()
+void moveSessionRight()
+bool fullScreen()
+void setFullScreen(bool on)
+ASYNC reparseConfiguration()
+</screen>
+<para>Here are the options for the main &konsole; program.
+</para>
+
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> session-1</option></userinput>
+QCStringList interfaces()
+QCStringList functions()
+bool closeSession()
+bool sendSignal(int signal)
+void clearHistory()
+void renameSession(QString name)
+QString sessionName()
+int sessionPID()
+QString schema()
+void setSchema(QString schema)
+QString encoding()
+void setEncoding(QString encoding)
+QString keytab()
+void setKeytab(QString keyboard)
+QSize size()
+void setSize(QSize size)
+</screen>
+<para>Here are the options for the first session, session-1.</para>
+
+<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option><option> setFullScreen</option><parameter> true</parameter></userinput>
+</screen>
+<para>This sets &konsole; to full screen.</para>
+
+</informalexample>
+
+<para>
+When there is more than one application/object, which one should you use?
+ Got a reference?
+</para>
+<screen><prompt>&percnt; </prompt><userinput><command>echo</command><option> $KONSOLE_DCOP</option></userinput>
+DCOPRef(konsole-7547,konsole)
+
+<prompt>&percnt; </prompt><userinput><command>dcop</command><option> $KONSOLE_DCOP</option><option> newSession</option></userinput>
+session-6
+
+<prompt>&percnt; </prompt><userinput><command>dcopstart</command><option> konsole</option></userinput>
+konsole-9058
+
+
+#!/bin/sh
+konsole=$(dcopstart konsole-script)
+session=$(dcop $konsole konsole currentSession)
+dcop $konsole $session renameSession Local
+
+session=$(dcop $konsole konsole newSession)
+dcop $konsole $session renameSession Remote
+
+session=$(dcop $konsole konsole newSession)
+dcop $konsole $session renameSession Code
+dcop $konsole $session sendSession 'cd /my/work/directory'
+
+</screen>
+
+</sect2>
+
+<sect2 id="kdialog">
+<title>KDialog</title>
+<subtitle>&tde; DIY - Building Your Own Tools</subtitle>
+
+<para>You can use &tde; dialogs from your own scripts, to combine the power
+of &UNIX; shell scripting with the ease of use of &tde;.</para>
+
+<screen><userinput><command>kdialog</command> <option>--msgbox 'You have new mail!'</option></userinput></screen>
+
+<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option></userinput></screen>
+
+<para>The <application>KDialog</application> part can be replaced via
+<option>--caption</option> option</para>
+
+<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option> <option>--dontagain myfile:mykey</option></userinput></screen>
+
+<para>Saves whether to show again in
+<filename>$<envar>TDEHOME</envar>/share/config/myfile</filename> (by writing
+into this file the following lines:</para>
+
+<screen>[Notification Messages]
+mykey=false</screen>
+
+<para>Instead of <option>--msgbox</option> you can also use
+<option>--sorry</option> and <option>--error</option>, as appropriate.  For
+instance, you might use <command>kdialog</command> <option>--sorry 'The
+network can not be reached'</option> or <command>kdialog</command>
+<option>--error 'Mail box can not be opened'</option>.</para>
+
+<para>It is also possible to create message boxes that accept a yes or no
+answer.</para>
+
+<screen><command>kdialog</command> <option>--yesno 'Do you want to connect
+to the Internet?'</option> <command>echo</command> <returnvalue>$?</returnvalue></screen>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Return Value</entry>
+<entry>Meaning</entry>
+</row>
+</thead>
+<tbody>
+<row><entry>0</entry><entry>Yes, OK, Continue</entry></row>
+<row><entry>1</entry><entry>No</entry></row>
+<row><entry>2</entry><entry>Cancel</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>Make sure to store the result in a variable if you do not use it
+directly, the next command will fill $? with a new value You can use
+<option>--dontagain</option> here as well, it will remember the users choice
+and returns it the next times without showing the dialog any more.</para>
+
+<para>Further variations are:</para>
+
+<variablelist>
+<varlistentry>
+<term><option>--warningyesno</option></term>
+<listitem>
+<para>like <option>--yesno</option> but with a different
+icon</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>--warningcontinuecancel</option></term>
+<listitem><para>With <guibutton>Continue</guibutton> and
+<guibutton>Cancel</guibutton> buttons.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>--warningyesnocancel</option></term>
+<listitem><para>With <guibutton>Yes</guibutton>, <guibutton>No</guibutton>
+and <guibutton>Cancel</guibutton> button.  For example:</para>
+<screen><command>kdialog</command> <option>--warningyesnocancel 'Do you want
+to save the changes?'</option></screen>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<screen><command>kdialog</command> <option>--inputbox "Enter your name:" "YourName"</option></screen>
+
+<para>The result is printed to stdout, to put it in a variable you can use
+<userinput>name=$(kdialog --inputbox "Enter your name:"
+"YourName")</userinput>.  The last argument is optional, it is used to
+pre-fill the dialog.</para>
+
+<screen><userinput><varname>password</varname>=$(<command>kdialog</command> <option>--password "Enter your password:"</option>)</userinput></screen>
+
+<para>The <option>--dontagain</option> option does not work with
+<option>--inputbox</option> or <option>--password</option></para>
+
+<para>There are two dialogs that let the user make a choice from a
+list:</para>
+
+<variablelist>
+<varlistentry>
+<term><option>--menu</option></term>
+<listitem>
+<para>Lets the user select a single item from a list.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>--checklist</option></term>
+<listitem>
+<para>Lets the user select one or more items from a list.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--menu "Select a city" a London b Madrid c Paris d Berlin</option>)</userinput></screen>
+
+<para><varname>$city</varname> will <returnvalue>a</returnvalue>, <returnvalue>b</returnvalue>, <returnvalue>c</returnvalue> or <returnvalue>d</returnvalue>.</para>
+
+<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--checklist "Select cities" a London off b Madrid on c Paris on d Berlin off</option>)</userinput></screen>
+
+<para>Madrid and Paris will be pre-selected.  The result with Madrid and
+Paris selected will be <returnvalue>"b"</returnvalue>
+<returnvalue>"c"</returnvalue>.</para>
+
+<para>If you add the <option>--separate-output</option> option, it will put
+<returnvalue>b</returnvalue> and <returnvalue>c</returnvalue> each on a line
+of its own, making the result easier to process.</para>
+
+<screen>file=$(kdialog --getopenfilename $HOME)
+file=$(kdialog --getopenfilename $HOME "*.png *.jpg|Image Files")
+file=$(kdialog --getsavefilename $HOME/SaveMe.png)
+file=$(kdialog --getexistingdirectory $HOME)</screen>
+
+</sect2>
+
+</sect1>
+
+</chapter>
+
+&groupware-with-kontact;
+
+</book>