summaryrefslogtreecommitdiffstats
path: root/doc/en/index.docbook
blob: b6b09bfa46b872429fa8f85a60f97d198731825e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN"
 "dtd/kdex.dtd" [
  <!ENTITY kkbswitch '<application>KKBSwitch</application>'>
  <!ENTITY kapp "&kkbswitch;"><!-- replace KKBSwitch here -->
  <!ENTITY kkbswitchVersion '1.4.3'>
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->


  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001   -->


<book lang="&language;">

<bookinfo>
<title>The &kkbswitch; Handbook</title>

<authorgroup>
<author>
<firstname>Leonid</firstname>
<surname>Zeitlin</surname>
<affiliation>
<address><email>lz@europe.com</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2002, 2003, 2004, 2005</year>
<holder>Leonid Zeitlin</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>23/01/2005</date>
<releaseinfo>&kkbswitchVersion;</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kkbswitch; is a keyboard layout indicator for &kde;.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KKBSwitch</keyword>
<keyword>keyboard</keyword>
<keyword>layout</keyword>
<keyword>indicator</keyword>
<keyword>XKeyboard</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&kkbswitch; is a keyboard layout indicator for &kde; 2 or 3. It is useful when
you have configured the XKeyboard extension of your X Server to have more than
one keyboard group (layout), for example US/ASCII and Russian. &kkbswitch;
displays an icon in the system tray that indicates which layout is currently
active. Note that &kkbswitch; does not help you configure XKeyboard, it merely
serves as the indicator of the current layout. You still have to configure
XKeyboard by editing the <filename>XF86Config</filename> file.
</para>
<para>
Please report any problems or feature requests to the author, Leonid
Zeitlin, at the address <email>lz@europe.com</email>.
</para>

</chapter>

<chapter id="using-kapp">
<title>Using &kkbswitch;</title>

<para>
The most basic usage is simply to let it sit in the system tray and show you
which keyboard layout is currently active. You can also click the KKBSwicth
system  tray icon to switch keyboard layouts. When right-clicked, the system
tray icon  displays a menu with the following entries:
</para>

<itemizedlist>
<listitem><para>
One or more entries corresponding to the configured keyboard layouts.
Note that XKeyboard can have up to 4 layouts configured. The currently active
layout will be checked. Selecting a menu entry corresponding to a layout will
make that layout active.
</para></listitem>
<listitem><para>
<guimenuitem>"Configure Keyboard Switch..."</guimenuitem>.
This entry lets you configure &kkbswitch;
</para></listitem>
<listitem><para>
<guimenuitem>"Help"</guimenuitem>. Brings up the online help (probably the
document you are reading now).
</para></listitem>
<listitem><para>
<guimenuitem>"About Keyboard Switch"</guimenuitem>.
This entry displays a standard "About" dialog box.
</para></listitem>
<listitem><para>
<guimenuitem>"Quit"</guimenuitem>.
Quit &kkbswitch;.
</para></listitem>
</itemizedlist>

<sect1 id="configure-kkbswitch">
<title>Configuring &kkbswitch;</title>

<para>
In the &kkbswitch; configuration dialog (invoked by selecting
<guimenuitem>"Configure Keyboard Switch..."</guimenuitem> from the tray icon's
context menu) you will be able to configure various aspects of &kkbswitch;'s
behavior. The configuration dialog consits of two pages, <guilabel>General</guilabel>
and <guilabel>Shortcuts</guilabel>.
</para>

<sect2 id="general-page">
<title>The <guilabel>General</guilabel> page</title>

<sect3 id="specifying-icons">
<title>Setting the icons corresponding to the available keyboard
layouts</title>

<para>
The appearance of the system tray icons that represent keyboard layouts depends on the icon <emphasis>style</emphasis>. &kkbswitch; implements the following three styles:
<variablelist>
<varlistentry>
<term>Country flag</term>
<listitem><para>
This style displays a country flag corresponding to the currently selected layout. 
Note that this was the only style in version of &kkbswitch; prior to 1.3.
</para></listitem>
</varlistentry>

<varlistentry>
<term>Language code</term>
<listitem><para>
This style displays the two-letter ISO language code corresponding to the currently selected layout. This style mimics &Windows; layout indicator.
</para></listitem>
</varlistentry>

<varlistentry>
<term>Flag and code</term>
<listitem><para>
This style displays the language code against the background of a country flag. This style mimics &kde;'s <application>kxkb</application> application.
</para></listitem>
</varlistentry>
</variablelist>
</para>

<para>The following table illustrates the look of &kkbswitch; tray icon menu with different icon styles.
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Country flag</entry>
<entry>Language code</entry>
<entry>Flag and code</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<inlinemediaobject>
<imageobject><imagedata fileref="flag_style.png"/></imageobject>
</inlinemediaobject>
</entry>

<entry>
<inlinemediaobject>
<imageobject><imagedata fileref="code_style.png"/></imageobject>
</inlinemediaobject>
</entry>

<entry>
<inlinemediaobject>
<imageobject><imagedata fileref="flag_code_style.png"/></imageobject>
</inlinemediaobject>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>

<para>
The desired style can be selected in the <guilabel>Layout icon style</guilabel> combo box.
</para>

<para>
Note that &kkbswitch; will try hard to guess the correct flag and language code based on the name of the
keyboard layout (the names are configured in XKeyboard). For example, it will
display the US flag and/or "EN" language code for US/ASCII layout, German flag and/or "DE" language code for German layout,
Russian flag and/or "RU" language code for Russian layout, etc. If it cannot guess
an icon, it will display a "default" icon, which simply shows the layout's number. 
Use the configuration dialog to customize flag icons: select a layout in the
<guilabel>"Available keyboard layouts"</guilabel> listbox and click
<guibutton>"Change icon..."</guibutton> button. You will be presented with "Pick icon" dialog box. There you will be able to select from the list of country flag pixmaps that are shipped with &kde;. If you'd like to use a custom image, click the <guibutton>"Browse"</guibutton> button in the bottom of the dialog box and browse for the image file you'd like to use. Note that the preferred size for layout icons is 21 by 14 pixels. If your image has different dimensions, &kkbswitch; will scale it appropriately, but the result might look not very good.
</para>

<para>
Note that changing the icon is not available for the Language Code style, which does not feature a flag.
</para>

<para>
If you have specified a custom icon for a layout, you can always go back to the standard icon (the one the &kkbswitch; has guessed) by clicking <guibutton>"Use Default Icon"</guibutton> button. This button will be enabled only when the layout selected in the <guilabel>"Available keyboard layouts"</guilabel> listbox has a custom icon.
</para>
</sect3>

<sect3 id="default-group">
<title>Specifying default layout</title>
<para>
You can mark one of the configured keyboard layouts as the default. The default
layout will be activated when &kkbswitch; starts up. To mark a layout as
default, simply select the layout in the <guilabel>"Available keyboard
layouts"</guilabel> listbox and click <guibutton>"Set as default"</guibutton>
button. The default layout's name is shown in boldface in the
<guilabel>"Available keyboard layouts"</guilabel> listbox.
</para>
</sect3>

<sect3 id="group-scope">
<title>Specifying layout scope</title>
<para>
&kkbswitch; supports three modes of operation with regards to the scope of the active keyboard layout. Possible settings are:
<variablelist>

<varlistentry>
<term>All windows</term>
<listitem>
<para>
In this mode the active layout applies to all windows on your desktop. In other words, at any given time all windows use the same layout.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Windows of one application</term>
<listitem>
<para>
In this mode the active layout applies to windows one application<footnote><para>A technically inclined user familiar with &X-Window; API would be interested to know that &kkbswitch; considers windows that have the same Window Class (from WM_CLASS property) as belonging to the same application.</para></footnote>. In other words, each application has its own active layout. When a window gets focused, KKBSwitch automatically shows the active layout of this window's application in the system tray. When you change the active layout, either by pressing XKeyboard's group switch key, or by clicking KKBSwitch's tray icon, or by using its context menu, this change affects only the currently active application. Other applications retain their layouts. 
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>One window</term>
<listitem>
<para>
In this mode the active layout applies to the focused window only. In other words, each window has its own active layout. When a window gets focused, KKBSwitch automatically shows this window's active layout in the system tray. When you change the active layout, either by pressing XKeyboard's group switch key, or by clicking KKBSwitch's tray icon, or by using its context menu, this change affects only the currently focused window. Other windows retain their layouts. 
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

<para>
Pick the mode that you prefer in the <guilabel>"Layout applies to"</guilabel> combo box. The author's opinion is that "Windows of one application" is the most reasonable choice, but opinions vary.
</para>

<para>
Note that in "Windows of one application" and "One window" modes, all new windows start up with the default layout. In "All windows" mode new windows start with the active (global) layout.
</para>
</sect3>

<sect3 id="toggle-mode">
<title>Using "Toggle Mode"</title>
<para>
"Toggle mode" is a convenient feature of &kkbswitch;, which is useful if you 
have more than 2 layouts. When "Toggle mode" is on, pressing the XKeyboard's 
group switch key or clicking &kkbswitch;'s tray icon will toggle between the 
two most recently used layouts. To activate the third or the fourth (if 
available) layout
you'll need to right-click  &kkbswitch;'s tray icon and select the desired 
layout from the menu or use keyboard shortcuts (see <xref linkend="shortcuts"/>). For example, I have US/ASCII, Russian and Ukrainian
layouts configured. Most of the time I use either US/ASCII or Russian layout and
switch back and forth between them without activating the rarely needed
Ukrainian layout. But sometimes I need to write something in Ukrainian, so I
select this layout from the tray icon's menu.
</para>
<para>
To turn the "Toggle mode" on and off use the <guilabel>Use "Toggle
Mode"</guilabel> checkbox in the configuration dialog.
</para>

<para>
When "Toggle mode" is on, the two most recently used layouts will be marked
with an asterisk in the &kkbswitch; tray icon's menu.
</para>

</sect3>

<sect3 id="autostart">
<title>Starting &kkbswitch; automatically when you log in</title>
<para>
Use <guilabel>"Autostart"</guilabel> checkbox to enable &kkbswitch; autostart feature. When this checkbox is on, &kkbswitch; will start automatically each time you log in to &kde;. Note that this is independent of &kde;'s session restoration feature. If you configure &kde; to restore the previous session on login (under &kde; Components | Session Manager in &kcontrolcenter;), and &kkbswitch; was running in your previous session, &kde; will restore &kkbswitch;
in the new session regardless of the autostart setting.
</para>
</sect3>

</sect2>

<sect2 id="shortcuts">
<title>The <guilabel>Shortcuts</guilabel> page</title>
<para>
&kkbswitch; allows you to quickly activate particular layouts with keyboard shortcuts. This is configured at the <guilabel>Shortcuts</guilabel> page. 
The <guilabel>"Use shortcuts to activate keyboard layouts"</guilabel> checkbox allows to turns the shortcut feature on and off. Uncheck the checkbox if you don't want to use shortcuts at all. If the checkbox is checked, the shortcuts are enabled. You can configure what key combinations activate which layouts at the key chooser pane under the checkbox. This is a standard &kde; key chooser widget that should be familiar to you from other &kde; applications. The default shortcuts are: <keycombo action="simul"><keycap>Ctrl</keycap> <keycap>Alt</keycap> <keycap>1</keycap></keycombo> to activate the first layout, <keycombo action="simul"><keycap>Ctrl</keycap> <keycap>Alt</keycap> <keycap>2</keycap></keycombo> the activate the second one, etc.
</para>
</sect2>

<sect2 id="group-names">
<title>How &kkbswitch; guesses icons for keyboard layouts</title>
<para>
&kkbswitch; uses the name of the keyboard layout, as defined by XKeyboard, to
guess the icon to represent it. The process is entirely automatic; this section
is only for those who want to tweak how this guessing works or just are curious.
The algorithm is very simple. The &kkbswitch; distribution contains a file named
<filename>group_names</filename>, which resides in &kkbswitch;'s data directory
(<filename
 class="directory">$<envar>KDEDIR</envar>/share/apps/kkbswitch</filename>).
The file is a standard &kde; config file. It contains two sections. The secion  named "Mapping" contains mappings from XKeyboard group names to country codes.
It contains various key=value pairs, key being the name of the XKeyboard layout and
value the two-letter country code of the flag to display. The second section, "Language" contains similar mappings from XKeyboard group names to language codes. Note that if a group name is not found in the "Language" section, it is looked up in "Mapping" section, thus only layouts where country code and language code do not coincide need to be listed in "Language" section (e.g. for US/ASCII group the country code would be "us", but the language code would be "en").
</para>

<para>
Once the country-code
has been determined, &kkbswitch; will look for an icon named
<filename>flag.png</filename> in the directory <filename
class="directory">$<envar>KDEDIR</envar>/share/locale/l10n/<replaceable>country code</replaceable></filename> for icons styles that feature a flag and use the language code for styles that feature the a language code.
</para>

<para>
As I was told, in &RedHat; 9 systems, the &kde; default country flag icons are missing. To work around that, if &kkbswitch; cannot find country flag icons in the location specified above, it will look for <acronym>GNOME</acronym>'s <application>gkb</application> icons in <filename class="directory">/usr/share/pixmaps/gkb</filename>. Unfortunately, <application>gkb</application> icons have size 40x60, while &kde; ones are 21x14. Thus &kkbswitch; rescales <application>gkb</application> icons on the fly, and the quality of the resulting images leaves a lot to be desired. But still it's better than nothing. 
</para>

<para>
Of course, you can override the flag icon selection algorithm by specifying the icon you want to use, as described in <xref linkend="specifying-icons"/>.
</para>

</sect2>
</sect1>
</chapter>

<chapter id="developers">
<title>Developer's Guide to &kkbswitch;</title>

<para>
&kkbswitch; can be manipulated programmatically via DCOP. It exports an
interface named <classname>KBSwitchIntf</classname>. The interface offers the
following methods.
</para>

<funcsynopsis>
<funcprototype>
<funcdef>int <function>getNumKbdGroups</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
This method returns the number of configured keyboard groups (layouts).
</para>

<funcsynopsis>
<funcprototype>
<funcdef>ASYNC <function>selectNextGroup</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
This method does the same thing as clicking on the &kkbswitch;'s
tray icon, i.e. makes the next keyboard layout active. If in "toggle mode",
toggles between the two recently used ones, just like clicking on the tray icon
does.
</para>

<funcsynopsis>
<funcprototype>
<funcdef>ASYNC <function>selectGroup</function></funcdef>
<paramdef>int <parameter>groupno</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This method makes the layout whose number is <parameter>groupno</parameter>
active (like selecting a layout from the tray icon popup menu).
</para>

<funcsynopsis>
<funcprototype>
<funcdef>QStringList <function>getGroupNames</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
This method returns the list of the keyboard layout names, as configured in
XKeyboard.
</para>

<sect1 id="examples">
<title>Examples</title>
<para>
The following examples illustrate how one can manipulate &kkbswitch; with the
command line tool <command>dcop</command>.
</para>

<informalexample>
<para>Select the next keyboard group (layout):</para>
<para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>dcop</command> kkbswitch KBSwitchIntf selectNextGroup</userinput> 
</screen>
</para>
</informalexample>

<informalexample>
<para>Select the group (layout) number 0:</para>
<para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>dcop</command> kkbswitch KBSwitchIntf selectGroup 0</userinput>
</screen>
</para>
</informalexample>

</sect1>
</chapter>


<chapter id="credits">

<title>Credits and License</title>

<para>
&kkbswitch;
</para>
<para>
Program copyright 2001-2004 Leonid Zeitlin <email>lz@europe.com</email>
</para>

<para>
Contributors:
<itemizedlist>
<listitem><para>Mikhail Senin <email>m_senin@mail.ru</email> - implemented
configuration for the default layout and per-window layouts
</para>
</listitem>

<listitem>
<para>
Rashid N. Achilov <email>achilov@granch.ru</email> - made a FreeBSD port, suggested "Browse" button in "Pick icon" dialog box.
</para>  
</listitem>  

<listitem>
<para>
Vadim Kriklivy <email>analitic@vinnitsa.com</email> - suggested "Language code" icon style (a la &Windows;) and shortcuts feature, made Ukrainian translation.
</para>  
</listitem>  

<listitem>
<para>
Sergey V Turchin <email>zerg@altlinux.org</email> - implemented autostart feature.
</para>
</listitem>

<listitem>
<para>
Stergios Dramis <email>sdramis@egnatia.ee.auth.gr</email> - contributed Greek translation.
</para>
</listitem>

<listitem>
<para>
Michal &Scaron;ulek <email>reloadshot@atlas.sk</email> - contributed Slovak translation.
</para>
</listitem>

<listitem>
<para>
Shlomi Loubaton <email>shlomister@gmail.com</email> - contributed manpage, Debian package 
maintainer.
</para>
</listitem>

<listitem>
<para>
Igal aka "Koala" <email>igalfr@netvision.net.il</email> - contributed Hebrew translation, Gentoo ebuild maintainer.
</para>
</listitem>

<listitem>
<para>
Petko Yotov <email>5ko@free.fr</email> - contributed Bulgarian translation.
</para>
</listitem>

<listitem>
<para>
Michal Bukovsk&yacute; <email>michal@trilogic.cz</email> - contributed Czech translation.
</para>
</listitem>

</itemizedlist>
</para>

<para>
Documentation copyright 2001-2005 Leonid Zeitlin <email>lz@europe.com</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL; <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-KKBSwitch">
<title>How to obtain &kkbswitch;</title>

<para>
&kkbswitch; has a home page at SourceForge: 
<ulink url="http://kkbswitch.sourceforge.net">
http://kkbswitch.sourceforge.net</ulink>. Check there for the latest news. The latest version is available for download from the project page: <ulink url="http://sourceforge.net/projects/kkbswitch">
http://sourceforge.net/projects/kkbswitch</ulink>.
</para>
<!-- <para>
&kkbswitch; can be found in the at the <ulink
url="http://apps.kde.com/">apps.kde.com</ulink> site at <ulink
url="http://ftp.kde.com/Desktop/Utilities/KKBSwitch/">
http://ftp.kde.com/Desktop/Utilities/KKBSwitch/</ulink>
</para>
<para>
&kkbswitch; doesn't have a homepage yet. For the latest version check <ulink
url="http://apps.kde.com/">apps.kde.com</ulink>
</para> -->
</sect1>

<sect1 id="requirements">
<title>Requirements</title>
<para>
&kkbswitch; doesn't require any special environment to compile and run besides
 the standard &kde; 2 or 3 kdelibs and kdebase.
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>
<para>
In order to compile and install &kkbswitch; on your system, type the following
in the  base directory of the &kkbswitch; distribution:
<screen width="40">
<prompt>&percnt;</prompt> <userinput>./configure</userinput>
<prompt>&percnt;</prompt> <userinput>make</userinput>
<prompt>&percnt;</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>
Options you may want or need to give to the <command>configure</command> command are:
</para>
<simplelist>
<member>
<option>--prefix</option>=<replaceable>dir</replaceable> - set the prefix where your &kde; installation is located. Alternatively, you can set $<envar>KDEDIR</envar> environment variable to the &kde; directory. Under regular circumstances, the configuration script will find the &kde; location automatically; use this option only if you are having problems without it.
</member>
<member>
<option>--enable-ru-ua-layout</option> - install the Russian/Ukrainian layout file (described in <xref linkend="ru_ua"/>). This option is useful for users of XFree86 prior to version 4.3, who want to use Russian/Ukrainian layout file. Note that with this option it is not possible to install &kkbswitch; without root privileges, because the layout file <emphasis>must</emphasis> go to the system XKB layout directory where ordinary users don't have write access.
</member>
<member>
<option>--without-arts</option> - do not check for &arts; development headers. &arts; is &kde;'s multimedia framework, which &kkbswitch; does not use. However, since &kkbswitch; uses standard &kde; configuration macros, the configuration script will check for &arts; headers and complain if they are not found. If this happens to you, specify this option to compile &kkbswitch;. Alternatively, install &arts; development headers, you'll need them one day.
</member>
</simplelist>


<para>
Since &kkbswitch; uses autoconf and automake you should have not trouble
compiling it. &kkbswitch; was tested under several versions of &Linux; and FreeBSD, 
and a FreeBSD port is available.
</para>

<para>
If you system uses <application>RPM</application> you may want to download
&kkbswitch; source RPM package. To build a binary RPM out of source RPM run this
command (as root):
<screen>
<prompt>&percnt;</prompt> <userinput><command>rpmbuild</command> <option>--rebuild</option> <filename>kkbswitch-&kkbswitchVersion;-1.src.rpm</filename></userinput>
</screen>

(You may add <option>--with ru_ua_layout</option> option if you need the Russian/Ukrainian layout file, see  <xref linkend="ru_ua"/>).
Then, still as root, go to your binary RPM directory (on &RedHat; Intel systems,
<filename class="directory">/usr/src/redhat/RPMS/i386</filename>) and install
the binary RPM you've just built with this command:
</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>rpm</command> <option>-ihv</option> <filename>kkbswitch-&kkbswitchVersion;-1.i386.rpm</filename></userinput>
</screen>

<para>
Note that with older versions of <application>RPM</application> you will need to use command <userinput><command>rpm</command> <option>--rebuild</option></userinput> instead of <userinput><command>rpmbuild</command> <option>--rebuild</option></userinput>
</para>

</sect1>
</appendix>

<appendix id="ru_ua">
<title>The Russian/Ukrainian keyboard layout file</title>
<para>
For the benefit of Ukrainian users of &kkbswitch; and XFree86 versions before 4.3,
a Russian/Ukrainian keyboard layout file is included with the distribution (users of XFree86 4.3 and later, including X.Org server, read the note in the end of this appendix). This file is experimental, so report any problems with it to the author of &kkbswitch;. The file is named
<filename>ru_ua</filename> and by default gets installed to the directory
<filename class="directory">/usr/X11R6/lib/X11/xkb/symbols</filename>, where
this type of XKeyboard configuation file is supposed to go. The file defines a
configuration with 3 keyboard groups (layouts): US/ASCII, Russian and Ukrainian.
To use this layout, you can do one of the following.
<orderedlist>
<listitem>
<para>
If you feel comfortable editing your <filename>XF86Config</filename> file and
know its structure you can simply edit the file (usually
<filename>/etc/X11/XF86Config-4</filename> for XFree86 4.x), and in InputDevice
section for keyboard set XkbLayout option to "ru_ua". It is recommented to set
XkbVariant to "winkeys", since only this variant was tested.
</para>
</listitem>
<listitem>
<para>
If you are using &RedHat; &Linux;, you may create a file named
<filename>.Xkbmap</filename> in your home directory and write the text "ru_ua"
(without quotes) in it. The default X session startup script will pick this file
and activate the layout named in it.
</para>
</listitem>
<listitem>
<para>
Run the command <userinput><command>setxkbmap</command> ru_ua</userinput> either
manually from command prompt our in one of your X session startup script.
</para>
</listitem>
</orderedlist>
</para>

<note>
<para>Users of XFree86 4.3 and later versions, including X.Org server, don't need any additional files if they want a three-language layout. Just specify <userinput>XkbLayout "us,ru,ua"</userinput> in your <filename>XF86Config</filename> (<filename>xorg.conf</filename> for X.Org server) file.
</para>
</note>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->