diff options
Diffstat (limited to 'doc/kxkb/index.docbook')
| -rw-r--r-- | doc/kxkb/index.docbook | 358 |
1 files changed, 358 insertions, 0 deletions
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. ⪚ +<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, ⪚ +<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>[email protected]</email>. Several other people +have worked on <application>kxkb</application>:</para> + +<itemizedlist> +<listitem><para>Shaheed Haque <email>[email protected]</email></para></listitem> +<listitem><para>Ilya Konstantinov <email>[email protected]</email></para></listitem> +</itemizedlist> + +&underFDL; +&underGPL; + +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + |