tdebase/doc/kxkb/index.docbook

<?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 "tdebase">
  <!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 &tde; 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>tdecmshell 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>