workspace/doc/kxkb/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
   3 "dtd/kdex.dtd" [
   4   <!ENTITY kappname "&kxkb;">
   5   <!ENTITY package "kdebase">
   6   <!ENTITY % addindex "IGNORE">
   7   <!ENTITY % English "INCLUDE" > <!-- change language only here -->
   8 ]>
   9
  10 <book lang="&language;">
  11 <bookinfo>
  12 <title>The &kxkb; Handbook</title>
  13
  14 <authorgroup>
  15 <author>
  16 &Andriy.Rysin; &Andriy.Rysin.mail;
  17 </author>
  18
  19 <othercredit role="developer">
  20 &Andriy.Rysin; &Andriy.Rysin.mail;
  21 <!-- <contrib>Developer</contrib> -->
  22 </othercredit>
  23
  24 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  25
  26 </authorgroup>
  27
  28 <copyright>
  29 <year>2003</year>
  30 <holder>&Andriy.Rysin;</holder>
  31 </copyright>
  32
  33 <legalnotice>&FDLNotice;</legalnotice>
  34
  35 <date>2003-08-23</date>
  36 <releaseinfo>1.01.00</releaseinfo>
  37
  38 <abstract><para>&kxkb; is a keyboard layout switching
  39 utility based on X11 xkb extension.</para></abstract>
  40
  41 <keywordset>
  42 <keyword>KDE</keyword>
  43 <keyword>kxkb</keyword>
  44 <keyword>keyboard</keyword>
  45 <keyword>layout</keyword>
  46 </keywordset>
  47 </bookinfo>
  48
  49 <chapter id="introduction">
  50 <title>Introduction</title>
  51
  52 <para>&kxkb; is the &kde; keyboard layout switching utility.
  53 It is based on X11 xkb extension and allows to use different keyboard
  54 layouts for inputting text. &kxkb; features keyboard layout indicator.
  55 </para>
  56
  57 </chapter>
  58
  59 <chapter id="usingthekxkb">
  60 <title>Using &kxkb;</title>
  61
  62 <sect1 id="getting-started">
  63 <title>Getting Started</title>
  64
  65 <para>&kxkb; starts automatically and stays in the system tray as a flag
  66 with 2 or 3 letter abbreviation of layout name on top of it if more
  67 than one layout is defined or <guilabel>Show indicator for single
  68 layout</guilabel> option is turned on.</para>
  69
  70 <para>When &kxkb; is running you can change layouts by clicking on its
  71 tray icon with the mouse or pressing its keyboard shortcut. Keyboard
  72 shortcut or mouse click will switch to the next layout or alternatively you
  73 can &RMB; click the &kxkb; icon and select layout from the
  74 list.</para>
  75
  76 <para>&RMB; clicking on the &kxkb; icon you can start its
  77 configuration by selecting <guimenuitem>Configure...</guimenuitem> or
  78 by opening <application>Control Center</application> and selecting
  79 Localization/Keyboard Layout. Alternatively, you can start it by
  80 typing <command>kcmshell keyboard_layout</command> in a
  81 terminal.</para>
  82
  83 </sect1>
  84 </chapter>
  85
  86 <chapter id="configuringkxkb">
  87 <title>Configuring &kxkb;</title>
  88
  89 <sect1 id="general-config">
  90 <title>General Information</title>
  91 <para>
  92 KXKB Configuration consists of two tabs: Layout Configuration and
  93 XKB Options which are mutually independent. The first one defines
  94 layouts you want to use and their options and second defines parameters
  95 for Xkb extension on which &kxkb; is based.
  96 Xkb options are property of X and are not handled in any way by kxkb -
  97 it just sets it up.
  98 </para>
  99 <note><para>
 100 &kxkb; configuration does not change anything in XFree86 configuration
 101 files and Layout settings from XFree86 configuration are overridden
 102 by &kxkb; if <option>Enable keyboard layout</option> option is turned on.
 103 </para></note>
 104 <note><para>
 105 To make your XFree86 configuration work you have to turn off both
 106 <option>Enable keyboard layout</option> in layout configuration tab
 107 <emphasis>and</emphasis> <option>Enable xkb options</option> in
 108 Xkb options configuration tab (for the latter the same effect can be
 109 reached if <option>Reset Old Options</option> is turned off and
 110 none of xkb options are set).
 111 </para></note>
 112 <para>
 113 &kxkb; does most of its actions through <command>setxkbmap</command> command.
 114 You can see the command line to be executed for each active layout
 115 when you select it and, on the xkb options tab, its available xkb option set.
 116 </para>
 117 </sect1>
 118
 119 <sect1 id="layout-config">
 120 <title>Layout Configuration</title>
 121 <para>
 122 In layout configuration dialog the list of available layouts on your left.
 123 You have to choose each layout you want to use and add them (one by one)
 124 to the list of active layouts on the right. You can also change the order
 125 in which active layouts will be switched when toggled by keyboard shortcut
 126 or mouse button. The first layout in the list becomes default layout.
 127 </para>
 128 <para>
 129 Some layouts have several variants. Layout variants usually represent
 130 different key maps for the same language. For example, Ukrainian
 131 layout might have four variants: basic, winkeys (as in &Windows;), typewriter
 132 (as in typewriters) and phonetic (each Ukrainian letter is placed on a
 133 transliterated Latin one). If your layout is a multi-variant one you can choose
 134 the variant in the combo box below the active layouts list.
 135 </para>
 136 <para>
 137 Keyboard model setting is independent of your keyboard layout and refers
 138 to the "hardware" model, &ie; the way your keyboard is manufactured.
 139 Modern keyboards that come with your computer usually have two extra keys
 140 and are referred to as "104-key" models, which is probably what you want
 141 if you don't know what kind of keyboard you have.
 142 </para>
 143 <para>
 144 You can also choose a switching policy for keyboard layout. By default it's
 145 <option>Global</option>, meaning all applications will share the same current
 146 layout. <option>Application</option> means each application will have its own
 147 layout and switching layout while you are working with one application will not
 148 affect the layout for any others. <option>Window</option> will make every window
 149 have its own layout even if they belong to the same program.
 150 </para>
 151 <para>
 152 If you set only one active layout, at startup kxkb configures the keyboard and
 153 exits, thus its indicator will not appear. If you still want a kxkb indicator,
 154 select the <option>Show indicator for single layout</option> option.
 155 </para>
 156 <note>
 157 <para>
 158 If you leave the active layout list empty, keyboard layouts will be disabled
 159 </para>
 160 </note>
 161 </sect1>
 162
 163 <sect1 id="xkboptions-config">
 164 <title>XKB Options Configuration</title>
 165 <para>
 166 Xkb options allow you to select behavior of your keyboard. These options are not
 167 handled by &kxkb; but may help tune your keyboard to your needs.
 168 </para>
 169 </sect1>
 170
 171 </chapter>
 172
 173 <chapter id="kxkbtroubleshooting">
 174 <title>Troubleshooting</title>
 175
 176 <sect1 id="troubles">
 177 <title>Common Problems</title>
 178
 179 <para>If you switch to some layout and you cannot see some characters
 180 from your layout as you type, please check your local settings.  &eg;
 181 <filename>~/.i18n</filename> or
 182 <filename>/etc/sysconfig/i18n</filename>, locale you have before
 183 starting kde applications must have an encoding which contains
 184 characters from your layout.  For example, to enter Ukrainian symbols
 185 you must have encoding KOI8-U, CP1251 or UTF-8. The last one is a good
 186 choice to try for most of the languages if you have such a problem.
 187 </para>
 188
 189 <para>If kxkb does not switch with keyboard shortcut when you switch
 190 it to some layout, but switching with mouse is OK, may mean that your layout
 191 does not contain the key assigned in shortcut.</para>
 192
 193 <para>In XFree86 prior to version 4.3.0 non-Latin layouts mutually included
 194 Latin group  and this group was the default thus pressing
 195 <keycombo action="simul">&Ctrl;&Alt;<keycap>k</keycap></keycombo>
 196 always yielded the right combination. From version 4.3.0 by default
 197 all layouts contain only one group thus non-Latin layouts may not work
 198 here.</para>
 199
 200 <para>Possible solutions are:</para>
 201
 202 <orderedlist>
 203 <listitem>
 204 <para>add your layout to $nonlatin or $oldlayouts lists in
 205 <filename>/etc/X11/xkb/rules/xfree86</filename> or the location of the
 206 xkb rules on your computer.</para>
 207 </listitem>
 208 <listitem>
 209 <para>Change the shortcut to something language neutral, &eg;
 210 <keycombo action="simul">&Ctrl;<keycap>Menu</keycap></keycombo></para>
 211 </listitem>
 212 <listitem>
 213 <para>Turn on the option to include the <quote>us</quote> group in
 214 your layout (effectively the same as solution 1).</para>
 215 </listitem>
 216 </orderedlist>
 217
 218 </sect1>
 219 </chapter>
 220
 221 <chapter id="xkb-files">
 222 <title>Files and Layout Descriptions</title>
 223 <sect1 id="xkb-files-and-layouts">
 224 <title><application>xkb</application> Files and Layouts</title>
 225
 226 <para>All available keyboard layouts are described in
 227 <filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and
 228 <filename>/etc/X11/xkb/rules/xfree86.xml</filename> since XFree86
 229 4.3.0), the layouts themselves can be found in
 230 <filename>/etc/X11/xkb/symbols/pc</filename> (or
 231 <filename>/etc/X11/xkb/symbols</filename> for XFree86 4.2.x and
 232 older). Note that the location of these files may differ depending on
 233 your operating system and distribution.</para>
 234
 235 <para>&kxkb; now uses the xkb extension instead of xmodmap, so to
 236 define your own layout you have to get one from <filename
 237 class="directory">/etc/X11/xkb/symbols</filename> which is closest to
 238 what you want to get (or <filename
 239 class="directory">/etc/X11/xkb/symbold/pc</filename> for XFree86
 240 4.3.0), rename it to something you like and edit it. Then just add the
 241 name to <filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and for
 242 XFree86 4.3.0 or later it is a good idea to add the name also to
 243 <filename>/etc/X11/xkb/rules/xfree86.xml</filename> - some packages
 244 already use it, not &kxkb; though yet) kxkb will pick it up on
 245 restart. Note: you have to be root to edit those files.</para>
 246
 247 </sect1>
 248
 249 </chapter>
 250
 251 <chapter id="credits-and-licenses">
 252 <title>Credits and Licenses</title>
 253
 254 <para>&kxkb; is currently developed and maintained by &Andriy.Rysin;
 255 &Andriy.Rysin.mail;. Several other people
 256 have worked on <application>kxkb</application>:</para>
 257
 258 <itemizedlist>
 259 <listitem><para>Shaheed Haque <email>srhaque@iee.org</email></para></listitem>
 260 <listitem><para>Ilya Konstantinov <email>kde-devel@future.galanet.net</email>
 261 </para></listitem>
 262 </itemizedlist>
 263
 264 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 265 &underFDL;
 266 &underGPL;
 267
 268 </chapter>
 269
 270 </book>
 271 <!--
 272 Local Variables:
 273 mode: sgml
 274 sgml-omittag: nil
 275 sgml-shorttag: t
 276 End:
 277 -->