components/x11/xorg-docs/src/input/XKB-Config.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The XKB Configuration Guide</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_9276" /><meta name="description" content="This document describes how to configure Xorg XKB from a user's point of view. It covers basic configuration syntax and gives also a few examples. This version covers Xorg server versions 1.8 and later, used with the data files from the xkeyboard-config project." /><style xmlns="" type="text/css">/*
   4  * Copyright (c) 2011 Gaetan Nadon
   5  * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a
   8  * copy of this software and associated documentation files (the "Software"),
   9  * to deal in the Software without restriction, including without limitation
  10  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  11  * and/or sell copies of the Software, and to permit persons to whom the
  12  * Software is furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice (including the next
  15  * paragraph) shall be included in all copies or substantial portions of the
  16  * Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24  * DEALINGS IN THE SOFTWARE.
  25  */
  26
  27 /*
  28  * Shared stylesheet for X.Org documentation translated to HTML format
  29  * http://www.sagehill.net/docbookxsl/UsingCSS.html
  30  * http://www.w3schools.com/css/default.asp
  31  * https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
  32  * https://addons.mozilla.org/en-US/firefox/addon/font-finder/
  33  */
  34
  35 /*
  36  * The sans-serif fonts are considered more legible on a computer screen
  37  * http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
  38  *
  39  */
  40 body {
  41   font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
  42   /* In support of using "em" font size unit, the w3c recommended method */
  43   font-size: 100%;
  44 }
  45
  46 /*
  47  * Selection: all elements requiring mono spaced fonts.
  48  *
  49  * The family names attempt to match the proportionally spaced font
  50  * family names such that the same font name is used for both.
  51  * We'd like to use Bitstream, for example, in both proportionally and
  52  * mono spaced font text.
  53  */
  54 .command,
  55 .errorcode,
  56 .errorname,
  57 .errortype,
  58 .filename,
  59 .funcsynopsis,
  60 .function,
  61 .parameter,
  62 .programlisting,
  63 .property,
  64 .screen,
  65 .structname,
  66 .symbol,
  67 .synopsis,
  68 .type
  69 {
  70   font-family:  "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
  71 }
  72
  73 /*
  74  * Books have a title page, a preface, some chapters and appendices,
  75  * a glossary, an index and a bibliography, in that order.
  76  *
  77  * An Article has no preface and no chapters. It has sections, appendices,
  78  * a glossary, an index and a bibliography.
  79  */
  80
  81 /*
  82  * Selection: book main title and subtitle
  83  */
  84 div.book>div.titlepage h1.title,
  85 div.book>div.titlepage h2.subtitle {
  86   text-align: center;
  87 }
  88
  89 /*
  90  * Selection: article main title and subtitle
  91  */
  92 div.article>div.titlepage h2.title,
  93 div.article>div.titlepage h3.subtitle,
  94 div.article>div.sect1>div.titlepage h2.title,
  95 div.article>div.section>div.titlepage h2.title {
  96   text-align: center;
  97 }
  98
  99 /*
 100  * Selection: various types of authors and collaborators, individuals or corporate
 101  *
 102  * These authors are not always contained inside an authorgroup.
 103  * They can be contained inside a lot of different parent types where they might
 104  * not be centered.
 105  * Reducing the margin at the bottom makes a visual separation between authors
 106  * We specify here the ones on the title page, others may be added based on merit.
 107  */
 108 div.titlepage .authorgroup,
 109 div.titlepage .author,
 110 div.titlepage .collab,
 111 div.titlepage .corpauthor,
 112 div.titlepage .corpcredit,
 113 div.titlepage .editor,
 114 div.titlepage .othercredit {
 115   text-align: center;
 116   margin-bottom: 0.25em;
 117 }
 118
 119 /*
 120  * Selection: the affiliation of various types of authors and collaborators,
 121  * individuals or corporate.
 122  */
 123 div.titlepage .affiliation {
 124   text-align: center;
 125 }
 126
 127 /*
 128  * Selection: product release information (X Version 11, Release 7)
 129  *
 130  * The releaseinfo element can be contained inside a lot of different parent
 131  * types where it might not be centered.
 132  * We specify here the one on the title page, others may be added based on merit.
 133  */
 134 div.titlepage p.releaseinfo {
 135   font-weight: bold;
 136   text-align: center;
 137 }
 138
 139 /*
 140  * Selection: publishing date
 141  */
 142 div.titlepage .pubdate {
 143   text-align: center;
 144 }
 145
 146 /*
 147  * The legal notices are displayed in smaller sized fonts
 148  * Justification is only supported in IE and therefore not requested.
 149  *
 150  */
 151 .legalnotice {
 152   font-size: small;
 153   font-style: italic;
 154 }
 155
 156 /*
 157  * For documentation having multiple licenses, the copyright and legalnotice
 158  * elements sequence cannot instantiated multiple times.
 159  * The copyright notice and license text are therefore coded inside a legalnotice
 160  * element. The role attribute on the paragraph is used to allow styling of the
 161  * copyright notice text which should not be italicized.
 162  */
 163 p.multiLicensing {
 164   font-style: normal;
 165   font-size: medium;
 166 }
 167
 168 /*
 169  * Selection: book or article main ToC title
 170  * A paragraph is generated for the title rather than a level 2 heading.
 171  * We do not want to select chapters sub table of contents, only the main one
 172  */
 173 div.book>div.toc>p,
 174 div.article>div.toc>p {
 175   font-size: 1.5em;
 176   text-align: center;
 177 }
 178
 179 /*
 180  * Selection: major sections of a book or an article
 181  *
 182  * Unlike books, articles do not have a titlepage element for appendix.
 183  * Using the selector "div.titlepage h2.title" would be too general.
 184  */
 185 div.book>div.preface>div.titlepage h2.title,
 186 div.book>div.chapter>div.titlepage h2.title,
 187 div.article>div.sect1>div.titlepage h2.title,
 188 div.article>div.section>div.titlepage h2.title,
 189 div.book>div.appendix>div.titlepage h2.title,
 190 div.article>div.appendix h2.title,
 191 div.glossary>div.titlepage h2.title,
 192 div.index>div.titlepage h2.title,
 193 div.bibliography>div.titlepage h2.title {
 194    /* Add a border top over the major parts, just like printed books */
 195    /* The Gray color is already used for the ruler over the main ToC. */
 196   border-top-style: solid;
 197   border-top-width: 2px;
 198   border-top-color: Gray;
 199   /* Put some space between the border and the title */
 200   padding-top: 0.2em;
 201   text-align: center;
 202 }
 203
 204 /*
 205  * A Screen is a verbatim environment for displaying text that the user might
 206  * see on a computer terminal. It is often used to display the results of a command.
 207  *
 208  * http://www.css3.info/preview/rounded-border/
 209  */
 210 .screen {
 211   background: #e0ffff;
 212   border-width: 1px;
 213   border-style: solid;
 214   border-color: #B0C4DE;
 215   border-radius: 1.0em;
 216   /* Browser's vendor properties prior to CSS 3 */
 217   -moz-border-radius: 1.0em;
 218   -webkit-border-radius: 1.0em;
 219   -khtml-border-radius: 1.0em;
 220   margin-left: 1.0em;
 221   margin-right: 1.0em;
 222   padding: 0.5em;
 223 }
 224
 225 /*
 226  * Emphasis program listings with a light shade of gray similar to what
 227  * DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
 228  * Found many C API docs on the web using like shades of gray.
 229  */
 230 .programlisting {
 231   background: #F4F4F4;
 232   border-width: 1px;
 233   border-style: solid;
 234   border-color: Gray;
 235   padding: 0.5em;
 236 }
 237
 238 /*
 239  * Emphasis functions synopsis using a darker shade of gray.
 240  * Add a border such that it stands out more.
 241  * Set the padding so the text does not touch the border.
 242  */
 243 .funcsynopsis, .synopsis {
 244   background: #e6e6fa;
 245   border-width: 1px;
 246   border-style: solid;
 247   border-color: Gray;
 248   clear: both;
 249   margin: 0.5em;
 250   padding: 0.25em;
 251 }
 252
 253 /*
 254  * Selection: paragraphs inside synopsis
 255  *
 256  * Removes the default browser margin, let the container set the padding.
 257  * Paragraphs are not always used in synopsis
 258  */
 259 .funcsynopsis p,
 260 .synopsis p {
 261   margin: 0;
 262   padding: 0;
 263 }
 264
 265 /*
 266  * Selection: variable lists, informal tables and tables
 267  *
 268  * Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
 269  * A table with rows and columns is constructed inside div.variablelist
 270  *
 271  * Set the left margin so it is indented to the right
 272  * Display informal tables with single line borders
 273  */
 274 table {
 275   margin-left: 0.5em;
 276   border-collapse: collapse;
 277 }
 278
 279 /*
 280  * Selection: paragraphs inside tables
 281  *
 282  * Removes the default browser margin, let the container set the padding.
 283  * Paragraphs are not always used in tables
 284  */
 285 td p {
 286   margin: 0;
 287   padding: 0;
 288 }
 289
 290 /*
 291  * Add some space between the left and right column.
 292  * The vertical alignment helps the reader associate a term
 293  * with a multi-line definition.
 294  */
 295 td, th {
 296   padding-left: 1.0em;
 297   padding-right: 1.0em;
 298   vertical-align: top;
 299 }
 300
 301 .warning {
 302   border: 1px solid red;
 303   background: #FFFF66;
 304   padding-left: 0.5em;
 305 }
 306 </style></head><body><div class="article"><div class="titlepage"><div><div><h2 class="title"><a id="XKB-Config"></a>The XKB Configuration Guide</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Kamil</span> <span class="surname">Toman</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Ivan</span> <span class="othername">U.</span> <span class="surname">Pascal</span></h3></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="pubdate">November 2010</p></div><div><div class="abstract"><p>
 307 This document describes how to configure Xorg XKB from a user's point
 308 of view. It covers basic configuration syntax and gives also a few examples.
 309       </p><p>
 310 This version covers Xorg server versions 1.8 and later, used with the
 311 data files from the <a class="ulink" href="http://www.freedesktop.org/wiki/Software/XKeyboardConfig" target="_top">xkeyboard-config</a> project.
 312       </p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="sect1"><a href="#Overview">Overview</a></span></dt><dt><span class="sect1"><a href="#Selecting_XKB_Configuration">Selecting XKB Configuration</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Basic_Configuration">Basic Configuration</a></span></dt><dt><span class="sect2"><a href="#Advanced_Configuration">Advanced Configuration</a></span></dt><dt><span class="sect2"><a href="#Even_More_Advanced_Configuration">Even More Advanced Configuration</a></span></dt><dt><span class="sect2"><a href="#Basic_Global_Options">Basic Global Options</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Keymap_XKB_Configuration">Keymap XKB Configuration</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Overview"></a>Overview</h2></div></div></div><p>
 313 The XKB configuration is decomposed into a number of components. Selecting
 314 proper parts and combining them back you can achieve most of the configurations
 315 you might need. Unless you have a completely atypical keyboard you really don't
 316 need to touch any of the xkb configuration files.
 317     </p><p>
 318 Some desktop environments now provide integrated graphical configuration
 319 tools for setting XKB configuration as part of your desktop session.  The
 320 instructions in this document are provided for those without such support,
 321 those who need to configure XKB before the session startup (such as at the
 322 login screen), or those who need to perform more advanced configuration
 323 than those tools provide.
 324     </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Selecting_XKB_Configuration"></a>Selecting XKB Configuration</h2></div></div></div><p>
 325 The easiest and the most natural way to specify a keyboard mapping is to use
 326 the <code class="literal">rules</code> component. As its name suggests it describes a number of
 327 general rules to combine all bits and pieces into a valid and useful keyboard
 328 mapping. All you need to do is to select a suitable rules file and then to
 329 feed it with a few parameters that will adjust the keyboard behaviour to
 330 fulfill your needs.
 331     </p><p>
 332       The parameters are:
 333
 334       </p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /></colgroup><tbody><tr><td><p><span class="term"><code class="option">XkbRules</code></span></p></td><td><p>
 335 files of rules to be used for keyboard mapping composition
 336           </p></td></tr><tr><td><p><span class="term"><code class="option">XkbModel</code></span></p></td><td><p>
 337  name of the model of your keyboard type
 338           </p></td></tr><tr><td><p><span class="term"><code class="option">XkbLayout</code></span></p></td><td><p>
 339  layout(s) you intend to use
 340           </p></td></tr><tr><td><p><span class="term"><code class="option">XkbVariant</code></span></p></td><td><p>
 341  variant(s) of the layout you intend to use
 342           </p></td></tr><tr><td><p><span class="term"><code class="option">XkbOptions</code></span></p></td><td><p>
 343  extra xkb configuration options
 344           </p></td></tr></tbody></table></div><p>
 345
 346     </p><p>
 347 The rules file used depends on your system.  The rules files commonly
 348 used with Xorg are provided by the <a class="ulink" href="http://www.freedesktop.org/wiki/Software/XKeyboardConfig" target="_top">xkeyboard-config</a> project.
 349 On Linux systems, the <code class="filename">evdev</code> rules are most
 350 commonly used, on other systems the <code class="filename">base</code> rules
 351 are used.  Some additional rules files exist for historical reasons,
 352 but are no longer widely used.  In general, it's best to simply not
 353 specify the rules file, in order to use the default rules selected
 354 automatically by the X server.
 355     </p><p>
 356 For each rules file there is a description file named
 357 <code class="filename">&lt;<em class="replaceable"><code>vendor-rules</code></em>&gt;.lst</code>,
 358 for instance <code class="filename">base.lst</code> which is located in
 359 the xkb configuration subdirectory <code class="filename">rules</code>
 360 (for example <code class="filename">/usr/share/X11/xkb/rules</code>).
 361     </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Basic_Configuration"></a>Basic Configuration</h3></div></div></div><p>
 362 Let's say you want to configure a PC-style American keyboard with 104
 363 keys as described in <code class="filename">base.lst</code>.  This can be done
 364 by simply writing several lines from below to a new configuration file
 365 in <code class="filename">/etc/X11/xorg.conf.d</code>, such
 366 as <code class="filename">/etc/X11/xorg.conf.d/90-custom-kbd.conf</code>.
 367
 368
 369         </p><pre class="screen">
 370 Section "InputClass"
 371     Identifier "keyboard defaults"
 372     MatchIsKeyboard "on"
 373
 374     Option "XkbModel" "pc104"
 375     Option "XkbLayout" "us"
 376     Option "XKbOptions" ""
 377 EndSection
 378         </pre><p>
 379
 380 The values of <code class="option">XkbModel</code> and <code class="option">XkbLayout</code> are
 381 really not surprising. The <code class="option">XkbOptions</code>
 382 has been explicitly set to the empty set of parameters.
 383 The <code class="option">XkbVariant</code> option has been left out.
 384 That means the default variant named <code class="literal">basic</code>
 385 is loaded.
 386       </p><p>
 387 Of course, this can be also done at runtime using the utility
 388 <span class="command"><strong>setxkbmap</strong></span>.
 389 The shell command loading the same keyboard mapping would look like:
 390
 391         </p><pre class="screen">
 392 setxkbmap -model pc104 -layout us -option ""
 393         </pre><p>
 394
 395 The configuration and the shell command would be very analogous
 396 for most other layouts (internationalized mappings).
 397       </p><p><a id="zap"></a>
 398 If you wanted to enable the <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Backspace</strong></span> sequence to kill
 399 the X server by default, you could create a configuration snippet
 400 <code class="filename">/etc/X11/xorg.conf.d/90-zap.conf</code> containing:
 401
 402         </p><pre class="screen">
 403 Section "InputClass"
 404     Identifier "keyboard defaults"
 405     MatchIsKeyboard "on"
 406
 407     Option "XKbOptions" "terminate:ctrl_alt_bksp"
 408 EndSection
 409         </pre><p>
 410
 411 This would be equivalent to running the shell command:
 412
 413         </p><pre class="screen">
 414 setxkbmap -option "terminate:ctrl_alt_bksp"
 415         </pre><p>
 416       </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Advanced_Configuration"></a>Advanced Configuration</h3></div></div></div><p>
 417 You can use multi-layouts xkb configuration.
 418 What does it mean? Basically it allows to load up to four different
 419 keyboard layouts at a time. Each such layout would reside in its
 420 own group. The groups (unlike complete keyboard remapping) can be
 421 switched very fast from one to another by a combination of keys.
 422       </p><p>
 423 Let's say you want to configure your new Logitech cordless desktop
 424 keyboard, you intend to use three different layouts at the same
 425 time - us, czech and german (in this order), and that you are used to
 426 <span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Shift</strong></span>
 427 combination for switching among them.
 428       </p><p>
 429 Then the configuration snippet could look like this:
 430
 431         </p><pre class="screen">
 432 Section "InputClass"
 433     Identifier "Logitech Cordless"
 434     MatchIsKeyboard   "on"
 435
 436     Option "XkbModel" "logicordless"
 437     Option "XkbLayout" "us,cz,de"
 438     Option "XKbOptions" "grp:alt_shift_toggle"
 439 EndSection
 440         </pre><p>
 441
 442 Of course, this can be also done at runtime using the utility
 443 <span class="command"><strong>setxkbmap</strong></span>.
 444 The shell command loading the same keyboard mapping would look like:
 445
 446         </p><pre class="screen">
 447 setxkbmap -model logicordless -layout "us,cz,de" \
 448          -option "grp:alt_shift_toggle"
 449         </pre><p>
 450
 451       </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Even_More_Advanced_Configuration"></a>Even More Advanced Configuration</h3></div></div></div><p>
 452 Okay, let's say you are more demanding. You do like the example
 453 above but you want it to change a bit. Let's imagine you want
 454 the czech keyboard mapping to use another variant but basic.
 455 The configuration snippet then changes into:
 456
 457         </p><pre class="screen">
 458 Section "InputClass"
 459     Identifier "Logitech Cordless"
 460     MatchIsKeyboard   "on"
 461
 462     Option "XkbModel" "logicordless"
 463     Option "XkbLayout" "us,cz,de"
 464     Option "XkbVariant" ",bksl,"
 465     Option "XKbOptions" "grp:alt_shift_toggle"
 466 EndSection
 467         </pre><p>
 468
 469 That seems tricky but it is not. The logic for settings of variants
 470 is the same as for layouts, that means the first and the third variant
 471 settings are left out (set to <code class="literal">basic</code>),
 472 the second is set to <code class="literal">bksl</code> (a special
 473 variant with an enhanced definition of the backslash key).
 474       </p><p>
 475 Analogously, the loading runtime will change to:
 476
 477         </p><pre class="screen">
 478 setxkbmap -model logicordless -layout "us,cz,de" \
 479          -variant ",bksl," -option "grp:alt_shift_toggle"
 480         </pre><p>
 481
 482       </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Basic_Global_Options"></a>Basic Global Options</h3></div></div></div><p>
 483 For a list of available options, with a short decription of what they do,
 484 see the section starting with <span class="quote">“<span class="quote"><code class="literal">! option</code></span>”</span> in the
 485 <code class="filename">rules/*.lst</code> files.
 486       </p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Keymap_XKB_Configuration"></a>Keymap XKB Configuration</h2></div></div></div><p>
 487 Keymap configuration is the way formerly used to configure xkb. The
 488 user included a special keymap file which specified the direct xkb
 489 configuration. This method has been obsoleted by previously described
 490 rules files which are far more flexible and allow simpler and more
 491 intuitive syntax. It is preserved merely for compatibility reasons and
 492 should be avoided if possible.
 493     </p></div></div></body></html>