Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

5 files changed, 362 insertions, 0 deletions

diff --git a/doc/kxkb/Makefile.am b/doc/kxkb/Makefile.am
new file mode 100644
index 000000000..085981d9b
--- /dev/null
+++ b/doc/kxkb/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kxkb/index.docbook b/doc/kxkb/index.docbook
new file mode 100644
index 000000000..6f3673aba
--- /dev/null
+++ b/doc/kxkb/index.docbook
@@ -0,0 +1,358 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
+"dtd/kdex.dtd" [
+  <!ENTITY kappname "&kxkb;">
+  <!ENTITY package "kdebase">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kxkb; Handbook</title>
+
+<authorgroup>
+<author>
+&Andriy.Rysin; &Andriy.Rysin.mail;
+</author>
+<author>
+&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
+</author>
+<othercredit role="developer">
+&Andriy.Rysin; &Andriy.Rysin.mail;
+<!-- <contrib>Developer</contrib> -->
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<copyright>
+<year>2003</year>
+<holder>&Andriy.Rysin;</holder>
+</copyright>
+<copyright>
+<year>2006</year>
+<holder>&Anne-Marie.Mahfouf;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2006-02-16</date>
+<releaseinfo>3.5.2</releaseinfo>
+
+<abstract><para>&kxkb; is a keyboard layout switching 
+utility based on X11 xkb extension.</para></abstract> 
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kxkb</keyword>
+<keyword>keyboard</keyword>
+<keyword>layout</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kxkb; is the &kde; keyboard layout switching utility.
+It is based on X11 xkb extension and allows to use different keyboard 
+layouts for inputing text. &kxkb; features keyboard layout indicator.
+</para>
+
+</chapter>
+
+<chapter id="usingthekxkb">
+<title>Using &kxkb;</title>
+
+<sect1 id="getting-started">
+<title>Getting Started</title>
+
+<para>&kxkb; starts automatically and stays in system tray as a flag
+with 2 or 3 letter abbreviation of layout name on top of it if more
+than one layout is defined or <guilabel>Show indicator for single
+layout</guilabel> option is turned on.</para>
+
+<para>When &kxkb; is running you can change layouts clicking on its
+tray icon with the mouse or pressing its keyboard shortcut. Keyboard
+shortcut or mouse click will switch to next layout or alternatively you
+can &RMB; click the &kxkb; icon and select layout from the
+list.</para>
+
+<para>&RMB; clicking on the &kxkb; icon you can start its
+configuration by selecting <guimenuitem>Configure...</guimenuitem> or
+by opening <application>Control Center</application> and selecting
+Localization/Keyboard Layout. Alternatively, you can start it by
+typing <command>kcmshell keyboard_layout</command> in a
+terminal.</para>
+
+</sect1>
+</chapter>
+
+<chapter id="configuringkxkb">
+<title>Configuring &kxkb;</title>
+
+<sect1 id="general-config">
+<title>General Information</title>
+<para>
+&kxkb; Configuration consists of three tabs: Layout, Switching
+ Options and Xkb Options. Layout and Xkb Options are mutually independent.
+The Layout tab defines layouts you want to use and their options, the Switching
+Options tab defines how you want to switch keyboards and the Xkb Otions tab
+defines parameters for Xkb extension on which &kxkb; is based.
+Xkb options are property of X and are not handled in any way by &kxkb; - 
+it just sets it up.
+</para>
+<note><para>
+&kxkb; configuration does not change anything in XFree86 configuration 
+files and Layout settings from XFree86 configuration are overridden 
+by &kxkb; if <option>Enable keyboard layout</option> option is turned on.
+</para></note>
+<note><para>
+To make your XFree86 configuration work you have to turn off both 
+<option>Enable keyboard layout</option> in layout configuration tab 
+<emphasis>and</emphasis> <option>Enable xkb options</option> in 
+Xkb options configuration tab (for the latter the same effect can be 
+reached if <option>Reset Old Options</option> is turned off and 
+none of xkb options are set).
+</para></note>
+<para>
+&kxkb; does most of its actions through <command>setxkbmap</command> command. 
+You can see the commandline to be executed for each active layout 
+when you select it and, on the xkb options tab, its available xkb option set.
+</para>
+</sect1>
+
+<sect1 id="layout-config">
+<title>Layout Configuration</title>
+
+<screenshot>
+<screeninfo>The Layout tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="layout.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>The Layout tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+
+<para>
+In layout configuration dialog the list of available layouts on your left. 
+You have to choose each layout you want to use and add them (one by one) 
+to the list of active layouts on the right. You can also change the order 
+in which active layouts will be switched when toggled by keyboard shortcut 
+or mouse button. The first layout in the list becomes default layout.
+</para>
+<para>
+Some layouts have several variants. Layout variants usually represent 
+different key maps for the same language. For example, Ukrainian 
+layout might have four variants: basic, winkeys (as in Windows), typewriter 
+(as in typewriters) and phonetic (each Ukrainian letter is placed on a 
+transliterated latin one). If your layout is multi-variant one 
+you can the variant in combobox below the active layouts list.
+</para>
+<para>
+Keyboard model setting is independent of your keyboard layout and refers 
+to the "hardware" model, i.e. the way your keyboard is manufactured. 
+Modern keyboards that come with your computer usually have two extra keys 
+and are referred to as "104-key" models, which is probably what you want 
+if you don't know what kind of keyboard you have.
+</para>
+<para>
+You can also choose switching policy for keyboard layout. By default it's 
+<option>Global meaning</option> all applications will share the same current layout. 
+<option>Application</option> means each application will have it's own layout and 
+switching layout while you are working with one application will not impact layout for any
+others. <option>Window</option> will make every window have its own layout even if they belong 
+to the same program.
+</para>
+<para>
+If you set only one active layout, at startup kxkb configures the keyboard and exits thus 
+its indicator will not appear. If you still want kxkb indicator select 
+<option>Show indicator for single layout</option> option.
+</para>
+<note>
+<para>
+If you leave active layout list empty keyboard layouts will be disabled
+</para>
+</note>
+</sect1>
+
+<sect1 id="switching-config">
+<title>Switching Options</title>
+
+<screenshot>
+<screeninfo>The Switching Options tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="switching.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>The Switching Options tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Show indicator for single layout</guilabel></term>
+<listitem><para>Shows icon in system tray even when thee is
+only one layout.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show country flag</guilabel></term>
+<listitem><para>Shows country flag on background of layout name in tray
+icon.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Switching Policy</guilabel></term>
+<listitem><para>If you select <guilabel>Application</guilabel> or
+<guilabel>Window</guilabel> switching policy,
+changing the keyboard layout will only affect the current application or
+window. <guilabel>Global</guilabel> will make the switching
+policy work globally for all applications and windows.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Sticky Switching</guilabel></term>
+<listitem><para>If you have more than two layouts and check <guilabel>Enable
+sticky switching</guilabel>, switching with the keyboard shortcut or clicking on
+the kxkb indicator will only cycle through the last few layouts. You can specify
+the number of layouts to rotate below in the <guilabel>Number of layouts to
+rotate</guilabel> box. You can still access all layouts by right-clicking on the
+&kxkb; indicator.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="xkboptions-config">
+<title>XKB Options Configuration</title>
+
+<screenshot>
+<screeninfo>The Xkb tab</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="xkb.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>The Xkb tab</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+
+<para>
+Xkb options allow you to select behavior of your keyboard. These options are not 
+handled by &kxkb; but may help tune your keyboard to your needs. You can set Xkb
+extension options instead of, or in addition to, specifying them in the X11
+configuration file.
+</para>
+</sect1>
+
+</chapter>
+
+<chapter id="kxkbtroubleshooting">
+<title>Troubleshooting</title>
+
+<sect1 id="troubles">
+<title>Common Problems</title>
+
+<para>If you switch to some layout and you can not see some characters
+from your layout as you type, please check your local settings.  &eg;
+<filename>~/.i18n</filename> or
+<filename>/etc/sysconfig/i18n</filename>, locale you have before
+starting kde applications must have an encoding which contains
+characters from your layout.  For example, to enter ukrainian symbols
+you must have encoding KOI8-U, CP1251 or UTF-8. The last one is a good
+choice to try for most of the languages if you have such a problem.
+</para>
+
+<para>If kxkb does not switch with keyboard shortcut when you switch
+it to some layout but switching with mouse is ok may mean 
+that your layout does not contain the key
+assigned in shortcut.</para>
+
+<para>In XFree86 prior to version 4.3.0 non-latin layouts mutually included
+latin group  and this group was the default thus pressing 
+<keycombo action="simul">&Ctrl;&Alt;<keycap>k</keycap></keycombo>
+always yielded the right combination. From version 4.3.0 by default
+all layouts contain only one group thus non-latin layouts may not work
+here.</para>
+
+<para>Possible solutions are:</para>
+
+<orderedlist>
+<listitem>
+<para>add your layout to $nonlatin or $oldlayouts lists in
+<filename>/etc/X11/xkb/rules/xfree86</filename> or the location of the
+xkb rules on your computer.</para>
+</listitem>
+<listitem>
+<para>Change the shortcut to something language neutral, &eg;
+<keycombo action="simul">&Ctrl;<keycap>Menu</keycap></keycombo></para>
+</listitem>
+<listitem>
+<para>Turn on the option to include the <quote>us</quote> group in
+your layout (effectively the same as solution 1).</para>
+</listitem>
+</orderedlist>
+
+</sect1>
+</chapter>
+
+<chapter id="xkb-files">
+<title>Files and Layout Descriptions</title>
+<sect1 id="xkb-files-and-layouts">
+<title><application>xkb</application> Files and Layouts</title>
+
+<para>All available keyboard layouts are described in
+<filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and
+<filename>/etc/X11/xkb/rules/xfree86.xml</filename> since XFree86
+4.3.0), the layouts themselves can be found in
+<filename>/etc/X11/xkb/symbols/pc</filename> (or
+<filename>/etc/X11/xkb/symbols</filename> for XFree86 4.2.x and
+older). Note that the location of these files may differ depending on
+your operating system and distribution.</para>
+
+<para>&kxkb; now uses the xkb extension instead of xmodmap, so to
+define your own layout you have to get one from <filename
+class="directory">/etc/X11/xkb/symbols</filename> which is closest to
+what you want to get (or <filename
+class="directory">/etc/X11/xkb/symbold/pc</filename> for XFree86
+4.3.0), rename it to something you like and edit it. Then just add the
+name to <filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and for
+XFree86 4.3.0 or later it is a good idea to add the name also to
+<filename>/etc/X11/xkb/ruls/xfree86.xml</filename> - some packages
+already use it, not &kxkb; though yet) kxkb will pick it up on
+restart. Note: you have to be root to edit those files.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="credits-and-licenses">
+<title>Credits and Licenses</title>
+
+<para>&kxkb; is currently developed and maintained by Andriy Rysin
+<email>rysin@kde.org</email>. Several other people
+have worked on <application>kxkb</application>:</para>
+
+<itemizedlist>
+<listitem><para>Shaheed Haque <email>srhaque@iee.org</email></para></listitem>
+<listitem><para>Ilya Konstantinov <email>kde-devel@future.galanet.net</email></para></listitem>
+</itemizedlist>
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->
+
diff --git a/doc/kxkb/layout.png b/doc/kxkb/layout.png
new file mode 100644
index 000000000..dfb30cbf6
--- /dev/null
+++ b/doc/kxkb/layout.png
diff --git a/doc/kxkb/switching.png b/doc/kxkb/switching.png
new file mode 100644
index 000000000..504eaa7b2
--- /dev/null
+++ b/doc/kxkb/switching.png
diff --git a/doc/kxkb/xkb.png b/doc/kxkb/xkb.png
new file mode 100644
index 000000000..df2db58f7
--- /dev/null
+++ b/doc/kxkb/xkb.png