tde-i18n/tde-i18n-en_GB/docs/tdebase/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 % British-English "INCLUDE"> <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &kxkb; Handbook</title>

<authorgroup>
<author>&Andriy.Rysin; &Andriy.Rysin.mail; </author>

<othercredit role="developer">&Andriy.Rysin; &Andriy.Rysin.mail; </othercredit>

<othercredit role="translator"><firstname>Jonathan</firstname><surname>Riddell</surname><affiliation><address><email>kde-en-gb@jriddell.org</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> 

</authorgroup>

<copyright>
<year>2003</year>
<holder>&Andriy.Rysin;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2003-08-23</date>
<releaseinfo>1.01.00</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 Centre</application> and selecting Localisation/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 two tabs: Layout Configuration and XKB Options which are mutually independent. The first one defines layouts you want to use and their options and second 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>
<para>In layout configuration dialogue 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="xkboptions-config">
<title>XKB Options Configuration</title>
<para>Xkb options allow you to select behaviour of your keyboard. These options are not handled by &kxkb; but may help tune your keyboard to your needs. </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 Licences</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:
-->